networking/udhcp/README.udhcpc

   1 udhcp client (udhcpc)
   2 --------------------
   3
   4 The udhcp client negotiates a lease with the DHCP server and notifies
   5 a set of scripts when a leases is obtained or lost.
   6
   7
   8 command line options
   9 -------------------
  10
  11 The command line options for the udhcp client are:
  12
  13 -c, --clientid=CLIENTID         Client identifier
  14 -H, --hostname=HOSTNAME         Client hostname
  15 -h,                             Alias for -H
  16 -f, --foreground                Do not fork after getting lease
  17 -b, --background                Fork to background if lease cannot be
  18                                 immediately negotiated.
  19 -i, --interface=INTERFACE       Interface to use (default: eth0)
  20 -n, --now                       Exit with failure if lease cannot be
  21                                 immediately negotiated.
  22 -p, --pidfile=file              Store process ID of daemon in file
  23 -q, --quit                      Quit after obtaining lease
  24 -r, --request=IP                IP address to request (default: none)
  25 -s, --script=file               Run file at dhcp events (default:
  26                                 /usr/share/udhcpc/default.script)
  27 -v, --version                   Display version
  28
  29
  30 If the requested IP address cannot be obtained, the client accepts the
  31 address that the server offers.
  32
  33
  34 udhcp client scripts
  35 -------------------
  36
  37 When an event occurs, udhcpc calls the action script. udhcpc never does
  38 any configuration of the network interface itself, but instead relies on
  39 a set of scripts. The script by default is
  40 /usr/share/udhcpc/default.script but this can be changed via the command
  41 line arguments. The three possible arguments to the script are:
  42
  43         deconfig: This argument is used when udhcpc starts, and
  44         when a leases is lost. The script must put the interface in an
  45         up, but deconfigured state, ie: ifconfig $interface 0.0.0.0.
  46
  47         bound: This argument is used when udhcpc moves from an
  48         unbound, to a bound state. All of the paramaters are set in
  49         enviromental variables, The script should configure the interface,
  50         and set any other relavent parameters (default gateway, dns server,
  51         etc).
  52
  53         renew: This argument is used when a DHCP lease is renewed. All of
  54         the paramaters are set in enviromental variables. This argument is
  55         used when the interface is already configured, so the IP address,
  56         will not change, however, the other DHCP paramaters, such as the
  57         default gateway, subnet mask, and dns server may change.
  58
  59         nak: This argument is used with udhcpc receives a NAK message.
  60         The script with the deconfig argument will be called directly
  61         afterwards, so no changes to the network interface are neccessary.
  62         This hook is provided for purely informational purposes (the
  63         message option may contain a reason for the NAK).
  64
  65 The paramaters for enviromental variables are as follows:
  66
  67         $HOME           - The set $HOME env or "/"
  68         $PATH           - the set $PATH env or "/bin:/usr/bin:/sbin:/usr/sbin"
  69         $1              - What action the script should perform
  70         interface       - The interface this was obtained on
  71         ip              - The obtained IP
  72         siaddr          - The bootp next server option
  73         sname           - The bootp server name option
  74         boot_file       - The bootp boot file option
  75         subnet          - The assigend subnet mask
  76         timezone        - Offset in seconds from UTC
  77         router          - A list of routers
  78         timesvr         - A list of time servers
  79         namesvr         - A list of IEN 116 name servers
  80         dns             - A list of DNS server
  81         logsvr          - A list of MIT-LCS UDP log servers
  82         cookiesvr       - A list of RFC 865 cookie servers
  83         lprsvr          - A list of LPR servers
  84         hostname        - The assigned hostname
  85         bootsize        - The length in 512 octect blocks of the bootfile
  86         domain          - The domain name of the network
  87         swapsvr         - The IP address of the client's swap server
  88         rootpath        - The path name of the client's root disk
  89         ipttl           - The TTL to use for this network
  90         mtu             - The MTU to use for this network
  91         broadcast       - The broadcast address for this network
  92         ntpsrv          - A list of NTP servers
  93         wins            - A list of WINS servers
  94         lease           - The lease time, in seconds
  95         dhcptype        - DHCP message type (safely ignored)
  96         serverid        - The IP of the server
  97         message         - Reason for a DHCPNAK
  98         tftp            - The TFTP server name
  99         bootfile        - The bootfile name
 100
 101 additional options are easily added in options.c.
 102
 103
 104 note on udhcpc's random seed
 105 ---------------------------
 106
 107 udhcpc will seed its random number generator (used for generating xid's)
 108 by reading /dev/urandom. If you have a lot of embedded systems on the same
 109 network, with no entropy, you can either seed /dev/urandom by a method of
 110 your own, or doing the following on startup:
 111
 112 ifconfig eth0 > /dev/urandom
 113
 114 in order to seed /dev/urandom with some data (mac address) unique to your
 115 system. If reading /dev/urandom fails, udhcpc will fall back to its old
 116 behavior of seeding with time(0).
 117
 118
 119 signals accepted by udhcpc
 120 -------------------------
 121
 122 udhcpc also responds to SIGUSR1 and SIGUSR2. SIGUSR1 will force a renew state,
 123 and SIGUSR2 will force a release of the current lease, and cause udhcpc to
 124 go into an inactive state (until it is killed, or receives a SIGUSR1). You do
 125 not need to sleep between sending signals, as signals received are processed
 126 sequencially in the order they are received.
 127
 128
 129 compile time options
 130 -------------------
 131
 132 options.c contains a set of dhcp options for the client:
 133
 134         name[10]: The name of the option as it will appear in scripts
 135
 136         flags: The type of option, as well as if it will be requested
 137         by the client (OPTION_REQ)
 138
 139         code: The DHCP code for this option
 140