NAME

     dhcpcd — an RFC 2131 compliant DHCP client

SYNOPSIS

     dhcpcd [-dknpAEGHMLNRSTY] [-c, --script script] [-h, --hostname hostname]
            [-i, --classid classid] [-l, --leasetime seconds] [-m, --metric metric]
            [-r, --request address] [-t, --timeout seconds] [-u, --userclass class]
            [-F, --fqdn FQDN] [-I, --clientid clientid] [-P, --pidfile pidfile] interface
     dhcpcd -k, --release interface
     dhcpcd -x, --exit interface

DESCRIPTION

     dhcpcd is an implementation of the DHCP client specified in RFC 2131.  dhcpcd gets the host
     information (IP address, routes, etc) from a DHCP server and configures the network
     interface of the machine on which it is running.  dhcpcd will then write DNS information to
     resolvconf(8), if available, otherwise directly to /etc/resolv.conf.  dhcpcd will also
     configure /etc/yp.conf and /etc/ntpd.conf with NIS and NTP information if the DHCP server
     provided them.  If those file contents changed, then dhcpcd will also attempt to restart the
     respective services to notify them of the change.  If the hostname is currenly blank, (null)
     or localhost then dhcpcd will set the hostname to the one supplied by the DHCP server, or
     look it up in DNS if none supplied.  dhcpcd then daemonises and waits for the lease renewal
     time to lapse.  Then it attempts to renew its lease and reconfigure if the new lease
     changes.

   Local Link configuration
     If dhcpcd failed to obtain a lease, it will probe for a valid IPv4LL address (aka Zeroconf,
     aka APIPA).  Once obtained it will probe every 10 seconds for a DHCP server to get a proper
     address.

     Even when dhcpcd obtains a proper lease, it will still add a Local Link route
     (165.254.0.0/16) so that the host can communicate with clients using these addresses.

     When using IPv4LL, dhcpcd will always succeed and return a 0 exit code. To disable this
     behaviour, you can use the -L, --noipv4ll option.

   Hooking into DHCP events
     dhcpcd will run /etc/dhcpcd.sh, or the script specified by the -c, --script option. It will
     set $1 to a shell compatible file that holds various configuration settings obtained from
     the DHCP server and $2 to either up, down or new depending on the state of dhcpcd.  dhcpcd
     ignores the exist code of the script.

   Fine tuning
     You can fine tune the behaviour of dhcpcd with the following options :-

     -d, --debug
             Echo debug and informational messages to the console.  Subsequent debug options stop
             dhcpcd from daemonising.

     -h, --hostname hostname
             By default, dhcpcd will send the current hostname to the DHCP server so it can
             register in DNS.  You can use this option to specify the hostname sent, or an empty
             string to stop any hostname from being sent.

     -i, --classid classid
             Override the DHCP vendor classid field we send. The default is dhcpcd-<version>.

     -k, --release
             This causes an existing dhcpcd process running on the interface to release it's
             lease, deconfigure the interface and then exit.

     -l, --leasetime seconds
             Request a specific lease time in seconds.  By default dhcpcd does not request any
             lease time and leaves the it in the hands of the DHCP server.

     -m, --metric metric
             Added routes will use the metric on systems where this is supported (presently only
             Linux).  Route metrics allow the addition of routes to the same destination across
             different interfaces, the lower the metric the more it is preferred.

     -n, --renew
             Notifies an existing dhcpcd process running on the interface to renew it's lease. If
             dhcpcd is not running, then it starts up as normal.

     -p, --persistent
             dhcpcd normally deconfigures the interface and configuration when it exits.
             Sometimes, this isn't desirable if for example you have root mounted over NFS.  You
             can use this option to stop this from happening.

     -r, --request [address]
             dhcpcd normally sends a DHCP Broadcast to find servers to offer an address.  dhcpcd
             will then request the address used. You can use this option to skip the broadcast
             step and just request an address.  The downside is if you request an address the
             DHCP server does not know about or the DHCP server is not authorative, it will
             remain silent. In this situation, we go back to the init state and broadcast again.
             If no address is given then we use the first address currently assigned to the
             interface.

     -s, --inform [address [/ cidr]]
             Behaves exactly like -r, --request as above, but sends a DHCP inform instead of a
             request. This requires the interface to be configured first. This does not get a
             lease as such, just notifies the DHCP server of the address we are using.

     -t, --timeout seconds
             Timeout after seconds, instead of the default 20.  A setting of 0 seconds causes
             dhcpcd to wait forever to get a lease.

     -u, --userclass class
             Tags the DHCP message with the userclass class.  DHCP servers use this give memebers
             of the class DHCP options other than the default, without having to know things like
             hardware address or hostname.  ∞Requests that the DHCP server updates DNS using FQDN
             instead of just a hostname. Valid values for fqdn are none, ptr and both.  dhcpcd
             dhcpcd itself never does any DNS updates.

     -H, ---sethostname
             Forces dhcpcd to set the hostname as supplied by the DHCP server. Because some OS's
             and users prefer to have just the hostname, or the full FQDN more -H, ---sethostname
             options change the behaviour. Below is the list of possible combinations:-

             -H      set the hostname to the full FQDN.

             -HH     strip the domain if it matches the dns domain.

             -HHH    strip the domain regardless.

             -HHHH   same as -H but force hostname lookup via DNS.

             -HHHHH  same as above, but strip the domain if it matches the dns domain.

             -HHHHHH
                     same as above, but strip the domain regardless.

     -I, --clientid clientid
             Send clientid as a client identifier string. If clientid matches a hardware address
             format, such as 01:00:01:02:03:04:05 then we encode it as that, otherwise as a
             string. You need to specify the hardware type in the first byte. Ethernet is 01, and
             the hardware address in the example is 00:01:02:03:04:05. If the clientid is a blank
             string, then we disable DUID support and use a clientid as shown above.

     -S, --mscsr
             Microsoft have their own code for Classless Static Routes (RFC 3442).  You can use
             this option to request this as well as the normal CSR. Another instace of this
             option only requests the Microsoft CSR to prevent DHCP message over-running its
             maximum size. DHCP server administrators should update their CSR code from the
             Microsoft specific one to the RFC compliant one as the content is fully compatible.

     -P, --pidfile filename
             Write the PID to filename instead of /var/run/dhcpcd-interface.pid.

   Restriciting behaviour
     dhcpcd will try to do as much as it can by default. However, there are sometimes situations
     where you don't want the things to be configured exactly how the the DHCP server wants. Here
     are some option that deal with turning these bits off.

     -A, --noarp
             Don't request or claim the address by ARP.

     -G, --nogateway
             Don't set any default routes.

     -L, --noipv4ll
             Don't use IPv4LL at all.

     -M, --nomtu
             Don't set the MTU of the interface.

     -N, --nontp
             Don't touch /etc/ntpd.conf or restart the ntp service.

     -R, --nodns
             Don't send DNS information to resolvconf or touch /etc/resolv.conf.

     -T, --test
             On receipt of discover messages, simply print the contents of the DHCP message to
             the console.  dhcpcd will not configure the interface, touch any files or restart
             any services.

     -Y, --nonis
             Don't touch /etc/yp.conf or restart the ypbind service.

NOTES

     Because dhcpcd supports InfiniBand, we put a Node-specific Client Identifier in the ClientID
     field. This is required by RFC 4390. It's also required for DHCP IPv6 which dhcpcd should
     support one day. However, some DHCP servers have no idea what this is and reject the message
     as they do not understand type 255. This is not conformant with RFC 2132 and the server
     should be fixed. Also, some DHCP server configurations require an ethernet hardware address
     of 6 hexacdecimal numbers in the ClientID which is the default behaviour of most other DHCP
     clients. If your DHCP server is as desribed above, you should fix the server, or if that is
     not an option you can compile DUID support out of dhcpcd or use the -I, --clientid clientid
     option and set clientid to ''.

     ISC dhcpd, dnsmasq, udhcpd and Microsoft DHCP server 2003 default configurations work just
     fine with the default dhcpcd configuration.

     dhcpcd requires a Berkley Packet Filter, or BPF device on BSD based systems and a Linux
     Socket Filter, or LPF device on Linux based systems.

FILES

     /etc/dhcpcd.sh
     Bourne shell script that is run when we configure or deconfigure an interface.

     /var/lib/dhcpcd/dhcpcd.duid
     Text file that holds the DUID used to identify the host.

     /var/lib/dhcpcd/dhcpcd-interface.info
     Bourne shell file that holds the DHCP values used in configuring the interface.  This path
     is passed as the first argument to /etc/dhcpcd.sh.

SEE ALSO

     ntp(1), resolv.conf(5), resolvconf(8), yp.conf(5), ypbind(8)

STANDARDS

     RFC 2131, RFC 2132, RFC 2855, RFC 3004, RFC 3361, RFC 3397, RFC 3442, RFC 3927, RFC 4361,
     RFC 4390, RFC 4702.

AUTHORS

     Roy Marples <roy@marples.name>

BUGS

     Please report them to http://bugs.marples.name

                                           Feb 20, 2008