[dhcp-agent-commits] dhcp-agent/doc dhcp-agent.texi,NONE,1.1 dhcp-client.texi,NONE,1.1 dhcp-relay.texi,NONE,1.1 dhcp-server.texi,NONE,1.1 dhcp-sniff.texi,NONE,1.1 introduction.texi,NONE,1.1

[<act...@us...>]

Update of /cvsroot/dhcp-agent/dhcp-agent/doc
In directory sc8-pr-cvs1:/tmp/cvs-serv19694

Added Files:
	dhcp-agent.texi dhcp-client.texi dhcp-relay.texi 
	dhcp-server.texi dhcp-sniff.texi introduction.texi 
Log Message:
renamed to texi

--- NEW FILE: dhcp-agent.texi ---
\input texinfo  @c -*-texinfo-*-

@c %** start of header
@setfilename dhcp-agent.info
@settitle dhcp-agent
@c %** end of header

@copying
Copyright 2003 Thamer Alharbash <tm...@wh...>
 
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
 
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in
   the documentation and/or other materials provided with the
   distribution.
3. The names of the authors may not be used to endorse or promote
   products derived from this software without specific prior
   written permission.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
@end copying

@titlepage
@title dhcp-agent
@page
@vskip 0pt plus 1filll
@end titlepage

@ifnottex
@node Top
@top dhcp-agent
@end ifnottex

@c **************** Menu list *******************
@c ** add new menu items here.
@menu
* Introduction::
* dhcp-client::
* dhcp-server::
* dhcp-sniff::
* dhcp-relay::
@end menu

@contents

@include introduction.txi
@include dhcp-client.txi
@include dhcp-server.txi
@include dhcp-sniff.txi
@include dhcp-relay.txi

@bye

--- NEW FILE: dhcp-client.texi ---
@c ***************** list ***********************
@node dhcp-client
@chapter dhcp-client
@cindex 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.

@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

[ TODO ]

@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/xl0.conf}

If this file does not exist then the default configuration file is
@file{/usr/local/etc/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 ';' character. 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. If you want newlines to be evaluated
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

@itemize bullet

@item 
request : The ``request'' 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

@item
require : the ``require'' 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.

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

@item
configure : the ``configure'' 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 [TODO write up extending the client
with guile].

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

@item

append : the ``append'' 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

@item

prepend : the ``prepend'' 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

@item

override : the ``override'' 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 itemize

@subheading Variable Settings

@itemize

@item
set : the ``set'' directive instructs the client to set a variable to
a defined value.

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

@item

enable: the ``enable'' 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 itemize

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

@itemize

@item

hostname : the ``hostname'' 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.

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

@item
dhcp-discovery-retries: the ``dhcp-discovery-retries'' 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

@item
icmp-retries: the ``icmp-retries'' 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

@item
default-interface-mtu: the ``default-interface-mtu'' 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

@item
default-subnet-mask: the ``default-subnet-mask'' 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

@item
do-measure-router-latency: the ``do-measure-router-latency'' 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 itemize

@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 it cannot handle.

[ TODO ]


--- NEW FILE: dhcp-relay.texi ---
@c ***************** list ***********************
@node dhcp-relay
@chapter dhcp-relay
@cindex dhcp-relay

[ TODO ]




--- NEW FILE: dhcp-server.texi ---
@c ***************** list ***********************
@node dhcp-server
@chapter dhcp-server
@cindex dhcp-server

[ TODO ]




--- NEW FILE: dhcp-sniff.texi ---
@c ***************** list ***********************
@node dhcp-sniff
@chapter dhcp-sniff
@cindex dhcp-sniff

@section Quickstart



--- NEW FILE: introduction.texi ---
@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 Linux

[ TODO ]

@subsection FreeBSD

[ TODO ]

@subsection Solaris

[ TODO ]