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 December 18, 2023 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 . 362To avoid delegating to any interface, use - as the invalid interface name. 363Each assigned address will have a 364.Ar suffix , 365defaulting to 1. 366If the 367.Ar suffix 368is 0 then a SLAAC address is assigned. 369You cannot assign a prefix to the requesting interface unless the 370DHCPv6 server supports the 371.Li RFC 6603 372Prefix Exclude Option. 373.Nm dhcpcd 374has to be running for all the interfaces it is delegating to. 375A default 376.Ar prefix_len 377of 64 is assumed, unless the maximum 378.Ar sla_id 379does not fit. 380In this case 381.Ar prefix_len 382is increased to the highest multiple of 8 that can accommodate the 383.Ar sla_id . 384.Ar sla_id 385is an integer which must be unique inside the 386.Ar iaid 387and is added to the prefix which must fit inside 388.Ar prefix_len 389less the length of the delegated prefix. 390You can specify multiple 391.Ar interface / 392.Ar sla_id / 393.Ar prefix_len 394per 395.Ic ia_pd , 396space separated. 397IPv6RS should be disabled globally when requesting a Prefix Delegation. 398.Pp 399In the following example eth0 is the externally facing interface to be 400configured for both IPv4 and IPv6. 401The DHCPv4 server will provide us with an IPv4 address and a default route. 402The DHCPv6 server is going to provide us with an IPv6 address, a default 403route and a /64 subnet to be delegated to the internal interface. 404The eth1 interface will be automatically configured 405for IPv6 using the first address (::1) from the delegated prefix. 406A second prefix is requested and assigned to two other interfaces. 407.Xr rtadvd 8 408can be used with an empty configuration file on eth1, eth2 and eth3, 409to provide automatic 410IPv6 address configuration for the internal network. 411.Bd -literal 412noipv6rs # disable routing solicitation 413denyinterfaces eth2 # Don't touch eth2 at all 414interface eth0 415 ipv6rs # enable routing solicitation for eth0 416 ia_na 1 # request an IPv6 address 417 ia_pd 2 eth1/0 # request a PD and assign it to eth1 418 ia_pd 3 eth2/1 eth3/2 # req a PD and assign it to eth2 and eth3 419 ia_pd 4 - # request a PD but don't assign it 420.Ed 421.It Ic ipv4only 422Only configure IPv4. 423.It Ic ipv6only 424Only configure IPv6. 425.It Ic fqdn Op disable | none | ptr | both 426.Ar none 427will not ask the DHCP server to update DNS. 428.Ar ptr 429just asks the DHCP server to update the PTR 430record of the host in DNS, whereas 431.Ar both 432also updates the A record. 433.Ar disable 434will disable the FQDN option. 435The default is 436.Ar both . 437.Nm dhcpcd 438itself never does any DNS updates. 439.Nm dhcpcd 440encodes the FQDN hostname as specified in 441.Li RFC 1035 . 442.It Ic interface Ar interface 443Subsequent options are only parsed for this 444.Ar interface . 445.It Ic ipv6ra_autoconf 446Generate SLAAC addresses for each Prefix advertised by an IPv6 447Router Advertisement message with the Auto flag set. 448On by default. 449.It Ic ipv6ra_noautoconf 450Disables the above option. 451.It Ic ipv6ra_fork 452By default, when 453.Nm dhcpcd 454receives an IPv6 Router Advertisement, 455.Nm dhcpcd 456will only fork to the background if the RA contains at least one unexpired 457RDNSS option and a valid prefix or no DHCPv6 instruction. 458Set this option so to make 459.Nm dhcpcd 460always fork on a RA. 461.It Ic ipv6rs 462Enables IPv6 Router Advertisement solicitation. 463This is on by default, but is documented here in the case where it is disabled 464globally but needs to be enabled for one interface. 465.It Ic leasetime Ar seconds 466Request DHCP a lease time of 467.Ar seconds . 468.Ar -1 469represents an infinite lease time. 470By default 471.Nm dhcpcd 472does not request any lease time and leaves it in the hands of the 473DHCP server. 474It is not possible to request a DHCPv6 lease time as this is not RFC compliant. 475See RFC 8415 21.4, 21.6, 21.21 and 21.22. 476.It Ic link_rcvbuf Ar size 477Override the size of the link receive buffer from the kernel default. 478While 479.Nm dhcpcd 480will recover from link buffer overflows, 481this may not be desirable on heavily loaded systems. 482.It Ic logfile Ar logfile 483Writes to the specified 484.Ar logfile . 485.Nm dhcpcd 486still writes to 487.Xr syslog 3 . 488The 489.Ar logfile 490is reopened when 491.Nm dhcpcd 492receives the 493.Dv SIGUSR2 494signal. 495.It Ic metric Ar metric 496Metrics are used to prefer an interface over another one, lowest wins. 497.Nm dhcpcd 498will supply a default metric of 1000 + 499.Xr if_nametoindex 3 . 500This will be offset by 2000 for wireless interfaces, with additional offsets 501of 1000000 for IPv4LL and 2000000 for roaming interfaces. 502.It Ic mudurl Ar url 503Specifies the URL for a Manufacturer Usage Description (MUD). 504The description is used by upstream network devices to instantiate any 505desired access lists. 506See draft-ietf-opsawg-mud for more information. 507.It Ic noalias 508Any pre-existing IPv4 addresses will be removed from the interface when 509adding a new IPv4 address. 510.It Ic noarp 511Don't send any ARP requests. 512This also disables IPv4LL. 513.It Ic noauthrequired 514Don't require authentication even though we requested it. 515Also allows FORCERENEW and RECONFIGURE messages without authentication. 516.It Ic nodelay 517Don't delay for an initial randomised time when starting protocols. 518.It Ic nodev 519Don't load 520.Pa /dev 521management modules. 522.It Ic nodhcp 523Don't start DHCP or listen to DHCP messages. 524This is only useful when allowing IPv4LL. 525.It Ic nodhcp6 526Don't start DHCPv6 or listen to DHCPv6 messages. 527Normally DHCPv6 is started by an IPv6 Router Advertisement instruction or 528configuration. 529.It Ic nogateway 530Don't install any default routes. 531.It Ic gateway 532Install a default route if available (default). 533.It Ic nohook Ar script 534Don't run this hook script. 535Matches full name, or prefixed with 2 numbers optionally ending with 536.Pa .sh . 537.Pp 538So to stop 539.Nm dhcpcd 540from touching your DNS settings or starting wpa_supplicant you would do:- 541.D1 nohook resolv.conf, wpa_supplicant 542.It Ic noipv4 543Don't attempt to configure an IPv4 address. 544.It Ic noipv4ll 545Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP. 546See 547.Rs 548.%T "RFC 3927" 549.Re 550.It Ic noipv6 551Don't solicit or accept IPv6 Router Advertisements and DHCPv6. 552.It Ic noipv6rs 553Don't solicit or accept IPv6 Router Advertisements. 554.It Ic nolink 555Don't receive link messages about carrier status. 556You should only set this for buggy interface drivers. 557.It Ic noup 558Don't bring the interface up when in manager mode. 559.It Ic option Ar option 560Requests the 561.Ar option 562from the server. 563It can be a variable to be used in 564.Xr dhcpcd-run-hooks 8 565or the numerical value. 566You can specify more 567.Ar option Ns s 568separated by commas, spaces or more 569.Ic option 570lines. 571Prepend dhcp6_ to 572.Ar option 573to request a DHCPv6 option. 574If no DHCPv6 options are configured, 575then DHCPv4 options are mapped to equivalent DHCPv6 options. 576.Pp 577Prepend nd_ to 578.Ar option 579to handle ND options, but this only works for the 580.Ic nooption , 581.Ic reject 582and 583.Ic require 584options. 585.Pp 586To see a list of options you can use, call 587.Nm dhcpcd 588with the 589.Fl V , Fl Fl variables 590argument. 591.It Ic nooption Ar option 592Remove the option from the message before it's processed. 593.It Ic require Ar option 594Requires the 595.Ar option 596to be present in all messages, otherwise the message is ignored. 597To enforce that 598.Nm dhcpcd 599only responds to DHCP servers and not BOOTP servers, you can 600.Ic require 601.Ar dhcp_message_type . 602This isn't an exact science though because a BOOTP server can send DHCP-like 603options. 604.It Ic reject Ar option 605Reject a message that contains the 606.Ar option . 607This is useful when you cannot use 608.Ic require 609to select / de-select BOOTP messages. 610.It Ic destination Ar option 611If 612.Nm 613detects an address added to a point to point interface (PPP, TUN, etc) then 614it will set the listed DHCP options to the destination address of the 615interface. 616.It Ic profile Ar name 617Subsequent options are only parsed for this profile 618.Ar name . 619.It Ic quiet 620Suppress any dhcpcd output to the console, except for errors. 621.It Ic reboot Ar seconds 622Allow 623.Ar reboot 624seconds before moving to the DISCOVER phase if we have an old lease to use. 625Allow 626.Ar reboot 627seconds before starting fallback states from the DISCOVER phase. 628IPv4LL is started when the first 629.Ar reboot 630timeout is reached. 631The default is 5 seconds. 632A setting of 0 seconds causes 633.Nm 634to skip the reboot phase and go straight into DISCOVER. 635This is desirable for mobile users because if you change from network A to 636network B and they use the same subnet and the address from network A isn't 637in use on network B, then the DHCP server will remain silent even if 638authoritative which means 639.Nm dhcpcd 640will timeout before moving back to the DISCOVER phase. 641This has no effect on DHCPv6 other than skipping the reboot phase. 642.It Ic release 643.Nm dhcpcd 644will release the lease prior to stopping the interface. 645.It Ic script Ar script 646Use 647.Ar script 648instead of the default 649.Pa /usr/libexec/dhcpcd-run-hooks . 650.It Ic ssid Ar ssid 651Subsequent options are only parsed for this wireless 652.Ar ssid . 653.It Ic slaac Ic hwaddr | Ic private | Ic token Ar token Op Ic temp | Ic temporary 654Selects the interface identifier used for SLAAC generated IPv6 addresses. 655If 656.Ic private 657is used, a RFC 7217 address is generated. 658If 659.Ic token Ar token 660is used then the token is combined with the prefix to make the final address. 661The 662.Ic temporary 663directive will create a temporary address for the prefix as well. 664.It Ic static Ar value 665Configures a static 666.Ar value . 667If you set 668.Ic ip_address 669then 670.Nm dhcpcd 671will not attempt to obtain a lease and will just use the value for the address 672with an infinite lease time. 673If you set an empty value this removes all prior static allocations to 674the same value. 675This is useful when using profiles and in the case of 676.Ic ip_address 677it will remove the static allocation. 678Note that setting 0.0.0.0 keeps the static allocation but waits for a 3rdparty 679to configure the address. 680If you set 681.Ic ip6_address , 682.Nm dhcpcd 683will continue auto-configuration as normal. 684.Pp 685Here is an example which configures two static address, overriding the default 686IPv4 broadcast address, an IPv4 router, DNS and disables IPv6 auto-configuration. 687You could also use the 688.Ic inform6 689command here if you wished to obtain more information via DHCPv6. 690For IPv4, you should use the 691.Ic inform Ar ipaddress 692option instead of setting a static address. 693.D1 interface eth0 694.D1 noipv6rs 695.D1 static ip_address=192.168.0.10/24 696.D1 static broadcast_address=192.168.0.63 697.D1 static ip6_address=fd51:42f8:caae:d92e::ff/64 698.D1 static routers=192.168.0.1 699.D1 static domain_name_servers=192.168.0.1 fd51:42f8:caae:d92e::1 700.Pp 701Here is an example for PPP which gives the destination a default route. 702It uses the special 703.Ar destination 704keyword to insert the destination address 705into the value. 706.D1 interface ppp0 707.D1 static ip_address=0.0.0.0 708.D1 destination routers 709.It Ic timeout Ar seconds 710Time out after 711.Ar seconds , 712instead of the default 30. 713A setting of 0 714.Ar seconds 715causes 716.Nm dhcpcd 717to wait forever to get a lease. 718If 719.Nm dhcpcd 720is working on a single interface then 721.Nm dhcpcd 722will exit when a timeout occurs, otherwise 723.Nm dhcpcd 724will fork into the background. 725If using IPv4LL then 726.Nm dhcpcd 727start the IPv4LL process after the timeout and then wait a little longer 728before really timing out. 729.It Ic userclass Ar string 730Tag the DHCPv4 message with the userclass. 731You can specify more than one. 732.It Ic msuserclass Ar string 733Tag the DHCPv4 mesasge with the Microsoft userclass. 734Unlike the 735.Ic userclass 736option, this one can only be added once. 737It should only be used for Microsoft DHCP servers and the 738.Ic vendorclassid 739should be set to "MSFT 98" or "MSFT 5.0". 740This option is not RFC compliant. 741.It Ic vendor Ar code , Ns Ar value 742Add an encapsulated vendor option. 743.Ar code 744should be between 1 and 254 inclusive. 745To add a raw vendor string, omit 746.Ar code 747but keep the comma. 748Examples. 749.Pp 750Set the vendor option 01 with an IP address. 751.D1 vendor 01,192.168.0.2 752Set the vendor option 02 with a hex code. 753.D1 vendor 02,01:02:03:04:05 754Set the vendor option 03 with an IP address as a string. 755.D1 vendor 03,\e"192.168.0.2\e" 756Set un-encapsulated vendor option to hello world. 757.D1 vendor ,"hello world" 758.It Ic vendorclassid Ar string 759Set the DHCP Vendor Class. 760DHCPv6 has its own option as shown below. 761The default is 762dhcpcd-<version>:<os>:<machine>:<platform>. 763For example 764.D1 dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386 765If not set then none is sent. 766Some badly configured DHCP servers reject unknown vendorclassids. 767To work around it, try and impersonate Windows by using the MSFT vendorclassid. 768.It Ic vendclass Ar en Ar data 769Add the DHCPv6 Vendor Indetifying Vendor Class with the IANA assigned Enterprise 770Number 771.Ar en 772with the 773.Ar data . 774This option can be set more than once to add more data, but the behaviour, 775as per RFC 3925 is undefined if the Enterprise Number differs. 776.It Ic waitip Op 4 | 6 777Wait for an address to be assigned before forking to the background. 7784 means wait for an IPv4 address to be assigned. 7796 means wait for an IPv6 address to be assigned. 780If no argument is given, 781.Nm 782will wait for any address protocol to be assigned. 783It is possible to wait for more than one address protocol and 784.Nm 785will only fork to the background when all waiting conditions are satisfied. 786.It Ic xidhwaddr 787Use the last four bytes of the hardware address as the DHCP xid instead 788of a randomly generated number. 789.El 790.Ss Defining new options 791DHCP, ND and DHCPv6 allow for the use of custom options, and RFC 3925 vendor 792options for DHCP can also be supplied. 793Each option needs to be started with the 794.Ic define , 795.Ic definend , 796.Ic define6 797or 798.Ic vendopt 799directive. 800This can optionally be followed by both 801.Ic embed 802or 803.Ic encap 804options. 805Both can be specified more than once and 806.Ic embed 807must come before 808.Ic encap . 809.Bl -tag -width indent 810.It Ic define Ar code Ar type Ar variable 811Defines the DHCP option 812.Ar code 813of 814.Ar type 815with a name of 816.Ar variable 817exported to 818.Xr dhcpcd-run-hooks 8 . 819.It Ic definend Ar code Ar type Ar variable 820Defines the ND option 821.Ar code 822of 823.Ar type 824with a name of 825.Ar variable 826exported to 827.Xr dhcpcd-run-hooks 8 , 828with a prefix of 829.Va nd_ . 830.It Ic define6 Ar code Ar type Ar variable 831Defines the DHCPv6 option 832.Ar code 833of 834.Ar type 835with a name of 836.Ar variable 837exported to 838.Xr dhcpcd-run-hooks 8 , 839with a prefix of 840.Va dhcp6_ . 841.It Ic vendopt Ar code Ar type Ar variable 842Defines the Vendor-Identifying Vendor Options. 843The 844.Ar code 845is the IANA Enterprise Number which will uniquely describe the encapsulated 846options. 847.Ar type 848is normally 849.Ar encap . 850.Ar variable 851names the Vendor option to be exported. 852.It Ic embed Ar type Ar variable 853Defines an embedded variable within the defined option. 854The length is determined by the 855.Ar type . 856If the 857.Ar variable 858is not the same as defined in the parent option, 859it is prefixed with the parent 860.Ar variable 861first with an underscore. 862If the 863.Ar variable 864has the name of 865.Ar reserved 866then it is not processed. 867.It Ic encap Ar code Ar type Ar variable 868Defines an encapsulated variable within the defined option. 869The length is determined by the 870.Ar type . 871If the 872.Ar variable 873is not the same as defined in the parent option, 874it is prefixed with the parent 875.Ar variable 876first with an underscore. 877.El 878.Ss Type prefix 879These keywords come before the type itself, to describe it more fully. 880You can use more than one, but they must appear in the order listed below. 881.Bl -tag -width -indent 882.It Ic request 883Requests the option by default without having to be specified in user 884configuration. 885.It Ic norequest 886This option cannot be requested, regardless of user configuration. 887.It Ic optional 888This option is optional. 889Only makes sense for embedded options like the client FQDN option, where 890the FQDN string itself is optional. 891.It Ic index 892The option can appear more than once and will be indexed. 893.It Ic array 894The option data is split into a space separated array, each element being 895the same type. 896.El 897.Ss Types to define 898The type directly affects the length of data consumed inside the option. 899Any remaining data is normally discarded. 900Lengths can be specified for string and binhex types, but this is generally 901with other data embedded afterwards in the same option. 902.Bl -tag -width indent 903.It Ic ipaddress 904An IPv4 address, 4 bytes. 905.It Ic ip6address 906An IPv6 address, 16 bytes. 907.It Ic string Op : Ic length 908A NVT ASCII string of printable characters. 909.It Ic byte 910A byte. 911.It Ic bitflags : Ic flags 912A byte represented as a string of flags, most significant bit first. 913For example, using ABCDEFGH then A would equal 10000000, B 01000000, 914C 00100000, etc. 915If the bit is not set, the flag is not printed. 916A flag of 0 is not printed even if the bit position is set. 917This is to allow reservation of the first bits while assigning the last bits. 918.It Ic int16 919A signed 16bit integer, 2 bytes. 920.It Ic uint16 921An unsigned 16bit integer, 2 bytes. 922.It Ic int32 923A signed 32bit integer, 4 bytes. 924.It Ic uint32 925An unsigned 32bit integer, 4 bytes. 926.It Ic flag 927A fixed value (1) to indicate that the option is present, 0 bytes. 928.It Ic domain 929An RFC 3397 encoded string. 930.It Ic dname 931An RFC 1035 validated string. 932.It Ic uri 933If an array then the first two bytes are the URI length inside the option data. 934Otherwise, the whole option data is the URI. 935As a space is not allowed in the URI encoding, the URIs are space separated. 936.It Ic binhex Op : Ic length 937Binary data expressed as hexadecimal. 938.It Ic embed 939Contains embedded options (implies encap as well). 940.It Ic encap 941Contains encapsulated options (implies embed as well). 942.It Ic option 943References an option from the global definition. 944.El 945.Ss Example definition 946.D1 # DHCP option 81, Fully Qualified Domain Name, RFC 4702 947.D1 define 81 embed fqdn 948.D1 embed byte flags 949.D1 embed byte rcode1 950.D1 embed byte rcode2 951.D1 embed domain fqdn 952.Pp 953.D1 # DHCP option 125, Vendor Specific Information Option, RFC 3925 954.D1 define 125 encap vsio 955.D1 embed uint32 enterprise_number 956.D1 # Options defined for the enterprise number 957.D1 encap 1 ipaddress ipaddress 958.Ss Supported Authentication Protocols 959.Bl -tag -width -indent 960.It Ic token 961Sends a plain text token the server expects and matches a token sent by 962the server. 963The tokens do not have to be the same. 964If unspecified, the token with a 965.Ar secretid 966of 0 will be used in sending messages 967and validating received messages. 968.It Ic delayedrealm 969Delayed Authentication. 970.Nm dhcpcd 971will send an authentication option with no key or MAC. 972The server will see this option, and select a key for 973.Nm , writing the 974.Ar realm 975and 976.Ar secretid 977in it. 978.Nm dhcpcd 979will then look for an unexpired token with a matching 980.Ar realm 981and 982.Ar secretid . 983This token is used to authenticate all other messages. 984.It Ic delayed 985Same as above, but without a realm. 986.El 987.Ss Supported Authentication Algorithms 988If none specified, 989.Ic hmac-md5 990is the default. 991.Bl -tag -width -indent 992.It Ic hmac-md5 993.El 994.Ss Supported Replay Detection Mechanisms 995If none specified, 996.Ic monotonic 997is the default. 998If this is changed from what was previously used, 999or the means of calculating or storing it is broken, then the DHCP server 1000will probably have to have its notion of the client's Replay Detection Value 1001reset. 1002.Bl -tag -width -indent 1003.It Ic monocounter 1004Read the number in the file 1005.Pa /var/db/dhcpcd/dhcpcd-rdm.monotonic 1006and add one to it. 1007.It Ic monotime 1008Create an NTP timestamp from the system time. 1009.It Ic monotonic 1010Same as 1011.Ic monotime . 1012.El 1013.Sh SEE ALSO 1014.Xr fnmatch 3 , 1015.Xr if_nametoindex 3 , 1016.Xr dhcpcd 8 , 1017.Xr dhcpcd-run-hooks 8 1018.Sh AUTHORS 1019.An Roy Marples Aq Mt roy@marples.name 1020.Sh BUGS 1021Please report them to 1022.Lk https://roy.marples.name/projects/dhcpcd 1023