userapps/opensource/udhcp.paul/readme

   1 udhcp server/client package readme
   2 -------------------------
   3
   4 The udhcp server/client package is primarily geared towards embedded
   5 systems. It does however, strive to be fully functional, and RFC
   6 compliant.
   7
   8 udhcp server (udhcpd)
   9 --------------------
  10
  11 The udhcp server employs a number of simple config files:
  12
  13 udhcpd.leased
  14 ------------
  15
  16 The udhcpd.leases behavior is designed for an embedded system. The
  17 file is written either every auto_time seconds, or when a SIGUSR1
  18 is received. When the file is written, a script can be optionally
  19 called to commit the file to flash. Lease times are stored in the
  20 file by time remaining in lease (for systems without clock that works
  21 when there is no power), or by the absolute time that it expires in
  22 seconds from epoch. In the remainig format, expired leases are stored
  23 as zero. The file is of the format:
  24
  25 16 byte MAC
  26 4 byte ip address
  27 u32 expire time
  28 16 byte MAC
  29 4 byte ip address
  30 u32 expire time
  31 .
  32 etc.
  33
  34 example: hexdump udhcpd.leases
  35
  36 0000000 1000 c95a 27d9 0000 0000 0000 0000 0000
  37 0000010 a8c0 150a 0d00 2d29 5000 23fc 8566 0000
  38 0000020 0000 0000 0000 0000 a8c0 140a 0d00 4e29
  39 0000030
  40
  41
  42 udhcpd.conf
  43 ----------
  44
  45 The format is fairly simple, there is a sample file with all the
  46 available options and comments describing them in samples/udhcpd.conf
  47
  48
  49 udhcp client (udhcpc)
  50 --------------------
  51
  52 The udhcp client negotiates a lease with the DHCP server and notifies
  53 a set of scripts when a leases is obtained or lost. The command line
  54 options for the udhcp client are:
  55
  56 -c, --clientid=CLIENTID         Client identifier
  57 -H, --hostname=HOSTNAME         Client hostname
  58 -f, --foreground                Do not fork after getting lease
  59 -i, --interface=INTERFACE       Interface to use (default: eth0)
  60 -n, --now                       Exit with failure if lease cannot be
  61                                 immediately negotiated.
  62 -p, --pidfile=file              Store process ID of daemon in file
  63 -q, --quit                      Quit after obtaining lease
  64 -r, --request=IP                IP address to request (default: none)
  65 -s, --script=file               Run file at dhcp events (default:
  66                                 /usr/share/udhcpc/default.script)
  67 -v, --version                   Display version
  68
  69 If the requested IP address cannot be obtained, the client accepts the
  70 address that the server offers.
  71
  72 When an event occurs, udhcpc calls the action script. The script by
  73 default is /usr/share/udhcpc/default.script but this can be changed via
  74 the command line arguments. The three possible arguments to the script
  75 are:
  76
  77         deconfig: This argument is used when udhcpc starts, and
  78         when a leases is lost. The script should put the interface in an
  79         up, but deconfigured state, ie: ifconfig $interface 0.0.0.0.
  80
  81         bound: This argument is used when udhcpc moves from an
  82         unbound, to a bound state. All of the paramaters are set in
  83         enviromental variables, The script should configure the interface,
  84         and set any other relavent parameters (default gateway, dns server,
  85         etc).
  86
  87         renew: This argument is used when a DHCP lease is renewed. All of
  88         the paramaters are set in enviromental variables. This argument is
  89         used when the interface is already configured, so the IP address,
  90         will not change, however, the other DHCP paramaters, such as the
  91         default gateway, subnet mask, and dns server may change.
  92
  93 The paramaters for enviromental variables are as follows:
  94
  95         $HOME           - The set $HOME env or "/"
  96         $PATH           - the set $PATH env or "/bin:/usr/bin:/sbin:/usr/sbin"
  97         $1              - What action the script should perform
  98         interface       - The interface this was obtained on
  99         ip              - The obtained IP
 100         siaddr          - The bootp next server option
 101         sname           - The bootp server name option
 102         boot_file       - The bootp boot file option
 103         subnet          - The assigend subnet mask
 104         timezone        - Offset in seconds from UTC
 105         router          - A list of routers
 106         timesvr         - A list of time servers
 107         namesvr         - A list of IEN 116 name servers
 108         dns             - A list of DNS server
 109         logsvr          - A list of MIT-LCS UDP log servers
 110         cookiesvr       - A list of RFC 865 cookie servers
 111         lprsvr          - A list of LPR servers
 112         hostname        - The assigned hostname
 113         bootsize        - The length in 512 octect blocks of the bootfile
 114         domain          - The domain name of the network
 115         swapsvr         - The IP address of the client's swap server
 116         rootpath        - The path name of the client's root disk
 117         ipttl           - The TTL to use for this network
 118         mtu             - The MTU to use for this network
 119         broadcast       - The broadcast address for this network
 120         ntpsrv          - A list of NTP servers
 121         wins            - A list of WINS servers
 122         lease           - The lease time, in seconds
 123         dhcptype        - DHCP message type (safely ignored)
 124         serverid        - The IP of the server
 125         tftp            - The TFTP server name
 126         bootfile        - The bootfile name
 127
 128 additional options are easily added in options.c.
 129
 130 udhcpc also responds to SIGUSR1 and SIGUSR2. SIGUSR1 will force a renew state,
 131 and SIGUSR2 will force a release of the current lease, and cause udhcpc to
 132 go into an inactive state (until it is killed, or receives a SIGUSR1).
 133
 134
 135
 136 compile time options
 137 -------------------
 138
 139 The Makefile contains three of the compile time options:
 140
 141         DEBUG: If DEBUG is defined, udhcpd will output extra debugging
 142         output, compile with -g, and not fork to the background when run.
 143         SYSLOG: If SYSLOG is defined, udhcpd will log all its messages
 144         syslog, otherwise, it will attempt to log them to stdout.
 145
 146         COMBINED_BINARY: If COMBINED_BINARY is define, one binary, udhcpd,
 147         is created. If called as udhcpd, the dhcp server will be started.
 148         If called as udhcpc, the dhcp client will be started.
 149
 150 dhcpd.h contains the other two compile time options:
 151
 152         LEASE_TIME: The default lease time if not specified in the config
 153         file.
 154
 155         DHCPD_CONFIG_FILE: What config file to use.
 156
 157
 158