[dhcp-agent-commits] dhcp-agent/doc Makefile.am,1.2,1.3 dhcp-client.texi,1.2,1.3 introduction.texi,1.1,1.2

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

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

Modified Files:
	Makefile.am dhcp-client.texi introduction.texi 
Log Message:
updated documentation

Index: Makefile.am
===================================================================
RCS file: /cvsroot/dhcp-agent/dhcp-agent/doc/Makefile.am,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** Makefile.am	20 May 2003 00:32:30 -0000	1.2
--- Makefile.am	27 Jun 2003 16:46:46 -0000	1.3
***************
*** 14,18 ****
  
  index.html: dhcp-agent.texi $(dhcp_agent_TEXINFOS)
! 	texi2html -toc_file index.html -split chapter dhcp-agent.texi
  
  endif
--- 14,20 ----
  
  index.html: dhcp-agent.texi $(dhcp_agent_TEXINFOS)
! 	texi2html -split chapter -top_file index.html dhcp-agent.texi
  
  endif
+ 
+ CLEANFILES=*.html

Index: dhcp-client.texi
===================================================================
RCS file: /cvsroot/dhcp-agent/dhcp-agent/doc/dhcp-client.texi,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** dhcp-client.texi	27 Jun 2003 04:05:40 -0000	1.2
--- dhcp-client.texi	27 Jun 2003 16:46:46 -0000	1.3
***************
*** 93,100 ****
  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
--- 93,100 ----
  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
***************
*** 107,112 ****
  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
--- 107,112 ----
  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
***************
*** 165,169 ****
  
  @deffn {Client Configuration Directive} request
! 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:
--- 165,170 ----
  
  @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:
***************
*** 179,183 ****
  @deffn {Client Configuration Directive} 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
--- 180,184 ----
  @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
***************
*** 193,197 ****
  @deffn {Client Configuration Directive} 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
--- 194,198 ----
  @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
***************
*** 208,214 ****
  
  
! @deffn {Client Configuration Directive} configure
  
! 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
--- 209,215 ----
  
  
! @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
***************
*** 225,229 ****
  @deffn {Client Configuration Directive} 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
--- 226,230 ----
  @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
***************
*** 238,242 ****
  @deffn {Client Configuration Directive} override
  
! 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
--- 239,243 ----
  @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
***************
*** 254,258 ****
  @deffn {Client Configuration Directive} set
  
! set : the ``set'' directive instructs the client to set a variable to
  a defined value.
  
--- 255,259 ----
  @deffn {Client Configuration Directive} set
  
! This directive instructs the client to set a variable to
  a defined value.
  
***************
*** 265,269 ****
  @deffn {Client Configuration Directive} enable
  
! 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.
--- 266,270 ----
  @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.
***************
*** 282,286 ****
  @defvr {Client Configuration Variable} 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
--- 283,287 ----
  @defvr {Client Configuration Variable} hostname
  
! 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
***************
*** 299,303 ****
  @defvr {Client Configuration Variable} 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.
--- 300,304 ----
  @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.
***************
*** 311,315 ****
  @defvr {Client Configuration Variable} 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,
--- 312,316 ----
  @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,
***************
*** 324,328 ****
  @defvr {Client Configuration Variable} 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
--- 325,329 ----
  @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
***************
*** 338,342 ****
  @defvr {Client Configuration Variable} 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
--- 339,343 ----
  @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
***************
*** 351,355 ****
  @defvr {Client Configuration Variable} 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
--- 352,356 ----
  @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
***************
*** 372,376 ****
  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 ]
--- 373,638 ----
  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 an @var{address-list} and performs ICMP ECHO latency tests to
! determine which host is responding fastest. A list is returned with
! the quickest responders first.
! 
! @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 ]

Index: introduction.texi
===================================================================
RCS file: /cvsroot/dhcp-agent/dhcp-agent/doc/introduction.texi,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** introduction.texi	18 May 2003 03:18:10 -0000	1.1
--- introduction.texi	27 Jun 2003 16:46:46 -0000	1.2
***************
*** 94,104 ****
  @subsection Linux
  
! [ TODO ]
  
  @subsection FreeBSD
  
! [ TODO ]
  
  @subsection Solaris
  
! [ TODO ]
--- 94,130 ----
  @subsection 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 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 Solaris
  
! No major issues so far. Building the package may become
! ``interesting'' if you have not setup your build environment properly.
! 
! @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.
! 
! 
! 
! 
! 
!