dhcp-client.texi

this is sample about DHCP-agent

@c ***************** list ***********************
@node dhcp-client
@chapter dhcp-client

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.

@section Quickstart

These instructions are for a quick no-hassle basic DHCP client
setup. You don't really need to do much except know the following:

@itemize bullet

@item 

That a DHCP server is waiting and responding to any queries
originating from your machine.

@item 

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.

@item

You want to setup your IP address (netmask and broadcast included),
default route, and domain name system and nothing else.

@item

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.

@item

Your PATH environment variable points to the dhcp-client binary.

@end itemize

As the root user run the following command:

@command{dhcp-client -i} @var{<interface>}

Where you substitute @var{<interface>} with the name of your
interface. Alternatively if the interface is down you can omit the
@option{-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 ].

@section Client Configuration

dhcp-client accepts a number of configuration directives. Some of
these can be passed by the command line, and others through a
configuration file.

@subsection Command Line Options

@itemize

@item
-h     Print out usage.


@item
-v     Print out version information


@item
-a     

Always run in the foreground and do not go into the background.



@item
-c     

Clear the cache. This is useful in case a stale cache is left behind
by an earlier invocation.

@item

-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.

@item
-p     

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.

@item
-w     

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.

@item
-s

Print out status information on the most recent lease acquired by
the client.

@item
-i @dfn{interface}
              
Force dhcp-client to use the interface specified.  This is useful to
make sure dhcp-client uses a specific interface if the host is
multi-homed.

@item
-l @dfn{level}

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.

@item
-m @dfn{mac address}
             
Fake a mac address during the DHCP operation. This will only affect
the DHCP operations and no others.  This is useful for debugging a
DHCP server that is not behaving itself.

@end itemize

@subsection The Configuration File

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
@file{/usr/local/etc} You can change this definition at build time by
specifying a different prefix to the @command{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
@file{/usr/local/etc/dhcp-agent/dhcp-client/xl0.conf}

If this file does not exist then the default configuration file is
@file{/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.

@subsection Layout of Configuration File.

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.

@example
foobar = yada,
blah;
@end example

And:

@example
foobar = yada, blah;
@end example

Are the same.

The parser also recognizes strings in two different formats. Quoted
and unquoted.

@example
"foobar"
@end example

Is parsed exactly the same as

@example
foobar
@end example

However:

@example
foo bar
@end example

Will parse as two different strings, so you should use:

@example
"foo bar"
@end example

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.

@subsection Configuration Directives

@subheading DHCP Option Handling

The following directives affect DHCP option handling by the client


@deffn {Client Configuration Directive} request

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:


@example
request subnet-mask, ip-address-lease-time, renewal-time,
        rebinding-time, interface-mtu, domain-name, domain-name-servers;
@end example

@end deffn

@deffn {Client Configuration Directive} require

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.

@example
require subnet-mask, ip-address-lease-time, renewal-time,
        rebinding-time, interface-mtu;
@end example

@end deffn

@deffn {Client Configuration Directive} configure

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.

@example
configure subnet-mask, ip-address-lease-time, renewal-time,
          rebinding-time, interface-mtu, domain-name, domain-name-servers;
@end example

@end deffn


@deffn {Client Configuration Directive} append

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.

@example
append domain-name-servers = 127.0.0.1, 192.168.0.1;
@end example

@end deffn

@deffn {Client Configuration Directive} prepend

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.

@example
prepend domain-name-servers = 127.0.0.1, 192.168.0.1;
@end example

@end deffn

@deffn {Client Configuration Directive} override

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.

@example
override domain-name = "example.com";
@end example

@end deffn

@subheading Variable Settings

@deffn {Client Configuration Directive} set

This directive instructs the client to set a variable to
a defined value.

@example
set default-subnet-mask = 255.255.255.0;
@end example

@end deffn

@deffn {Client Configuration Directive} enable

This directive instructs the client to set a boolean
variable to a defined value. The boolean variable only accepts ``yes'' or
``no'' for values.

@example
enable do-measure-router-latency = no;
@end example

@end deffn

@subheading Configurable Variables

dhcp-client accepts a number of variables to configure default values,
values passed to the server, and control some of its behaviour.

@defvr {Client Configuration Variable} hostname

This variable can be set to a string which is passed as