dhcp-client.texi

this is sample about DHCP-agent

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.

@example
set hostname = "foo.example.com";
@end example


@end defvr

@defvr {Client Configuration Variable} dhcp-discovery-retries 

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.

@example
set dhcp-discovery-retries = 3;
@end example

@end defvr

@defvr {Client Configuration Variable} icmp-retries 

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.

@example
set icmp-retries = 3;
@end example

@end defvr

@defvr {Client Configuration Variable} default-interface-mtu

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.

@example
set default-interface-mtu = 1500;
@end example

@end defvr

@defvr {Client Configuration Variable} default-subnet-mask

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.

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

@end defvr

@defvr {Client Configuration Variable} do-measure-router-latency

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.

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

@end defvr

@section Writing Client Extensions

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.

@subsection The Sysconf Script

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.

@subsection Looking At The Sysconf Script

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.

@subsection The DNS Configuration: An Example

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.

@example
(define configure-dns #f)
(define unconfigure-dns #f)
@end example

First we define two top level symbols to false. We'll later bind
against these in the closure.

@example
(let ((configured-domain-name #f)
       (configured-domain-name-servers #f)
@end example

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.

@example
      ; 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)))))
@end example

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.

@example
  ; 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)))))

@end example

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.

@example
                                        ; unconfigure dns options
  (set! unconfigure-dns
        (lambda()

         ; We shouldn't really be doing anything. Any name server
         ; is a good server :-)

          #t)))
@end example

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.

@example

(add-hook! dhcp-bind-hook configure-dns)
(add-hook! dhcp-release-hook unconfigure-dns)

@end example

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.

@subsection The DHCP BOUND and DHCP RELEASE hooks

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

@subsection How DHCP Options Are Passed To The Sysconf Script

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.

@example

; check for the routers option

(defined? 'dhcp-routers)

@end example

This will return a boolean value of true of false depending on whether
the DHCP option has been bound at the top level.

@subsection Scheme Routines Provided By The Client

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.

@deffn {Client Sysconf Routine} client-configure? client-control option-symbol

Returns #t of #f depending on whether or not the user has explicitly
stated that the dhcp option should be configured.

@end deffn

@deffn {Client Sysconf Routine} client-interface-up client-control ip-address netmask mtu

Initializes the network interface the client is handling and assigns
the requested @var{ip-address}, the @var{netmask} and @var{mtu}.

@end deffn

@deffn {Client Sysconf Routine} client-set-default-route client-control ip-address

Sets the default route to the @var{ip-address} specified.

@end deffn

@deffn {Client Sysconf Routine} client-remove-default-route client-control ip-address

Removes the default route to the @var{ip-address} specified.

@end deffn

@deffn {Client Sysconf Routine} client-get-default-mtu client-control

Returns the default mtu specified by the user.

@end deffn

@deffn {Client Sysconf Routine} client-get-default-subnet-mask client-control

Returns the default subnet-mask specified by the user.

@end deffn

@deffn {Client Sysconf Routine} client-info-message  string

Prints out the string using the client's @dfn{info_message} routine.

@end deffn

@deffn {Client Sysconf Routine} client-error-message string

Prints out the string using the client's @dfn{error_message} routine.

@end deffn

@deffn {Client Sysconf Routine} client-fatal-message string

Prints out the string using the client's @dfn{fatal_message}
routine. This exits after passing the message to the user.

@end deffn

@deffn {Client Sysconf Routine} client-shutdown client-control

Invokes the @dfn{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.

@end deffn

@deffn {Client Sysconf Routine} client-discover-icmp-latency client-control address-list

Accepts a list of addresses @var{address-list} and performs ICMP ECHO
latency tests to determine which host is responding fastest. A list of
address/average-latency pairs is returned.

@end deffn

@deffn {Client Sysconf Routine} client-do-discover-icmp-latency client-control

Returns #t if the user enabled ``do-measure-router-latency'' or #f if
not.

@end deffn

@subsection Why Not Just Use A Shell Script?

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.

@section Advanced Client Use

[ TODO ]