introduction.texi

this is sample about DHCP-agent

@c ***************** list ***********************
@node Introduction
@chapter Introduction
@cindex Introduction

dhcp-agent is a suite, or a set of tools, that allow a UNIX host to
make use of the Dynamic Host Configuration protocol.

Currently the suite is packaged with the following tools:

@itemize @bullet

@item 
dhcp-client : A highly configurable and extendable DHCP client.

@item
dhcp-sniff  : A command line DHCP sniffer.

@end itemize

In good time the suite will also be packaged with:

@itemize @bullet

@item
dhcp-server : A configurable and extendable DHCP server.

@item
dhcp-relay : A DHCP relay agent.

@end itemize

@section Building and Installing

You can download a copy of dhcp-agent from:

@url{http://dhcp-agent.sourceforge.net/}

You will also need libdnet, libpcap, and guile from the following
locations:

@itemize bullet

@item
libdnet version 1.7 or higher: @url{http://libdnet.sourceforge.net/}

@item
libpcap version 0.6.2 or higher: @url{http://www.tcpdump.org/}

@item
guile version 1.6.4 or higher: @url{http://www.gnu.org/software/guile/guile.html}

@end itemize

Once these dependencies are installed use the @command{configure}
script to configure the build of dhcp-agent. Then @command{make} and
@command{make install} to install it on your system.

The @command{configure} script accepts a number of flags and
environment variables. You should use @command{configure --help} to
list these.

@section Default Settings

The @command{configure} script will allow you to set some default
paths including where dhcp-agent keeps its configuration and data
files.

These are the more prominent options:

@itemize

@item
--prefix : the ``prefix'' is where all the directories are
created. If you wish to install dhcp-agent in @file{/opt/dhcp-agent}
then you will need to specify that directory prefix. By default
dhcp-agent will use @file{/usr/local} as its prefix.

@item
--bindir: the directory where binaries are installed

@item
--sysconfdir: the directory where the configuration files are
installed

@item
--localstatedir: the directory where data files are stored. lease
information is kept here.

@end itemize

@section System Specific Notes

@subsection GNU/Linux

The client under Linux may not be entirely happy when applied to an
aliased interface. You will see some error messages, however things
should proceed OK.

@subsection Solaris

No major issues so far. Building the package may become
``interesting'' if you have not setup your build environment properly.

@subsection FreeBSD

Under FreeBSD the client will make use of two bpf devices. This is
because of a limitation in dnet. If you run out of bpf devices you may
need to compile a kernel with more bpf devices.

@subsection NetBSD

NetBSD ships with a pcap which does not come with @dfn{pcap_freecode}
this results in a small mem leak when the client reinitializes its raw
network code. To avoid this upgrade to the latest version of pcap and
nuke your old pcap library.

@subsection OpenBSD

OpenBSD has some brain damage with its bpf structure. Unlike the other
BSD flavors it insists on using unsigned instead of signed integers
for the number of seconds in its timestamp. This results in some
inaccuracy when calculating timeouts. Lobby your OpenBSD developers to
stop the brain damage.

@section Overview of DHCP

DHCP (Dynamic Host Configuration Protocol) is a protocol designed to
assign host configuration parameters from a DHCP server to a DHCP
client. The parameters are passed as a lease to the client.  The term
lease is used because the parameters usually have a finite
lifetime. This allows the network administrator to update the
configuration parameters, and later propogate the configuration
changes to the client hosts.

DHCP is a convenient method of maintaining configuration across
multiple machines from a central configuration repository.

@subsection Lease Acquisition

The client begins by broadcasting a DHCP DISCOVER message, which
solicits DHCP leases from servers. 

DHCP OFFER messages are sent from DHCP servers to the client. 

The client picks one of the lease offers and responds with a DHCP
REQUEST. The server responds with a DHCP ACK to acknowledge, or
DHCP NACK to refuse assigning the lease.

Once the client receives the acknowledgement it checks to see if the
IP address is currently active. If no address collision is detected,
the client performs its configuration based on the address passed from
the server and additional options provided in the lease.

If address collision is detected, the client transmits a DHCP DECLINE
message informing the server that the lease is no good.

@subsection Lease Renewal

Each lease comes with three timers, a rebind, renew, and an expiry
timer. If no rebind or renew time is specified the client can create
default rebind and renew timers from the expiry time.

When these timers are reached the client attempts to renew the lease
by transmitting a DHCP REQUEST and awaiting an acknowledgement. If the
timer expires and the lease is not renewed, the client undoes the
system configuration and revers to its lease acquisition stage.

@subsection Lease Release

When the client is shut down it sends a DHCP RELEASE message to the
server notifying it that the lease is no longer in use. The client,
also, unconfigures the host system its running on.

@section Other Information Worth Noting.

@subsection  On Timeout Thresholds And Retries

The dhcp-agent suite never allows the user to specify exact timeout
and retries for any of its operations. This is intentional. Instead,
the user can specify an upper timeout period called a threshold and a
retry counter which is decremented per amount of times the threshold
is reached.

For example, in the client configuration you can specify the
@var{arp-retries} and @var{arp-timeout-threshold}. If you set the
retries to two, and the threshold to fifteen the client, when
performing an ARP operation will begin by transmitting the first
datagram, and then wait up to four seconds (default hard coded
setting: see dhcp-libutil.h). Then if this timeout is reached it will
double the timeout, add a small random amount to it, and try
again. When the timeout has reached fifteen seconds, it will consider
the operation to have timed out completely, and decrement its retry
counter. Then it starts again.

A setting of one for retries, and ten for a timeout threshold will not
cause the client to just try once, but keep trying for up to ten
seconds using the back-off algorithm mentioned above. This algorithm
is mentioned in RFC2131 and implemented for compliance. It also makes
good sense for ethernet networks that have high collisions or are
congested enough to have heavy packet loss.