| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
dhcp-client is a highly configurable and extendable DHCP client. Out of the box it has been built to start up and perform DHCP for a basic network setup with minimal fuss.
This chapter of the manual is divided into two parts. A quickstart guide written to get things up and going with minimal fuss and absolutely no file editing, and a more in depth reference manual to making use of the other DHCP client features.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These instructions are for a quick no-hassle basic DHCP client setup. You don't really need to do much except know the following:
That a DHCP server is waiting and responding to any queries originating from your machine.
That you are using an ethernet connection and know the name of the network interface you are using. Under Linux this is usually "eth0", and under other operating systems like FreeBSD or Solaris the interface may be called "le0" or "xl0". If you are using a system with multiple network interfaces you should probably read the rest of this manual thoroughly to make sure your system is configured correctly by the client.
You want to setup your IP address (netmask and broadcast included), default route, and domain name system and nothing else.
You can send an ICMP echo request to the default gateway, otherwise you need to disable icmp latency discovery which is explained further down in the manual.
Your PATH environment variable points to the dhcp-client binary.
As the root user run the following command:
dhcp-client -i <interface>
Where you substitute <interface> with the name of your interface. Alternatively if the interface is down you can omit the `-i' and dhcp-client will automatically use the first ethernet interface which is not up.
You should be greeted by copyright text and the output of the client as it queries the DHCP server and configures your system. Once the client is done, it will fork into the background and continue to renew your lease as timers expire. In the event of the lease expiring the client will down your interface and cleanup any of the system configuration it had done before.
Although you can run the client in the foreground, if you do not, the client will send the rest of its messages to syslogd. Currently it logs to the daemon service [ FIXME: in the future the syslog service will be configurable ].
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
dhcp-client accepts a number of configuration directives. Some of these can be passed by the command line, and others through a configuration file.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Always run in the foreground and do not go into the background.
Clear the cache. This is useful in case a stale cache is left behind by an earlier invocation.
-k
Kill a dhcp-client instance. Coupled with the -i option this will kill a specific instance of dhcp-client. Otherwise the first dhcp-client found on an active ethernet interface is terminated.
Forces dhcp-client to use promiscious mode. This is only useful on systems which are sufficiently broken that require promiscious mode to receive broadcast messages.
Wake a dhcp-client instance. Coupled with the -i option this will wake up a client on a specified interface and cause it to either rebind, or renew earlier depending on which timer is next. Use this to force the client to reacquire a lease.
Print out status information on the most recent lease acquired by the client.
Generate messages at the level specified. The level should be an integer between 0 - 4. The levels are no messages, error messages, info messages (default), warnings, diagnostic-messages, respectively. Each level includes all messages below it. The default is info messages which also include error messages.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
dhcp-client will look for two files for a configuration
information. Both these files should be located in the system
configuration directory. By default this is defined as
`/usr/local/etc' You can change this definition at build time by
specifying a different prefix to the configure script.
The first file that is checked for begins with the name of the interface the client is configuring. For example, if the name of our interface is "xl0" then the configuration file to be checked will be `/usr/local/etc/dhcp-agent/dhcp-client/xl0.conf'
If this file does not exist then the default configuration file is `/usr/local/etc/dhcp-agent/dhcp-client/default.conf'
This allows dhcp-client to accept configuration per interface, and use a default file without forcing the user to name interfaces in the actual configuration file. It is believed that configuration files are more portable this way and are not dependant on interface names.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The configuration file is made up of directives. Each directive can take up one line or fall on multiple lines . Each directive is terminated by a semicolon. Whitespace is ignored unless it is found in a quoted sting. Newlines are always ignored.
foobar = yada, blah; |
And:
foobar = yada, blah; |
Are the same.
The parser also recognizes strings in two different formats. Quoted and unquoted.
"foobar" |
Is parsed exactly the same as
foobar |
However:
foo bar |
Will parse as two different strings, so you should use:
"foo bar" |
Quoting is useful for strings which contain whitespace. Newlines in quoted strings will result in an error unless preceeded by the '\' character. There should be no need to put newlines in quoted strings and expect them to be evaluated without the backslash (much like a Makefile). If you want newlines to be silently ignored you need to convince the author that they should be :-)
The '\' character can be used to escape double quotes too.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following directives affect DHCP option handling by the client
This directive instructs the client to request a set of dhcp options. The request directive accepts a list of strings which name the options to be requested:
request subnet-mask, ip-address-lease-time, renewal-time,
rebinding-time, interface-mtu, domain-name, domain-name-servers;
|
This directive instructs the client to require a set of dhcp options to be passed before accepting the lease. This is useful to make sure you receive a minimum of desired options. If these options are never met the client will eventually timeout. If this directive is not set, the first DHCP lease offer will be accepted.
require subnet-mask, ip-address-lease-time, renewal-time,
rebinding-time, interface-mtu;
|
This directive instructs the client to only configure a set of dhcp options. This is useful if the server is passing you options you would rather not configure but implicitly claim to configure by accepting the lease. This directive does not define how options are configured. In order to define how configuration is done see "Writing Client Extensions," for more info.
configure subnet-mask, ip-address-lease-time, renewal-time,
rebinding-time, interface-mtu, domain-name, domain-name-servers;
|
This directive instructs the client to append a value to a DHCP option prior to system configuration. If this option is a list of values, the value specified is merely appended. If this value is a string the value is appended to the string. If this option is a single datum then you should be using the override option instead.
append domain-name-servers = 127.0.0.1, 192.168.0.1; |
This directive works the same as the append directive only the values are placed at the beginning of the list or string. You should not use prepend on single datum options and should use override instead.
prepend domain-name-servers = 127.0.0.1, 192.168.0.1; |
This directive instructs the client to overwrite a DHCP option with a specified value prior to system configuration. This is useful to for clients that wish to use an alternate value for a DHCP option than the one passed by the DHCP server.
override domain-name = "example.com"; |
This directive instructs the client to set a variable to a defined value.
set default-subnet-mask = 255.255.255.0; |
This directive instructs the client to set a boolean variable to a defined value. The boolean variable only accepts "yes" or "no" for values.
enable do-measure-router-latency = no; |
dhcp-client accepts a number of variables to configure default values, values passed to the server, and control some of its behaviour.
This variable can be set to a string which is passed as the hostname DHCP option to the server. This allows servers to pass configuration based on a hostname passed by the client. It will also instruct the client to set the hostname to that variable. If you want to pass a hostname to the server you should set this variable and not use the "override" directive because the "override" directive only affects system configuration.
set hostname = "foo.example.com"; |
This variable can be set to an integer value which instructs the client on how many times it should retry a DHCP discover before it gives up.
set dhcp-discovery-retries = 3; |
This variable can be set to an integer value which instructs the client on how many times it should retry an ICMP operation. This affects operations such as router latency discovery, ICMP netmask discovery etc.
set icmp-retries = 3; |
This variable can be set to an integer value which instructs the client on what it's default interface MTU should be. This MTU is used during the initial DHCP discovery messages, and later used to configure the interface MTU if no MTU was specified by the DHCP server.
set default-interface-mtu = 1500; |
This variable can be set to a netmask value to specify a default subnet mask in case none is provided by the DHCP operation. Unlike the "override" directive this provides a fallback in case no subnet-mask is provided by the server.
set default-subnet-mask = 255.255.255.0; |
This variable can be set to a boolean value to indicate whether or not the client should attempt to send ICMP ECHO requests to routers passed by the DHCP server and determine which is one has the least latency to become the default route. Disabling this variable stops this operation from taking place, and the first router is used as the default route. This is useful if the routers cannot be reached by ICMP ECHO requests.
enable do-measure-router-latency = yes; |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
dhcp-client uses guile (GNU's Ubiquitous Intelligent Language for Extensions) to extend itself. Extensions can currently be written for handling DHCP options. The rest of this section assumes you are familiar with the Scheme programming language. If you are not familiar with the Scheme programming language then you cannot extend the client to configure options is not programmed to handle.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
dhcp-client calls a sysconf script which is placed in the same directory as the configuration file. This script, like the configuration file, can be named either "default.sysconf" or after an interface name.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The default sysconf script which is shipped with dhcp-agent is made up of several lambda expressions which are placed inside closures. If you're not familiar with the concept of closures, refer to the guile documentation.
Under each closure is a configure/unconfigure lambda expression which are bound to top level symbols. These symbols are then placed in two hooks, one for the bound state, and one for the release state.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
We'll walk through the DNS configuration (a very simple example) to see how it was written. After this example a more in-depth discussion follows. If you notice some details are skipped over, don't worry. It will become clear later.
(define configure-dns #f) (define unconfigure-dns #f) |
First we define two top level symbols to false. We'll later bind against these in the closure.
(let ((configured-domain-name #f)
(configured-domain-name-servers #f)
|
We begin the closure by defining two variables which will be used to hold any configured domain name and domain name servers. For DNS configuration these aren't useful, but for other sysconf code keeping the values of configured data is useful when it comes time to unconfigure the system on a DHCP RELEASE.
; check to see if we really need to configure
(do-configure
(lambda()
(and (client-configure? client-control
'dhcp-domain-name-servers)
(client-configure? client-control 'dhcp-domain-name)
(defined? 'dhcp-domain-name-servers)
(defined? 'dhcp-domain-name)))))
|
Here we define a lambda expression which will tell us whether or not we should be performing any configuration for dns. The expression will return true if the options "domain-name-servers" and "domain-name" have been passed to us by the DHCP server. Also it checks if the user has requested that we configure these options.
; configure dns options
(set! configure-dns
(lambda ()
(if (do-configure)
(let ((resolv-conf-file-port (open "/etc/resolv.conf" O_WRONLY 0644)))
(client-info-message "configuring resolver")
(map-in-order
(lambda (dns-server)
(simple-format resolv-conf-file-port "nameserver ~A\n" dns-server)) dhcp-domain-name-servers)
(simple-format resolv-conf-file-port "search ~A\n" dhcp-domain-name)
(close-port resolv-conf-file-port)
; now setup the options so we can use them again in unconfigure.
(set! configured-domain-name dhcp-domain-name)
(set! configured-domain-name-servers dhcp-domain-name-servers)))))
|
The "configure-dns" function will first check if "do-configure" returns true. It will then open "/etc/resolv.conf" and notify the user that the resolver is being configured. It then writes out the contents of the string list "dhcp-domain-name-servers" to the file prefixing each string with the keyword "nameserver." Finally the "search" keyword is written with the domain name.
After the configuration is complete, the values are stored in "configured-domain-name" and "configured-domain-name-servers." This allows us to remember the values in the event of unconfiguring the system.
; unconfigure dns options
(set! unconfigure-dns
(lambda()
; We shouldn't really be doing anything. Any name server
; is a good server :-)
#t)))
|
As mentioned in the comment there's no need to do any unconfiguration. We'd rather have a resolv.conf than delete it. You can always modify this to delete the file, or insert a different set of values.
(add-hook! dhcp-bind-hook configure-dns) (add-hook! dhcp-release-hook unconfigure-dns) |
Finally the two routines are bound to the DHCP BIND and DHCP RELEASE hooks. It is important to add the option handlers in reverse order. You'll notice "configure-interface" is added last so that the interface is configured first.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Two hooks are defined at the top level by the client. "dhcp-bind-hook" and "dhcp-release-hook." When the client wants to configure itself it will call "dhcp-bind-hook" and when it releases its lease it will call "dhcp-release-hook."
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When the DHCP BOUND hook is called, all the options are defined as top level symbols which refer to either a string, or a list of strings depending on whether the option is a single atom, or a list of atoms [ TODO: make list of handled options along with their types. ]
In order to check for the existance of an option, simple use "defined?" to check if the symbol is bound.
; check for the routers option (defined? 'dhcp-routers) |
This will return a boolean value of true of false depending on whether the DHCP option has been bound at the top level.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
At the top level a "client-control" symbol is bound to a control object which is used in every invocation of routines provided by the client.
Returns #t of #f depending on whether or not the user has explicitly stated that the dhcp option should be configured.
Initializes the network interface the client is handling and assigns the requested ip-address, the netmask and mtu.
Sets the default route to the ip-address specified.
Removes the default route to the ip-address specified.
Returns the default mtu specified by the user.
Returns the default subnet-mask specified by the user.
Prints out the string using the client's info_message routine.
Prints out the string using the client's error_message routine.
Prints out the string using the client's fatal_message routine. This exits after passing the message to the user.
Invokes the shutdown routine in the client and causes the client to exit as cleanly as possible, relinquishing any leases it has. Warning! This should not be called from within a release hook.
Accepts a list of addresses address-list and performs ICMP ECHO latency tests to determine which host is responding fastest. A list of address/average-latency pairs is returned.
Returns #t if the user enabled "do-measure-router-latency" or #f if not.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Traditionally the UNIX initialization process is programmed with simple shell scripts. This is fine because all the variables are passed from the local system (usually set by the administrator or vendor).
In the case of DHCP configuration data is passed from a server which ought to be handled as untrustworthy data unless you're willing to use it in a certain way.
For example, assuming you wish to configure your hostname according to the DHCP server, you will receive the hostname as a string and use that string for your hostname. You don't, though, want the hostname passed to be arbitrary shell code which is run inadvertently from your shell script.
Most DHCP clients in the wild have fixed this problem by quoting the DHCP options as they are passed to the shell. I still foresee this as problematic, and a security hazard.
Guile offers the Scheme programming language which is an incredibly small subset of Lisp. It's easy to pick up. The DHCP options are passed to the Scheme system configuration script as strings or lists of strings. These strings are harmless unless you are specifically asking the Scheme interpreter to evaluate them.
On the other hand most casual users just want basic networking up, and the ability to tweak certain options. The DHCP client already offers this to anyone, irregardless of their knowledge of Scheme.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |