]>
Commit | Line | Data |
---|---|---|
601fb3d5 | 1 | .\" Copyright (c) 2006-2009 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 | .\" | |
21090e3d | 25 | .Dd October 7, 2009 |
ba9dfb7a | 26 | .Dt DHCPCD.CONF 5 SMM |
918338f2 | 27 | .Os |
ba9dfb7a RM |
28 | .Sh NAME |
29 | .Nm dhcpcd.conf | |
30 | .Nd dhcpcd configuration file | |
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. | |
6bfd88f1 RM |
86 | .It Ic env Ar value |
87 | Push | |
88 | .Ar value | |
89 | to the environment for use in | |
90 | .Xr dhcpcd-run-hooks 8 . | |
91 | For example, you can force the hostname hook to always set the hostname with | |
92 | .Ic env | |
93 | .Va force_hostname=YES . | |
d2616b08 | 94 | .It Ic clientid Ar string |
c989b023 RM |
95 | Send the |
96 | .Ar clientid . | |
d2616b08 | 97 | If the string is of the format 01:02:03 then it is encoded as hex. |
3faba9e6 RM |
98 | For interfaces whose hardware address is longer than 8 bytes, or if the |
99 | .Ar clientid | |
100 | is an empty string then | |
101 | .Nm dhcpcd | |
102 | sends a default | |
103 | .Ar clientid | |
104 | of the hardware family and the hardware address. | |
d2616b08 RM |
105 | .It Ic duid |
106 | Generate an | |
107 | .Rs | |
108 | .%T "RFC 4361" | |
109 | .Re | |
cf42802e RM |
110 | compliant clientid. |
111 | This requires persistent storage and not all DHCP servers work with it so it's | |
112 | not enabled by default. | |
d2616b08 RM |
113 | The duid generated will be held in |
114 | .Pa @SYSCONFDIR@/dhcpcd.duid | |
115 | and should not be copied to other hosts. | |
ff021b0b RM |
116 | .It Ic fallback Ar profile |
117 | Fallback to using this profile if DHCP fails. | |
118 | This allows you to configure a static profile instead of using ZeroConf. | |
ba9dfb7a | 119 | .It Ic hostname Ar name |
35d02ae6 | 120 | Sends |
ff021b0b | 121 | .Ar hostname |
35d02ae6 RM |
122 | to the DHCP server so it can be registered in DNS. |
123 | If | |
35ff0dbb | 124 | .Ar hostname |
35d02ae6 RM |
125 | is an empty string then the current system hostname is sent. |
126 | If | |
127 | .Ar hostname | |
128 | is a FQDN (ie, contains a .) then it will be encoded as such. | |
35ff0dbb RM |
129 | .It Ic fqdn Op none | ptr | both |
130 | none disables FQDN encoding, ptr just asks the DHCP server to update the PTR | |
131 | record of the host in DNS whereas both also updates the A record. | |
1b3bc477 RM |
132 | .Nm dhcpcd |
133 | itself never does any DNS updates. | |
e837a670 RM |
134 | .Nm dhcpcd |
135 | encodes the FQDN hostname as specified in | |
136 | .Li RFC1035 . | |
3adc5520 | 137 | .It Ic interface Ar interface |
012fd5d3 RM |
138 | Subsequent options are only parsed for this |
139 | .Ar interface . | |
ba9dfb7a RM |
140 | .It Ic leasetime Ar seconds |
141 | Request a leasetime of | |
142 | .Ar seconds . | |
065125d4 RM |
143 | .It Ic metric Ar metric |
144 | Metrics are used to prefer an interface over another one, lowest wins. | |
145 | .Nm dhcpcd | |
146 | will supply a default metic of 200 + | |
147 | .Xr if_nametoindex 3 . | |
148 | An extra 100 will be added for wireless interfaces. | |
ba9dfb7a | 149 | .It Ic noarp |
cf42802e RM |
150 | Don't send any ARP requests. |
151 | This also disables IPv4LL. | |
ba9dfb7a RM |
152 | .It Ic nogateway |
153 | Don't install any default routes. | |
37156a6b RM |
154 | .It Ic nohook Ar script |
155 | Don't run this hook script. | |
8276da82 RM |
156 | Matches full name, or prefixed with 2 numbers optionally ending with |
157 | .Pa .sh . | |
fc7ee231 RM |
158 | .Pp |
159 | So to stop | |
160 | .Nm dhcpcd | |
161 | from touching your DNS or MTU settings you would do:- | |
162 | .D1 nohook resolv.conf, mtu | |
ba9dfb7a RM |
163 | .It Ic noipv4ll |
164 | Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP. | |
165 | See | |
166 | .Rs | |
167 | .%T "RFC 3927" | |
168 | .Re | |
a26af491 RM |
169 | .It Ic nolink |
170 | Don't receive link messages about carrier status. | |
171 | You should only set this for buggy interface drivers. | |
cc45fbd7 | 172 | .It Ic option Ar option |
d2616b08 | 173 | Requests the |
cc45fbd7 | 174 | .Ar option |
cf42802e RM |
175 | from the server. |
176 | It can be a variable to be used in | |
ee4e620a | 177 | .Xr dhcpcd-run-hooks 8 |
cf42802e | 178 | or the numerical value. |
cc45fbd7 | 179 | You can specify more options seperated by commas, spaces or more option lines. |
2063c6f9 RM |
180 | .It Ic nooption Ar option |
181 | Remove the option from the DHCP message. | |
182 | This should only be used when a DHCP server sends a non requested option | |
183 | that should not be processed. | |
1abffd5b RM |
184 | .It Ic destination Ar option |
185 | If | |
186 | .Nm | |
187 | detects an address added to a point to point interface (PPP, TUN, etc) then | |
188 | it will set the listed DHCP options to the destination address of the | |
189 | interface. | |
6f767217 RM |
190 | .It Ic profile Ar name |
191 | Subsequent options are only parsed for this profile | |
192 | .Ar name . | |
1abffd5b | 193 | .It Ic quiet |
f19b6499 | 194 | Supress any dhcpcd output to the console, except for errors. |
1abffd5b | 195 | .It Ic reboot Ar seconds |
a2a9a498 RM |
196 | Allow |
197 | .Ar reboot | |
198 | seconds before moving to the discover phase if we have an old lease to use. | |
199 | The default is 10 seconds. | |
200 | A setting if 0 seconds causes | |
201 | .Nm dhcpcd | |
202 | to skip the reboot phase and go straight into discover. | |
2662d519 RM |
203 | .It Ic release |
204 | .Nm dhcpcd | |
205 | will release the lease prior to stopping the interface. | |
cc45fbd7 RM |
206 | .It Ic require Ar option |
207 | Requires the | |
208 | .Ar option | |
209 | to be present in all DHCP messages, otherwise the message is ignored. | |
210 | It can be a variable to be used in | |
211 | .Xr dhcpcd-run-hooks 8 | |
212 | or the numerical value. | |
213 | You can specify more options seperated by commas, spaces or more require lines. | |
02d339e3 RM |
214 | To enforce that |
215 | .Nm dhcpcd | |
216 | only responds to DHCP servers and not BOOTP servers, you can | |
217 | .Ic require | |
218 | .Ar dhcp_message_type . | |
0aeb350c RM |
219 | .It Ic script Ar script |
220 | Use | |
221 | .Ar script | |
222 | instead of the default | |
223 | .Pa @SCRIPT@ . | |
c53cf4ef RM |
224 | .It Ic ssid Ar ssid |
225 | Subsequent options are only parsed for this wireless | |
226 | .Ar ssid . | |
91a44b91 RM |
227 | .It Ic static Ar value |
228 | Configures a static | |
229 | .Ar value . | |
230 | If you set | |
231 | .Ic ip_address | |
232 | then | |
233 | .Nm dhcpcd | |
234 | will not attempt to obtain a lease and just use the value for the address with | |
235 | an infinite lease time. | |
236 | .Pp | |
237 | Here is an example which configures a static address, routes and dns. | |
238 | .D1 interface eth0 | |
239 | .D1 static ip_address=192.168.0.10/24 | |
240 | .D1 static routers=192.168.0.1 | |
241 | .D1 static domain_name_servers=192.168.0.1 | |
1abffd5b RM |
242 | .Pp |
243 | Here is an example for PPP which gives the destination a default route. | |
244 | It uses the special destination keyword to insert the destination address | |
245 | into the value. | |
246 | .D1 interface ppp0 | |
247 | .D1 static ip_address= | |
248 | .D1 destination routers | |
d2616b08 | 249 | .It Ic timeout Ar seconds |
fedb3da0 | 250 | The default timeout for waiting for a DHCP response is 30 seconds which may |
d2616b08 RM |
251 | be too long or too short and can be changed here. |
252 | .It Ic userclass Ar string | |
cf42802e RM |
253 | Tag the DHCP messages with the userclass. |
254 | You can specify more than one. | |
bac03ede | 255 | .It Ic vendor Ar code , Ns Ar value |
757520c5 RM |
256 | Add an enscapulated vendor option. |
257 | .Ar code | |
258 | should be between 1 and 254 inclusive. | |
95d6dcfa RM |
259 | To add a raw vendor string, omit |
260 | .Ar code | |
261 | but keep the comma. | |
757520c5 RM |
262 | Examples. |
263 | .Pp | |
264 | Set the vendor option 01 with an IP address. | |
265 | .D1 vendor 01,192.168.0.2 | |
266 | Set the vendor option 02 with a hex code. | |
267 | .D1 vendor 02,01:02:03:04:05 | |
268 | Set the vendor option 03 with an IP address as a string. | |
269 | .D1 vendor 03,\e"192.168.0.2\e" | |
95d6dcfa | 270 | Set un-encapulated vendor option to hello world. |
9cb58952 | 271 | .D1 vendor ,"hello world" |
bac03ede RM |
272 | .It Ic vendorclassid Ar string |
273 | Change the default vendorclassid sent from dhcpcd-version. | |
274 | If not set then none is sent. | |
eaa90296 | 275 | .El |
ba9dfb7a | 276 | .Sh SEE ALSO |
ee4e620a | 277 | .Xr dhcpcd-run-hooks 8 , |
ba97e494 | 278 | .Xr dhcpcd 8 , |
065125d4 | 279 | .Xr if_nametoindex 3 , |
ba97e494 | 280 | .Xr fnmatch 3 |
ba9dfb7a | 281 | .Sh AUTHORS |
760f7628 | 282 | .An Roy Marples Aq roy@marples.name |
ba9dfb7a | 283 | .Sh BUGS |
56d212f2 | 284 | Please report them to http://roy.marples.name/projects/dhcpcd |