DHCP-BINDINGS-TOOL(8)

NAME
dhcp-bindings-tool - manipulate a CMU+PU dhcpd bindings directory

SYNPOSIS
dhcp-bindings-tool --read-bindings-dir directory | --read-report filename
[ --prune-cliid 0xhh... ] [ --prune-cliidhw 0xhh... ] [ --prune-code number ] [ --prune-expire 'gt|lt|eq time_t' ] [ --prune-last-touch 'gt|lt|eq time_t' ] [ --prune-last-ip IP[&netmask] ]
[ --write-bindings-dir directory ] [ --write-report filename ] [ --write-statistics filename ]
[ --debug ] [ --help ] [ --usage ] [ --version ]

DESCRIPTION
dhcp-bindings-tool may be used to read a bindings directory in the format used by Carnegie Mellon University dhcpd with the Princeton University patches, henceforth referred to as CMU+PU dhcpd, or simply dhcpd.

After reading the bindings into memory, the program may optionally prune the in-memory data. After any optional pruning, the resulting in-memory data may be written to create a new bindings directory, written to a plain text report file, and/or used as the basis to write a plain text statistics file.

The program can also read the plain text report file instead of a bindings directory. This allows you to use the program to write a report based on a bindings directory, manipulate that report using other software, then read the resulting report to create a new bindings directory.

The program relies on perl 5.8.0 or later, and the following modules from the Comprehensive Perl Archive Network (CPAN): Readonly, Statistics::Descriptive.

AVAILABILITY
dhcp-bindings-tool is distributed as part of CMU_PU dhcpd at http://www.net.princeton.edu/software/dhcpd/.

perl is available from http://www.perl.com.

The additional required perl modules are available from CPAN at http://www.cpan.org.

OPTIONS

--debug
    Enables debugging messages.

--help
    Displays usage information and exits.

--prune-cliid 0xhh...
    After the data has been read into memory, prune from the in-memory data any bindings where the cliid field matches the hexadecimal value 0xhh... The value specified must represent a value with 1-255 bytes. It must contain an even number of hexadecimal nibbles.

--prune-cliidhw 0xhh...
    After the data has been read into memory, prune from the in-memory data any bindings where the cliidhw field matches the hexadecimal value 0xhh... The value specified must represent a value with 1-255 bytes. It must contain an even number of hexadecimal nibbles.

--prune-code number
    After the data has been read into memory, prune from the in-memory data any bindings where the code field matches the specified decimal value. The value must be a whole number in the range 0 through 255. (This field is used internally by dhcpd to categorize the binding.)

--prune-expire 'gt|lt|eq time_t'
    After the data has been read into memory, prune from the in-memory data any bindings where the expire field is greater than, less than, or equal to time_t. The time_t value must be an integer in the range 0 through 2**32-1, and represents a UNIX time value. Because there is white space between the operator gt, lt, or eq and time_t, the entire argument to this option must be quoted.

--prune-last-touch 'gt|lt|eq time_t'
    After the data has been read into memory, prune from the in-memory data any bindings where the last_touch field is greater than, less than, or equal to time_t. The time_t value must be an integer in the range 0 through 2**32-1, and represents a UNIX time value. Because there is white space between the operator gt, lt, or eq and time_t, the entire argument to this option must be quoted.

--prune-last-ip IP[&netmask]
    After the data has been read into memory, prune from the in-memory data any bindings where the last_ip field matches the specified IP[&netmask]. The specified IP and optional netmask values must each be in decimal dotted quad format; e.g. 192.168.1.7 or 192.168.1.0&255.255.255.0. If the &netmask is omitted, it defaults to 255.255.255.255. If the ampersand character has special meaning to your shell, you will need to quote it.

--read-bindings-dir directory
    Read bindings data from the specified directory. The directory should be a bindings directory created by dhcpd, or by an earlier run of this program using the --write-bindings-dir option. The data is read into memory. Either the --read-bindings-dir or --read-report option must be specified, but not both. If any error is encountered reading the data, this program halts without producing any output files.

--read-report filename
    Read bindings data from the specified plain text report file. The report file should be one created by an earlier run of this program using the --write-report option. The data is read into memory. Either the --read-bindings-dir or --read-report option must be specified, but not both. If any error is encountered reading the data, this program halts without producing any output files.

--write-bindings-dir directory
    Create a new directory and write the in-memory data to it. The new directory is in the same format read and written by dhcpd and by this program's --read-bindings-dir option. The directory must not already exist. Any error writing output may leave behind missing or truncated output files.

--write-report filename
    Write a file containing the in-memory data in plain text format. The report is in a format which may be read by this program's --read-report option. Any error writing output may leave behind missing or truncated output files.

--write-statistics filename
    Write a file containing statistics summarizing the in-memory data. Any error writing output may leave behind missing or truncated output files.

--usage
    Displays usage information and exits (same as --help).

--version
    Displays version information and exits.

USAGE
This program does its work in three phases. It first reads all the input, either from a bindings directory or from a report file. After all input has been read successfully into memory, it perform any (optional) pruning that was requested; the pruning is applied to the in-memory data. (No change is made to the input file(s).) Finally, it uses the in-memory data as the basis to write any optional output files that were specified.

If you use the --read-bindings-dir option, be sure that the directory is not changing while this program reads it. (E.g. stop the DHCP server before reading the bindings directory.)

If you use the --write-bindings-dir option, keep in mind that the owner, group, and permissions of the created directory tree may not match those the DHCP server expects. Before pointing the DHCP server to the new bindings directory, you will need to adjust the owner, group, and permissions of the new bindings directory.

Prudence would dictate that you use extreme care when replacing the DHCP server's bindings directory with a new version created by this program. Keep a version of the old bindings directory around just in case you need to back out.

If more than one of the pruning options is specified, they are all AND'd together.

Any or all of the --write-report, --write-statistics, and --write-bindings-dir options may be specified. If more than one is specified, care should be taken to ensure that the specified output files/directory do not conflict with each other, to avoid overwriting output.

EXAMPLES

Read a bindings directory, then create a new bindings directory containing a copy of that data:
    dhcp-bindings-tool --read-bindings-dir ./bindings --write-bindings-dir ./new-bindings

Read a bindings directory, then write a text report of that data:
    dhcp-bindings-tool --read-bindings-dir ./bindings --write-report /tmp/report

Read a report file, then create a new bindings directory based on it:
    dhcp-bindings-tool --read-report /tmp/report --write-bindings-dir ./new-bindings

Read a bindings directory, then prune those bindings where the expire field is less than 1006655461 and the last_ip field is in the range 192.168.1.0 - 192.168.1.255, then write the remaining bindings to a new bindings directory:
    dhcp-bindings-tool --read-bindings-dir ./bindings --write-bindings-dir ./new-bindings --prune-expire 'lt 1006655461' --prune-last-ip 192.168.1.0&255.255.255.0

Read a bindings directory, prune those bindings where the cliid field is 0x01000c02bd6a4f, then write the remaining bindings to a report file, and also write statistics based on the remaining bindings:
    dhcp-bindings-tool --read-bindings-dir ./bindings --write-report /tmp/report --write-statistics /tmp/statistics --prune-cliid 0x01000c02bd6a4f

EXIT STATUS

The following exit values are returned:
      0 No errors
      >0 An error occurred

AUTHOR
dhcp-bindings-tool was written by Irwin Tillman of Princeton University's OIT Network Systems Group.

SEE ALSO
bootptab(5), dhcpd(8), dhcpd.conf(5).