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