| udhcp server/client package readme |
| ------------------------- |
| |
| The udhcp server/client package is primarily geared towards embedded |
| systems. It does however, strive to be fully functional, and RFC |
| compliant. |
| |
| udhcp server (udhcpd) |
| -------------------- |
| |
| The only command line argument to udhcpd is an optional specifed |
| config file. If no config file is specified, udhcpd uses the default |
| config file, /etc/udhcpd.conf. Ex: |
| |
| udhcpd /etc/udhcpd.eth1.conf |
| |
| The udhcp server employs a number of simple config files: |
| |
| udhcpd.leases |
| ------------ |
| |
| The udhcpd.leases behavior is designed for an embedded system. The |
| file is written either every auto_time seconds, or when a SIGUSR1 |
| is received (the auto_time timer restarts if a SIGUSR1 is received). |
| If you send a SIGTERM to udhcpd directly after a SIGUSR1, udhcpd will |
| finish writing the leases file and wait for the aftermentioned script |
| to be executed and finish before quiting, so you do not need to sleep |
| between sending signals. When the file is written, a script can be |
| optionally called to commit the file to flash. Lease times are stored |
| in the file by time remaining in lease (for systems without clock |
| that works when there is no power), or by the absolute time that it |
| expires in seconds from epoch. In the remainig format, expired leases |
| are stored as zero. The file is of the format: |
| |
| 16 byte MAC |
| 4 byte ip address |
| u32 expire time |
| 16 byte MAC |
| 4 byte ip address |
| u32 expire time |
| . |
| etc. |
| |
| example: hexdump udhcpd.leases |
| |
| 0000000 1000 c95a 27d9 0000 0000 0000 0000 0000 |
| 0000010 a8c0 150a 0d00 2d29 5000 23fc 8566 0000 |
| 0000020 0000 0000 0000 0000 a8c0 140a 0d00 4e29 |
| 0000030 |
| |
| |
| udhcpd.conf |
| ---------- |
| |
| The format is fairly simple, there is a sample file with all the |
| available options and comments describing them in samples/udhcpd.conf |
| |
| |
| udhcp client (udhcpc) |
| -------------------- |
| |
| The udhcp client negotiates a lease with the DHCP server and notifies |
| a set of scripts when a leases is obtained or lost. The command line |
| options for the udhcp client are: |
| |
| -c, --clientid=CLIENTID Client identifier |
| -H, --hostname=HOSTNAME Client hostname |
| -h, Alias for -H |
| -f, --foreground Do not fork after getting lease |
| -b, --background Fork to background if lease cannot be |
| immediately negotiated. |
| -i, --interface=INTERFACE Interface to use (default: eth0) |
| -n, --now Exit with failure if lease cannot be |
| immediately negotiated. |
| -p, --pidfile=file Store process ID of daemon in file |
| -q, --quit Quit after obtaining lease |
| -r, --request=IP IP address to request (default: none) |
| -s, --script=file Run file at dhcp events (default: |
| /usr/share/udhcpc/default.script) |
| -v, --version Display version |
| |
| If the requested IP address cannot be obtained, the client accepts the |
| address that the server offers. |
| |
| When an event occurs, udhcpc calls the action script. The script by |
| default is /usr/share/udhcpc/default.script but this can be changed via |
| the command line arguments. The three possible arguments to the script |
| are: |
| |
| deconfig: This argument is used when udhcpc starts, and |
| when a leases is lost. The script should put the interface in an |
| up, but deconfigured state, ie: ifconfig $interface 0.0.0.0. |
| |
| bound: This argument is used when udhcpc moves from an |
| unbound, to a bound state. All of the paramaters are set in |
| enviromental variables, The script should configure the interface, |
| and set any other relavent parameters (default gateway, dns server, |
| etc). |
| |
| renew: This argument is used when a DHCP lease is renewed. All of |
| the paramaters are set in enviromental variables. This argument is |
| used when the interface is already configured, so the IP address, |
| will not change, however, the other DHCP paramaters, such as the |
| default gateway, subnet mask, and dns server may change. |
| |
| nak: This argument is used with udhcpc receives a NAK message. |
| The script with the deconfig argument will be called directly |
| afterwards, so no changes to the network interface are neccessary. |
| This hook is provided for purely informational purposes (the |
| message option may contain a reason for the NAK). |
| |
| The paramaters for enviromental variables are as follows: |
| |
| $HOME - The set $HOME env or "/" |
| $PATH - the set $PATH env or "/bin:/usr/bin:/sbin:/usr/sbin" |
| $1 - What action the script should perform |
| interface - The interface this was obtained on |
| ip - The obtained IP |
| siaddr - The bootp next server option |
| sname - The bootp server name option |
| boot_file - The bootp boot file option |
| subnet - The assigend subnet mask |
| timezone - Offset in seconds from UTC |
| router - A list of routers |
| timesvr - A list of time servers |
| namesvr - A list of IEN 116 name servers |
| dns - A list of DNS server |
| logsvr - A list of MIT-LCS UDP log servers |
| cookiesvr - A list of RFC 865 cookie servers |
| lprsvr - A list of LPR servers |
| hostname - The assigned hostname |
| bootsize - The length in 512 octect blocks of the bootfile |
| domain - The domain name of the network |
| swapsvr - The IP address of the client's swap server |
| rootpath - The path name of the client's root disk |
| ipttl - The TTL to use for this network |
| mtu - The MTU to use for this network |
| broadcast - The broadcast address for this network |
| ntpsrv - A list of NTP servers |
| wins - A list of WINS servers |
| lease - The lease time, in seconds |
| dhcptype - DHCP message type (safely ignored) |
| serverid - The IP of the server |
| message - Reason for a DHCPNAK |
| tftp - The TFTP server name |
| bootfile - The bootfile name |
| |
| additional options are easily added in options.c. |
| |
| udhcpc also responds to SIGUSR1 and SIGUSR2. SIGUSR1 will force a renew state, |
| and SIGUSR2 will force a release of the current lease, and cause udhcpc to |
| go into an inactive state (until it is killed, or receives a SIGUSR1). You do |
| not need to sleep between sending signals, as signals received are processed |
| sequencially in the order they are received. |
| |
| |
| |
| compile time options |
| ------------------- |
| |
| The Makefile contains three of the compile time options: |
| |
| DEBUG: If DEBUG is defined, udhcpd will output extra debugging |
| output, compile with -g, and not fork to the background when run. |
| SYSLOG: If SYSLOG is defined, udhcpd will log all its messages |
| syslog, otherwise, it will attempt to log them to stdout. |
| |
| COMBINED_BINARY: If COMBINED_BINARY is define, one binary, udhcpd, |
| is created. If called as udhcpd, the dhcp server will be started. |
| If called as udhcpc, the dhcp client will be started. |
| |
| dhcpd.h contains the other two compile time options: |
| |
| LEASE_TIME: The default lease time if not specified in the config |
| file. |
| |
| DHCPD_CONFIG_FILE: The defualt config file to use. |
| |
| options.c contains a set of dhcp options for the client: |
| |
| name[10]: The name of the option as it will appear in scripts |
| |
| flags: The type of option, as well as if it will be requested |
| by the client (OPTION_REQ) |
| |
| code: The DHCP code for this option |
| |
| busybox drop-in |
| -------------- |
| udhcp is now a drop-in component for busybox (http://busybox.net). |
| To update busybox to the latest revision, simply do a: |
| |
| cp *.[ch] README AUTHORS COPYING ChangeLog TODO \ |
| <busybox_source>/networking/udhcp |
| |
| The only two files udhcp does not provide are config.in and |
| Makefile.in, so these may need to be updated from time to time. |
