| blob | 7becfa11f904bcc59096a761b0b2b162697b1c30 |
1 .\" Copyright (c) 2006-2009 Roy Marples
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 .\"
25 .Dd October 16, 2009
26 .Dt DHCPCD.CONF 5 SMM
27 .Os
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
35 to do it once in a configuration file.
36 Most of the options found in
37 .Xr dhcpcd 8
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.
42 .Pp
43 Blank lines and lines starting with # are ignored.
44 .Pp
45 Here's a list of available options:
46 .Bl -tag -width indent
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 .
60 .It Ic arping Ar address Op address
61 .Nm dhcpcd
62 will arping each address in order before attempting DHCP.
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
72 .It Ic background
73 Background immediately.
74 This is useful for startup scripts which don't disable link messages for
75 carrier status.
76 .It Ic blacklist Ar address Ns Op /cidr
77 Ignores all packets from
78 .Ar address Ns Op /cidr .
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.
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 .
94 .It Ic clientid Ar string
95 Send the
96 .Ar clientid .
97 If the string is of the format 01:02:03 then it is encoded as hex.
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.
105 .It Ic duid
106 Generate an
107 .Rs
108 .%T "RFC 4361"
109 .Re
110 compliant clientid.
111 This requires persistent storage and not all DHCP servers work with it so it's
112 not enabled by default.
113 The duid generated will be held in
114 .Pa @SYSCONFDIR@/dhcpcd.duid
115 and should not be copied to other hosts.
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.
119 .It Ic hostname Ar name
120 Sends
121 .Ar hostname
122 to the DHCP server so it can be registered in DNS.
123 If
124 .Ar hostname
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.
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.
132 .Nm dhcpcd
133 itself never does any DNS updates.
134 .Nm dhcpcd
135 encodes the FQDN hostname as specified in
136 .Li RFC1035 .
137 .It Ic interface Ar interface
138 Subsequent options are only parsed for this
139 .Ar interface .
140 .It Ic leasetime Ar seconds
141 Request a leasetime of
142 .Ar seconds .
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.
149 .It Ic noarp
150 Don't send any ARP requests.
151 This also disables IPv4LL.
152 .It Ic nogateway
153 Don't install any default routes.
154 .It Ic nohook Ar script
155 Don't run this hook script.
156 Matches full name, or prefixed with 2 numbers optionally ending with
157 .Pa .sh .
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
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
169 .It Ic nolink
170 Don't receive link messages about carrier status.
171 You should only set this for buggy interface drivers.
172 .It Ic option Ar option
173 Requests the
174 .Ar option
175 from the server.
176 It can be a variable to be used in
177 .Xr dhcpcd-run-hooks 8
178 or the numerical value.
179 You can specify more options seperated by commas, spaces or more option lines.
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.
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.
190 .It Ic profile Ar name
191 Subsequent options are only parsed for this profile
192 .Ar name .
193 .It Ic quiet
194 Supress any dhcpcd output to the console, except for errors.
195 .It Ic reboot Ar seconds
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.
203 .It Ic release
204 .Nm dhcpcd
205 will release the lease prior to stopping the interface.
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.
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 .
219 .It Ic script Ar script
220 Use
221 .Ar script
222 instead of the default
223 .Pa @SCRIPT@ .
224 .It Ic ssid Ar ssid
225 Subsequent options are only parsed for this wireless
226 .Ar ssid .
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
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
249 .It Ic timeout Ar seconds
250 The default timeout for waiting for a DHCP response is 30 seconds which may
251 be too long or too short and can be changed here.
252 .It Ic userclass Ar string
253 Tag the DHCP messages with the userclass.
254 You can specify more than one.
255 .It Ic vendor Ar code , Ns Ar value
256 Add an enscapulated vendor option.
257 .Ar code
258 should be between 1 and 254 inclusive.
259 To add a raw vendor string, omit
260 .Ar code
261 but keep the comma.
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"
270 Set un-encapulated vendor option to hello world.
271 .D1 vendor ,"hello world"
272 .It Ic vendorclassid Ar string
273 Change the default vendorclassid sent from dhcpcd-version.
274 If not set then none is sent.
275 .It Ic waitip
276 Wait for an address to be assigned before forking to the background.
277 .El
278 .Sh SEE ALSO
279 .Xr dhcpcd-run-hooks 8 ,
280 .Xr dhcpcd 8 ,
281 .Xr if_nametoindex 3 ,
282 .Xr fnmatch 3
283 .Sh AUTHORS
284 .An Roy Marples Aq roy@marples.name
285 .Sh BUGS
286 Please report them to http://roy.marples.name/projects/dhcpcd