1.\" Copyright 2006-2008 Roy Marples 2.\" All rights reserved 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd August 20, 2008 26.Dt DHCPCD 8 SMM 27.Sh NAME 28.Nm dhcpcd 29.Nd an RFC 2131 compliant DHCP client 30.Sh SYNOPSIS 31.Nm 32.Op Fl bdknpqABDEGKLSTV 33.Op Fl c , -script Ar script 34.Op Fl f , -config Ar file 35.Op Fl h , -hostname Ar hostname 36.Op Fl i , -vendorclassid Ar vendorclassid 37.Op Fl l , -leasetime Ar seconds 38.Op Fl m , -metric Ar metric 39.Op Fl o , -option Ar option 40.Op Fl r , -request Ar address 41.Op Fl s , -inform Ar address Ns Op Ar /cidr 42.Op Fl t , -timeout Ar seconds 43.Op Fl u , -userclass Ar class 44.Op Fl v , -vendor Ar code , Ar value 45.Op Fl C , -nohook Ar hook 46.Op Fl F , -fqdn Ar FQDN 47.Op Fl I , -clientid Ar clientid 48.Op Fl O , -nooption Ar option 49.Op Fl Q , -require Ar option 50.Op Fl X , -blacklist Ar address 51.Ar interface 52.Nm 53.Fl k , -release 54.Ar interface 55.Nm 56.Fl x , -exit 57.Ar interface 58.Sh DESCRIPTION 59.Nm 60is an implementation of the DHCP client specified in 61.Li RFC 2131 . 62.Nm 63gets the host information 64.Po 65IP address, routes, etc 66.Pc 67from a DHCP server and configures the network 68.Ar interface 69of the 70machine on which it is running. 71.Nm 72then runs the configuration script which writes DNS information to 73.Xr resolvconf 8 , 74if available, otherwise directly to 75.Pa /etc/resolv.conf . 76If the hostname is currenly blank, (null) or localhost then 77.Nm 78sets the hostname to the one supplied by the DHCP server. 79.Nm 80then daemonises and waits for the lease renewal time to lapse. 81Then it attempts to renew its lease and reconfigure if the new lease changes. 82.Ss Local Link configuration 83If 84.Nm 85failed to obtain a lease, it probes for a valid IPv4LL address 86.Po 87aka ZeroConf, aka APIPA 88.Pc . 89Once obtained it restarts the process of looking for a DHCP server to get a 90proper address. 91.Pp 92When using IPv4LL, 93.Nm 94nearly always succeeds and returns an exit code of 0. 95In the rare case it fails, it normally means that there is a reverse ARP proxy 96installed which always defeats IPv4LL probing. 97To disable this behaviour, you can use the 98.Fl L , -noipv4ll 99option. 100.Ss Hooking into DHCP events 101.Nm 102runs 103.Pa @SCRIPT@ , 104or the script specified by the 105.Fl c , -script 106option. 107This script runs each script found in 108.Pa @HOOKDIR@ 109in a lexical order. 110The default installation supplies the scripts 111.Pa 01-test , 112.Pa 10-mtu , 113.Pa 20-resolv.conf 114and 115.Pa 30-hostname . 116You can disable each script by using the 117.Fl C , -nohook 118option. 119See 120.Xr dhcpcd-run-hooks 8 121for details on how these scripts work. 122.Nm 123currently ignores the exit code of the script. 124.Ss Fine tuning 125You can fine tune the behaviour of 126.Nm 127with the following options: 128.Bl -tag -width indent 129.It Fl b , -background 130Background immediately. 131This is useful for startup scripts which don't disable link messages for 132carrier status. 133.It Fl c , -script Ar script 134Use this 135.Ar script 136instead of the default 137.Pa @SCRIPT@ . 138.It Fl d , -debug 139Echo debug and informational messages to the console. 140Subsequent debug options stop 141.Nm 142from daemonising. 143.It Fl f , -config Ar file 144Specify a config to load instead of 145.Pa @SYSCONFDIR@/dhcpcd.conf . 146.Nm 147always processes the config file before any command line options. 148.It Fl h , -hostname Ar hostname 149By default, 150.Nm 151sends the current hostname to the DHCP server so it can register in DNS. 152You can use this option to specify the 153.Ar hostname 154sent, or an empty string to 155stop any 156.Ar hostname 157from being sent. 158.It Fl i , -vendorclassid Ar vendorclassid 159Override the 160.Ar vendorclassid 161field sent. The default is 162dhcpcd <version>. 163If not set then none is sent. 164.It Fl k , -release 165This causes an existing 166.Nm 167process running on the 168.Ar interface 169to release its lease, deconfigure the 170.Ar interface 171and then exit. 172.Nm 173then waits until this process has exited. 174.It Fl l , -leasetime Ar seconds 175Request a specific lease time in 176.Ar seconds . 177By default 178.Nm 179does not request any lease time and leaves the it in the hands of the 180DHCP server. 181.It Fl m , -metric Ar metric 182Added routes will use the 183.Ar metric 184on systems where this is supported 185.Po 186presently only Linux 187.Pc . 188Route metrics allow the addition of routes to the same destination across 189different interfaces, the lower the metric the more it is preferred. 190.It Fl o , -option Ar option 191Request the DHCP 192.Ar option 193variable for use in 194.Pa @SCRIPT@ . 195.It Fl n , -rebind 196Notifies an existing 197.Nm 198process running on the 199.Ar interface 200to rebind it's lease. 201.Nm 202will not re-configure itself or use any other command line arguments. 203.Nm 204will timeout the rebind after 30 seconds at which point the lease will be 205expired and 206.Nm 207will enter the discovery state to obtain a new lease. 208Use the 209.Fl t , -timeout 210option to change this. 211If 212.Nm 213is not running, then it starts up as normal. 214This option used to be renew, but rebind is more accurate as we need to 215broadcast the request instead of unicasting. 216.It Fl p , -persistent 217.Nm 218normally deconfigures the 219.Ar interface 220and configuration when it exits. 221Sometimes, this isn't desirable if for example you have root mounted over NFS. 222You can use this option to stop this from happening. 223.It Fl r , -request Op Ar address 224.Nm 225normally sends a DHCP DISCOVER to find servers to offer an address. 226.Nm 227then requests the address used. 228You can use this option to skip the BROADCAST step and just request the 229.Ar address . 230The downside is if you request an 231.Ar address 232the DHCP server does not know about or the DHCP server is not 233authorative, it will remain silent. 234In this situation, we go back to the init state and DISCOVER again. 235If no 236.Ar address 237is given then the first address currently assigned to the 238.Ar interface 239is used. 240.It Fl s , -inform Op Ar address Ns Op Ar /cidr 241Behaves like 242.Fl r , -request 243as above, but sends a DHCP INFORM instead of a REQUEST. 244This does not get a lease as such, just notifies the DHCP server of the 245.Ar address 246in use. 247You should also include the optional 248.Ar cidr 249network number in-case the address is not already configured on the interface. 250.Nm 251remains running and pretends it has an infinite lease. 252.Nm 253will not de-configure the interface when it exits. 254If 255.Nm 256fails to contact a DHCP server then it returns a failure instead of falling 257back on IPv4LL. 258.It Fl t , -timeout Ar seconds 259Timeout after 260.Ar seconds , 261instead of the default 30. 262A setting of 0 263.Ar seconds 264causes 265.Nm 266to wait forever to get a lease. 267.It Fl u , -userclass Ar class 268Tags the DHCP message with the userclass 269.Ar class . 270DHCP servers use this give members of the class DHCP options other than the 271default, without having to know things like hardware address or hostname. 272.It Fl v , -vendor Ar code , Ns Ar value 273Add an enscapulated vendor option. 274.Ar code 275should be between 1 and 254 inclusive. 276Examples. 277.Pp 278Set the vendor option 01 with an IP address. 279.D1 dhcpcd \-v 01,192.168.0.2 eth0 280Set the vendor option 02 with a hex code. 281.D1 dhcpcd \-v 02,01:02:03:04:05 eth0 282Do the above and set a third option with a string and not an IP address. 283.D1 dhcpcd \-v 01,192.168.0.2 \-v 02,01:02:03:04:05 \-v 03,\e"192.168.0.2\e" eth0 284.It Fl x , -exit 285This will signal an existing 286.Nm 287process running on the 288.Ar interface 289to deconfigure the 290.Ar interface 291and exit. 292.Nm 293then waits until this process has exited. 294.It Fl D , -duid 295Generate an 296.Li RFC 4361 297compliant clientid. 298This requires persistent storage and not all DHCP servers work with it so it's 299not enabled by default. 300.Nm 301generates the DUID and stores in it 302.Pa @SYSCONFDIR@/dhcpcd.duid 303This file should not be copied to other hosts. 304.It Fl E , -lastlease 305If 306.Nm 307cannot obtain a lease, then try to use the last lease acquired for the 308interface. 309If the 310.Fl p, -persistent 311option is not given then the lease is used if it hasn't expired. 312.It Fl F , -fqdn Ar fqdn 313Requests that the DHCP server updates DNS using FQDN instead of just a 314hostname. 315Valid values for 316.Ar fqdn 317are disable, none, ptr and both. 318The current hostname or the hostname specified using the 319.Fl h , -hostname 320option must be a FQDN. 321.Nm 322itself never does any DNS updates. 323.Nm 324encodes the FQDN hostname as specified in 325.Li RFC1035 . 326.It Fl I , -clientid Ar clientid 327Change the default clientid sent from the interface hardware address. 328If the string is of the format 01:02:03 then it is encoded as hex. 329If not set then none is sent. 330.El 331.Ss Restriciting behaviour 332.Nm 333will try to do as much as it can by default. 334However, there are sometimes situations where you don't want the things to be 335configured exactly how the the DHCP server wants. 336Here are some options that deal with turning these bits off. 337.Bl -tag -width indent 338.It Fl q , -quiet 339Quiet 340.Nm 341on the command line, only warnings and errors will be displayed. 342The messages are still logged though. 343.It Fl A , -noarp 344Don't request or claim the address by ARP. 345This also disables IPv4LL. 346.It Fl B , -nobackground 347Don't run in the background when we acquire a lease. 348This is mainly useful for running under the control of another process, such 349as a debugger or a network manager. 350.It Fl C , -nohook Ar script 351Don't run this hook script. 352Matches full name, or prefixed with 2 numbers optionally ending with 353.Pa .sh . 354.Pp 355So to stop dhcpcd from touching your DNS or MTU settings you would do:- 356.D1 dhcpcd -C resolv.conf -C mtu eth0 357.It Fl G , -nogateway 358Don't set any default routes. 359.It Fl K , -nolink 360Don't receive link messages for carrier status. 361You should only have to use this with buggy device drivers or running 362.Nm 363through a network manager. 364.It Fl L , -noipv4ll 365Don't use IPv4LL (aka APIPA, aka Bonjour, aka ZeroConf). 366.It Fl O , -nooption Ar option 367Don't request the specified option. 368If no option given, then don't request any options other than those to 369configure the interface and routing. 370.It Fl Q , -require Ar option 371Requires the 372.Ar option 373to be present in all DHCP messages, otherwise the message is ignored. 374.It Fl T, -test 375On receipt of OFFER messages just call 376.Pa @SCRIPT@ 377with the reason of TEST which echo's the DHCP variables found in the message 378to the console. 379The interface configuration isn't touched and neither are any configuration 380files. 381.It Fl V, -variables 382Display a list of option codes and the associated variable for use in 383.Xr dhcpcd-run-hooks 8 . 384.It Fl X, -blacklist Ar address 385Ignores all DHCP messages which have this 386.Ar address 387as the server ID. 388This may be expanded in future releases to ignore all packets 389matching either the IP or hardware 390.Ar address . 391.El 392.Sh NOTES 393.Nm 394requires a Berkley Packet Filter, or BPF device on BSD based systems and a 395Linux Socket Filter, or LPF device on Linux based systems. 396.Sh FILES 397.Bl -ohang 398.It Pa @SYSCONFDIR@/dhcpcd.conf 399Configuration file for dhcpcd. 400If you always use the same options, put them here. 401.It Pa @SYSCONFDIR@/dhcpcd.duid 402Text file that holds the DUID used to identify the host. 403.It Pa @SCRIPT@ 404Bourne shell script that is run to configure or deconfigure an interface. 405.It Pa @HOOKDIR@ 406A directory containing bourne shell scripts that are run by the above script. 407Each script can be disabled by using the 408.Fl C , -nohook 409option described above. 410.It Pa @DBDIR@/dhcpcd\- Ns Ar interface Ns .lease 411The actual DHCP message send by the server. We use this when reading the last 412lease and use the files mtime as when it was issued. 413.It Pa /var/run/dhcpcd\- Ns Ar interface Ns .pid 414Stores the PID of 415.Nm 416running on the 417.Ar interface . 418.El 419.Sh SEE ALSO 420.Xr dhcpcd.conf 5 , 421.Xr dhcpcd-run-hooks 8 , 422.Xr resolv.conf 5 , 423.Xr resolvconf 8 , 424.Sh STANDARDS 425RFC 2131, RFC 2132, RFC 2855, RFC 3004, RFC 3361, RFC 3396, RFC 3397, 426RFC 3442, RFC 3927, RFC 4361, RFC 4390, RFC 4702. 427.Sh AUTHORS 428.An Roy Marples <roy@marples.name> 429.Sh BUGS 430Please report them to http://bugs.marples.name 431