Table of Contents
dhcp-bindings-tool - manipulate a CMU+PU dhcpd bindings directory
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 ]
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.
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.
- --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.
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.
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
The following exit values are returned:
0 No errors
>0 An error occurred
dhcp-bindings-tool was written by Irwin Tillman of Princeton University’s
OIT Network Systems Group.
bootptab(5), dhcpd(8), dhcpd.conf(5).
Table of Contents