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