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