| blob | 8827f03b174525e735abaa78c857ecf536157aff |
1 .\" $NetBSD: dhcpcd.conf.5.in,v 1.23 2015/08/21 10:39:00 roy Exp $
2 .\" Copyright (c) 2006-2015 Roy Marples
3 .\" All rights reserved
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\"
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 .\" SUCH DAMAGE.
25 .\"
26 .Dd August 1, 2015
27 .Dt DHCPCD.CONF 5
28 .Os
29 .Sh NAME
30 .Nm dhcpcd.conf
31 .Nd dhcpcd configuration file
32 .Sh DESCRIPTION
33 Although
34 .Nm dhcpcd
35 can do everything from the command line, there are cases where it's just easier
36 to do it once in a configuration file.
37 Most of the options found in
38 .Xr dhcpcd 8
39 can be used here.
40 The first word on the line is the option and the rest of the line is the value.
41 Leading and trailing whitespace for the option and value are trimmed.
42 You can escape characters in the value using the \\ character.
43 .Pp
44 Blank lines and lines starting with # are ignored.
45 .Pp
46 Here's a list of available options:
47 .Bl -tag -width indent
48 .It Ic allowinterfaces Ar pattern
49 When discovering interfaces, the interface name must match
50 .Ar pattern
51 which is a space or comma separated list of patterns passed to
52 .Xr fnmatch 3 .
53 If the same interface is matched in
54 .Ic denyinterfaces
55 then it is still denied.
56 .It Ic denyinterfaces Ar pattern
57 When discovering interfaces, the interface name must not match
58 .Ar pattern
59 which is a space or comma separated list of patterns passed to
60 .Xr fnmatch 3 .
61 .It Ic arping Ar address Op address
62 .Nm dhcpcd
63 will arping each address in order before attempting DHCP.
64 If an address is found, we will select the replying hardware address as the
65 profile, otherwise the ip address.
66 Example:
67 .Pp
68 .D1 interface bge0
69 .D1 arping 192.168.0.1
70 .Pp
71 .D1 profile 192.168.0.1
72 .D1 static ip_address=192.168.0.10/24
73 .It Ic authprotocol Ar protocol Ar algorithm Ar rdm
74 Authenticate DHCP messages.
75 See the Supported Authentication Protocols section.
76 .It Ic authtoken Ar secretid Ar realm Ar expire Ar key
77 Define a shared key for use in authentication.
78 .Ar realm can be "" to for use with the
79 .Ar delayed
80 prptocol.
81 .Ar expire
82 is the date the token expires and should be formatted "yyy-mm-dd HH:MM".
83 You can use the keyword
84 .Ar forever
85 or
86 .Ar 0
87 which means the token never expires.
88 For the token protocol,
89 .Ar secretid
90 needs to be 0 and
91 .Ar realm
92 needs to be "".
93 If
94 .Nm dhcpcd
95 has the error
96 .D1 dhcp_auth_encode: Invalid argument
97 then it means that
98 .Nm dhcpcd
99 could not find the correct authentication token in your configuration.
100 .It Ic background
101 Background immediately.
102 This is useful for startup scripts which don't disable link messages for
103 carrier status.
104 .It Ic blacklist Ar address Ns Op /cidr
105 Ignores all packets from
106 .Ar address Ns Op /cidr .
107 .It Ic whitelist Ar address Ns Op /cidr
108 Only accept packets from
109 .Ar address Ns Op /cidr .
110 .Ic blacklist
111 is ignored if
112 .Ic whitelist
113 is set.
114 .It Ic bootp
115 Be a BOOTP client.
116 Basically, this just doesn't send a DHCP Message Type option and will only
117 interact with a BOOTP server.
118 All other DHCP options still work.
119 .It Ic broadcast
120 Instructs the DHCP server to broadcast replies back to the client.
121 Normally this is only set for non Ethernet interfaces,
122 such as FireWire and InfiniBand.
123 In most cases,
124 .Nm dhcpcd
125 will set this automatically.
126 .It Ic controlgroup Ar group
127 Sets the group ownership of
128 .Pa @RUNDIR@/dhcpcd.sock
129 so that users other than root can connect to
130 .Nm dhcpcd .
131 .It Ic debug
132 Echo debug messages to the stderr and syslog.
133 .It Ic dev Ar value
134 Load the
135 .Ar value
136 .Pa /dev
137 management module.
138 .Nm dhcpcd
139 will load the first one found to work, if any.
140 .It Ic env Ar value
141 Push
142 .Ar value
143 to the environment for use in
144 .Xr dhcpcd-run-hooks 8 .
145 For example, you can force the hostname hook to always set the hostname with
146 .Ic env
147 .Va force_hostname=YES .
148 Or set which driver
149 .Xr wpa_supplicant 8
150 should use with
151 .Ic env
152 .Va wpa_supplicant_driver=nl80211
153 .Pp
154 If the hostname is set, will be will set to the FQDN if possible as per
155 RFC 4702 section 3.1.
156 If the FQDN option is missing,
157 .Nm dhcpcd
158 will still try and set a FQDN from the hostname and domain options for
159 consistency.
160 To override this, set
161 .Ic env
162 .Va hostname_fqdn=[YES|NO|SERVER] .
163 A value of server means just what the server says, don't manipulate it.
164 This could lead to an inconsistent hostname on a DHCPv4 and DHCPv6 network
165 where the DHCPv4 hostname is short and the DHCPv6 has an FQDN.
166 DHCPv6 has no hostname option.
167 .It Ic clientid Ar string
168 Send the
169 .Ar clientid .
170 If the string is of the format 01:02:03 then it is encoded as hex.
171 For interfaces whose hardware address is longer than 8 bytes, or if the
172 .Ar clientid
173 is an empty string then
174 .Nm dhcpcd
175 sends a default
176 .Ar clientid
177 of the hardware family and the hardware address.
178 .It Ic duid
179 Generate an
180 .Rs
181 .%T "RFC 4361"
182 .Re
183 compliant DHCP Unique Identifier.
184 If persistent storage is available then a DUID-LLT (link local address + time)
185 is generated, otherwise DUID-LL is generated (link local address).
186 This, plus the IAID will be used as the
187 .Ic clientid .
188 The DUID-LLT generated will be held in
189 .Pa @SYSCONFDIR@/dhcpcd.duid
190 and should not be copied to other hosts.
191 .It Ic iaid Ar iaid
192 Set the Interface Association Identifier to
193 .Ar iaid .
194 This option must be used in an
195 .Ic interface
196 block.
197 This defaults to the last 4 bytes of the hardware address assigned to the
198 interface.
199 Each instance of this should be unique within the scope of the client and
200 .Nm dhcpcd
201 warns if a conflict is detected.
202 If there is a conflict, it is only a problem if the conflicted IAIDs are
203 used on the same network.
204 .It Ic dhcp
205 Enable DHCP on the interface, on by default.
206 .It Ic dhcp6
207 Enable DHCPv6 on the interface, on by default.
208 .It Ic ipv4
209 Enable IPv4 on the interface, on by default.
210 .It Ic ipv6
211 Enable IPv6 on the interface, on by default.
212 .It Ic persistent
213 .Nm dhcpcd
214 normally de-configures the interface and configuration when it exits.
215 Sometimes, this isn't desirable if, for example, you have root mounted over
216 NFS or SSH clients connect to this host and they need to be notified of
217 the host shutting down.
218 You can use this option to stop this from happening.
219 .It Ic fallback Ar profile
220 Fallback to using this profile if DHCP fails.
221 This allows you to configure a static profile instead of using ZeroConf.
222 .It Ic hostname Ar name
223 Sends
224 .Ar hostname
225 to the DHCP server so it can be registered in DNS.
226 If
227 .Ar hostname
228 is an empty string then the current system hostname is sent.
229 If
230 .Ar hostname
231 is a FQDN (ie, contains a .) then it will be encoded as such.
232 .It Ic hostname_short
233 Sends the short hostname to the DHCP server instead of the FQDN.
234 This is useful because DHCP servers will not register the FQDN in their
235 DNS if the domain part does not match theirs.
236 .Pp
237 Also, see the
238 .Ic env
239 option above to control how the hostname is set on the host.
240 .It Ic ia_na Op Ar iaid Op / address
241 Request a DHCPv6 Normal Address for
242 .Ar iaid .
243 .Ar iaid
244 defaults to the
245 .Ic iaid
246 option as described above.
247 You can request more than one ia_na by specifying a unique
248 .Ar iaid
249 for each one.
250 .It Ic ia_ta Op Ar iaid
251 Request a DHCPv6 Temporary Address for
252 .Ar iaid .
253 You can request more than one ia_ta by specifying a unique
254 .Ar iaid
255 for each one.
256 .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
257 Request a DHCPv6 Delegated Prefix for
258 .Ar iaid .
259 This option must be used in an
260 .Ic interface
261 block.
262 Unless a
263 .Ar sla_id
264 of 0 is assigned, a reject route is installed for the Delegated Prefix to
265 stop unallocated addresses being resolved upstream.
266 This reject route is in essence SLA 0, thus you need space within the prefix
267 to assign a SLA per interface.
268 If no
269 .Ar interface
270 is given then we will assign a prefix to every other interface with a
271 .Ar sla_id
272 equivalent to the interface index assigned by the OS.
273 Otherwise addresses are only assigned for each
274 .Ar interface
275 and
276 .Ar sla_id .
277 Each assigned address will have a suffix of 1.
278 You cannot assign a prefix to the requesting interface unless the
279 DHCPv6 server supports
280 .Li RFC6603
281 Prefix Exclude Option.
282 .Nm dhcpcd
283 has to be running for all the interfaces it is delegating to.
284 A default
285 .Ar prefix_len
286 of 64 is assumed, unless the maximum
287 .Ar sla_id
288 does not fit.
289 In this case
290 .Ar prefix_len
291 is increased to the highest multiple of 8 that can accommodate the
292 .Ar sla_id .
293 .Ar sla_id
294 is an integer and is added to the prefix which must fit inside
295 .Ar prefix_len
296 less the length of the delegated prefix.
297 .Ar sla_id can be 0 only if the Delegated Prefix is assigned to one interface.
298 You can specify multiple
299 .Ar interface /
300 .Ar sla_id /
301 .Ar prefix_len
302 per
303 .Ic ia_pd ,
304 space separated.
305 IPv6RS should be disabled globally when requesting a Prefix Delegation.
306 .Pp
307 In the following example eth0 is the externally facing interface to be
308 configured for both IPv4 and IPv6.
309 The DHCPv4 server will provide us with an IPv4 address and a default route.
310 The DHCPv6 server is going to provide us with an IPv6 address, a default
311 route and a /64 subnet to be delegated to the internal interface.
312 The eth1 interface will be automatically configured
313 for IPv6 using the first address (::1) from the delegated prefix.
314 A second prefix is requested and assigned to two other interfaces.
315 .Xr rtadvd 8
316 can be used with an empty configuration file on eth1, eth2 and eth3,
317 to provide automatic
318 IPv6 address configuration for the internal network.
319 .Bd -literal -indent
320 noipv6rs # disable routing solicitation
321 denyinterfaces eth2 # Don't touch eth2 at all
322 interface eth0
323 ipv6rs # enable routing solicitation get the
324 # default IPv6 route
325 ia_na 1 # request an IPv6 address
326 ia_pd 2 eth1/0 # request a PD and assign it to eth1
327 ia_pd 3 eth2/1 eth3/2 # req a PD and assign it to eth2 and eth3
328 # we cannot use SLA 0 above because we are
329 # assinging the PD to more than one interface
330 .Ed
331 .It Ic ipv4only
332 Only configure IPv4.
333 .It Ic ipv6only
334 Only confgiure IPv6.
335 .It Ic fqdn Op disable | ptr | both
336 ptr just asks the DHCP server to update the PTR
337 record of the host in DNS whereas both also updates the A record.
338 disable will disable the FQDN option.
339 The default is both.
340 .Nm dhcpcd
341 itself never does any DNS updates.
342 .Nm dhcpcd
343 encodes the FQDN hostname as specified in
344 .Li RFC1035 .
345 .It Ic interface Ar interface
346 Subsequent options are only parsed for this
347 .Ar interface .
348 .It Ic ipv6ra_autoconf
349 Generate SLAAC addresses for each Prefix advertised by a
350 Router Advertisement message with the Auto flag set.
351 On by default.
352 .It Ic ipv6ra_noautoconf
353 Disables the above option.
354 .It Ic ipv6ra_fork
355 By default, when
356 .Nm dhcpcd
357 receives an IPv6 RA,
358 .Nm dhcpcd
359 will only fork to the background if the RA contains at least one unexpired
360 RDNSS option and a valid prefix or no DHCPv6 instruction.
361 Set this option so to make
362 .Nm dhcpcd
363 always fork on an RA.
364 .It Ic ipv6ra_own
365 Disables kernel IPv6 Router Advertisment processing so dhcpcd can manage
366 addresses and routes.
367 .It Ic ipv6ra_own_default
368 Each time dhcpcd receives an IPv6 Router Adveristment, dhcpcd will manage
369 the default route only.
370 This allows dhcpcd to prefer an interface for outbound traffic based on metric
371 and/or user selection rather than the kernel.
372 .It Ic ipv6ra_accept_nopublic
373 Some IPv6 routers advertise themselves as a default router without any
374 public prefixes or managed addresses.
375 Generally, this is incorrect behaviour and
376 .Nm dhcpcd
377 will ignore the advertisement unless this option is turned on.
378 .It Ic ipv6rs
379 Enables IPv6 Router Advertisment solicitation.
380 This is on by default, but is documented here in the case where it is disabled
381 globally but needs to be enabled for one interface.
382 .It Ic leasetime Ar seconds
383 Request a leasetime of
384 .Ar seconds .
385 .It Ic logfile Ar logfile
386 Writes to the specified
387 .Ar logfile
388 rather than
389 .Xr syslog 3 .
390 The
391 .Ar logfile
392 is truncated when opened and is reopened when
393 .Nm dhcpcd
394 receives the
395 .Dv SIGUSR2
396 signal.
397 .It Ic metric Ar metric
398 Metrics are used to prefer an interface over another one, lowest wins.
399 .Nm dhcpcd
400 will supply a default metric of 200 +
401 .Xr if_nametoindex 3 .
402 An extra 100 will be added for wireless interfaces.
403 .It Ic noalias
404 Any pre-existing IPv4 addresses existing address will be removed from the
405 interface when adding a new IPv4 address.
406 .It Ic noarp
407 Don't send any ARP requests.
408 This also disables IPv4LL.
409 .It Ic noauthrequired
410 Don't require authentication even though we requested it.
411 Also allows FORCERENEW and RECONFIGURE messages without authentication.
412 .It Ic nodelay
413 Don't delay for an initial randomised time when starting protocols.
414 .It Ic nodev
415 Don't load
416 .Pa /dev
417 management modules.
418 .It Ic nodhcp
419 Don't start DHCP or listen to DHCP messages.
420 This is only useful when allowing IPv4LL.
421 .It Ic nodhcp6
422 Don't start DHCPv6 or listen to DHCPv6 messages.
423 Normally DHCPv6 is started by a RA instruction or configuration.
424 .It Ic nogateway
425 Don't install any default routes.
426 .It Ic gateway
427 Install a default route if available (default).
428 .It Ic nohook Ar script
429 Don't run this hook script.
430 Matches full name, or prefixed with 2 numbers optionally ending with
431 .Pa .sh .
432 .Pp
433 So to stop
434 .Nm dhcpcd
435 from touching your DNS settings or starting wpa_supplicant you would do:-
436 .D1 nohook resolv.conf, wpa_supplicant
437 .It Ic noipv4
438 Don't attempt to configure an IPv4 address.
439 .It Ic noipv4ll
440 Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP.
441 See
442 .Rs
443 .%T "RFC 3927"
444 .Re
445 .It Ic noipv6
446 Don't attmept to configure an IPv6 address.
447 .It Ic noipv6rs
448 Disable solicitation and receipt of IPv6 Router Advertisements.
449 .It Ic nolink
450 Don't receive link messages about carrier status.
451 You should only set this for buggy interface drivers.
452 .It Ic noup
453 Don't bring the interface up when in master mode.
454 If
455 .Nm
456 cannot determine the carrier state,
457 .Nm
458 will enter a tight polling loop until the interface is marked up and running
459 or a valid carrier state is reported.
460 .It Ic option Ar option
461 Requests the
462 .Ar option
463 from the server.
464 It can be a variable to be used in
465 .Xr dhcpcd-run-hooks 8
466 or the numerical value.
467 You can specify more
468 .Ar option Ns s
469 separated by commas, spaces or more
470 .Ic option
471 lines.
472 .Ar option
473 Prepend dhcp6_ to
474 .Ar option
475 to request a DHCPv6 option.
476 If no DHCPv6 options are configured,
477 then DHCPv4 options are mapped to equivalent DHCPv6 options.
478 .Pp
479 Prepend nd_ to
480 .Ar option
481 to handle ND options, but this only works for the
482 .Ic nooption ,
483 .Ic reject
484 and
485 .Ic require
486 options.
487 .It Ic nooption Ar option
488 Remove the option from the message before it's processed.
489 .It Ic require Ar option
490 Requires the
491 .Ar option
492 to be present in all messages, otherwise the message is ignored.
493 To enforce that
494 .Nm dhcpcd
495 only responds to DHCP servers and not BOOTP servers, you can
496 .Ic require
497 .Ar dhcp_message_type .
498 This isn't an exact science though because a BOOTP server can send DHCP like
499 options.
500 .It Ic reject Ar option
501 Reject a message that contains the
502 .Ar option .
503 This is useful when you cannot use
504 .Ic require
505 to select / de-select BOOTP messages.
506 .It Ic destination Ar option
507 If
508 .Nm
509 detects an address added to a point to point interface (PPP, TUN, etc) then
510 it will set the listed DHCP options to the destination address of the
511 interface.
512 .It Ic profile Ar name
513 Subsequent options are only parsed for this profile
514 .Ar name .
515 .It Ic quiet
516 Suppress any dhcpcd output to the console, except for errors.
517 .It Ic reboot Ar seconds
518 Allow
519 .Ar reboot
520 seconds before moving to the DISCOVER phase if we have an old lease to use
521 and moving from DISCOVER to IPv4LL if no reply.
522 The default is 5 seconds.
523 A setting of 0 seconds causes
524 .Nm dhcpcd
525 to skip the REBOOT phase and go straight into DISCOVER.
526 This is desirable for mobile users because if you change from network A to
527 network B and they use the same subnet and the address from network A isn't
528 in use on network B, then the DHCP server will remain silent even if authorative
529 which means
530 .Nm dhcpcd
531 will timeout before moving back to the DISCOVER phase.
532 .It Ic release
533 .Nm dhcpcd
534 will release the lease prior to stopping the interface.
535 .It Ic script Ar script
536 Use
537 .Ar script
538 instead of the default
539 .Pa @SCRIPT@ .
540 .It Ic ssid Ar ssid
541 Subsequent options are only parsed for this wireless
542 .Ar ssid .
543 .It Ic slaac Op Ar hwaddr | Ar private
544 Selects the interface identifier used for SLAAC generated IPv6 addresses.
545 If
546 .Ar private
547 is used, a RFC7217 address is generated.
548 .It Ic static Ar value
549 Configures a static
550 .Ar value .
551 If you set
552 .Ic ip_address
553 then
554 .Nm dhcpcd
555 will not attempt to obtain a lease and just use the value for the address with
556 an infinite lease time.
557 .Pp
558 Here is an example which configures a static address, routes and dns.
559 .D1 interface eth0
560 .D1 static ip_address=192.168.0.10/24
561 .D1 static routers=192.168.0.1
562 .D1 static domain_name_servers=192.168.0.1
563 .Pp
564 Here is an example for PPP which gives the destination a default route.
565 It uses the special destination keyword to insert the destination address
566 into the value.
567 .D1 interface ppp0
568 .D1 static ip_address=
569 .D1 destination routers
570 .It Ic timeout Ar seconds
571 Timeout after
572 .Ar seconds ,
573 instead of the default 30.
574 A setting of 0
575 .Ar seconds
576 causes
577 .Nm dhcpcd
578 to wait forever to get a lease.
579 If
580 .Nm dhcpcd
581 is working on a single interface then
582 .Nm dhcpcd
583 will exit when a timeout occurs, otherwise
584 .Nm dhcpcd
585 will fork into the background.
586 If using IPv4LL then
587 .Nm dhcpcd
588 start the IPv4LL process after the timeout and then wait a little longer
589 before really timing out.
590 .It Ic userclass Ar string
591 Tag the DHCPv4 messages with the userclass.
592 You can specify more than one.
593 .It Ic vendor Ar code , Ns Ar value
594 Add an encapsulated vendor option.
595 .Ar code
596 should be between 1 and 254 inclusive.
597 To add a raw vendor string, omit
598 .Ar code
599 but keep the comma.
600 Examples.
601 .Pp
602 Set the vendor option 01 with an IP address.
603 .D1 vendor 01,192.168.0.2
604 Set the vendor option 02 with a hex code.
605 .D1 vendor 02,01:02:03:04:05
606 Set the vendor option 03 with an IP address as a string.
607 .D1 vendor 03,\e"192.168.0.2\e"
608 Set un-encapsulated vendor option to hello world.
609 .D1 vendor ,"hello world"
610 .It Ic vendorclassid Ar string
611 Set the DHCP Vendor Class.
612 DHCPv6 has it's own option as shown below.
613 The default is
614 dhcpcd-<version>:<os>:<machine>:<platform>.
615 For example
616 .D1 dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386
617 If not set then none is sent.
618 Some badly configured DHCP servers reject unknown vendorclassids.
619 To work around it, try and impersonate Windows by using the MSFT vendorclassid.
620 .It Ic vendclass Ar en Ar data
621 Add the DHCPv6 Vendor Indetifying Vendor Class with the IANA assigned Enterprise
622 Number
623 .Ar en
624 with the
625 .Ar data .
626 This option can be set more than once to add more data, but the behaviour,
627 as per
628 .Xr RFC 3925
629 is undefined if the Enterprise Number differs.
630 .It Ic waitip Op 4 | 6
631 Wait for an address to be assigned before forking to the background.
632 4 means wait for an IPv4 address to be assigned.
633 6 means wait for an IPv6 address to be assigned.
634 If no argument is given,
635 .Nm
636 will wait for any address protocol to be assigned.
637 It is possible to wait for more than one address protocol and
638 .Nm
639 will only fork to the background when all waiting conditions are satisfied.
640 .It Ic xidhwaddr
641 Use the last four bytes of the hardware address as the DHCP xid instead
642 of a randomly generated number.
643 .El
644 .Ss Defining new options
645 DHCP, ND and DHCPv6 allow for the use of custom options.
646 Each option needs to be started with the
647 .Ic define ,
648 .If definend
649 or
650 .Ic define6
651 directive.
652 This can optionally be followed by both
653 .Ic embed
654 or
655 .Ic encap
656 options.
657 Both can be specified more than once and
658 .Ic embed
659 must come before
660 .Ic encap .
661 .Bl -tag -width indent
662 .It Ic define Ar code Ar type Ar variable
663 Defines the DHCP option
664 .Ar code
665 of
666 .Ar type
667 with a name of
668 .Ar variable
669 exported to
670 .Xr dhcpcd-run-hooks 8 .
671 .It Ic definend Ar code Ar type Ar variable
672 Defines the ND option
673 .Ar code
674 of
675 .Ar type
676 with a name of
677 .Ar variable
678 exported to
679 .Xr dhcpcd-run-hooks 8 ,
680 with a prefix of
681 .Va _nd .
682 .It Ic define6 Ar code Ar type Ar variable
683 Defines the DHCPv6 option
684 .Ar code
685 of
686 .Ar type
687 with a name of
688 .Ar variable
689 exported to
690 .Xr dhcpcd-run-hooks 8 ,
691 with a prefix of
692 .Va _dhcp6 .
693 .It Ic vendopt Ar code Ar type Ar variable
694 Defines the Vendor-Identifying Vendor Options.
695 The
696 .Ar code
697 is the IANA Enterprise Number which will unqiuely describe the encapsulated
698 options.
699 .Ar type
700 is normally
701 .Ar encap .
702 .Ar variable
703 names the Vendor option to be exported.
704 .It Ic embed Ar type Ar variable
705 Defines an embedded variable within the defined option.
706 The length is determined by the
707 .Ar type .
708 If the
709 .Ar variable
710 is not the same as defined in the parent option,
711 it is prefixed with the parent
712 .Ar variable
713 first with an underscore.
714 If the
715 .Ar variable
716 has the name of
717 .Ar reserved
718 then it is not processed.
719 .It Ic encap Ar code Ar type Ar variable
720 Defines an encapsulated variable within the defined option.
721 The length is determined by the
722 .Ar type .
723 If the
724 .Ar variable
725 is not the same as defined in the parent option,
726 it is prefixed with the parent
727 .Ar variable
728 first with an underscore.
729 .El
730 .Ss Type prefix
731 These keywords come before the type itself, to describe it more fully.
732 You can use more than one, but they must appear in the order listed below.
733 .Bl -tag -width -indent
734 .It Ic request
735 Requests the option by default without having to be specified in user
736 configuration
737 .It Ic norequest
738 This option cannot be requested, regardless of user configuration
739 .It Ic index
740 The option can appear more than once and will be indexed.
741 .It Ic array
742 The option data is split into a space separated array, each element being
743 the same type.
744 .El
745 .Ss Types to define
746 The type directly affects the length of data consumed inside the option.
747 Any remaining data is normally discarded.
748 Lengths can be specified for string and binhex types, but this is generally
749 with other data embedded afterwards in the same option.
750 .Bl -tag -width indent
751 .It Ic ipaddress
752 An IPv4 address, 4 bytes.
753 .It Ic ip6address
754 An IPv6 address, 16 bytes.
755 .It Ic string Op : Ic length
756 A NVT ASCII string of printable characters.
757 .It Ic byte
758 A byte.
759 .It Ic bitflags : Ic flags
760 A byte represented as a string of flags, most significant bit first.
761 For example, using ABCDEFGH then A would equal 10000000, B 01000000,
762 C 00100000, etc.
763 If the bit is not set, the flag is not printed.
764 A flag of 0 is not printed even if the bit postition is set.
765 This is to allow reservation of the first bits while assinging the last bits.
766 .It Ic int16
767 A signed 16bit integer, 2 bytes.
768 .It Ic uint16
769 An unsigned 16bit integer, 2 bytes.
770 .It Ic int32
771 A signed 32bit integer, 4 bytes.
772 .It Ic uint32
773 An unsigned 32bit integer, 4 bytes.
774 .It Ic flag
775 A fixed value (1) to indicate that the option is present, 0 bytes.
776 .It Ic domain
777 A RFC 3397 encoded string.
778 .It Ic dname
779 A RFC 1035 validated string.
780 .It Ic binhex Op : Ic length
781 Binary data expressed as hexadecimal.
782 .It Ic embed
783 Contains embedded options (implies encap as well).
784 .It Ic encap
785 Contains encapsulated options (implies embed as well).
786 .It Ic option
787 References an option from the global definition.
788 .El
789 .Ss Example definition
790 .D1 # DHCP option 81, Fully Qualified Domain Name, RFC4702
791 .D1 define 81 embed fqdn
792 .D1 embed byte flags
793 .D1 embed byte rcode1
794 .D1 embed byte rcode2
795 .D1 embed domain fqdn
796 .Pp
797 .D1 # DHCP option 125, Vendor Specific Information Option, RFC3925
798 .D1 define 125 encap vsio
799 .D1 embed uint32 enterprise_number
800 .D1 # Options defined for the enterprise number
801 .D1 encap 1 ipaddress ipaddress
802 .Ss Supported Authentication Protocols
803 .Bl -tag -width -indent
804 .It Ic token
805 Sends and expects the token with the secretid 0 and realm of "" in each message.
806 .It Ic delayedrealm
807 Delayed Authentication.
808 .Nm dhcpcd
809 will send an authentication option with no key or MAC.
810 The server will see this option, and select a key for
811 .Nm , writing the
812 .Ar realm
813 and
814 .Ar secretid
815 in it.
816 .Nm dhcpcd
817 will then look for a non-expired token with a matching realm and secretid.
818 This token is used to authenicate all other messages.
819 .It Ic delayed
820 Same as above, but without a realm.
821 .El
822 .Ss Supported Authentication Algorithms
823 If none specified,
824 .Ic hmac-md5
825 is the default.
826 .Bl -tag -width -indent
827 .It Ic hmac-md5
828 .El
829 .Ss Supported Replay Detection Mechanisms
830 If none specified,
831 .Ic monotonic
832 is the default.
833 If this is changed from what was previously used,
834 or the means of calculating or storing it is broken then the DHCP server
835 will probably have to have its notion of the clients Replay Detection Value
836 reset.
837 .Bl -tag -width -indent
838 .It Ic monocounter
839 Read the number in the file
840 .Pa @DBDIR@/dhcpcd-rdm.monotonic
841 and add one to it.
842 .It Ic monotime
843 Create a NTP timestamp from the system time.
844 .It Ic monotonic
845 Same as
846 .Ic monotime .
847 .El
848 .Sh SEE ALSO
849 .Xr fnmatch 3 ,
850 .Xr if_nametoindex 3 ,
851 .Xr dhcpcd 8 ,
852 .Xr dhcpcd-run-hooks 8
853 .Sh AUTHORS
854 .An Roy Marples Aq Mt roy@marples.name
855 .Sh BUGS
856 Please report them to
857 .Lk http://roy.marples.name/projects/dhcpcd