1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2006-2023 Roy Marples 4.\" All rights reserved 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd August 31, 2022 28.Dt DHCPCD.CONF 5 29.Os 30.Sh NAME 31.Nm dhcpcd.conf 32.Nd dhcpcd configuration file 33.Sh DESCRIPTION 34Although 35.Nm dhcpcd 36can do everything from the command line, there are cases where it's just easier 37to do it once in a configuration file. 38Most of the options found in 39.Xr dhcpcd 8 40can be used here. 41The first word on the line is the option and the rest of the line is the value. 42Leading and trailing whitespace for the option and value are trimmed. 43You can escape characters in the value using the \\ character. 44Comments can be prefixed with the # character. 45String values should be quoted with the " character. 46.Pp 47Here's a list of available options: 48.Bl -tag -width indent 49.It Ic allowinterfaces Ar pattern 50When discovering interfaces, the interface name must match 51.Ar pattern 52which is a space or comma separated list of patterns passed to 53.Xr fnmatch 3 . 54If the same interface is matched in 55.Ic denyinterfaces 56then it is still denied. 57.It Ic denyinterfaces Ar pattern 58When discovering interfaces, the interface name must not match 59.Ar pattern 60which is a space or comma separated list of patterns passed to 61.Xr fnmatch 3 . 62.It Ic anonymous 63Enables Anonymity Profiles for DHCP, RFC 7844. 64Any DUID is ignored and ClientID is set to LL only. 65All non essential options are then masked at this point, 66but they could be unmasked by explicitly requesting the option 67.Sy after 68the 69.Ic anonymous 70option is processed. 71As such, the 72.Ic anonymous 73option 74.Sy should 75be the last option in the configuration unless you really want to 76send something which could identify you. 77.Nm dhcpcd 78will not try and reboot an old lease, it will go straight into 79DISCOVER/SOLICIT. 80.It Ic randomise_hwaddr 81Forces a hardware address randomisation when the interface is brought up 82or when the carrier is lost. 83This is generally used in tandem with the anonymous option. 84.It Ic arping Ar address Op address 85.Nm dhcpcd 86will arping each address in order before attempting DHCP. 87If an address is found, we will select the replying hardware address as the 88profile, otherwise the IP address. 89Example: 90.Pp 91.D1 interface bge0 92.D1 arping 192.168.0.1 93.Pp 94.D1 # My specific 192.168.0.1 network 95.D1 profile dd:ee:aa:dd:bb:ee 96.D1 static ip_address=192.168.0.10/24 97.Pp 98.D1 # A generic 192.168.0.1 network 99.D1 profile 192.168.0.1 100.D1 static ip_address=192.168.0.98/24 101.It Ic authprotocol Ar protocol Op Ar algorithm Op Ar rdm 102Authenticate DHCP messages. 103See the Supported Authentication Protocols section. 104If 105.Ar protocol 106is 107.Ar token 108then 109.Ar algorithm is 110snd_secretid/rcv_secretid so you can send and receive different tokens. 111.It Ic authtoken Ar secretid Ar realm Ar expire Ar key 112Define a shared key for use in authentication. 113.Ar realm 114can be "" to for use with the 115.Ar delayed 116protocol. 117.Ar expire 118is the date the token expires and should be formatted "yyy-mm-dd HH:MM". 119You can use the keyword 120.Ar forever 121or 122.Ar 0 123which means the token never expires. 124For the token protocol, 125.Ar secretid 126needs to be 0 and 127.Ar realm 128needs to be "". 129If 130.Nm dhcpcd 131has the error 132.D1 dhcp_auth_encode: Invalid argument 133then it means that 134.Nm dhcpcd 135could not find the correct authentication token in your configuration. 136.It Ic background 137Fork to the background immediately. 138This is useful for startup scripts which don't disable link messages for 139carrier status. 140.It Ic blacklist Ar address Ns Op /cidr 141Ignores all packets from 142.Ar address Ns Op /cidr . 143.It Ic whitelist Ar address Ns Op /cidr 144Only accept packets from 145.Ar address Ns Op /cidr . 146.Ic blacklist 147is ignored if 148.Ic whitelist 149is set. 150.It Ic bootp 151Be a BOOTP client. 152Basically, this just doesn't send a DHCP Message Type option and will only 153interact with a BOOTP server. 154All other DHCP options still work. 155.It Ic broadcast 156Instructs the DHCP server to broadcast replies back to the client. 157Normally this is only set for non-Ethernet interfaces, 158such as FireWire and InfiniBand. 159In most cases, 160.Nm dhcpcd 161will set this automatically. 162.It Ic controlgroup Ar group 163Sets the group ownership of 164.Pa /var/run/dhcpcd/sock 165so that users other than root can connect to 166.Nm dhcpcd . 167.It Ic debug 168Echo debug messages to the stderr and syslog. 169.It Ic dev Ar value 170Load the 171.Ar value 172.Pa /dev 173management module. 174.Nm dhcpcd 175will load the first one found to work, if any. 176.It Ic env Ar value 177Push 178.Ar value 179to the environment for use in 180.Xr dhcpcd-run-hooks 8 . 181For example, you can force the hostname hook to always set the hostname with 182.Ic env 183.Va force_hostname=YES . 184Or set which driver 185.Xr wpa_supplicant 8 186should use with 187.Ic env 188.Va wpa_supplicant_driver=nl80211 189.Pp 190If the hostname is set, it will be will set to the FQDN if possible as per 191RFC 4702, section 3.1. 192If the FQDN option is missing, 193.Nm dhcpcd 194will still try and set a FQDN from the hostname and domain options for 195consistency. 196To override this, set 197.Ic env 198.Va hostname_fqdn=[YES|NO|SERVER] . 199A value of 200.Va SERVER 201means just what the server says, don't manipulate it. 202This could lead to an inconsistent hostname on a DHCPv4 and DHCPv6 network 203where the DHCPv4 hostname is short and the DHCPv6 has an FQDN. 204DHCPv6 has no hostname option. 205.It Ic clientid Ar string 206Send the 207.Ar clientid . 208If the string is of the format 01:02:03 then it is encoded as hex. 209For interfaces whose hardware address is longer than 8 bytes, or if the 210.Ar clientid 211is an empty string then 212.Nm dhcpcd 213sends a default 214.Ar clientid 215of the hardware family and the hardware address. 216.It Ic duid Op ll | lt | uuid | value 217Use a DHCP Unique Identifier. 218If a system UUID is available, that will be used to create a DUID-UUID, 219otherwise if persistent storage is available then a DUID-LLT 220(link local address + time) is generated, 221otherwise DUID-LL is generated (link local address). 222The DUID type can be hinted as an optional parameter if the file 223.Pa /var/db/dhcpcd/duid 224does not exist. 225If not 226.Va ll , 227.Va lt 228or 229.Va uuid 230then 231.Va value 232will be converted from 00:11:22:33 format. 233This, plus the IAID will be used as the 234.Ic clientid . 235The DUID generated will be held in 236.Pa /var/db/dhcpcd/duid 237and should not be copied to other hosts. 238This file also takes precedence over the above rules except for setting a value. 239.It Ic iaid Ar iaid 240Set the Interface Association Identifier to 241.Ar iaid . 242This option must be used in an 243.Ic interface 244block. 245This defaults to the VLANID (prefixed with 0xff) for the interface if set, 246otherwise the last 4 bytes of the hardware address assigned to the 247interface. 248Each instance of this should be unique within the scope of the client and 249.Nm dhcpcd 250warns if a conflict is detected. 251If there is a conflict, it is only a problem if the conflicted IAIDs are 252used on the same network. 253.It Ic dhcp 254Enable DHCP on the interface, on by default. 255.It Ic dhcp6 256Enable DHCPv6 on the interface, on by default. 257.It Ic ipv4 258Enable IPv4 on the interface, on by default. 259.It Ic ipv6 260Enable IPv6 on the interface, on by default. 261.It Ic request Op Ar address 262Request the 263.Ar address 264in the DHCP DISCOVER message. 265There is no guarantee this is the address the DHCP server will actually give. 266If no 267.Ar address 268is given then the first address currently assigned to the 269.Ar interface 270is used. 271.It Ic inform Op Ar address Ns Op Ar /cidr Ns Op Ar /broadcast_address 272Behaves like 273.Ic request 274as above, but sends a DHCP INFORM instead of DISCOVER/REQUEST. 275This does not get a lease as such, just notifies the DHCP server of the 276.Ar address 277in use. 278You should also include the optional 279.Ar cidr 280network number in case the address is not already configured on the interface. 281.Nm dhcpcd 282remains running and pretends it has an infinite lease. 283.Nm dhcpcd 284will not de-configure the interface when it exits. 285If 286.Nm dhcpcd 287fails to contact a DHCP server then it returns a failure instead of falling 288back on IPv4LL. 289.It Ic inform6 290Performs a DHCPv6 Information Request. 291No address is requested or specified, but all other DHCPv6 options are allowed. 292This is normally performed automatically when an IPv6 Router Advertisement 293indicates that the client should perform this operation. 294This option is only needed when 295.Nm dhcpcd 296is not processing IPv6 RA messages and the need for a DHCPv6 Information Request 297exists. 298.It Ic persistent 299.Nm dhcpcd 300normally de-configures the interface and configuration when it exits. 301Sometimes, this isn't desirable if, for example, you have root mounted over 302NFS or SSH clients connect to this host and they need to be notified of 303the host shutting down. 304You can use this option to stop this from happening. 305.It Ic fallback Ar profile 306Fall back to using this profile if DHCP fails. 307This allows you to configure a static profile instead of using ZeroConf. 308.It Ic hostname Ar name 309Sends the hostname 310.Ar name 311to the DHCP server so it can be registered in DNS. 312If 313.Ar name 314is an empty string then the current system hostname is sent. 315If 316.Ar name 317is a FQDN (i.e., contains a .) then it will be encoded as such. 318.It Ic hostname_short 319Sends the short hostname to the DHCP server instead of the FQDN. 320This is useful because DHCP servers will not register the FQDN in their 321DNS if the domain part does not match theirs. 322.Pp 323Also, see the 324.Ic env 325option above to control how the hostname is set on the host. 326.It Ic ia_na Op Ar iaid Op / address 327Request a DHCPv6 Normal Address for 328.Ar iaid . 329.Ar iaid 330defaults to the 331.Ic iaid 332option as described above. 333You can request more than one ia_na by specifying a unique 334.Ar iaid 335for each one. 336.It Ic ia_ta Op Ar iaid 337Request a DHCPv6 Temporary Address for 338.Ar iaid . 339You can request more than one ia_ta by specifying a unique 340.Ar iaid 341for each one. 342.It Ic ia_pd Op Ar iaid Oo / Ar prefix / Ar prefix_len Oc Op Ar interface Op / Ar sla_id Op / Ar prefix_len Op / Ar suffix 343Request a DHCPv6 Delegated Prefix for 344.Ar iaid . 345This option must be used in an 346.Ic interface 347block. 348Unless a 349.Ar sla_id 350of 0 is assigned with the same resultant prefix length as the delegation, 351a reject route is installed for the Delegated Prefix to 352stop unallocated addresses being resolved upstream. 353If no 354.Ar interface 355is given then we will assign a prefix to every other interface with a 356.Ar sla_id 357equivalent to the interface index assigned by the OS. 358Otherwise addresses are only assigned for each 359.Ar interface 360and 361.Ar sla_id . 362Each assigned address will have a 363.Ar suffix , 364defaulting to 1. 365If the 366.Ar suffix 367is 0 then a SLAAC address is assigned. 368You cannot assign a prefix to the requesting interface unless the 369DHCPv6 server supports the 370.Li RFC 6603 371Prefix Exclude Option. 372.Nm dhcpcd 373has to be running for all the interfaces it is delegating to. 374A default 375.Ar prefix_len 376of 64 is assumed, unless the maximum 377.Ar sla_id 378does not fit. 379In this case 380.Ar prefix_len 381is increased to the highest multiple of 8 that can accommodate the 382.Ar sla_id . 383.Ar sla_id 384is an integer which must be unique inside the 385.Ar iaid 386and is added to the prefix which must fit inside 387.Ar prefix_len 388less the length of the delegated prefix. 389You can specify multiple 390.Ar interface / 391.Ar sla_id / 392.Ar prefix_len 393per 394.Ic ia_pd , 395space separated. 396IPv6RS should be disabled globally when requesting a Prefix Delegation. 397.Pp 398In the following example eth0 is the externally facing interface to be 399configured for both IPv4 and IPv6. 400The DHCPv4 server will provide us with an IPv4 address and a default route. 401The DHCPv6 server is going to provide us with an IPv6 address, a default 402route and a /64 subnet to be delegated to the internal interface. 403The eth1 interface will be automatically configured 404for IPv6 using the first address (::1) from the delegated prefix. 405A second prefix is requested and assigned to two other interfaces. 406.Xr rtadvd 8 407can be used with an empty configuration file on eth1, eth2 and eth3, 408to provide automatic 409IPv6 address configuration for the internal network. 410.Bd -literal 411noipv6rs # disable routing solicitation 412denyinterfaces eth2 # Don't touch eth2 at all 413interface eth0 414 ipv6rs # enable routing solicitation for eth0 415 ia_na 1 # request an IPv6 address 416 ia_pd 2 eth1/0 # request a PD and assign it to eth1 417 ia_pd 3 eth2/1 eth3/2 # req a PD and assign it to eth2 and eth3 418.Ed 419.It Ic ipv4only 420Only configure IPv4. 421.It Ic ipv6only 422Only configure IPv6. 423.It Ic fqdn Op disable | none | ptr | both 424.Ar none 425will not ask the DHCP server to update DNS. 426.Ar ptr 427just asks the DHCP server to update the PTR 428record of the host in DNS, whereas 429.Ar both 430also updates the A record. 431.Ar disable 432will disable the FQDN option. 433The default is 434.Ar both . 435.Nm dhcpcd 436itself never does any DNS updates. 437.Nm dhcpcd 438encodes the FQDN hostname as specified in 439.Li RFC 1035 . 440.It Ic interface Ar interface 441Subsequent options are only parsed for this 442.Ar interface . 443.It Ic ipv6ra_autoconf 444Generate SLAAC addresses for each Prefix advertised by an IPv6 445Router Advertisement message with the Auto flag set. 446On by default. 447.It Ic ipv6ra_noautoconf 448Disables the above option. 449.It Ic ipv6ra_fork 450By default, when 451.Nm dhcpcd 452receives an IPv6 Router Advertisement, 453.Nm dhcpcd 454will only fork to the background if the RA contains at least one unexpired 455RDNSS option and a valid prefix or no DHCPv6 instruction. 456Set this option so to make 457.Nm dhcpcd 458always fork on a RA. 459.It Ic ipv6rs 460Enables IPv6 Router Advertisement solicitation. 461This is on by default, but is documented here in the case where it is disabled 462globally but needs to be enabled for one interface. 463.It Ic leasetime Ar seconds 464Request DHCP a lease time of 465.Ar seconds . 466.Ar -1 467represents an infinite lease time. 468By default 469.Nm dhcpcd 470does not request any lease time and leaves it in the hands of the 471DHCP server. 472It is not possible to request a DHCPv6 lease time as this is not RFC compliant. 473See RFC 8415 21.4, 21.6, 21.21 and 21.22. 474.It Ic link_rcvbuf Ar size 475Override the size of the link receive buffer from the kernel default. 476While 477.Nm dhcpcd 478will recover from link buffer overflows, 479this may not be desirable on heavily loaded systems. 480.It Ic logfile Ar logfile 481Writes to the specified 482.Ar logfile . 483.Nm dhcpcd 484still writes to 485.Xr syslog 3 . 486The 487.Ar logfile 488is reopened when 489.Nm dhcpcd 490receives the 491.Dv SIGUSR2 492signal. 493.It Ic metric Ar metric 494Metrics are used to prefer an interface over another one, lowest wins. 495.Nm dhcpcd 496will supply a default metric of 1000 + 497.Xr if_nametoindex 3 . 498This will be offset by 2000 for wireless interfaces, with additional offsets 499of 1000000 for IPv4LL and 2000000 for roaming interfaces. 500.It Ic mudurl Ar url 501Specifies the URL for a Manufacturer Usage Description (MUD). 502The description is used by upstream network devices to instantiate any 503desired access lists. 504See draft-ietf-opsawg-mud for more information. 505.It Ic noalias 506Any pre-existing IPv4 addresses will be removed from the interface when 507adding a new IPv4 address. 508.It Ic noarp 509Don't send any ARP requests. 510This also disables IPv4LL. 511.It Ic noauthrequired 512Don't require authentication even though we requested it. 513Also allows FORCERENEW and RECONFIGURE messages without authentication. 514.It Ic nodelay 515Don't delay for an initial randomised time when starting protocols. 516.It Ic nodev 517Don't load 518.Pa /dev 519management modules. 520.It Ic nodhcp 521Don't start DHCP or listen to DHCP messages. 522This is only useful when allowing IPv4LL. 523.It Ic nodhcp6 524Don't start DHCPv6 or listen to DHCPv6 messages. 525Normally DHCPv6 is started by an IPv6 Router Advertisement instruction or 526configuration. 527.It Ic nogateway 528Don't install any default routes. 529.It Ic gateway 530Install a default route if available (default). 531.It Ic nohook Ar script 532Don't run this hook script. 533Matches full name, or prefixed with 2 numbers optionally ending with 534.Pa .sh . 535.Pp 536So to stop 537.Nm dhcpcd 538from touching your DNS settings or starting wpa_supplicant you would do:- 539.D1 nohook resolv.conf, wpa_supplicant 540.It Ic noipv4 541Don't attempt to configure an IPv4 address. 542.It Ic noipv4ll 543Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP. 544See 545.Rs 546.%T "RFC 3927" 547.Re 548.It Ic noipv6 549Don't solicit or accept IPv6 Router Advertisements and DHCPv6. 550.It Ic noipv6rs 551Don't solicit or accept IPv6 Router Advertisements. 552.It Ic nolink 553Don't receive link messages about carrier status. 554You should only set this for buggy interface drivers. 555.It Ic noup 556Don't bring the interface up when in manager mode. 557.It Ic option Ar option 558Requests the 559.Ar option 560from the server. 561It can be a variable to be used in 562.Xr dhcpcd-run-hooks 8 563or the numerical value. 564You can specify more 565.Ar option Ns s 566separated by commas, spaces or more 567.Ic option 568lines. 569Prepend dhcp6_ to 570.Ar option 571to request a DHCPv6 option. 572If no DHCPv6 options are configured, 573then DHCPv4 options are mapped to equivalent DHCPv6 options. 574.Pp 575Prepend nd_ to 576.Ar option 577to handle ND options, but this only works for the 578.Ic nooption , 579.Ic reject 580and 581.Ic require 582options. 583.Pp 584To see a list of options you can use, call 585.Nm dhcpcd 586with the 587.Fl V , Fl Fl variables 588argument. 589.It Ic nooption Ar option 590Remove the option from the message before it's processed. 591.It Ic require Ar option 592Requires the 593.Ar option 594to be present in all messages, otherwise the message is ignored. 595To enforce that 596.Nm dhcpcd 597only responds to DHCP servers and not BOOTP servers, you can 598.Ic require 599.Ar dhcp_message_type . 600This isn't an exact science though because a BOOTP server can send DHCP-like 601options. 602.It Ic reject Ar option 603Reject a message that contains the 604.Ar option . 605This is useful when you cannot use 606.Ic require 607to select / de-select BOOTP messages. 608.It Ic destination Ar option 609If 610.Nm 611detects an address added to a point to point interface (PPP, TUN, etc) then 612it will set the listed DHCP options to the destination address of the 613interface. 614.It Ic profile Ar name 615Subsequent options are only parsed for this profile 616.Ar name . 617.It Ic quiet 618Suppress any dhcpcd output to the console, except for errors. 619.It Ic reboot Ar seconds 620Allow 621.Ar reboot 622seconds before moving to the DISCOVER phase if we have an old lease to use. 623Allow 624.Ar reboot 625seconds before starting fallback states from the DISCOVER phase. 626IPv4LL is started when the first 627.Ar reboot 628timeout is reached. 629The default is 5 seconds. 630A setting of 0 seconds causes 631.Nm 632to skip the reboot phase and go straight into DISCOVER. 633This is desirable for mobile users because if you change from network A to 634network B and they use the same subnet and the address from network A isn't 635in use on network B, then the DHCP server will remain silent even if 636authoritative which means 637.Nm dhcpcd 638will timeout before moving back to the DISCOVER phase. 639This has no effect on DHCPv6 other than skipping the reboot phase. 640.It Ic release 641.Nm dhcpcd 642will release the lease prior to stopping the interface. 643.It Ic script Ar script 644Use 645.Ar script 646instead of the default 647.Pa /usr/libexec/dhcpcd-run-hooks . 648.It Ic ssid Ar ssid 649Subsequent options are only parsed for this wireless 650.Ar ssid . 651.It Ic slaac Ic hwaddr | Ic private | Ic token Ar token Op Ic temp | Ic temporary 652Selects the interface identifier used for SLAAC generated IPv6 addresses. 653If 654.Ic private 655is used, a RFC 7217 address is generated. 656If 657.Ic token Ar token 658is used then the token is combined with the prefix to make the final address. 659The 660.Ic temporary 661directive will create a temporary address for the prefix as well. 662.It Ic static Ar value 663Configures a static 664.Ar value . 665If you set 666.Ic ip_address 667then 668.Nm dhcpcd 669will not attempt to obtain a lease and will just use the value for the address 670with an infinite lease time. 671If you set an empty value this removes all prior static allocations to 672the same value. 673This is useful when using profiles and in the case of 674.Ic ip_address 675it will remove the static allocation. 676Note that setting 0.0.0.0 keeps the static allocation but waits for a 3rdparty 677to configure the address. 678If you set 679.Ic ip6_address , 680.Nm dhcpcd 681will continue auto-configuration as normal. 682.Pp 683Here is an example which configures two static address, overriding the default 684IPv4 broadcast address, an IPv4 router, DNS and disables IPv6 auto-configuration. 685You could also use the 686.Ic inform6 687command here if you wished to obtain more information via DHCPv6. 688For IPv4, you should use the 689.Ic inform Ar ipaddress 690option instead of setting a static address. 691.D1 interface eth0 692.D1 noipv6rs 693.D1 static ip_address=192.168.0.10/24 694.D1 static broadcast_address=192.168.0.63 695.D1 static ip6_address=fd51:42f8:caae:d92e::ff/64 696.D1 static routers=192.168.0.1 697.D1 static domain_name_servers=192.168.0.1 fd51:42f8:caae:d92e::1 698.Pp 699Here is an example for PPP which gives the destination a default route. 700It uses the special 701.Ar destination 702keyword to insert the destination address 703into the value. 704.D1 interface ppp0 705.D1 static ip_address=0.0.0.0 706.D1 destination routers 707.It Ic timeout Ar seconds 708Time out after 709.Ar seconds , 710instead of the default 30. 711A setting of 0 712.Ar seconds 713causes 714.Nm dhcpcd 715to wait forever to get a lease. 716If 717.Nm dhcpcd 718is working on a single interface then 719.Nm dhcpcd 720will exit when a timeout occurs, otherwise 721.Nm dhcpcd 722will fork into the background. 723If using IPv4LL then 724.Nm dhcpcd 725start the IPv4LL process after the timeout and then wait a little longer 726before really timing out. 727.It Ic userclass Ar string 728Tag the DHCPv4 message with the userclass. 729You can specify more than one. 730.It Ic msuserclass Ar string 731Tag the DHCPv4 mesasge with the Microsoft userclass. 732Unlike the 733.Ic userclass 734option, this one can only be added once. 735It should only be used for Microsoft DHCP servers and the 736.Ic vendorclassid 737should be set to "MSFT 98" or "MSFT 5.0". 738This option is not RFC compliant. 739.It Ic vendor Ar code , Ns Ar value 740Add an encapsulated vendor option. 741.Ar code 742should be between 1 and 254 inclusive. 743To add a raw vendor string, omit 744.Ar code 745but keep the comma. 746Examples. 747.Pp 748Set the vendor option 01 with an IP address. 749.D1 vendor 01,192.168.0.2 750Set the vendor option 02 with a hex code. 751.D1 vendor 02,01:02:03:04:05 752Set the vendor option 03 with an IP address as a string. 753.D1 vendor 03,\e"192.168.0.2\e" 754Set un-encapsulated vendor option to hello world. 755.D1 vendor ,"hello world" 756.It Ic vendorclassid Ar string 757Set the DHCP Vendor Class. 758DHCPv6 has its own option as shown below. 759The default is 760dhcpcd-<version>:<os>:<machine>:<platform>. 761For example 762.D1 dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386 763If not set then none is sent. 764Some badly configured DHCP servers reject unknown vendorclassids. 765To work around it, try and impersonate Windows by using the MSFT vendorclassid. 766.It Ic vendclass Ar en Ar data 767Add the DHCPv6 Vendor Indetifying Vendor Class with the IANA assigned Enterprise 768Number 769.Ar en 770with the 771.Ar data . 772This option can be set more than once to add more data, but the behaviour, 773as per RFC 3925 is undefined if the Enterprise Number differs. 774.It Ic waitip Op 4 | 6 775Wait for an address to be assigned before forking to the background. 7764 means wait for an IPv4 address to be assigned. 7776 means wait for an IPv6 address to be assigned. 778If no argument is given, 779.Nm 780will wait for any address protocol to be assigned. 781It is possible to wait for more than one address protocol and 782.Nm 783will only fork to the background when all waiting conditions are satisfied. 784.It Ic xidhwaddr 785Use the last four bytes of the hardware address as the DHCP xid instead 786of a randomly generated number. 787.El 788.Ss Defining new options 789DHCP, ND and DHCPv6 allow for the use of custom options, and RFC 3925 vendor 790options for DHCP can also be supplied. 791Each option needs to be started with the 792.Ic define , 793.Ic definend , 794.Ic define6 795or 796.Ic vendopt 797directive. 798This can optionally be followed by both 799.Ic embed 800or 801.Ic encap 802options. 803Both can be specified more than once and 804.Ic embed 805must come before 806.Ic encap . 807.Bl -tag -width indent 808.It Ic define Ar code Ar type Ar variable 809Defines the DHCP option 810.Ar code 811of 812.Ar type 813with a name of 814.Ar variable 815exported to 816.Xr dhcpcd-run-hooks 8 . 817.It Ic definend Ar code Ar type Ar variable 818Defines the ND option 819.Ar code 820of 821.Ar type 822with a name of 823.Ar variable 824exported to 825.Xr dhcpcd-run-hooks 8 , 826with a prefix of 827.Va nd_ . 828.It Ic define6 Ar code Ar type Ar variable 829Defines the DHCPv6 option 830.Ar code 831of 832.Ar type 833with a name of 834.Ar variable 835exported to 836.Xr dhcpcd-run-hooks 8 , 837with a prefix of 838.Va dhcp6_ . 839.It Ic vendopt Ar code Ar type Ar variable 840Defines the Vendor-Identifying Vendor Options. 841The 842.Ar code 843is the IANA Enterprise Number which will uniquely describe the encapsulated 844options. 845.Ar type 846is normally 847.Ar encap . 848.Ar variable 849names the Vendor option to be exported. 850.It Ic embed Ar type Ar variable 851Defines an embedded variable within the defined option. 852The length is determined by the 853.Ar type . 854If the 855.Ar variable 856is not the same as defined in the parent option, 857it is prefixed with the parent 858.Ar variable 859first with an underscore. 860If the 861.Ar variable 862has the name of 863.Ar reserved 864then it is not processed. 865.It Ic encap Ar code Ar type Ar variable 866Defines an encapsulated variable within the defined option. 867The length is determined by the 868.Ar type . 869If the 870.Ar variable 871is not the same as defined in the parent option, 872it is prefixed with the parent 873.Ar variable 874first with an underscore. 875.El 876.Ss Type prefix 877These keywords come before the type itself, to describe it more fully. 878You can use more than one, but they must appear in the order listed below. 879.Bl -tag -width -indent 880.It Ic request 881Requests the option by default without having to be specified in user 882configuration. 883.It Ic norequest 884This option cannot be requested, regardless of user configuration. 885.It Ic optional 886This option is optional. 887Only makes sense for embedded options like the client FQDN option, where 888the FQDN string itself is optional. 889.It Ic index 890The option can appear more than once and will be indexed. 891.It Ic array 892The option data is split into a space separated array, each element being 893the same type. 894.El 895.Ss Types to define 896The type directly affects the length of data consumed inside the option. 897Any remaining data is normally discarded. 898Lengths can be specified for string and binhex types, but this is generally 899with other data embedded afterwards in the same option. 900.Bl -tag -width indent 901.It Ic ipaddress 902An IPv4 address, 4 bytes. 903.It Ic ip6address 904An IPv6 address, 16 bytes. 905.It Ic string Op : Ic length 906A NVT ASCII string of printable characters. 907.It Ic byte 908A byte. 909.It Ic bitflags : Ic flags 910A byte represented as a string of flags, most significant bit first. 911For example, using ABCDEFGH then A would equal 10000000, B 01000000, 912C 00100000, etc. 913If the bit is not set, the flag is not printed. 914A flag of 0 is not printed even if the bit position is set. 915This is to allow reservation of the first bits while assigning the last bits. 916.It Ic int16 917A signed 16bit integer, 2 bytes. 918.It Ic uint16 919An unsigned 16bit integer, 2 bytes. 920.It Ic int32 921A signed 32bit integer, 4 bytes. 922.It Ic uint32 923An unsigned 32bit integer, 4 bytes. 924.It Ic flag 925A fixed value (1) to indicate that the option is present, 0 bytes. 926.It Ic domain 927An RFC 3397 encoded string. 928.It Ic dname 929An RFC 1035 validated string. 930.It Ic binhex Op : Ic length 931Binary data expressed as hexadecimal. 932.It Ic embed 933Contains embedded options (implies encap as well). 934.It Ic encap 935Contains encapsulated options (implies embed as well). 936.It Ic option 937References an option from the global definition. 938.El 939.Ss Example definition 940.D1 # DHCP option 81, Fully Qualified Domain Name, RFC 4702 941.D1 define 81 embed fqdn 942.D1 embed byte flags 943.D1 embed byte rcode1 944.D1 embed byte rcode2 945.D1 embed domain fqdn 946.Pp 947.D1 # DHCP option 125, Vendor Specific Information Option, RFC 3925 948.D1 define 125 encap vsio 949.D1 embed uint32 enterprise_number 950.D1 # Options defined for the enterprise number 951.D1 encap 1 ipaddress ipaddress 952.Ss Supported Authentication Protocols 953.Bl -tag -width -indent 954.It Ic token 955Sends a plain text token the server expects and matches a token sent by 956the server. 957The tokens do not have to be the same. 958If unspecified, the token with a 959.Ar secretid 960of 0 will be used in sending messages 961and validating received messages. 962.It Ic delayedrealm 963Delayed Authentication. 964.Nm dhcpcd 965will send an authentication option with no key or MAC. 966The server will see this option, and select a key for 967.Nm , writing the 968.Ar realm 969and 970.Ar secretid 971in it. 972.Nm dhcpcd 973will then look for an unexpired token with a matching 974.Ar realm 975and 976.Ar secretid . 977This token is used to authenticate all other messages. 978.It Ic delayed 979Same as above, but without a realm. 980.El 981.Ss Supported Authentication Algorithms 982If none specified, 983.Ic hmac-md5 984is the default. 985.Bl -tag -width -indent 986.It Ic hmac-md5 987.El 988.Ss Supported Replay Detection Mechanisms 989If none specified, 990.Ic monotonic 991is the default. 992If this is changed from what was previously used, 993or the means of calculating or storing it is broken, then the DHCP server 994will probably have to have its notion of the client's Replay Detection Value 995reset. 996.Bl -tag -width -indent 997.It Ic monocounter 998Read the number in the file 999.Pa /var/db/dhcpcd/dhcpcd-rdm.monotonic 1000and add one to it. 1001.It Ic monotime 1002Create an NTP timestamp from the system time. 1003.It Ic monotonic 1004Same as 1005.Ic monotime . 1006.El 1007.Sh SEE ALSO 1008.Xr fnmatch 3 , 1009.Xr if_nametoindex 3 , 1010.Xr dhcpcd 8 , 1011.Xr dhcpcd-run-hooks 8 1012.Sh AUTHORS 1013.An Roy Marples Aq Mt roy@marples.name 1014.Sh BUGS 1015Please report them to 1016.Lk https://roy.marples.name/projects/dhcpcd 1017