]>
Commit | Line | Data |
---|---|---|
4c6a8bec | 1 | .\" Copyright (c) 2006-2013 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 | .\" | |
413652c1 | 25 | .Dd September 12, 2013 |
ba9dfb7a | 26 | .Dt DHCPCD.CONF 5 SMM |
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 | |
bac03ede RM |
72 | .It Ic background |
73 | Background immediately. | |
74 | This is useful for startup scripts which don't disable link messages for | |
75 | carrier status. | |
6f767217 | 76 | .It Ic blacklist Ar address Ns Op /cidr |
ce6b39df | 77 | Ignores all packets from |
6f767217 | 78 | .Ar address Ns Op /cidr . |
bf80d526 RM |
79 | .It Ic whitelist Ar address Ns Op /cidr |
80 | Only accept packets from | |
81 | .Ar address Ns Op /cidr . | |
82 | .Ic blacklist | |
83 | is ignored if | |
84 | .Ic whitelist | |
85 | is set. | |
900b3da4 RM |
86 | .It Ic broadcast |
87 | Instructs the DHCP server to broadcast replies back to the client. | |
88 | Normally this is only set for non Ethernet interfaces, | |
89 | such as FireWire and InfiniBand. | |
90 | In most cases, | |
91 | .Nm dhcpcd | |
92 | will set this automatically. | |
413652c1 RM |
93 | .It Ic dev Ar value |
94 | Load the | |
95 | .Ar value | |
96 | .Pa /dev | |
97 | management module. | |
98 | .Nm dhcpcd | |
99 | will load the first one found to work, if any. | |
6bfd88f1 RM |
100 | .It Ic env Ar value |
101 | Push | |
102 | .Ar value | |
103 | to the environment for use in | |
104 | .Xr dhcpcd-run-hooks 8 . | |
105 | For example, you can force the hostname hook to always set the hostname with | |
106 | .Ic env | |
107 | .Va force_hostname=YES . | |
77961e7b RM |
108 | .Pp |
109 | If the hostname is set, will be will set to the FQDN if possible as per | |
110 | RFC 4702 section 3.1. | |
111 | If the FQDN option is missing, | |
112 | .Nm dhcpcd | |
113 | will still try and set a FQDN from the hostname and domain options for | |
114 | consistency. | |
115 | To override this, set | |
116 | .Ic env | |
117 | .Va hostname_fqdn=[YES|NO|SERVER] . | |
118 | A value of server means just what the server says, don't manipulate it. | |
119 | This could lead to an inconsistent hostname on a DHCPv4 and DHCPv6 network | |
120 | where the DHCPv4 hostname is short and the DHCPv6 has an FQDN. | |
121 | DHCPv6 has no hostname option. | |
d2616b08 | 122 | .It Ic clientid Ar string |
c989b023 RM |
123 | Send the |
124 | .Ar clientid . | |
d2616b08 | 125 | If the string is of the format 01:02:03 then it is encoded as hex. |
3faba9e6 RM |
126 | For interfaces whose hardware address is longer than 8 bytes, or if the |
127 | .Ar clientid | |
128 | is an empty string then | |
129 | .Nm dhcpcd | |
130 | sends a default | |
131 | .Ar clientid | |
132 | of the hardware family and the hardware address. | |
d2616b08 RM |
133 | .It Ic duid |
134 | Generate an | |
135 | .Rs | |
136 | .%T "RFC 4361" | |
137 | .Re | |
cf42802e | 138 | compliant clientid. |
7e068c85 RM |
139 | If persistent storage is available then a DUID-LLT (link local address + time) |
140 | is generated, otherwise DUID-LL is generated (link local address). | |
141 | The DUID-LLT generated will be held in | |
d2616b08 RM |
142 | .Pa @SYSCONFDIR@/dhcpcd.duid |
143 | and should not be copied to other hosts. | |
15fc1181 RM |
144 | .It Ic persistent |
145 | .Nm dhcpcd | |
146 | normally de-configures the interface and configuration when it exits. | |
147 | Sometimes, this isn't desirable if, for example, you have root mounted over | |
a544b76a RM |
148 | NFS or SSH clients connect to this host and they need to be notified of |
149 | the host shutting down. | |
15fc1181 | 150 | You can use this option to stop this from happening. |
ff021b0b RM |
151 | .It Ic fallback Ar profile |
152 | Fallback to using this profile if DHCP fails. | |
153 | This allows you to configure a static profile instead of using ZeroConf. | |
ba9dfb7a | 154 | .It Ic hostname Ar name |
35d02ae6 | 155 | Sends |
ff021b0b | 156 | .Ar hostname |
35d02ae6 RM |
157 | to the DHCP server so it can be registered in DNS. |
158 | If | |
35ff0dbb | 159 | .Ar hostname |
35d02ae6 RM |
160 | is an empty string then the current system hostname is sent. |
161 | If | |
162 | .Ar hostname | |
163 | is a FQDN (ie, contains a .) then it will be encoded as such. | |
d6a18654 RM |
164 | .It Ic hostname_short |
165 | Sends the short hostname to the DHCP server instead of the FQDN. | |
166 | This is useful because DHCP servers will not register the FQDN in their | |
167 | DNS if the domain part does not match theirs. | |
77961e7b RM |
168 | .Pp |
169 | Also, see the | |
170 | .Ic env | |
171 | option above to control how the hostname is set on the host. | |
22ea2b0d | 172 | .It Ic ia_na Op Ar iaid |
00ababe4 RM |
173 | Request a DHCPv6 Normal Address for |
174 | .Ar iaid . | |
175 | If none is specified, a default | |
176 | .Ar iaid | |
177 | is used. | |
178 | If the interface name is 4 characters or less then that is used, | |
179 | otherwise the interface index is used. | |
7cece083 | 180 | You can request more than one ia_na by specifying a unique iaid for each one. |
22ea2b0d | 181 | .It Ic ia_ta Op Ar iaid |
00ababe4 RM |
182 | Request a DHCPv6 Temporary Address for |
183 | .Ar iaid . | |
7cece083 | 184 | You can request more than one ia_ta by specifying a unique iaid for each one. |
5985c4e2 | 185 | .It Ic ia_pd Op Ar iaid Op Ar interface Op / Ar sla_id Op / Ar prefix_len |
00ababe4 RM |
186 | Request a DHCPv6 Delegated Prefix for |
187 | .Ar iaid . | |
22ea2b0d RM |
188 | If no |
189 | .Ar interface | |
190 | is given then we will assign a prefix to every other interface with a unique | |
191 | .Ar sla_id | |
192 | for each, starting from 0. | |
193 | Otherwise addresses are only assigned for each | |
00ababe4 RM |
194 | .Ar interface |
195 | and | |
196 | .Ar sla_id | |
00ababe4 | 197 | A default |
367f7b11 | 198 | .Ar prefix_len |
22ea2b0d | 199 | of 64 is assumed. |
367f7b11 RM |
200 | .Ar sla_id |
201 | is an integer and is added to the prefix which must fit inside | |
202 | .Ar prefix_len | |
203 | less the length of the delegated prefix. | |
22ea2b0d RM |
204 | You can specify multiple |
205 | .Ar interface / | |
206 | .Ar sla_id / | |
207 | .Ar prefix_len | |
208 | per | |
209 | .Ic ia_pd , | |
210 | space separated. | |
00ababe4 RM |
211 | IPv6RS should be disabled globally when requesting a Prefix Delegation like so: |
212 | .Pp | |
213 | .D1 noipv6rs | |
214 | .Pp | |
215 | .D1 interface eth0 | |
74ceb961 | 216 | .D1 ia_pd 1 eth1/0 eth2/1 |
d7555c12 RM |
217 | .It Ic ipv4only |
218 | Only configure IPv4. | |
219 | .It Ic ipv6only | |
220 | Only confgiure IPv6. | |
cc3c3560 RM |
221 | .It Ic fqdn Op disable | ptr | both |
222 | ptr just asks the DHCP server to update the PTR | |
35ff0dbb | 223 | record of the host in DNS whereas both also updates the A record. |
cc3c3560 RM |
224 | disable will disable the FQDN option. |
225 | The default is both. | |
1b3bc477 RM |
226 | .Nm dhcpcd |
227 | itself never does any DNS updates. | |
e837a670 RM |
228 | .Nm dhcpcd |
229 | encodes the FQDN hostname as specified in | |
230 | .Li RFC1035 . | |
3adc5520 | 231 | .It Ic interface Ar interface |
012fd5d3 RM |
232 | Subsequent options are only parsed for this |
233 | .Ar interface . | |
61dd6cf9 RM |
234 | .It Ic ipv6ra_fork |
235 | By default, when | |
236 | .Nm dhcpcd | |
237 | receives an IPv6 RA, | |
238 | .Nm dhcpcd | |
239 | will only fork to the background if the RA contains at least one unexpired | |
240 | RDNSS option. | |
241 | Set this option so to make | |
242 | .Nm dhcpcd | |
243 | always fork on an RA. | |
d7555c12 | 244 | .It Ic ipv6ra_own |
eebe9a18 RM |
245 | Disables kernel IPv6 Router Advertisment processing so dhcpcd can manage |
246 | addresses and routes. | |
a521cdce | 247 | This does not work reliably on any BSD system, probably due to kernel issues. |
d7555c12 | 248 | .It Ic ipv6ra_own_default |
eebe9a18 RM |
249 | Each time dhcpcd receives an IPv6 Router Adveristment, dhcpcd will manage |
250 | the default route only. | |
251 | This allows dhcpcd to prefer an interface for outbound traffic based on metric | |
252 | and/or user selection rather than the kernel. | |
a521cdce | 253 | This does work reliably on BSD systems. |
d7555c12 | 254 | .It Ic ipv6rs |
eebe9a18 RM |
255 | Enables IPv6 Router Advertisment solicitation. |
256 | This is on by default, but is documented here in the case where it is disabled | |
257 | globally but needs to be enabled for one interface. | |
ba9dfb7a RM |
258 | .It Ic leasetime Ar seconds |
259 | Request a leasetime of | |
260 | .Ar seconds . | |
065125d4 RM |
261 | .It Ic metric Ar metric |
262 | Metrics are used to prefer an interface over another one, lowest wins. | |
263 | .Nm dhcpcd | |
87b266d2 | 264 | will supply a default metric of 200 + |
065125d4 RM |
265 | .Xr if_nametoindex 3 . |
266 | An extra 100 will be added for wireless interfaces. | |
7dab081f RM |
267 | .It Ic noalias |
268 | IPv4 addresses added will overwrite a pre-existing address instead of working | |
269 | alongside. | |
ba9dfb7a | 270 | .It Ic noarp |
cf42802e RM |
271 | Don't send any ARP requests. |
272 | This also disables IPv4LL. | |
413652c1 RM |
273 | .It Ic nodev |
274 | Don't load | |
275 | .Pa /dev | |
276 | management modules. | |
ba9dfb7a RM |
277 | .It Ic nogateway |
278 | Don't install any default routes. | |
37156a6b RM |
279 | .It Ic nohook Ar script |
280 | Don't run this hook script. | |
8276da82 RM |
281 | Matches full name, or prefixed with 2 numbers optionally ending with |
282 | .Pa .sh . | |
fc7ee231 RM |
283 | .Pp |
284 | So to stop | |
285 | .Nm dhcpcd | |
286 | from touching your DNS or MTU settings you would do:- | |
287 | .D1 nohook resolv.conf, mtu | |
ba9dfb7a RM |
288 | .It Ic noipv4ll |
289 | Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP. | |
290 | See | |
291 | .Rs | |
292 | .%T "RFC 3927" | |
293 | .Re | |
91cd7324 | 294 | .It Ic noipv6rs |
4c6a8bec | 295 | Disable solicitation and receipt of IPv6 Router Advertisements. |
a26af491 RM |
296 | .It Ic nolink |
297 | Don't receive link messages about carrier status. | |
298 | You should only set this for buggy interface drivers. | |
cc45fbd7 | 299 | .It Ic option Ar option |
d2616b08 | 300 | Requests the |
cc45fbd7 | 301 | .Ar option |
cf42802e RM |
302 | from the server. |
303 | It can be a variable to be used in | |
ee4e620a | 304 | .Xr dhcpcd-run-hooks 8 |
cf42802e | 305 | or the numerical value. |
b8ffa3cd RM |
306 | You can specify more |
307 | .Ar option Ns s | |
308 | separated by commas, spaces or more | |
309 | .Ic option | |
310 | lines. | |
311 | Prepend dhcp6_ to | |
312 | .Ar option | |
313 | to request a DHCPv6 option. | |
314 | DHCPv4 options are mapped to DHCPv6 where applicable. | |
2063c6f9 RM |
315 | .It Ic nooption Ar option |
316 | Remove the option from the DHCP message. | |
317 | This should only be used when a DHCP server sends a non requested option | |
318 | that should not be processed. | |
1abffd5b RM |
319 | .It Ic destination Ar option |
320 | If | |
321 | .Nm | |
322 | detects an address added to a point to point interface (PPP, TUN, etc) then | |
323 | it will set the listed DHCP options to the destination address of the | |
324 | interface. | |
6f767217 RM |
325 | .It Ic profile Ar name |
326 | Subsequent options are only parsed for this profile | |
327 | .Ar name . | |
1abffd5b | 328 | .It Ic quiet |
87b266d2 | 329 | Suppress any dhcpcd output to the console, except for errors. |
1abffd5b | 330 | .It Ic reboot Ar seconds |
a2a9a498 RM |
331 | Allow |
332 | .Ar reboot | |
901b42de | 333 | seconds before moving to the DISCOVER phase if we have an old lease to use. |
499225e4 | 334 | The default is 5 seconds. |
901b42de | 335 | A setting of 0 seconds causes |
a2a9a498 | 336 | .Nm dhcpcd |
901b42de RM |
337 | to skip the REBOOT phase and go straight into DISCOVER. |
338 | This is desirable for mobile users because if you change from network A to | |
339 | network B and they use the same subnet and the address from network A isn't | |
340 | in use on network B, then the DHCP server will remain silent even if authorative | |
341 | which means | |
342 | .Nm dhcpcd | |
343 | will timeout before moving back to the DISCOVER phase. | |
2662d519 RM |
344 | .It Ic release |
345 | .Nm dhcpcd | |
346 | will release the lease prior to stopping the interface. | |
cc45fbd7 RM |
347 | .It Ic require Ar option |
348 | Requires the | |
349 | .Ar option | |
350 | to be present in all DHCP messages, otherwise the message is ignored. | |
351 | It can be a variable to be used in | |
352 | .Xr dhcpcd-run-hooks 8 | |
353 | or the numerical value. | |
87b266d2 | 354 | You can specify more options separated by commas, spaces or more require lines. |
02d339e3 RM |
355 | To enforce that |
356 | .Nm dhcpcd | |
357 | only responds to DHCP servers and not BOOTP servers, you can | |
358 | .Ic require | |
359 | .Ar dhcp_message_type . | |
0aeb350c RM |
360 | .It Ic script Ar script |
361 | Use | |
362 | .Ar script | |
363 | instead of the default | |
364 | .Pa @SCRIPT@ . | |
c53cf4ef RM |
365 | .It Ic ssid Ar ssid |
366 | Subsequent options are only parsed for this wireless | |
367 | .Ar ssid . | |
91a44b91 RM |
368 | .It Ic static Ar value |
369 | Configures a static | |
370 | .Ar value . | |
371 | If you set | |
372 | .Ic ip_address | |
373 | then | |
374 | .Nm dhcpcd | |
375 | will not attempt to obtain a lease and just use the value for the address with | |
376 | an infinite lease time. | |
377 | .Pp | |
378 | Here is an example which configures a static address, routes and dns. | |
379 | .D1 interface eth0 | |
380 | .D1 static ip_address=192.168.0.10/24 | |
381 | .D1 static routers=192.168.0.1 | |
382 | .D1 static domain_name_servers=192.168.0.1 | |
1abffd5b RM |
383 | .Pp |
384 | Here is an example for PPP which gives the destination a default route. | |
385 | It uses the special destination keyword to insert the destination address | |
386 | into the value. | |
387 | .D1 interface ppp0 | |
388 | .D1 static ip_address= | |
389 | .D1 destination routers | |
d2616b08 | 390 | .It Ic timeout Ar seconds |
fedb3da0 | 391 | The default timeout for waiting for a DHCP response is 30 seconds which may |
d2616b08 | 392 | be too long or too short and can be changed here. |
d93d7adc RM |
393 | A setting of 0 |
394 | .Ar seconds | |
395 | causes | |
396 | .Nm dhcpcd | |
397 | to wait forever to get a lease. | |
d2616b08 | 398 | .It Ic userclass Ar string |
cf42802e RM |
399 | Tag the DHCP messages with the userclass. |
400 | You can specify more than one. | |
bac03ede | 401 | .It Ic vendor Ar code , Ns Ar value |
87b266d2 | 402 | Add an encapsulated vendor option. |
757520c5 RM |
403 | .Ar code |
404 | should be between 1 and 254 inclusive. | |
95d6dcfa RM |
405 | To add a raw vendor string, omit |
406 | .Ar code | |
407 | but keep the comma. | |
757520c5 RM |
408 | Examples. |
409 | .Pp | |
410 | Set the vendor option 01 with an IP address. | |
411 | .D1 vendor 01,192.168.0.2 | |
412 | Set the vendor option 02 with a hex code. | |
413 | .D1 vendor 02,01:02:03:04:05 | |
414 | Set the vendor option 03 with an IP address as a string. | |
415 | .D1 vendor 03,\e"192.168.0.2\e" | |
87b266d2 | 416 | Set un-encapsulated vendor option to hello world. |
9cb58952 | 417 | .D1 vendor ,"hello world" |
bac03ede | 418 | .It Ic vendorclassid Ar string |
eebe9a18 RM |
419 | The default is |
420 | dhcpcd-<version>:<os>:<machine>:<platform>. | |
421 | For example | |
422 | .D1 dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386 | |
bac03ede | 423 | If not set then none is sent. |
eebe9a18 RM |
424 | Some badly configured DHCP servers reject unknown vendorclassids. |
425 | To work around it, try and impersonate Windows by using the MSFT vendorclassid. | |
7013b073 | 426 | .It Ic waitip Op 4 | 6 |
2a07a2af | 427 | Wait for an address to be assigned before forking to the background. |
7013b073 RM |
428 | 4 means wait for an IPv4 address to be assigned. |
429 | 6 means wait for an IPv6 address to be assigned. | |
8b7499fd RM |
430 | If no argument is given, |
431 | .Nm | |
432 | will wait for any address protocol to be assigned. | |
433 | It is possible to wait for more than one address protocol and | |
434 | .Nm | |
435 | will only fork to the background when all waiting conditions are satisfied. | |
4242c9b3 RM |
436 | .It Ic xidhwaddr |
437 | Use the last four bytes of the hardware address as the DHCP xid instead | |
438 | of a randomly generated number. | |
eaa90296 | 439 | .El |
ba9dfb7a | 440 | .Sh SEE ALSO |
ee4e620a | 441 | .Xr dhcpcd-run-hooks 8 , |
ba97e494 | 442 | .Xr dhcpcd 8 , |
065125d4 | 443 | .Xr if_nametoindex 3 , |
ba97e494 | 444 | .Xr fnmatch 3 |
ba9dfb7a | 445 | .Sh AUTHORS |
2cfe8d07 | 446 | .An Roy Marples Aq Mt roy@marples.name |
ba9dfb7a | 447 | .Sh BUGS |
fd73ceb1 RM |
448 | Please report them to |
449 | .Lk http://roy.marples.name/projects/dhcpcd |