1DHCPCD.CONF(5) BSD File Formats Manual DHCPCD.CONF(5)
2
4 dhcpcd.conf — dhcpcd configuration file
5
7 Although dhcpcd can do everything from the command line, there are cases
8 where it's just easier to do it once in a configuration file. Most of
9 the options found in dhcpcd(8) can be used here. The first word on the
10 line is the option and the rest of the line is the value. Leading and
11 trailing whitespace for the option and value are trimmed. You can escape
12 characters in the value using the \ character. Comments can be prefixed
13 with the # character. String values should be quoted with the " charac‐
14 ter.
15 Here's a list of available options:
17 allowinterfaces pattern
19 When discovering interfaces, the interface name must match
20 pattern which is a space or comma separated list of patterns
21 passed to fnmatch(3). If the same interface is matched in
22 denyinterfaces then it is still denied.
23 denyinterfaces pattern
25 When discovering interfaces, the interface name must not match
26 pattern which is a space or comma separated list of patterns
27 passed to fnmatch(3).
28 arping address [address]
30 dhcpcd will arping each address in order before attempting DHCP.
31 If an address is found, we will select the replying hardware
32 address as the profile, otherwise the ip address. Example:
33 interface bge0
35 arping 192.168.0.1
36 # My specific 192.168.0.1 network
38 profile dd:ee:aa:dd:bb:ee
39 static ip_address=192.168.0.10/24
40 # A generic 192.168.0.1 network
42 profile 192.168.0.1
43 static ip_address=192.168.0.98/24
44 authprotocol protocol algorithm rdm
46 Authenticate DHCP messages. See the Supported Authentication
47 Protocols section.
48 authtoken secretid realm expire key
50 Define a shared key for use in authentication. realm can be to
51 for use with the delayed prptocol. expire is the date the token
52 expires and should be formatted "yyy-mm-dd HH:MM". You can use
53 the keyword forever or 0 which means the token never expires.
54 For the token protocol, secretid needs to be 0 and realm needs to
55 be "". If dhcpcd has the error
56 dhcp_auth_encode: Invalid argument
57 then it means that dhcpcd could not find the correct authentica‐
58 tion token in your configuration.
59 background
61 Background immediately. This is useful for startup scripts which
62 don't disable link messages for carrier status.
63 blacklist address[/cidr]
65 Ignores all packets from address[/cidr].
66 whitelist address[/cidr]
68 Only accept packets from address[/cidr]. blacklist is ignored if
69 whitelist is set.
70 bootp Be a BOOTP client. Basically, this just doesn't send a DHCP Mes‐
72 sage Type option and will only interact with a BOOTP server. All
73 other DHCP options still work.
74 broadcast
76 Instructs the DHCP server to broadcast replies back to the
77 client. Normally this is only set for non Ethernet interfaces,
78 such as FireWire and InfiniBand. In most cases, dhcpcd will set
79 this automatically.
80 controlgroup group
82 Sets the group ownership of /var/run/dhcpcd.sock so that users
83 other than root can connect to dhcpcd.
84 debug Echo debug messages to the stderr and syslog.
86 dev value
88 Load the value /dev management module. dhcpcd will load the
89 first one found to work, if any.
90 env value
92 Push value to the environment for use in dhcpcd-run-hooks(8).
93 For example, you can force the hostname hook to always set the
94 hostname with env force_hostname=YES. Or set which driver
95 wpa_supplicant(8) should use with env
96 wpa_supplicant_driver=nl80211
97 If the hostname is set, it will be will set to the FQDN if possi‐
99 ble as per RFC 4702 section 3.1. If the FQDN option is missing,
100 dhcpcd will still try and set a FQDN from the hostname and domain
101 options for consistency. To override this, set env
102 hostname_fqdn=[YES|NO|SERVER]. A value of server means just what
103 the server says, don't manipulate it. This could lead to an
104 inconsistent hostname on a DHCPv4 and DHCPv6 network where the
105 DHCPv4 hostname is short and the DHCPv6 has an FQDN. DHCPv6 has
106 no hostname option.
107 clientid string
109 Send the clientid. If the string is of the format 01:02:03 then
110 it is encoded as hex. For interfaces whose hardware address is
111 longer than 8 bytes, or if the clientid is an empty string then
112 dhcpcd sends a default clientid of the hardware family and the
113 hardware address.
114 duid Generate an RFC 4361. compliant DHCP Unique Identifier. If per‐
116 sistent storage is available then a DUID-LLT (link local address
117 + time) is generated, otherwise DUID-LL is generated (link local
118 address). This, plus the IAID will be used as the clientid. The
119 DUID-LLT generated will be held in /etc/dhcpcd.duid and should
120 not be copied to other hosts.
121 iaid iaid
123 Set the Interface Association Identifier to iaid. This option
124 must be used in an interface block. This defaults to the last 4
125 bytes of the hardware address assigned to the interface. Each
126 instance of this should be unique within the scope of the client
127 and dhcpcd warns if a conflict is detected. If there is a con‐
128 flict, it is only a problem if the conflicted IAIDs are used on
129 the same network.
130 dhcp Enable DHCP on the interface, on by default.
132 dhcp6 Enable DHCPv6 on the interface, on by default.
134 ipv4 Enable IPv4 on the interface, on by default.
136 ipv6 Enable IPv6 on the interface, on by default.
138 request [address]
140 Request the address in the DHCP DISCOVER message. There is no
141 guarantee this is the address the DHCP server will actually give.
142 If no address is given then the first address currently assigned
143 to the interface is used.
144 inform [address[/cidr]]
146 Behaves like request as above, but sends a DHCP INFORM instead of
147 DISCOVER/REQUEST. This does not get a lease as such, just noti‐
148 fies the DHCP server of the address in use. You should also
149 include the optional cidr network number in case the address is
150 not already configured on the interface. dhcpcd remains running
151 and pretends it has an infinite lease. dhcpcd will not de-con‐
152 figure the interface when it exits. If dhcpcd fails to contact a
153 DHCP server then it returns a failure instead of falling back on
154 IPv4LL.
155 inform6
157 Performs a DHCPv6 Information Request. No address is requested
158 or specified, but all other DHCPv6 options are allowed. This is
159 normally performed automatically when the IPv6 Router Advertises
160 that the client should perform this operation. This option is
161 only needed when dhcpcd is not processing IPv6RA messages and the
162 need for DHCPv6 Information Request exists.
163 persistent
165 dhcpcd normally de-configures the interface and configuration
166 when it exits. Sometimes, this isn't desirable if, for example,
167 you have root mounted over NFS or SSH clients connect to this
168 host and they need to be notified of the host shutting down. You
169 can use this option to stop this from happening.
170 fallback profile
172 Fallback to using this profile if DHCP fails. This allows you to
173 configure a static profile instead of using ZeroConf.
174 hostname name
176 Sends the hostname name to the DHCP server so it can be regis‐
177 tered in DNS. If name is an empty string then the current system
178 hostname is sent. If name is a FQDN (ie, contains a .) then it
179 will be encoded as such.
180 hostname_short
182 Sends the short hostname to the DHCP server instead of the FQDN.
183 This is useful because DHCP servers will not register the FQDN in
184 their DNS if the domain part does not match theirs.
185 Also, see the env option above to control how the hostname is set
187 on the host.
188 ia_na [iaid [/ address]]
190 Request a DHCPv6 Normal Address for iaid. iaid defaults to the
191 iaid option as described above. You can request more than one
192 ia_na by specifying a unique iaid for each one.
193 ia_ta [iaid]
195 Request a DHCPv6 Temporary Address for iaid. You can request
196 more than one ia_ta by specifying a unique iaid for each one.
197 ia_pd [iaid [/ prefix / prefix_len] [interface [/ sla_id [/ prefix_len [/
199 suffix]]]]]
200 Request a DHCPv6 Delegated Prefix for iaid. This option must be
201 used in an interface block. Unless a sla_id of 0 is assigned
202 with the same resultant prefix length as the delegation, a reject
203 route is installed for the Delegated Prefix to stop unallocated
204 addresses being resolved upstream. If no interface is given then
205 we will assign a prefix to every other interface with a sla_id
206 equivalent to the interface index assigned by the OS. Otherwise
207 addresses are only assigned for each interface and sla_id. Each
208 assigned address will have a suffix, defaulting to 1. If the
209 suffix is 0 then a slaac address is assigned. You cannot assign
210 a prefix to the requesting interface unless the DHCPv6 server
211 supports RFC6603 Prefix Exclude Option. dhcpcd has to be running
212 for all the interfaces it is delegating to. A default prefix_len
213 of 64 is assumed, unless the maximum sla_id does not fit. In
214 this case prefix_len is increased to the highest multiple of 8
215 that can accommodate the sla_id. sla_id is an integer which must
216 be unique inside the iaid and is added to the prefix which must
217 fit inside prefix_len less the length of the delegated prefix.
218 You can specify multiple interface / sla_id / prefix_len per
219 ia_pd, space separated. IPv6RS should be disabled globally when
220 requesting a Prefix Delegation.
221 In the following example eth0 is the externally facing interface
223 to be configured for both IPv4 and IPv6. The DHCPv4 server will
224 provide us with an IPv4 address and a default route. The DHCPv6
225 server is going to provide us with an IPv6 address, a default
226 route and a /64 subnet to be delegated to the internal interface.
227 The eth1 interface will be automatically configured for IPv6
228 using the first address (::1) from the delegated prefix. A sec‐
229 ond prefix is requested and assigned to two other interfaces.
230 rtadvd(8) can be used with an empty configuration file on eth1,
231 eth2 and eth3, to provide automatic IPv6 address configuration
232 for the internal network.
233 noipv6rs # disable routing solicitation
235 denyinterfaces eth2 # Don't touch eth2 at all
236 interface eth0
237 ipv6rs # enable routing solicitation get the
238 # default IPv6 route
239 ia_na 1 # request an IPv6 address
240 ia_pd 2 eth1/0 # request a PD and assign it to eth1
241 ia_pd 3 eth2/1 eth3/2 # req a PD and assign it to eth2 and eth3
242 ipv4only
244 Only configure IPv4.
245 ipv6only
247 Only confgiure IPv6.
248 fqdn [disable | ptr | both]
250 ptr just asks the DHCP server to update the PTR record of the
251 host in DNS whereas both also updates the A record. disable will
252 disable the FQDN option. The default is both. dhcpcd itself
253 never does any DNS updates. dhcpcd encodes the FQDN hostname as
254 specified in RFC1035.
255 interface interface
257 Subsequent options are only parsed for this interface.
258 ipv6ra_autoconf
260 Generate SLAAC addresses for each Prefix advertised by a Router
261 Advertisement message with the Auto flag set. On by default.
262 ipv6ra_noautoconf
264 Disables the above option.
265 ipv6ra_fork
267 By default, when dhcpcd receives an IPv6 RA, dhcpcd will only
268 fork to the background if the RA contains at least one unexpired
269 RDNSS option and a valid prefix or no DHCPv6 instruction. Set
270 this option so to make dhcpcd always fork on an RA.
271 ipv6ra_own
273 Disables kernel IPv6 Router Advertisement processing so dhcpcd
274 can manage addresses and routes.
275 ipv6ra_own_default
277 Each time dhcpcd receives an IPv6 Router Adveristment, dhcpcd
278 will manage the default route only. This allows dhcpcd to prefer
279 an interface for outbound traffic based on metric and/or user
280 selection rather than the kernel.
281 ipv6rs Enables IPv6 Router Advertisement solicitation. This is on by
283 default, but is documented here in the case where it is disabled
284 globally but needs to be enabled for one interface.
285 leasetime seconds
287 Request a leasetime of seconds.
288 logfile logfile
290 Writes to the specified logfile rather than syslog(3). The
291 logfile is truncated when opened and is reopened when dhcpcd
292 receives the SIGUSR2 signal.
293 metric metric
295 Metrics are used to prefer an interface over another one, lowest
296 wins. dhcpcd will supply a default metric of 200 +
297 if_nametoindex(3). An extra 100 will be added for wireless
298 interfaces.
299 noalias
301 Any pre-existing IPv4 addresses existing address will be removed
302 from the interface when adding a new IPv4 address.
303 noarp Don't send any ARP requests. This also disables IPv4LL.
305 noauthrequired
307 Don't require authentication even though we requested it. Also
308 allows FORCERENEW and RECONFIGURE messages without authentica‐
309 tion.
310 nodelay
312 Don't delay for an initial randomised time when starting proto‐
313 cols.
314 nodev Don't load /dev management modules.
316 nodhcp Don't start DHCP or listen to DHCP messages. This is only useful
318 when allowing IPv4LL.
319 nodhcp6
321 Don't start DHCPv6 or listen to DHCPv6 messages. Normally DHCPv6
322 is started by a RA instruction or configuration.
323 nogateway
325 Don't install any default routes.
326 gateway
328 Install a default route if available (default).
329 nohook script
331 Don't run this hook script. Matches full name, or prefixed with
332 2 numbers optionally ending with .sh.
333 So to stop dhcpcd from touching your DNS settings or starting
335 wpa_supplicant you would do:-
336 nohook resolv.conf, wpa_supplicant
337 noipv4 Don't attempt to configure an IPv4 address.
339 noipv4ll
341 Don't attempt to obtain an IPv4LL address if we failed to get one
342 via DHCP. See RFC 3927.
343 noipv6 Don't attmept to configure an IPv6 address.
345 noipv6rs
347 Disable solicitation and receipt of IPv6 Router Advertisements.
348 nolink Don't receive link messages about carrier status. You should
350 only set this for buggy interface drivers.
351 noup Don't bring the interface up when in master mode. If dhcpcd.conf
353 cannot determine the carrier state, dhcpcd.conf will enter a
354 tight polling loop until the interface is marked up and running
355 or a valid carrier state is reported.
356 option option
358 Requests the option from the server. It can be a variable to be
359 used in dhcpcd-run-hooks(8) or the numerical value. You can
360 specify more options separated by commas, spaces or more option
361 lines. option Prepend dhcp6_ to option to request a DHCPv6
362 option. If no DHCPv6 options are configured, then DHCPv4 options
363 are mapped to equivalent DHCPv6 options.
364 Prepend nd_ to option to handle ND options, but this only works
366 for the nooption, reject and require options.
367 To see a list of options you can use, call dhcpcd with the -V,
369 --variables argument.
370 nooption option
372 Remove the option from the message before it's processed.
373 require option
375 Requires the option to be present in all messages, otherwise the
376 message is ignored. To enforce that dhcpcd only responds to DHCP
377 servers and not BOOTP servers, you can require dhcp_message_type.
378 This isn't an exact science though because a BOOTP server can
379 send DHCP like options.
380 reject option
382 Reject a message that contains the option. This is useful when
383 you cannot use require to select / de-select BOOTP messages.
384 destination option
386 If dhcpcd.conf detects an address added to a point to point
387 interface (PPP, TUN, etc) then it will set the listed DHCP
388 options to the destination address of the interface.
389 profile name
391 Subsequent options are only parsed for this profile name.
392 quiet Suppress any dhcpcd output to the console, except for errors.
394 reboot seconds
396 Allow reboot seconds before moving to the DISCOVER phase if we
397 have an old lease to use and moving from DISCOVER to IPv4LL if no
398 reply. The default is 5 seconds. A setting of 0 seconds causes
399 dhcpcd to skip the REBOOT phase and go straight into DISCOVER.
400 This is desirable for mobile users because if you change from
401 network A to network B and they use the same subnet and the
402 address from network A isn't in use on network B, then the DHCP
403 server will remain silent even if authoritative which means
404 dhcpcd will timeout before moving back to the DISCOVER phase.
405 release
407 dhcpcd will release the lease prior to stopping the interface.
408 script script
410 Use script instead of the default /usr/libexec/dhcpcd-run-hooks.
411 ssid ssid
413 Subsequent options are only parsed for this wireless ssid.
414 slaac [hwaddr | private]
416 Selects the interface identifier used for SLAAC generated IPv6
417 addresses. If private is used, a RFC7217 address is generated.
418 static value
420 Configures a static value. If you set ip_address then dhcpcd
421 will not attempt to obtain a lease and just use the value for the
422 address with an infinite lease time. If you set ip6_address,
423 dhcpcd will continue auto-configuation as normal.
424 Here is an example which configures two static address, an IPv4
426 router, DNS and disables IPv6 auto-configuration. You could also
427 use the inform6 command here if you wished to obtain more infor‐
428 mation via DHCPv6. For IPv4, you should use the inform ipaddress
429 option instead of setting a static address.
430 interface eth0
431 noipv6rs
432 static ip_address=192.168.0.10/24
433 static ip6_address=fd51:42f8:caae:d92e::ff/64
434 static routers=192.168.0.1
435 static domain_name_servers=192.168.0.1
436 fd51:42f8:caae:d92e::1
437 Here is an example for PPP which gives the destination a default
439 route. It uses the special destination keyword to insert the
440 destination address into the value.
441 interface ppp0
442 static ip_address=
443 destination routers
444 timeout seconds
446 Timeout after seconds, instead of the default 30. A setting of 0
447 seconds causes dhcpcd to wait forever to get a lease. If dhcpcd
448 is working on a single interface then dhcpcd will exit when a
449 timeout occurs, otherwise dhcpcd will fork into the background.
450 If using IPv4LL then dhcpcd start the IPv4LL process after the
451 timeout and then wait a little longer before really timing out.
452 userclass string
454 Tag the DHCPv4 messages with the userclass. You can specify more
455 than one.
456 vendor code,value
458 Add an encapsulated vendor option. code should be between 1 and
459 254 inclusive. To add a raw vendor string, omit code but keep
460 the comma. Examples.
461 Set the vendor option 01 with an IP address.
463 vendor 01,192.168.0.2
464 Set the vendor option 02 with a hex code.
465 vendor 02,01:02:03:04:05
466 Set the vendor option 03 with an IP address as a string.
467 vendor 03,\"192.168.0.2\"
468 Set un-encapsulated vendor option to hello world.
469 vendor ,"hello world"
470 vendorclassid string
472 Set the DHCP Vendor Class. DHCPv6 has it's own option as shown
473 below. The default is dhcpcd-<version>:<os>:<machine>:<plat‐
474 form>. For example
475 dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386
476 If not set then none is sent. Some badly configured DHCP servers
477 reject unknown vendorclassids. To work around it, try and imper‐
478 sonate Windows by using the MSFT vendorclassid.
479 vendclass en data
481 Add the DHCPv6 Vendor Indetifying Vendor Class with the IANA
482 assigned Enterprise Number en with the data. This option can be
483 set more than once to add more data, but the behaviour, as per
484 RFC(3925) is undefined if the Enterprise Number differs.
485 waitip [4 | 6]
487 Wait for an address to be assigned before forking to the back‐
488 ground. 4 means wait for an IPv4 address to be assigned. 6
489 means wait for an IPv6 address to be assigned. If no argument is
490 given, dhcpcd.conf will wait for any address protocol to be
491 assigned. It is possible to wait for more than one address pro‐
492 tocol and dhcpcd.conf will only fork to the background when all
493 waiting conditions are satisfied.
494 xidhwaddr
496 Use the last four bytes of the hardware address as the DHCP xid
497 instead of a randomly generated number.
498 Defining new options
500 DHCP, ND and DHCPv6 allow for the use of custom options. Each option
501 needs to be started with the define, ∞or define6 directive. This can
502 optionally be followed by both embed or encap options. Both can be spec‐
503 ified more than once and embed must come before encap.
504 define code type variable
506 Defines the DHCP option code of type with a name of variable
507 exported to dhcpcd-run-hooks(8).
508 definend code type variable
510 Defines the ND option code of type with a name of variable
511 exported to dhcpcd-run-hooks(8), with a prefix of _nd.
512 define6 code type variable
514 Defines the DHCPv6 option code of type with a name of variable
515 exported to dhcpcd-run-hooks(8), with a prefix of _dhcp6.
516 vendopt code type variable
518 Defines the Vendor-Identifying Vendor Options. The code is the
519 IANA Enterprise Number which will unqiuely describe the encapsu‐
520 lated options. type is normally encap. variable names the Ven‐
521 dor option to be exported.
522 embed type variable
524 Defines an embedded variable within the defined option. The
525 length is determined by the type. If the variable is not the
526 same as defined in the parent option, it is prefixed with the
527 parent variable first with an underscore. If the variable has
528 the name of reserved then it is not processed.
529 encap code type variable
531 Defines an encapsulated variable within the defined option. The
532 length is determined by the type. If the variable is not the
533 same as defined in the parent option, it is prefixed with the
534 parent variable first with an underscore.
535 Type prefix
537 These keywords come before the type itself, to describe it more fully.
538 You can use more than one, but they must appear in the order listed
539 below.
540 request Requests the option by default without having to be specified in
542 user configuration
543 norequest
545 This option cannot be requested, regardless of user configura‐
546 tion
547 optional
549 This option is optional. Only makes sense for embedded options
550 where like the client FQDN option where the FQDN string itself
551 is optional.
552 index The option can appear more than once and will be indexed.
554 array The option data is split into a space separated array, each ele‐
556 ment being the same type.
557 Types to define
559 The type directly affects the length of data consumed inside the option.
560 Any remaining data is normally discarded. Lengths can be specified for
561 string and binhex types, but this is generally with other data embedded
562 afterwards in the same option.
563 ipaddress
565 An IPv4 address, 4 bytes.
566 ip6address
568 An IPv6 address, 16 bytes.
569 string [: length]
571 A NVT ASCII string of printable characters.
572 byte A byte.
574 bitflags: flags
576 A byte represented as a string of flags, most significant bit
577 first. For example, using ABCDEFGH then A would equal 10000000,
578 B 01000000, C 00100000, etc. If the bit is not set, the flag is
579 not printed. A flag of 0 is not printed even if the bit posti‐
580 tion is set. This is to allow reservation of the first bits
581 while assinging the last bits.
582 int16 A signed 16bit integer, 2 bytes.
584 uint16 An unsigned 16bit integer, 2 bytes.
586 int32 A signed 32bit integer, 4 bytes.
588 uint32 An unsigned 32bit integer, 4 bytes.
590 flag A fixed value (1) to indicate that the option is present, 0
592 bytes.
593 domain A RFC 3397 encoded string.
595 dname A RFC 1035 validated string.
597 binhex [: length]
599 Binary data expressed as hexadecimal.
600 embed Contains embedded options (implies encap as well).
602 encap Contains encapsulated options (implies embed as well).
604 option References an option from the global definition.
606 Example definition
608 # DHCP option 81, Fully Qualified Domain Name, RFC4702
609 define 81 embed fqdn
610 embed byte flags
611 embed byte rcode1
612 embed byte rcode2
613 embed domain fqdn
614 # DHCP option 125, Vendor Specific Information Option, RFC3925
616 define 125 encap vsio
617 embed uint32 enterprise_number
618 # Options defined for the enterprise number
619 encap 1 ipaddress ipaddress
620 Supported Authentication Protocols
622 token Sends and expects the token with the secretid 0 and realm of ""
623 in each message.
624 delayedrealm
626 Delayed Authentication. dhcpcd will send an authentication
627 option with no key or MAC. The server will see this option, and
628 select a key for dhcpcd.conf, writing the realm and secretid in
629 it. dhcpcd will then look for a non-expired token with a match‐
630 ing realm and secretid. This token is used to authenicate all
631 other messages.
632 delayed Same as above, but without a realm.
634 Supported Authentication Algorithms
636 If none specified, hmac-md5 is the default.
637 hmac-md5
639 Supported Replay Detection Mechanisms
641 If none specified, monotonic is the default. If this is changed from
642 what was previously used, or the means of calculating or storing it is
643 broken then the DHCP server will probably have to have its notion of the
644 clients Replay Detection Value reset.
645 monocounter
647 Read the number in the file /var/lib/dhcpcd/dhcpcd-rdm.monotonic
648 and add one to it.
649 monotime
651 Create a NTP timestamp from the system time.
652 monotonic
654 Same as monotime.
655
657 fnmatch(3), if_nametoindex(3), dhcpcd(8), dhcpcd-run-hooks(8)
658
660 Roy Marples <roy@marples.name>
661
663 Please report them to
664 http://roy.marples.name/projects/dhcpcd
665BSD June 27, 2016 BSD