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         mask            - The number of bits in the netmask (ie: 24)
  73         siaddr          - The bootp next server option
  74         sname           - The bootp server name option
  75         boot_file       - The bootp boot file option
  76         subnet          - The assigend subnet mask
  77         timezone        - Offset in seconds from UTC
  78         router          - A list of routers
  79         timesvr         - A list of time servers
  80         namesvr         - A list of IEN 116 name servers
  81         dns             - A list of DNS server
  82         logsvr          - A list of MIT-LCS UDP log servers
  83         cookiesvr       - A list of RFC 865 cookie servers
  84         lprsvr          - A list of LPR servers
  85         hostname        - The assigned hostname
  86         bootsize        - The length in 512 octect blocks of the bootfile
  87         domain          - The domain name of the network
  88         swapsvr         - The IP address of the client's swap server
  89         rootpath        - The path name of the client's root disk
  90         ipttl           - The TTL to use for this network
  91         mtu             - The MTU to use for this network
  92         broadcast       - The broadcast address for this network
  93         ntpsrv          - A list of NTP servers
  94         wins            - A list of WINS servers
  95         lease           - The lease time, in seconds
  96         dhcptype        - DHCP message type (safely ignored)
  97         serverid        - The IP of the server
  98         message         - Reason for a DHCPNAK
  99         tftp            - The TFTP server name
 100         bootfile        - The bootfile name
 101
 102 additional options are easily added in options.c.
 103
 104
 105 note on udhcpc's random seed
 106 ---------------------------
 107
 108 udhcpc will seed its random number generator (used for generating xid's)
 109 by reading /dev/urandom. If you have a lot of embedded systems on the same
 110 network, with no entropy, you can either seed /dev/urandom by a method of
 111 your own, or doing the following on startup:
 112
 113 ifconfig eth0 > /dev/urandom
 114
 115 in order to seed /dev/urandom with some data (mac address) unique to your
 116 system. If reading /dev/urandom fails, udhcpc will fall back to its old
 117 behavior of seeding with time(0).
 118
 119
 120 signals accepted by udhcpc
 121 -------------------------
 122
 123 udhcpc also responds to SIGUSR1 and SIGUSR2. SIGUSR1 will force a renew state,
 124 and SIGUSR2 will force a release of the current lease, and cause udhcpc to
 125 go into an inactive state (until it is killed, or receives a SIGUSR1). You do
 126 not need to sleep between sending signals, as signals received are processed
 127 sequencially in the order they are received.
 128
 129
 130 compile time options
 131 -------------------
 132
 133 options.c contains a set of dhcp options for the client:
 134
 135         name[10]: The name of the option as it will appear in scripts
 136
 137         flags: The type of option, as well as if it will be requested
 138         by the client (OPTION_REQ)
 139
 140         code: The DHCP code for this option
 141