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