xref: /dragonfly/contrib/dhcpcd/src/dhcpcd.conf.5 (revision f984587a)
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