1.\" Copyright (c) 2006-2012 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 June 7, 2012 26.Dt DHCPCD 8 27.Os 28.Sh NAME 29.Nm dhcpcd 30.Nd an RFC 2131 compliant DHCP client 31.Sh SYNOPSIS 32.Nm 33.Op Fl ABbDdEGgHJKkLnpqTVw 34.Op Fl C , Fl Fl nohook Ar hook 35.Op Fl c , Fl Fl script Ar script 36.Op Fl e , Fl Fl env Ar value 37.Op Fl F , Fl Fl fqdn Ar FQDN 38.Op Fl f , Fl Fl config Ar file 39.Op Fl h , Fl Fl hostname Ar hostname 40.Op Fl I , Fl Fl clientid Ar clientid 41.Op Fl i , Fl Fl vendorclassid Ar vendorclassid 42.Op Fl l , Fl Fl leasetime Ar seconds 43.Op Fl m , Fl Fl metric Ar metric 44.Op Fl O , Fl Fl nooption Ar option 45.Op Fl o , Fl Fl option Ar option 46.Op Fl Q , Fl Fl require Ar option 47.Op Fl r , Fl Fl request Ar address 48.Op Fl S , Fl Fl static Ar value 49.Op Fl s , Fl Fl inform Ar address Ns Op Ar /cidr 50.Op Fl t , Fl Fl timeout Ar seconds 51.Op Fl u , Fl Fl userclass Ar class 52.Op Fl v , Fl Fl vendor Ar code , Ar value 53.Op Fl W , Fl Fl whitelist Ar address Ns Op Ar /cidr 54.Op Fl y , Fl Fl reboot Ar seconds 55.Op Fl X , Fl Fl blacklist Ar address Ns Op Ar /cidr 56.Op Fl Z , Fl Fl denyinterfaces Ar pattern 57.Op Fl z , Fl Fl allowinterfaces Ar pattern 58.Op interface 59.Op ... 60.Nm 61.Fl k , Fl Fl release 62.Op interface 63.Nm 64.Fl U, Fl Fl dumplease 65.Ar interface 66.Nm 67.Fl Fl version 68.Nm 69.Fl x , Fl Fl exit 70.Op interface 71.Sh DESCRIPTION 72.Nm 73is an implementation of the DHCP client specified in 74.Li RFC 2131 . 75.Nm 76gets the host information 77.Po 78IP address, routes, etc 79.Pc 80from a DHCP server and configures the network 81.Ar interface 82of the 83machine on which it is running. 84.Nm 85then runs the configuration script which writes DNS information to 86.Xr resolvconf 8 , 87if available, otherwise directly to 88.Pa /etc/resolv.conf . 89If the hostname is currently blank, (null) or localhost, or 90.Va force_hostname 91is YES or TRUE or 1 then 92.Nm 93sets the hostname to the one supplied by the DHCP server. 94.Nm 95then daemonises and waits for the lease renewal time to lapse. 96It will then attempt to renew its lease and reconfigure if the new lease 97changes. 98.Pp 99.Nm 100is also an implementation of the BOOTP client specified in 101.Li RFC 951 . 102.Pp 103.Nm 104is also an implementation of an IPv6 Router Solicitor as specified in 105.Li RFC 4861 106and 107.Li RFC 6106 . 108.Nm 109can optionally handle address and route management itself, 110and will do so by default if Router Solicitation is disabled in the kernel. 111If 112.Nm 113is managing routes, 114.Nm 115sends Neighbor Solicitions to each advertising router periodically and will 116expire the ones that do not respond. 117.Ss Local Link configuration 118If 119.Nm 120failed to obtain a lease, it probes for a valid IPv4LL address 121.Po 122aka ZeroConf, aka APIPA 123.Pc . 124Once obtained it restarts the process of looking for a DHCP server to get a 125proper address. 126.Pp 127When using IPv4LL, 128.Nm 129nearly always succeeds and returns an exit code of 0. 130In the rare case it fails, it normally means that there is a reverse ARP proxy 131installed which always defeats IPv4LL probing. 132To disable this behaviour, you can use the 133.Fl L , Fl Fl noipv4ll 134option. 135.Ss Multiple interfaces 136If a list of interfaces are given on the command line, then 137.Nm 138only works with those interfaces, otherwise 139.Nm 140discovers available Ethernet interfaces. 141If any interface reports a working carrier then 142.Nm 143will try and obtain a lease before forking to the background, 144otherwise it will fork right away. 145This behaviour can be modified with the 146.Fl b , Fl Fl background 147and 148.Fl w , Fl Fl waitip 149options. 150.Pp 151If a single interface is given then 152.Nm 153only works for that interface and runs as a separate instance. 154The 155.Fl w , Fl Fl waitip 156option is enabled in this instance to maintain compatibility with older 157versions. 158.Pp 159Interfaces are preferred by carrier, DHCP lease/IPv4LL and then lowest metric. 160For systems that support route metrics, each route will be tagged with the 161metric, otherwise 162.Nm 163changes the routes to use the interface with the same route and the lowest 164metric. 165See options below for controlling which interfaces we allow and deny through 166the use of patterns. 167.Ss Hooking into DHCP events 168.Nm 169runs 170.Pa /libexec/dhcpcd-run-hooks , 171or the script specified by the 172.Fl c , Fl Fl script 173option. 174This script runs each script found in 175.Pa /libexec/dhcpcd-hooks 176in a lexical order. 177The default installation supplies the scripts 178.Pa 01-test , 179.Pa 10-mtu , 180.Pa 20-resolv.conf 181and 182.Pa 30-hostname . 183You can disable each script by using the 184.Fl C , Fl Fl nohook 185option. 186See 187.Xr dhcpcd-run-hooks 8 188for details on how these scripts work. 189.Nm 190currently ignores the exit code of the script. 191.Ss Fine tuning 192You can fine-tune the behaviour of 193.Nm 194with the following options: 195.Bl -tag -width indent 196.It Fl b , Fl Fl background 197Background immediately. 198This is useful for startup scripts which don't disable link messages for 199carrier status. 200.It Fl c , Fl Fl script Ar script 201Use this 202.Ar script 203instead of the default 204.Pa /libexec/dhcpcd-run-hooks . 205.It Fl D , Fl Fl duid 206Generate an 207.Li RFC 4361 208compliant clientid. 209This requires persistent storage and not all DHCP servers work with it so it 210is not enabled by default. 211.Nm 212generates the DUID and stores it in 213.Pa /etc/dhcpcd.duid . 214This file should not be copied to other hosts. 215.It Fl d , Fl Fl debug 216Echo debug messages to the stderr and syslog. 217.It Fl E , Fl Fl lastlease 218If 219.Nm 220cannot obtain a lease, then try to use the last lease acquired for the 221interface. 222If the 223.Fl p, Fl Fl persistent 224option is not given then the lease is used if it hasn't expired. 225.It Fl e , Fl Fl env Ar value 226Push 227.Ar value 228to the environment for use in 229.Xr dhcpcd-run-hooks 8 . 230For example, you can force the hostname hook to always set the hostname with 231.Fl e 232.Va force_hostname=YES . 233.It Fl g , Fl Fl reconfigure 234.Nm 235will re-apply IP address, routing and run 236.Xr dhcpcd-run-hooks 8 237for each interface. 238This is useful so that a 3rd party such as PPP or VPN can change the routing 239table and / or DNS, etc and then instruct 240.Nm 241to put things back afterwards. 242.Nm 243does not read a new configuration when this happens - you should rebind if you 244need that functionality. 245.It Fl F , Fl Fl fqdn Ar fqdn 246Requests that the DHCP server updates DNS using FQDN instead of just a 247hostname. 248Valid values for 249.Ar fqdn 250are disable, none, ptr and both. 251.Nm 252itself never does any DNS updates. 253.Nm 254encodes the FQDN hostname as specified in 255.Li RFC1035 . 256.It Fl f , Fl Fl config Ar file 257Specify a config to load instead of 258.Pa /etc/dhcpcd.conf . 259.Nm 260always processes the config file before any command line options. 261.It Fl h , Fl Fl hostname Ar hostname 262Sends 263.Ar hostname 264to the DHCP server so it can be registered in DNS. 265If 266.Ar hostname 267is an empty string then the current system hostname is sent. 268If 269.Ar hostname 270is a FQDN (ie, contains a .) then it will be encoded as such. 271.It Fl I , Fl Fl clientid Ar clientid 272Send the 273.Ar clientid . 274If the string is of the format 01:02:03 then it is encoded as hex. 275For interfaces whose hardware address is longer than 8 bytes, or if the 276.Ar clientid 277is an empty string then 278.Nm 279sends a default 280.Ar clientid 281of the hardware family and the hardware address. 282.It Fl i , Fl Fl vendorclassid Ar vendorclassid 283Override the 284.Ar vendorclassid 285field sent. 286The default is 287dhcpcd-<version>:<os>:<machine>:<platform>. 288For example 289.D1 dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386 290If not set then none is sent. 291Some badly configured DHCP servers reject unknown vendorclassids. 292To work around it, try and impersonate Windows by using the MSFT vendorclassid. 293.It Fl k , Fl Fl release 294This causes an existing 295.Nm 296process running on the 297.Ar interface 298to release its lease, de-configure the 299.Ar interface 300and then exit. 301.Nm 302then waits until this process has exited. 303.It Fl l , Fl Fl leasetime Ar seconds 304Request a specific lease time in 305.Ar seconds . 306By default 307.Nm 308does not request any lease time and leaves it in the hands of the 309DHCP server. 310.It Fl m , Fl Fl metric Ar metric 311Metrics are used to prefer an interface over another one, lowest wins. 312.Nm 313will supply a default metic of 200 + 314.Xr if_nametoindex 3 . 315An extra 100 will be added for wireless interfaces. 316.It Fl n , Fl Fl rebind 317Notifies 318.Nm 319to reload its configuration and rebind its interfaces. 320If 321.Nm 322is not running, then it starts up as normal. 323.It Fl o , Fl Fl option Ar option 324Request the DHCP 325.Ar option 326variable for use in 327.Pa /libexec/dhcpcd-run-hooks . 328.It Fl p , Fl Fl persistent 329.Nm 330normally de-configures the 331.Ar interface 332and configuration when it exits. 333Sometimes, this isn't desirable if, for example, you have root mounted over 334NFS. 335You can use this option to stop this from happening. 336.It Fl r , Fl Fl request Op Ar address 337Request the 338.Ar address 339in the DHCP DISCOVER message. 340There is no guarantee this is the address the DHCP server will actually give. 341If no 342.Ar address 343is given then the first address currently assigned to the 344.Ar interface 345is used. 346.It Fl s , Fl Fl inform Op Ar address Ns Op Ar /cidr 347Behaves like 348.Fl r , Fl Fl request 349as above, but sends a DHCP INFORM instead of DISCOVER/REQUEST. 350This does not get a lease as such, just notifies the DHCP server of the 351.Ar address 352in use. 353You should also include the optional 354.Ar cidr 355network number in case the address is not already configured on the interface. 356.Nm 357remains running and pretends it has an infinite lease. 358.Nm 359will not de-configure the interface when it exits. 360If 361.Nm 362fails to contact a DHCP server then it returns a failure instead of falling 363back on IPv4LL. 364.It Fl t , Fl Fl timeout Ar seconds 365Timeout after 366.Ar seconds , 367instead of the default 30. 368A setting of 0 369.Ar seconds 370causes 371.Nm 372to wait forever to get a lease. 373.It Fl u , Fl Fl userclass Ar class 374Tags the DHCP message with the userclass 375.Ar class . 376DHCP servers use this to give members of the class DHCP options other than the 377default, without having to know things like hardware address or hostname. 378.It Fl v , Fl Fl vendor Ar code , Ns Ar value 379Add an encapsulated vendor option. 380.Ar code 381should be between 1 and 254 inclusive. 382To add a raw vendor string, omit 383.Ar code 384but keep the comma. 385Examples. 386.Pp 387Set the vendor option 01 with an IP address. 388.D1 dhcpcd \-v 01,192.168.0.2 eth0 389Set the vendor option 02 with a hex code. 390.D1 dhcpcd \-v 02,01:02:03:04:05 eth0 391Set the vendor option 03 with an IP address as a string. 392.D1 dhcpcd \-v 03,\e"192.168.0.2\e" eth0 393Set un-encapsulated vendor option to hello world. 394.D1 dhcpcd \-v ,"hello world" eth0 395.It Fl Fl version 396Display both program version and copyright information. 397.Nm 398then exits before doing any configuration. 399.It Fl w , Fl Fl waitip 400Wait for an address to be assigned before forking to the background. 401.It Fl x , Fl Fl exit 402This will signal an existing 403.Nm 404process running on the 405.Ar interface 406to de-configure the 407.Ar interface 408and exit. 409.Nm 410then waits until this process has exited. 411.It Fl y , Fl Fl reboot Ar seconds 412Allow 413.Ar reboot 414seconds before moving to the discover phase if we have an old lease to use. 415The default is 5 seconds. 416A setting of 0 seconds causes 417.Nm 418to skip the reboot phase and go straight into discover. 419.El 420.Ss Restricting behaviour 421.Nm 422will try to do as much as it can by default. 423However, there are sometimes situations where you don't want the things to be 424configured exactly how the the DHCP server wants. 425Here are some options that deal with turning these bits off. 426.Bl -tag -width indent 427.It Fl A , Fl Fl noarp 428Don't request or claim the address by ARP. 429This also disables IPv4LL. 430.It Fl B , Fl Fl nobackground 431Don't run in the background when we acquire a lease. 432This is mainly useful for running under the control of another process, such 433as a debugger or a network manager. 434.It Fl C , Fl Fl nohook Ar script 435Don't run this hook script. 436Matches full name, or prefixed with 2 numbers optionally ending with 437.Pa .sh . 438.Pp 439So to stop 440.Nm 441from touching your DNS or MTU settings you would do:- 442.D1 dhcpcd -C resolv.conf -C mtu eth0 443.It Fl G , Fl Fl nogateway 444Don't set any default routes. 445.It Fl H , Fl Fl xidhwaddr 446Use the last four bytes of the hardware address as the DHCP xid instead 447of a randomly generated number. 448.It Fl J , Fl Fl broadcast 449Instructs the DHCP server to broadcast replies back to the client. 450Normally this is only set for non Ethernet interfaces, 451such as FireWire and InfiniBand. 452In most instances, 453.Nm 454will set this automatically. 455.It Fl K , Fl Fl nolink 456Don't receive link messages for carrier status. 457You should only have to use this with buggy device drivers or running 458.Nm 459through a network manager. 460.It Fl L , Fl Fl noipv4ll 461Don't use IPv4LL (aka APIPA, aka Bonjour, aka ZeroConf). 462.It Fl O , Fl Fl nooption Ar option 463Don't request the specified option. 464If no option given, then don't request any options other than those to 465configure the interface and routing. 466.It Fl Q , Fl Fl require Ar option 467Requires the 468.Ar option 469to be present in all DHCP messages, otherwise the message is ignored. 470To enforce that 471.Nm 472only responds to DHCP servers and not BOOTP servers, you can 473.Fl Q 474.Ar dhcp_message_type . 475.It Fl q , Fl Fl quiet 476Quiet 477.Nm 478on the command line, only warnings and errors will be displayed. 479The messages are still logged though. 480.It Fl S, Fl Fl static Ar value 481Configures a static 482.Ar value . 483If you set 484.Ic ip_address 485then 486.Nm 487will not attempt to obtain a lease and just use the value for the address with 488an infinite lease time. 489.Pp 490Here is an example which configures a static address, routes and dns. 491.D1 dhcpcd -S ip_address=192.168.0.10/24 \e 492.D1 -S routers=192.168.0.1 \e 493.D1 -S domain_name_servers=192.168.0.1 \e 494.D1 eth0 495.It Fl T, Fl Fl test 496On receipt of DHCP messages just call 497.Pa /libexec/dhcpcd-run-hooks 498with the reason of TEST which echos the DHCP variables found in the message 499to the console. 500The interface configuration isn't touched and neither are any configuration 501files. 502To test INFORM the interface needs to be configured with the desired address 503before starting 504.Nm . 505.It Fl U, Fl Fl dumplease Ar interface 506Dumps the last lease for the 507.Ar interface 508to stdout. 509.Ar interface 510could also be a path to a DHCP wire formatted file. 511.It Fl V, Fl Fl variables 512Display a list of option codes and the associated variable for use in 513.Xr dhcpcd-run-hooks 8 . 514Variables are prefixed with new_ and old_ unless the option number is -. 515Variables without an option are part of the DHCP message and cannot be 516directly requested. 517.It Fl W, Fl Fl whitelist Ar address Ns Op /cidr 518Only accept packets from 519.Ar address Ns Op /cidr . 520.Fl X, Fl Fl blacklist 521is ignored if 522.Fl W, Fl Fl whitelist 523is set. 524.It Fl X, Fl Fl blacklist Ar address Ns Op Ar /cidr 525Ignore all packets from 526.Ar address Ns Op Ar /cidr . 527.It Fl Z , Fl Fl denyinterfaces Ar pattern 528When discovering interfaces, the interface name must not match 529.Ar pattern 530which is a space or comma separated list of patterns passed to 531.Xr fnmatch 3 . 532.It Fl z , Fl Fl allowinterfaces Ar pattern 533When discovering interfaces, the interface name must match 534.Ar pattern 535which is a space or comma separated list of patterns passed to 536.Xr fnmatch 3 . 537If the same interface is matched in 538.Fl Z , Fl Fl denyinterfaces 539then it is still denied. 540.El 541.Sh 3RDPARTY LINK MANAGEMENT 542Some interfaces require configuration by 3rd parties, such as PPP or VPN. 543When an interface configuration in 544.Nm 545is marked as STATIC or INFORM without an address then 546.Nm 547will monitor the interface until an address is added or removed from it and 548act accordingly. 549For point to point interfaces (like PPP), a default route to its 550destination is automatically added to the configuration. 551If the point to point interface is configured for INFORM, then 552.Nm 553unicasts INFORM to the destination, otherwise it defaults to STATIC. 554.Sh NOTES 555.Nm 556requires a Berkley Packet Filter, or BPF device on BSD based systems and a 557Linux Socket Filter, or LPF device on Linux based systems. 558.Sh FILES 559.Bl -ohang 560.It Pa /etc/dhcpcd.conf 561Configuration file for dhcpcd. 562If you always use the same options, put them here. 563.It Pa /etc/dhcpcd.duid 564Text file that holds the DUID used to identify the host. 565.It Pa /libexec/dhcpcd-run-hooks 566Bourne shell script that is run to configure or de-configure an interface. 567.It Pa /libexec/dhcpcd-hooks 568A directory containing bourne shell scripts that are run by the above script. 569Each script can be disabled by using the 570.Fl C , Fl Fl nohook 571option described above. 572.It Pa /var/db/dhcpcd\- Ns Ar interface Ns .lease 573The actual DHCP message send by the server. 574We use this when reading the last 575lease and use the files mtime as when it was issued. 576.It Pa /var/run/dhcpcd.pid 577Stores the PID of 578.Nm 579running on all interfaces. 580.It Pa /var/run/dhcpcd\- Ns Ar interface Ns .pid 581Stores the PID of 582.Nm 583running on the 584.Ar interface . 585.El 586.Sh SEE ALSO 587.Xr fnmatch 3 , 588.Xr if_nametoindex 3 , 589.Xr dhcpcd.conf 5 , 590.Xr resolv.conf 5 , 591.Xr dhcpcd-run-hooks 8 , 592.Xr resolvconf 8 593.Sh STANDARDS 594RFC 951, RFC 1534, RFC 2131, RFC 2132, RFC 2855, RFC 3004, RFC 3361, RFC 3396, 595RFC 3397, RFC 3442, RFC 3927, RFC 4361, RFC 4390, RFC 4702, RFC 4861, RFC 5969, 596RFC 6106. 597.Sh AUTHORS 598.An Roy Marples Aq roy@marples.name 599.Sh BUGS 600Please report them to 601.Lk http://roy.marples.name/projects/dhcpcd 602