| .\" Copyright 2006-2008 Roy Marples |
| .\" All rights reserved |
| .\" |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" |
| .Dd August 20, 2008 |
| .Dt DHCPCD 8 SMM |
| .Sh NAME |
| .Nm dhcpcd |
| .Nd an RFC 2131 compliant DHCP client |
| .Sh SYNOPSIS |
| .Nm |
| .Op Fl bdknpqABDEGKLSTV |
| .Op Fl c , -script Ar script |
| .Op Fl f , -config Ar file |
| .Op Fl h , -hostname Ar hostname |
| .Op Fl i , -vendorclassid Ar vendorclassid |
| .Op Fl l , -leasetime Ar seconds |
| .Op Fl m , -metric Ar metric |
| .Op Fl o , -option Ar option |
| .Op Fl r , -request Ar address |
| .Op Fl s , -inform Ar address Ns Op Ar /cidr |
| .Op Fl t , -timeout Ar seconds |
| .Op Fl u , -userclass Ar class |
| .Op Fl v , -vendor Ar code , Ar value |
| .Op Fl C , -nohook Ar hook |
| .Op Fl F , -fqdn Ar FQDN |
| .Op Fl I , -clientid Ar clientid |
| .Op Fl O , -nooption Ar option |
| .Op Fl Q , -require Ar option |
| .Op Fl X , -blacklist Ar address |
| .Ar interface |
| .Nm |
| .Fl k , -release |
| .Ar interface |
| .Nm |
| .Fl x , -exit |
| .Ar interface |
| .Sh DESCRIPTION |
| .Nm |
| is an implementation of the DHCP client specified in |
| .Li RFC 2131 . |
| .Nm |
| gets the host information |
| .Po |
| IP address, routes, etc |
| .Pc |
| from a DHCP server and configures the network |
| .Ar interface |
| of the |
| machine on which it is running. |
| .Nm |
| then runs the configuration script which writes DNS information to |
| .Xr resolvconf 8 , |
| if available, otherwise directly to |
| .Pa /etc/resolv.conf . |
| If the hostname is currenly blank, (null) or localhost then |
| .Nm |
| sets the hostname to the one supplied by the DHCP server. |
| .Nm |
| 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. |
| .Ss Local Link configuration |
| If |
| .Nm |
| failed to obtain a lease, it probes for a valid IPv4LL address |
| .Po |
| aka ZeroConf, aka APIPA |
| .Pc . |
| Once obtained it restarts the process of looking for a DHCP server to get a |
| proper address. |
| .Pp |
| When using IPv4LL, |
| .Nm |
| nearly always succeeds and returns an exit code of 0. |
| In the rare case it fails, it normally means that there is a reverse ARP proxy |
| installed which always defeats IPv4LL probing. |
| To disable this behaviour, you can use the |
| .Fl L , -noipv4ll |
| option. |
| .Ss Hooking into DHCP events |
| .Nm |
| runs |
| .Pa /system/etc/dhcpcd/dhcpcd-run-hooks , |
| or the script specified by the |
| .Fl c , -script |
| option. |
| This script runs each script found in |
| .Pa /system/etc/dhcpcd/dhcpcd-hooks |
| in a lexical order. |
| The default installation supplies the scripts |
| .Pa 01-test , |
| .Pa 10-mtu , |
| .Pa 20-resolv.conf |
| and |
| .Pa 30-hostname . |
| You can disable each script by using the |
| .Fl C , -nohook |
| option. |
| See |
| .Xr dhcpcd-run-hooks 8 |
| for details on how these scripts work. |
| .Nm |
| currently ignores the exit code of the script. |
| .Ss Fine tuning |
| You can fine tune the behaviour of |
| .Nm |
| with the following options: |
| .Bl -tag -width indent |
| .It Fl b , -background |
| Background immediately. |
| This is useful for startup scripts which don't disable link messages for |
| carrier status. |
| .It Fl c , -script Ar script |
| Use this |
| .Ar script |
| instead of the default |
| .Pa /system/etc/dhcpcd/dhcpcd-run-hooks . |
| .It Fl d , -debug |
| Echo debug and informational messages to the console. |
| Subsequent debug options stop |
| .Nm |
| from daemonising. |
| .It Fl f , -config Ar file |
| Specify a config to load instead of |
| .Pa /system/etc/dhcpcd/dhcpcd.conf . |
| .Nm |
| always processes the config file before any command line options. |
| .It Fl h , -hostname Ar hostname |
| By default, |
| .Nm |
| sends the current hostname to the DHCP server so it can register in DNS. |
| You can use this option to specify the |
| .Ar hostname |
| sent, or an empty string to |
| stop any |
| .Ar hostname |
| from being sent. |
| .It Fl i , -vendorclassid Ar vendorclassid |
| Override the |
| .Ar vendorclassid |
| field sent. The default is |
| dhcpcd <version>. |
| If not set then none is sent. |
| .It Fl k , -release |
| This causes an existing |
| .Nm |
| process running on the |
| .Ar interface |
| to release its lease, deconfigure the |
| .Ar interface |
| and then exit. |
| .Nm |
| then waits until this process has exited. |
| .It Fl l , -leasetime Ar seconds |
| Request a specific lease time in |
| .Ar seconds . |
| By default |
| .Nm |
| does not request any lease time and leaves the it in the hands of the |
| DHCP server. |
| .It Fl m , -metric Ar metric |
| Added routes will use the |
| .Ar metric |
| on systems where this is supported |
| .Po |
| presently only Linux |
| .Pc . |
| Route metrics allow the addition of routes to the same destination across |
| different interfaces, the lower the metric the more it is preferred. |
| .It Fl o , -option Ar option |
| Request the DHCP |
| .Ar option |
| variable for use in |
| .Pa /system/etc/dhcpcd/dhcpcd-run-hooks . |
| .It Fl n , -rebind |
| Notifies an existing |
| .Nm |
| process running on the |
| .Ar interface |
| to rebind it's lease. |
| .Nm |
| will not re-configure itself or use any other command line arguments. |
| .Nm |
| will timeout the rebind after 30 seconds at which point the lease will be |
| expired and |
| .Nm |
| will enter the discovery state to obtain a new lease. |
| Use the |
| .Fl t , -timeout |
| option to change this. |
| If |
| .Nm |
| is not running, then it starts up as normal. |
| This option used to be renew, but rebind is more accurate as we need to |
| broadcast the request instead of unicasting. |
| .It Fl p , -persistent |
| .Nm |
| normally deconfigures the |
| .Ar 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. |
| .It Fl r , -request Op Ar address |
| .Nm |
| normally sends a DHCP DISCOVER to find servers to offer an address. |
| .Nm |
| then requests the address used. |
| You can use this option to skip the BROADCAST step and just request the |
| .Ar address . |
| The downside is if you request an |
| .Ar 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 DISCOVER again. |
| If no |
| .Ar address |
| is given then the first address currently assigned to the |
| .Ar interface |
| is used. |
| .It Fl s , -inform Op Ar address Ns Op Ar /cidr |
| Behaves like |
| .Fl r , -request |
| as above, but sends a DHCP INFORM instead of a REQUEST. |
| This does not get a lease as such, just notifies the DHCP server of the |
| .Ar address |
| in use. |
| You should also include the optional |
| .Ar cidr |
| network number in-case the address is not already configured on the interface. |
| .Nm |
| remains running and pretends it has an infinite lease. |
| .Nm |
| will not de-configure the interface when it exits. |
| If |
| .Nm |
| fails to contact a DHCP server then it returns a failure instead of falling |
| back on IPv4LL. |
| .It Fl t , -timeout Ar seconds |
| Timeout after |
| .Ar seconds , |
| instead of the default 30. |
| A setting of 0 |
| .Ar seconds |
| causes |
| .Nm |
| to wait forever to get a lease. |
| .It Fl u , -userclass Ar class |
| Tags the DHCP message with the userclass |
| .Ar class . |
| DHCP servers use this give members of the class DHCP options other than the |
| default, without having to know things like hardware address or hostname. |
| .It Fl v , -vendor Ar code , Ns Ar value |
| Add an enscapulated vendor option. |
| .Ar code |
| should be between 1 and 254 inclusive. |
| Examples. |
| .Pp |
| Set the vendor option 01 with an IP address. |
| .D1 dhcpcd \-v 01,192.168.0.2 eth0 |
| Set the vendor option 02 with a hex code. |
| .D1 dhcpcd \-v 02,01:02:03:04:05 eth0 |
| Do the above and set a third option with a string and not an IP address. |
| .D1 dhcpcd \-v 01,192.168.0.2 \-v 02,01:02:03:04:05 \-v 03,\e"192.168.0.2\e" eth0 |
| .It Fl x , -exit |
| This will signal an existing |
| .Nm |
| process running on the |
| .Ar interface |
| to deconfigure the |
| .Ar interface |
| and exit. |
| .Nm |
| then waits until this process has exited. |
| .It Fl D , -duid |
| Generate an |
| .Li RFC 4361 |
| compliant clientid. |
| This requires persistent storage and not all DHCP servers work with it so it's |
| not enabled by default. |
| .Nm |
| generates the DUID and stores in it |
| .Pa /system/etc/dhcpcd/dhcpcd.duid |
| This file should not be copied to other hosts. |
| .It Fl E , -lastlease |
| If |
| .Nm |
| cannot obtain a lease, then try to use the last lease acquired for the |
| interface. |
| If the |
| .Fl p, -persistent |
| option is not given then the lease is used if it hasn't expired. |
| .It Fl F , -fqdn Ar fqdn |
| Requests that the DHCP server updates DNS using FQDN instead of just a |
| hostname. |
| Valid values for |
| .Ar fqdn |
| are disable, none, ptr and both. |
| The current hostname or the hostname specified using the |
| .Fl h , -hostname |
| option must be a FQDN. |
| .Nm |
| itself never does any DNS updates. |
| .Nm |
| encodes the FQDN hostname as specified in |
| .Li RFC1035 . |
| .It Fl I , -clientid Ar clientid |
| Change the default clientid sent from the interface hardware address. |
| If the string is of the format 01:02:03 then it is encoded as hex. |
| If not set then none is sent. |
| .El |
| .Ss Restriciting behaviour |
| .Nm |
| 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 options that deal with turning these bits off. |
| .Bl -tag -width indent |
| .It Fl q , -quiet |
| Quiet |
| .Nm |
| on the command line, only warnings and errors will be displayed. |
| The messages are still logged though. |
| .It Fl A , -noarp |
| Don't request or claim the address by ARP. |
| This also disables IPv4LL. |
| .It Fl B , -nobackground |
| Don't run in the background when we acquire a lease. |
| This is mainly useful for running under the control of another process, such |
| as a debugger or a network manager. |
| .It Fl C , -nohook Ar script |
| Don't run this hook script. |
| Matches full name, or prefixed with 2 numbers optionally ending with |
| .Pa .sh . |
| .Pp |
| So to stop dhcpcd from touching your DNS or MTU settings you would do:- |
| .D1 dhcpcd -C resolv.conf -C mtu eth0 |
| .It Fl G , -nogateway |
| Don't set any default routes. |
| .It Fl K , -nolink |
| Don't receive link messages for carrier status. |
| You should only have to use this with buggy device drivers or running |
| .Nm |
| through a network manager. |
| .It Fl L , -noipv4ll |
| Don't use IPv4LL (aka APIPA, aka Bonjour, aka ZeroConf). |
| .It Fl O , -nooption Ar option |
| Don't request the specified option. |
| If no option given, then don't request any options other than those to |
| configure the interface and routing. |
| .It Fl Q , -require Ar option |
| Requires the |
| .Ar option |
| to be present in all DHCP messages, otherwise the message is ignored. |
| .It Fl T, -test |
| On receipt of OFFER messages just call |
| .Pa /system/etc/dhcpcd/dhcpcd-run-hooks |
| with the reason of TEST which echo's the DHCP variables found in the message |
| to the console. |
| The interface configuration isn't touched and neither are any configuration |
| files. |
| .It Fl V, -variables |
| Display a list of option codes and the associated variable for use in |
| .Xr dhcpcd-run-hooks 8 . |
| .It Fl X, -blacklist Ar address |
| Ignores all DHCP messages which have this |
| .Ar address |
| as the server ID. |
| This may be expanded in future releases to ignore all packets |
| matching either the IP or hardware |
| .Ar address . |
| .El |
| .Sh NOTES |
| .Nm |
| requires a Berkley Packet Filter, or BPF device on BSD based systems and a |
| Linux Socket Filter, or LPF device on Linux based systems. |
| .Sh FILES |
| .Bl -ohang |
| .It Pa /system/etc/dhcpcd/dhcpcd.conf |
| Configuration file for dhcpcd. |
| If you always use the same options, put them here. |
| .It Pa /system/etc/dhcpcd/dhcpcd.duid |
| Text file that holds the DUID used to identify the host. |
| .It Pa /system/etc/dhcpcd/dhcpcd-run-hooks |
| Bourne shell script that is run to configure or deconfigure an interface. |
| .It Pa /system/etc/dhcpcd/dhcpcd-hooks |
| A directory containing bourne shell scripts that are run by the above script. |
| Each script can be disabled by using the |
| .Fl C , -nohook |
| option described above. |
| .It Pa /data/misc/dhcp/dhcpcd\- Ns Ar interface Ns .lease |
| The actual DHCP message send by the server. We use this when reading the last |
| lease and use the files mtime as when it was issued. |
| .It Pa /var/run/dhcpcd\- Ns Ar interface Ns .pid |
| Stores the PID of |
| .Nm |
| running on the |
| .Ar interface . |
| .El |
| .Sh SEE ALSO |
| .Xr dhcpcd.conf 5 , |
| .Xr dhcpcd-run-hooks 8 , |
| .Xr resolv.conf 5 , |
| .Xr resolvconf 8 , |
| .Sh STANDARDS |
| RFC 2131, RFC 2132, RFC 2855, RFC 3004, RFC 3361, RFC 3396, RFC 3397, |
| RFC 3442, RFC 3927, RFC 4361, RFC 4390, RFC 4702. |
| .Sh AUTHORS |
| .An Roy Marples <roy@marples.name> |
| .Sh BUGS |
| Please report them to http://bugs.marples.name |