networking/udhcp/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 only command line argument to udhcpd is an optional specifed
  12 config file. If no config file is specified, udhcpd uses the default
  13 config file, /etc/udhcpd.conf. Ex:
  14
  15 udhcpd /etc/udhcpd.eth1.conf
  16
  17 The udhcp server employs a number of simple config files:
  18
  19 udhcpd.leases
  20 ------------
  21
  22 The udhcpd.leases behavior is designed for an embedded system. The
  23 file is written either every auto_time seconds, or when a SIGUSR1
  24 is received (the auto_time timer restarts if a SIGUSR1 is received).
  25 If you send a SIGTERM to udhcpd directly after a SIGUSR1, udhcpd will
  26 finish writing the leases file and wait for the aftermentioned script
  27 to be executed and finish before quiting, so you do not need to sleep
  28 between sending signals. When the file is written, a script can be
  29 optionally called to commit the file to flash. Lease times are stored
  30 in the file by time remaining in lease (for systems without clock
  31 that works when there is no power), or by the absolute time that it
  32 expires in seconds from epoch. In the remainig format, expired leases
  33 are stored as zero. The file is of the format:
  34
  35 16 byte MAC
  36 4 byte ip address
  37 u32 expire time
  38 16 byte MAC
  39 4 byte ip address
  40 u32 expire time
  41 .
  42 etc.
  43
  44 example: hexdump udhcpd.leases
  45
  46 0000000 1000 c95a 27d9 0000 0000 0000 0000 0000
  47 0000010 a8c0 150a 0d00 2d29 5000 23fc 8566 0000
  48 0000020 0000 0000 0000 0000 a8c0 140a 0d00 4e29
  49 0000030
  50
  51
  52 udhcpd.conf
  53 ----------
  54
  55 The format is fairly simple, there is a sample file with all the
  56 available options and comments describing them in samples/udhcpd.conf
  57
  58
  59 udhcp client (udhcpc)
  60 --------------------
  61
  62 The udhcp client negotiates a lease with the DHCP server and notifies
  63 a set of scripts when a leases is obtained or lost. The command line
  64 options for the udhcp client are:
  65
  66 -c, --clientid=CLIENTID         Client identifier
  67 -H, --hostname=HOSTNAME         Client hostname
  68 -h,                             Alias for -H
  69 -f, --foreground                Do not fork after getting lease
  70 -b, --background                Fork to background if lease cannot be
  71                                 immediately negotiated.
  72 -i, --interface=INTERFACE       Interface to use (default: eth0)
  73 -n, --now                       Exit with failure if lease cannot be
  74                                 immediately negotiated.
  75 -p, --pidfile=file              Store process ID of daemon in file
  76 -q, --quit                      Quit after obtaining lease
  77 -r, --request=IP                IP address to request (default: none)
  78 -s, --script=file               Run file at dhcp events (default:
  79                                 /usr/share/udhcpc/default.script)
  80 -v, --version                   Display version
  81
  82 If the requested IP address cannot be obtained, the client accepts the
  83 address that the server offers.
  84
  85 When an event occurs, udhcpc calls the action script. The script by
  86 default is /usr/share/udhcpc/default.script but this can be changed via
  87 the command line arguments. The three possible arguments to the script
  88 are:
  89
  90         deconfig: This argument is used when udhcpc starts, and
  91         when a leases is lost. The script should put the interface in an
  92         up, but deconfigured state, ie: ifconfig $interface 0.0.0.0.
  93
  94         bound: This argument is used when udhcpc moves from an
  95         unbound, to a bound state. All of the paramaters are set in
  96         enviromental variables, The script should configure the interface,
  97         and set any other relavent parameters (default gateway, dns server,
  98         etc).
  99
 100         renew: This argument is used when a DHCP lease is renewed. All of
 101         the paramaters are set in enviromental variables. This argument is
 102         used when the interface is already configured, so the IP address,
 103         will not change, however, the other DHCP paramaters, such as the
 104         default gateway, subnet mask, and dns server may change.
 105
 106         nak: This argument is used with udhcpc receives a NAK message.
 107         The script with the deconfig argument will be called directly
 108         afterwards, so no changes to the network interface are neccessary.
 109         This hook is provided for purely informational purposes (the
 110         message option may contain a reason for the NAK).
 111
 112 The paramaters for enviromental variables are as follows:
 113
 114         $HOME           - The set $HOME env or "/"
 115         $PATH           - the set $PATH env or "/bin:/usr/bin:/sbin:/usr/sbin"
 116         $1              - What action the script should perform
 117         interface       - The interface this was obtained on
 118         ip              - The obtained IP
 119         siaddr          - The bootp next server option
 120         sname           - The bootp server name option
 121         boot_file       - The bootp boot file option
 122         subnet          - The assigend subnet mask
 123         timezone        - Offset in seconds from UTC
 124         router          - A list of routers
 125         timesvr         - A list of time servers
 126         namesvr         - A list of IEN 116 name servers
 127         dns             - A list of DNS server
 128         logsvr          - A list of MIT-LCS UDP log servers
 129         cookiesvr       - A list of RFC 865 cookie servers
 130         lprsvr          - A list of LPR servers
 131         hostname        - The assigned hostname
 132         bootsize        - The length in 512 octect blocks of the bootfile
 133         domain          - The domain name of the network
 134         swapsvr         - The IP address of the client's swap server
 135         rootpath        - The path name of the client's root disk
 136         ipttl           - The TTL to use for this network
 137         mtu             - The MTU to use for this network
 138         broadcast       - The broadcast address for this network
 139         ntpsrv          - A list of NTP servers
 140         wins            - A list of WINS servers
 141         lease           - The lease time, in seconds
 142         dhcptype        - DHCP message type (safely ignored)
 143         serverid        - The IP of the server
 144         message         - Reason for a DHCPNAK
 145         tftp            - The TFTP server name
 146         bootfile        - The bootfile name
 147
 148 additional options are easily added in options.c.
 149
 150 udhcpc also responds to SIGUSR1 and SIGUSR2. SIGUSR1 will force a renew state,
 151 and SIGUSR2 will force a release of the current lease, and cause udhcpc to
 152 go into an inactive state (until it is killed, or receives a SIGUSR1). You do
 153 not need to sleep between sending signals, as signals received are processed
 154 sequencially in the order they are received.
 155
 156
 157
 158 compile time options
 159 -------------------
 160
 161 The Makefile contains three of the compile time options:
 162
 163         DEBUG: If DEBUG is defined, udhcpd will output extra debugging
 164         output, compile with -g, and not fork to the background when run.
 165         SYSLOG: If SYSLOG is defined, udhcpd will log all its messages
 166         syslog, otherwise, it will attempt to log them to stdout.
 167
 168         COMBINED_BINARY: If COMBINED_BINARY is define, one binary, udhcpd,
 169         is created. If called as udhcpd, the dhcp server will be started.
 170         If called as udhcpc, the dhcp client will be started.
 171
 172 dhcpd.h contains the other two compile time options:
 173
 174         LEASE_TIME: The default lease time if not specified in the config
 175         file.
 176
 177         DHCPD_CONFIG_FILE: The defualt config file to use.
 178
 179 options.c contains a set of dhcp options for the client:
 180
 181         name[10]: The name of the option as it will appear in scripts
 182
 183         flags: The type of option, as well as if it will be requested
 184         by the client (OPTION_REQ)
 185
 186         code: The DHCP code for this option
 187
 188 busybox drop-in
 189 --------------
 190 udhcp is now a drop-in component for busybox (http://busybox.net).
 191 To update busybox to the latest revision, simply do a:
 192
 193 cp *.[ch] README AUTHORS COPYING ChangeLog TODO \
 194         <busybox_source>/networking/udhcp
 195
 196 The only two files udhcp does not provide are config.in and
 197 Makefile.in, so these may need to be updated from time to time.