1 .\" SPDX-License-Identifier: BSD-2-Clause
3 .\" Copyright (c) 2006-2019 Roy Marples
4 .\" All rights reserved
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd dhcpcd configuration file
36 can do everything from the command line, there are cases where it's just easier
37 to do it once in a configuration file.
38 Most of the options found in
41 The first word on the line is the option and the rest of the line is the value.
42 Leading and trailing whitespace for the option and value are trimmed.
43 You can escape characters in the value using the \\ character.
44 Comments can be prefixed with the # character.
45 String values should be quoted with the " character.
47 Here's a list of available options:
48 .Bl -tag -width indent
49 .It Ic allowinterfaces Ar pattern
50 When discovering interfaces, the interface name must match
52 which is a space or comma separated list of patterns passed to
54 If the same interface is matched in
56 then it is still denied.
57 .It Ic denyinterfaces Ar pattern
58 When discovering interfaces, the interface name must not match
60 which is a space or comma separated list of patterns passed to
62 .It Ic arping Ar address Op address
64 will arping each address in order before attempting DHCP.
65 If an address is found, we will select the replying hardware address as the
66 profile, otherwise the IP address.
70 .D1 arping 192.168.0.1
72 .D1 # My specific 192.168.0.1 network
73 .D1 profile dd:ee:aa:dd:bb:ee
74 .D1 static ip_address=192.168.0.10/24
76 .D1 # A generic 192.168.0.1 network
77 .D1 profile 192.168.0.1
78 .D1 static ip_address=192.168.0.98/24
79 .It Ic authprotocol Ar protocol Op Ar algorithm Op Ar rdm
80 Authenticate DHCP messages.
81 See the Supported Authentication Protocols section.
88 snd_secretid/rcv_secretid so you can send and recieve different tokens.
89 .It Ic authtoken Ar secretid Ar realm Ar expire Ar key
90 Define a shared key for use in authentication.
92 can be "" to for use with the
96 is the date the token expires and should be formatted "yyy-mm-dd HH:MM".
97 You can use the keyword
101 which means the token never expires.
102 For the token protocol,
110 .D1 dhcp_auth_encode: Invalid argument
113 could not find the correct authentication token in your configuration.
115 Fork to the background immediately.
116 This is useful for startup scripts which don't disable link messages for
118 .It Ic blacklist Ar address Ns Op /cidr
119 Ignores all packets from
120 .Ar address Ns Op /cidr .
121 .It Ic whitelist Ar address Ns Op /cidr
122 Only accept packets from
123 .Ar address Ns Op /cidr .
130 Basically, this just doesn't send a DHCP Message Type option and will only
131 interact with a BOOTP server.
132 All other DHCP options still work.
134 Instructs the DHCP server to broadcast replies back to the client.
135 Normally this is only set for non-Ethernet interfaces,
136 such as FireWire and InfiniBand.
139 will set this automatically.
140 .It Ic controlgroup Ar group
141 Sets the group ownership of
142 .Pa @RUNDIR@/dhcpcd.sock
143 so that users other than root can connect to
146 Echo debug messages to the stderr and syslog.
153 will load the first one found to work, if any.
157 to the environment for use in
158 .Xr dhcpcd-run-hooks 8 .
159 For example, you can force the hostname hook to always set the hostname with
161 .Va force_hostname=YES .
166 .Va wpa_supplicant_driver=nl80211
168 If the hostname is set, it will be will set to the FQDN if possible as per
169 RFC 4702, section 3.1.
170 If the FQDN option is missing,
172 will still try and set a FQDN from the hostname and domain options for
174 To override this, set
176 .Va hostname_fqdn=[YES|NO|SERVER] .
179 means just what the server says, don't manipulate it.
180 This could lead to an inconsistent hostname on a DHCPv4 and DHCPv6 network
181 where the DHCPv4 hostname is short and the DHCPv6 has an FQDN.
182 DHCPv6 has no hostname option.
183 .It Ic clientid Ar string
186 If the string is of the format 01:02:03 then it is encoded as hex.
187 For interfaces whose hardware address is longer than 8 bytes, or if the
189 is an empty string then
193 of the hardware family and the hardware address.
195 Use a DHCP Unique Identifier.
196 If a system UUID is available, that will be used to create a DUID-UUID,
197 otheriwse if persistent storage is available then a DUID-LLT
198 (link local address + time) is generated,
199 otherwise DUID-LL is generated (link local address).
200 This, plus the IAID will be used as the
202 The DUID generated will be held in
204 and should not be copied to other hosts.
205 This file also takes precedence over the above rules.
207 Set the Interface Association Identifier to
209 This option must be used in an
212 This defaults to the VLANID (prefixed with 0xff) for the interface if set,
213 otherwise the last 4 bytes of the hardware address assigned to the
215 Each instance of this should be unique within the scope of the client and
217 warns if a conflict is detected.
218 If there is a conflict, it is only a problem if the conflicted IAIDs are
219 used on the same network.
221 Enable DHCP on the interface, on by default.
223 Enable DHCPv6 on the interface, on by default.
225 Enable IPv4 on the interface, on by default.
227 Enable IPv6 on the interface, on by default.
228 .It Ic request Op Ar address
231 in the DHCP DISCOVER message.
232 There is no guarantee this is the address the DHCP server will actually give.
235 is given then the first address currently assigned to the
238 .It Ic inform Op Ar address Ns Op Ar /cidr Ns Op Ar /broadcast_address
241 as above, but sends a DHCP INFORM instead of DISCOVER/REQUEST.
242 This does not get a lease as such, just notifies the DHCP server of the
245 You should also include the optional
247 network number in case the address is not already configured on the interface.
249 remains running and pretends it has an infinite lease.
251 will not de-configure the interface when it exits.
254 fails to contact a DHCP server then it returns a failure instead of falling
257 Performs a DHCPv6 Information Request.
258 No address is requested or specified, but all other DHCPv6 options are allowed.
259 This is normally performed automatically when an IPv6 Router Advertisement
260 indicates that the client should perform this operation.
261 This option is only needed when
263 is not processing IPv6 RA messages and the need for a DHCPv6 Information Request
267 normally de-configures the interface and configuration when it exits.
268 Sometimes, this isn't desirable if, for example, you have root mounted over
269 NFS or SSH clients connect to this host and they need to be notified of
270 the host shutting down.
271 You can use this option to stop this from happening.
272 .It Ic fallback Ar profile
273 Fall back to using this profile if DHCP fails.
274 This allows you to configure a static profile instead of using ZeroConf.
275 .It Ic hostname Ar name
278 to the DHCP server so it can be registered in DNS.
281 is an empty string then the current system hostname is sent.
284 is a FQDN (i.e., contains a .) then it will be encoded as such.
285 .It Ic hostname_short
286 Sends the short hostname to the DHCP server instead of the FQDN.
287 This is useful because DHCP servers will not register the FQDN in their
288 DNS if the domain part does not match theirs.
292 option above to control how the hostname is set on the host.
293 .It Ic ia_na Op Ar iaid Op / address
294 Request a DHCPv6 Normal Address for
299 option as described above.
300 You can request more than one ia_na by specifying a unique
303 .It Ic ia_ta Op Ar iaid
304 Request a DHCPv6 Temporary Address for
306 You can request more than one ia_ta by specifying a unique
309 .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
310 Request a DHCPv6 Delegated Prefix for
312 This option must be used in an
317 of 0 is assigned with the same resultant prefix length as the delegation,
318 a reject route is installed for the Delegated Prefix to
319 stop unallocated addresses being resolved upstream.
322 is given then we will assign a prefix to every other interface with a
324 equivalent to the interface index assigned by the OS.
325 Otherwise addresses are only assigned for each
329 Each assigned address will have a
334 is 0 then a SLAAC address is assigned.
335 You cannot assign a prefix to the requesting interface unless the
336 DHCPv6 server supports the
338 Prefix Exclude Option.
340 has to be running for all the interfaces it is delegating to.
343 of 64 is assumed, unless the maximum
348 is increased to the highest multiple of 8 that can accommodate the
351 is an integer which must be unique inside the
353 and is added to the prefix which must fit inside
355 less the length of the delegated prefix.
356 You can specify multiple
363 IPv6RS should be disabled globally when requesting a Prefix Delegation.
365 In the following example eth0 is the externally facing interface to be
366 configured for both IPv4 and IPv6.
367 The DHCPv4 server will provide us with an IPv4 address and a default route.
368 The DHCPv6 server is going to provide us with an IPv6 address, a default
369 route and a /64 subnet to be delegated to the internal interface.
370 The eth1 interface will be automatically configured
371 for IPv6 using the first address (::1) from the delegated prefix.
372 A second prefix is requested and assigned to two other interfaces.
374 can be used with an empty configuration file on eth1, eth2 and eth3,
376 IPv6 address configuration for the internal network.
378 noipv6rs # disable routing solicitation
379 denyinterfaces eth2 # Don't touch eth2 at all
381 ipv6rs # enable routing solicitation for eth0
382 ia_na 1 # request an IPv6 address
383 ia_pd 2 eth1/0 # request a PD and assign it to eth1
384 ia_pd 3 eth2/1 eth3/2 # req a PD and assign it to eth2 and eth3
390 .It Ic fqdn Op disable | none | ptr | both
392 will not ask the DHCP server to update DNS.
394 just asks the DHCP server to update the PTR
395 record of the host in DNS, whereas
397 also updates the A record.
399 will disable the FQDN option.
403 itself never does any DNS updates.
405 encodes the FQDN hostname as specified in
407 .It Ic interface Ar interface
408 Subsequent options are only parsed for this
410 .It Ic ipv6ra_autoconf
411 Generate SLAAC addresses for each Prefix advertised by an IPv6
412 Router Advertisement message with the Auto flag set.
414 .It Ic ipv6ra_noautoconf
415 Disables the above option.
419 receives an IPv6 Router Advertisement,
421 will only fork to the background if the RA contains at least one unexpired
422 RDNSS option and a valid prefix or no DHCPv6 instruction.
423 Set this option so to make
425 always fork on an RA.
427 Enables IPv6 Router Advertisement solicitation.
428 This is on by default, but is documented here in the case where it is disabled
429 globally but needs to be enabled for one interface.
430 .It Ic leasetime Ar seconds
431 Request a leasetime of
433 .It Ic link_rcvbuf Ar size
434 Override the size of the link receive buffer from the kernel default.
437 will recover from link buffer overflows,
438 this may not be desirable on heavily loaded systems.
439 .It Ic logfile Ar logfile
440 Writes to the specified
451 .It Ic metric Ar metric
452 Metrics are used to prefer an interface over another one, lowest wins.
454 will supply a default metric of 200 +
455 .Xr if_nametoindex 3 .
456 An extra 100 will be added for wireless interfaces.
458 Specifies the URL for a Manufacturer Usage Description (MUD).
459 The description is used by upstream network devices to instantiate any
460 desired access lists.
461 See draft-ietf-opsawg-mud for more information.
463 Any pre-existing IPv4 addresses will be removed from the interface when
464 adding a new IPv4 address.
466 Don't send any ARP requests.
467 This also disables IPv4LL.
468 .It Ic noauthrequired
469 Don't require authentication even though we requested it.
470 Also allows FORCERENEW and RECONFIGURE messages without authentication.
472 Don't delay for an initial randomised time when starting protocols.
478 Don't start DHCP or listen to DHCP messages.
479 This is only useful when allowing IPv4LL.
481 Don't start DHCPv6 or listen to DHCPv6 messages.
482 Normally DHCPv6 is started by an IPv6 Router Advertisement instruction or
485 Don't install any default routes.
487 Install a default route if available (default).
488 .It Ic nohook Ar script
489 Don't run this hook script.
490 Matches full name, or prefixed with 2 numbers optionally ending with
495 from touching your DNS settings or starting wpa_supplicant you would do:-
496 .D1 nohook resolv.conf, wpa_supplicant
498 Don't attempt to configure an IPv4 address.
500 Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP.
506 Don't solicit or accept IPv6 Router Advertisements and DHCPv6.
508 Don't solicit or accept IPv6 Router Advertisements.
510 Don't receive link messages about carrier status.
511 You should only set this for buggy interface drivers.
513 Don't bring the interface up when in master mode.
516 cannot determine the carrier state,
518 will enter a tight polling loop until the interface is marked up and running
519 or a valid carrier state is reported.
520 .It Ic option Ar option
524 It can be a variable to be used in
525 .Xr dhcpcd-run-hooks 8
526 or the numerical value.
529 separated by commas, spaces or more
534 to request a DHCPv6 option.
535 If no DHCPv6 options are configured,
536 then DHCPv4 options are mapped to equivalent DHCPv6 options.
540 to handle ND options, but this only works for the
547 To see a list of options you can use, call
550 .Fl V , Fl Fl variables
552 .It Ic nooption Ar option
553 Remove the option from the message before it's processed.
554 .It Ic require Ar option
557 to be present in all messages, otherwise the message is ignored.
560 only responds to DHCP servers and not BOOTP servers, you can
562 .Ar dhcp_message_type .
563 This isn't an exact science though because a BOOTP server can send DHCP-like
565 .It Ic reject Ar option
566 Reject a message that contains the
568 This is useful when you cannot use
570 to select / de-select BOOTP messages.
571 .It Ic destination Ar option
574 detects an address added to a point to point interface (PPP, TUN, etc) then
575 it will set the listed DHCP options to the destination address of the
577 .It Ic profile Ar name
578 Subsequent options are only parsed for this profile
581 Suppress any dhcpcd output to the console, except for errors.
582 .It Ic reboot Ar seconds
585 seconds before moving to the DISCOVER phase if we have an old lease to use
586 and moving from DISCOVER to IPv4LL if no reply.
587 The default is 5 seconds.
588 A setting of 0 seconds causes
590 to skip the REBOOT phase and go straight into DISCOVER.
591 This is desirable for mobile users because if you change from network A to
592 network B and they use the same subnet and the address from network A isn't
593 in use on network B, then the DHCP server will remain silent even if
594 authoritative which means
596 will timeout before moving back to the DISCOVER phase.
599 will release the lease prior to stopping the interface.
600 .It Ic script Ar script
603 instead of the default
606 Subsequent options are only parsed for this wireless
608 .It Ic slaac Op Ar hwaddr | Ar private
609 Selects the interface identifier used for SLAAC generated IPv6 addresses.
612 is used, an RFC 7217 address is generated.
613 .It Ic static Ar value
620 will not attempt to obtain a lease and will just use the value for the address
621 with an infinite lease time.
625 will continue auto-configuration as normal.
627 Here is an example which configures two static address, overriding the default
628 IPv4 broadcast address, an IPv4 router, DNS and disables IPv6 auto-configuration.
629 You could also use the
631 command here if you wished to obtain more information via DHCPv6.
632 For IPv4, you should use the
633 .Ic inform Ar ipaddress
634 option instead of setting a static address.
637 .D1 static ip_address=192.168.0.10/24
638 .D1 static broadcast_address=192.168.0.63
639 .D1 static ip6_address=fd51:42f8:caae:d92e::ff/64
640 .D1 static routers=192.168.0.1
641 .D1 static domain_name_servers=192.168.0.1 fd51:42f8:caae:d92e::1
643 Here is an example for PPP which gives the destination a default route.
646 keyword to insert the destination address
649 .D1 static ip_address=
650 .D1 destination routers
651 .It Ic timeout Ar seconds
654 instead of the default 30.
659 to wait forever to get a lease.
662 is working on a single interface then
664 will exit when a timeout occurs, otherwise
666 will fork into the background.
669 start the IPv4LL process after the timeout and then wait a little longer
670 before really timing out.
671 .It Ic userclass Ar string
672 Tag the DHCPv4 messages with the userclass.
673 You can specify more than one.
674 .It Ic vendor Ar code , Ns Ar value
675 Add an encapsulated vendor option.
677 should be between 1 and 254 inclusive.
678 To add a raw vendor string, omit
683 Set the vendor option 01 with an IP address.
684 .D1 vendor 01,192.168.0.2
685 Set the vendor option 02 with a hex code.
686 .D1 vendor 02,01:02:03:04:05
687 Set the vendor option 03 with an IP address as a string.
688 .D1 vendor 03,\e"192.168.0.2\e"
689 Set un-encapsulated vendor option to hello world.
690 .D1 vendor ,"hello world"
691 .It Ic vendorclassid Ar string
692 Set the DHCP Vendor Class.
693 DHCPv6 has its own option as shown below.
695 dhcpcd-<version>:<os>:<machine>:<platform>.
697 .D1 dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386
698 If not set then none is sent.
699 Some badly configured DHCP servers reject unknown vendorclassids.
700 To work around it, try and impersonate Windows by using the MSFT vendorclassid.
701 .It Ic vendclass Ar en Ar data
702 Add the DHCPv6 Vendor Indetifying Vendor Class with the IANA assigned Enterprise
707 This option can be set more than once to add more data, but the behaviour,
708 as per RFC 3925 is undefined if the Enterprise Number differs.
709 .It Ic waitip Op 4 | 6
710 Wait for an address to be assigned before forking to the background.
711 4 means wait for an IPv4 address to be assigned.
712 6 means wait for an IPv6 address to be assigned.
713 If no argument is given,
715 will wait for any address protocol to be assigned.
716 It is possible to wait for more than one address protocol and
718 will only fork to the background when all waiting conditions are satisfied.
720 Use the last four bytes of the hardware address as the DHCP xid instead
721 of a randomly generated number.
723 .Ss Defining new options
724 DHCP, ND and DHCPv6 allow for the use of custom options, and RFC 3925 vendor
725 options for DHCP can also be supplied.
726 Each option needs to be started with the
733 This can optionally be followed by both
738 Both can be specified more than once and
742 .Bl -tag -width indent
743 .It Ic define Ar code Ar type Ar variable
744 Defines the DHCP option
751 .Xr dhcpcd-run-hooks 8 .
752 .It Ic definend Ar code Ar type Ar variable
753 Defines the ND option
760 .Xr dhcpcd-run-hooks 8 ,
763 .It Ic define6 Ar code Ar type Ar variable
764 Defines the DHCPv6 option
771 .Xr dhcpcd-run-hooks 8 ,
774 .It Ic vendopt Ar code Ar type Ar variable
775 Defines the Vendor-Identifying Vendor Options.
778 is the IANA Enterprise Number which will uniquely describe the encapsulated
784 names the Vendor option to be exported.
785 .It Ic embed Ar type Ar variable
786 Defines an embedded variable within the defined option.
787 The length is determined by the
791 is not the same as defined in the parent option,
792 it is prefixed with the parent
794 first with an underscore.
799 then it is not processed.
800 .It Ic encap Ar code Ar type Ar variable
801 Defines an encapsulated variable within the defined option.
802 The length is determined by the
806 is not the same as defined in the parent option,
807 it is prefixed with the parent
809 first with an underscore.
812 These keywords come before the type itself, to describe it more fully.
813 You can use more than one, but they must appear in the order listed below.
814 .Bl -tag -width -indent
816 Requests the option by default without having to be specified in user
819 This option cannot be requested, regardless of user configuration.
821 This option is optional.
822 Only makes sense for embedded options like the client FQDN option, where
823 the FQDN string itself is optional.
825 The option can appear more than once and will be indexed.
827 The option data is split into a space separated array, each element being
831 The type directly affects the length of data consumed inside the option.
832 Any remaining data is normally discarded.
833 Lengths can be specified for string and binhex types, but this is generally
834 with other data embedded afterwards in the same option.
835 .Bl -tag -width indent
837 An IPv4 address, 4 bytes.
839 An IPv6 address, 16 bytes.
840 .It Ic string Op : Ic length
841 A NVT ASCII string of printable characters.
844 .It Ic bitflags : Ic flags
845 A byte represented as a string of flags, most significant bit first.
846 For example, using ABCDEFGH then A would equal 10000000, B 01000000,
848 If the bit is not set, the flag is not printed.
849 A flag of 0 is not printed even if the bit position is set.
850 This is to allow reservation of the first bits while assigning the last bits.
852 A signed 16bit integer, 2 bytes.
854 An unsigned 16bit integer, 2 bytes.
856 A signed 32bit integer, 4 bytes.
858 An unsigned 32bit integer, 4 bytes.
860 A fixed value (1) to indicate that the option is present, 0 bytes.
862 An RFC 3397 encoded string.
864 An RFC 1035 validated string.
865 .It Ic binhex Op : Ic length
866 Binary data expressed as hexadecimal.
868 Contains embedded options (implies encap as well).
870 Contains encapsulated options (implies embed as well).
872 References an option from the global definition.
874 .Ss Example definition
875 .D1 # DHCP option 81, Fully Qualified Domain Name, RFC 4702
876 .D1 define 81 embed fqdn
878 .D1 embed byte rcode1
879 .D1 embed byte rcode2
880 .D1 embed domain fqdn
882 .D1 # DHCP option 125, Vendor Specific Information Option, RFC 3925
883 .D1 define 125 encap vsio
884 .D1 embed uint32 enterprise_number
885 .D1 # Options defined for the enterprise number
886 .D1 encap 1 ipaddress ipaddress
887 .Ss Supported Authentication Protocols
888 .Bl -tag -width -indent
890 Sends a plain text token the server expects and matches a token sent by
892 The tokens do not have to be the same.
893 If unspecified, the token with a
895 of 0 will be used in sending messages
896 and validating received messages.
898 Delayed Authentication.
900 will send an authentication option with no key or MAC.
901 The server will see this option, and select a key for
908 will then look for an unexpired token with a matching
912 This token is used to authenticate all other messages.
914 Same as above, but without a realm.
916 .Ss Supported Authentication Algorithms
920 .Bl -tag -width -indent
923 .Ss Supported Replay Detection Mechanisms
927 If this is changed from what was previously used,
928 or the means of calculating or storing it is broken, then the DHCP server
929 will probably have to have its notion of the client's Replay Detection Value
931 .Bl -tag -width -indent
933 Read the number in the file
934 .Pa @DBDIR@/dhcpcd-rdm.monotonic
937 Create an NTP timestamp from the system time.
944 .Xr if_nametoindex 3 ,
946 .Xr dhcpcd-run-hooks 8
948 .An Roy Marples Aq Mt roy@marples.name
950 Please report them to
951 .Lk http://roy.marples.name/projects/dhcpcd