DHCP Admin

Company: PC & Web Xperience, Inc.

admin@pcxperience.com

03/28/2001


Design Document

Version 0.2


Overview

The purpose of this document is to define the configuration and organization of the DHCP administration program. This program will allow modifications to a template DHCP configuration file in order to facilitate setting up, removing, and modifying hostname - MAC address entries for known hosts inside network sections of the configuration file.


DHCP Admin Configuration Files

Requirements

The DHCP administration program needs the version of the ISC DHCP server that allows for client-type recognition via vendor-class-identifier tags. This version of DHCP needs to be installed on the server that will hand out IP addresses to booting workstations. These features are available in ISC dhcpd 3.0b2pl14 and subsequent releases.

Purpose

In an environment where many clients need to be added quickly (setting up large networks, labs, etc.) it becomes useful to have a tool that will aid in entering all required data for the settings of a given host workstation. In addition, the network may consist of clients that boot using different methods and/or require different data to be sent to them by DHCP.

Implementation

The configuration file for the DHCP server will need to be modified in order to allow the DHCP administration program to recognize the different classes of clients that can connect (known PXE, known Etherboot, unknown PXE, unknown Etherboot, etc.) and the different networks these known clients will be booting into. This will be accomplished by the use of keywords that will be substituted for every time they are encountered in the template DHCP configuration file. It will normally be stored in the /etc/dhcpadmin/dhcpd.conf.template file. These keywords will be specified in and substitute values from the /etc/dhcpadmin/dhcpadmin.conf file.

As the template DHCP configuration file is parsed, the DHCP administration program will substitute the contents of the appropriate variable or file for the recognized keyword. Keywords starting with a dollar sign ($) will be translated directly as a value. Keywords starting with the (@) symbol will be translated as a file from which to pull the contents and substitute (include files).

The structure of the include files must contain lists of valid hostname entries for DHCP. Once the template DHCP configuration file has been parsed and the known clients' host entries have been inserted into a temporary file (/tmp/..., obtained by using tmpnam()), the /etc/dhcpd.conf file will be copied to /etc/dhcpd.conf~ (just like the DHCP server does with the leases file) and then the /etc/dhcpd.conf file will be overwritten with the new temporary file. The DHCP server will then need to be restarted for any new changes to take place.


Configuration File Format

There are two main groups of configuration files the DHCP administration program deals with: 1) its own configuration file(s) and 2) the configuration file(s) (include files) for known host entries. Both of these types of files need to be in the correct format.

The configuration file for the DHCP administration program (/etc/dhcpadmin/dhcpadmin.conf) has the following format:


<keyword> = "<value>"

# <- comment character; anything after this character on a line is a comment


Keywords must start with an alphabetical character (a-zA-Z) or an underscore (_) and can contain alphanumerical values (a-zA-Z0-9) and underscores (_). Values can be anything. All values MUST be surrounded by double quotes ("). If the double quote character is to be embedded into the value, it must be escaped (\").


The configuration file(s) (include files) for known host entries must be correctly formatted to be recognized by the DHCP server parser. The known host configuration file is simply a section of the dhcpd.conf file that would normally have been entered manually wherever the filename keyword substitution takes place.


Operation

The purpose of the DHCP administration program is to substitute values from its configuration file for keywords recognized in the template DHCP configuration file and to add, modify, and delete known host entries in the files that will be included when the template DHCP configuration file is parsed.

To facilitate these features, the dhcpadmin program will have the following command-line interface:


Commands

--parse: instructs dhcpadmin to perform the keyword substitution on the template DHCP configuration file and overwrite the DHCP configuration file (usually /etc/dhcpd.conf) after it has processed any other commands on the command-line (i.e., add, update, delete, etc.); after this step has succeeded, the DHCP server will need to be restarted in order for the changes to take effect


--add: add a known host entry to <file> using the <host> as the hostname or <MAC> address as the hardware declaration for the entry and the value of <host_entry> as the information in the host entry (i.e., dhcpadmin --add --host <host> --file <file> --hostentry <host_entry> or dhcpadmin --add --host <host> --mac <MAC> --ipaddr <IP> --file <file>); one or both of <host> or <MAC> address must be supplied on the command line; the contents of the host entry value must contain the information that resides in the DHCP host declaration; if no host entry value is specified on the command line or STDIN but both <host> and <MAC> are, then the host entry will be inserted into <file> using <host> and <MAC> as the only entries to define a known host (if <IP> is supplied, this value will be used as the fixed-address entry)


--delete: delete a known host entry from <file> using the <host> as the hostname or <MAC> address as the hardware declaration or <IP> as the fixed-address declaration for the entry; any combination of <host> or <MAC> address or <IP> address must be supplied on the command line; if more than one are supplied, then only the record that has all entries matching hostname <host> or a "hardware ether <MAC>" entry or a "fixed-address <IP>" entry of the command-line combination will be removed from <file>; since there can be more than one host entry for the same MAC address, implying multiple host entries in <file> with the same MAC address, only the first instance that is recognized will be deleted for a given <host> or <MAC> or <IP>


--update: update a known host entry in <file> using the <host> as the hostname or <MAC> address as the hardware declaration or <IP> as the fixed-address declaration for the entry and replacing the contents of the entry with the value of <host_entry>; if no host entry value is specified on the command line but both <host> and <MAC> are, then the host entry matching both the <host> and <MAC> will be updated to only contain the <host> and <MAC> to define that known host (if <IP> is supplied, this value will be used as the fixed-address entry)


--find: this option attempts to use the <host> and/or <MAC> and/or <IP> options to find all entries that match the options passed on the command-line


Configuration Options

--file <file>: the filename to modify when adding, updating, or deleting a known host entry


--hostentry <host_entry_value>: this option contains the lines for insertion into <file> for the <host> entry that is to be added to or updated in <file>; it can be sent on the command-line as an optional string parameter or through STDIN


--host <host>: this value specifies the hostname to use for adding, updating, or deleting an entry in <file>


--mac <MAC>: this value specifies the MAC address to use for adding, updating, or deleting an entry in <file>; it must be a colon separated value of the form 00:AA:11:BB:22:CC


--ipaddr <IP>: this value specifies the IP address to use for adding, updating, or deleting an entry in <file>; it must be a decimal formatted value of the form <255>.<255>.<255>.<255>; this value will be used for the fixed-address line in the host entry


--config <config_file>: alternate location for dhcpadmin's configuration file which normally resides in /etc/dhcpadmin/dhcpadmin.conf


--dhcpconfig <dhcp_file>: alternate location for the DHCP server's configuration file which normally resides in /etc/dhcpd.conf; this option is only relevant when parsing the template DHCP configuration file to replace keywords and include files; this file will be overwritten by the newly parsed and substituted template file


--templatefile <template_file>: alternate location for dhcpadmin's template DHCP configuration file which normally resides in /etc/dhcpadmin/dhcpd.conf.template


Values that are to be used for the contents of the host entry must be of the format that goes between the curly braces of a valid DHCP host entry. Values that are passed on the command-line will NOT override values passed by the --hostentry option or STDIN:


host <host> {

# the following lines are what go into the host entry value

hardware ether 00:11:22:33:44:55;

fixed-address 192.168.0.10;

filename "/tftpboot/download.me";

rootpath "/tftpboot/root";

# up to here

}


Command-line Dependencies

Whenever an option is sent on the command-line, it almost never operates alone. The only command-line option that does not need any other options and can use the defaults is --parse. This option performs the actions of parsing the dhcpadmin configuration file, parsing the template DHCP configuration file, and substituting all found keywords in the template with the values of those keywords from the dhcpadmin configuration file. The default configuration options are sufficient for this command to run.

All other command-line options rely on other command-line options to be present when the dhcpadmin program is run.


--add:


--update:


--delete:


--find: