Dmitry Shmidt | a3a2260 | 2012-07-23 16:45:46 -0700 | [diff] [blame] | 1 | .\" Copyright (c) 2006-2012 Roy Marples |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 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 | .\" |
Dmitry Shmidt | a3a2260 | 2012-07-23 16:45:46 -0700 | [diff] [blame] | 25 | .Dd May 21, 2012 |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 26 | .Dt DHCPCD.CONF 5 SMM |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 27 | .Os |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 28 | .Sh NAME |
| 29 | .Nm dhcpcd.conf |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 30 | .Nd dhcpcd configuration file |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 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 |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 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 |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 72 | .It Ic background |
| 73 | Background immediately. |
| 74 | This is useful for startup scripts which don't disable link messages for |
| 75 | carrier status. |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 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 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. |
| 93 | .It Ic env Ar value |
| 94 | Push |
| 95 | .Ar value |
| 96 | to the environment for use in |
| 97 | .Xr dhcpcd-run-hooks 8 . |
| 98 | For example, you can force the hostname hook to always set the hostname with |
| 99 | .Ic env |
| 100 | .Va force_hostname=YES . |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 101 | .It Ic clientid Ar string |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 102 | Send the |
| 103 | .Ar clientid . |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 104 | If the string is of the format 01:02:03 then it is encoded as hex. |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 105 | For interfaces whose hardware address is longer than 8 bytes, or if the |
| 106 | .Ar clientid |
| 107 | is an empty string then |
| 108 | .Nm dhcpcd |
| 109 | sends a default |
| 110 | .Ar clientid |
| 111 | of the hardware family and the hardware address. |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 112 | .It Ic duid |
| 113 | Generate an |
| 114 | .Rs |
| 115 | .%T "RFC 4361" |
| 116 | .Re |
| 117 | compliant clientid. |
| 118 | This requires persistent storage and not all DHCP servers work with it so it's |
| 119 | not enabled by default. |
| 120 | The duid generated will be held in |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 121 | .Pa /etc/dhcpcd.duid |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 122 | and should not be copied to other hosts. |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 123 | .It Ic fallback Ar profile |
| 124 | Fallback to using this profile if DHCP fails. |
| 125 | This allows you to configure a static profile instead of using ZeroConf. |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 126 | .It Ic hostname Ar name |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 127 | Sends |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 128 | .Ar hostname |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 129 | to the DHCP server so it can be registered in DNS. |
| 130 | If |
| 131 | .Ar hostname |
| 132 | is an empty string then the current system hostname is sent. |
| 133 | If |
| 134 | .Ar hostname |
| 135 | is a FQDN (ie, contains a .) then it will be encoded as such. |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 136 | .It Ic fqdn Op none | ptr | both |
| 137 | none disables FQDN encoding, ptr just asks the DHCP server to update the PTR |
| 138 | record of the host in DNS whereas both also updates the A record. |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 139 | .Nm dhcpcd |
| 140 | itself never does any DNS updates. |
| 141 | .Nm dhcpcd |
| 142 | encodes the FQDN hostname as specified in |
| 143 | .Li RFC1035 . |
| 144 | .It Ic interface Ar interface |
| 145 | Subsequent options are only parsed for this |
| 146 | .Ar interface . |
Dmitry Shmidt | a3a2260 | 2012-07-23 16:45:46 -0700 | [diff] [blame] | 147 | .It Ic ipv6ra_fork |
| 148 | By default, when |
| 149 | .Nm dhcpcd |
| 150 | receives an IPv6 RA, |
| 151 | .Nm dhcpcd |
| 152 | will only fork to the background if the RA contains at least one unexpired |
| 153 | RDNSS option. |
| 154 | Set this option so to make |
| 155 | .Nm dhcpcd |
| 156 | always fork on an RA. |
| 157 | .It ic ipv6ra_own |
| 158 | Disables kernel IPv6 Router Advertisment processing so dhcpcd can manage |
| 159 | addresses and routes. |
| 160 | .It ic ipv6ra_own_default |
| 161 | Each time dhcpcd receives an IPv6 Router Adveristment, dhcpcd will manage |
| 162 | the default route only. |
| 163 | This allows dhcpcd to prefer an interface for outbound traffic based on metric |
| 164 | and/or user selection rather than the kernel. |
| 165 | .It ic ipv6rs |
| 166 | Enables IPv6 Router Advertisment solicitation. |
| 167 | This is on by default, but is documented here in the case where it is disabled |
| 168 | globally but needs to be enabled for one interface. |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 169 | .It Ic leasetime Ar seconds |
| 170 | Request a leasetime of |
| 171 | .Ar seconds . |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 172 | .It Ic metric Ar metric |
| 173 | Metrics are used to prefer an interface over another one, lowest wins. |
| 174 | .Nm dhcpcd |
| 175 | will supply a default metric of 200 + |
| 176 | .Xr if_nametoindex 3 . |
| 177 | An extra 100 will be added for wireless interfaces. |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 178 | .It Ic noarp |
| 179 | Don't send any ARP requests. |
| 180 | This also disables IPv4LL. |
| 181 | .It Ic nogateway |
| 182 | Don't install any default routes. |
| 183 | .It Ic nohook Ar script |
| 184 | Don't run this hook script. |
| 185 | Matches full name, or prefixed with 2 numbers optionally ending with |
| 186 | .Pa .sh . |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 187 | .Pp |
| 188 | So to stop |
| 189 | .Nm dhcpcd |
| 190 | from touching your DNS or MTU settings you would do:- |
| 191 | .D1 nohook resolv.conf, mtu |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 192 | .It Ic noipv4ll |
| 193 | Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP. |
| 194 | See |
| 195 | .Rs |
| 196 | .%T "RFC 3927" |
| 197 | .Re |
Dmitry Shmidt | a3a2260 | 2012-07-23 16:45:46 -0700 | [diff] [blame] | 198 | .It Ic noipv6rs |
| 199 | Disable solicition of IPv6 Router Advertisements. |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 200 | .It Ic nolink |
| 201 | Don't receive link messages about carrier status. |
| 202 | You should only set this for buggy interface drivers. |
| 203 | .It Ic option Ar option |
| 204 | Requests the |
| 205 | .Ar option |
| 206 | from the server. |
| 207 | It can be a variable to be used in |
| 208 | .Xr dhcpcd-run-hooks 8 |
| 209 | or the numerical value. |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 210 | You can specify more options separated by commas, spaces or more option lines. |
| 211 | .It Ic nooption Ar option |
| 212 | Remove the option from the DHCP message. |
| 213 | This should only be used when a DHCP server sends a non requested option |
| 214 | that should not be processed. |
| 215 | .It Ic destination Ar option |
| 216 | If |
| 217 | .Nm |
| 218 | detects an address added to a point to point interface (PPP, TUN, etc) then |
| 219 | it will set the listed DHCP options to the destination address of the |
| 220 | interface. |
| 221 | .It Ic profile Ar name |
| 222 | Subsequent options are only parsed for this profile |
| 223 | .Ar name . |
| 224 | .It Ic quiet |
| 225 | Suppress any dhcpcd output to the console, except for errors. |
| 226 | .It Ic reboot Ar seconds |
| 227 | Allow |
| 228 | .Ar reboot |
| 229 | seconds before moving to the discover phase if we have an old lease to use. |
Dmitry Shmidt | a3a2260 | 2012-07-23 16:45:46 -0700 | [diff] [blame] | 230 | The default is 5 seconds. |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 231 | A setting if 0 seconds causes |
| 232 | .Nm dhcpcd |
| 233 | to skip the reboot phase and go straight into discover. |
| 234 | .It Ic release |
| 235 | .Nm dhcpcd |
| 236 | will release the lease prior to stopping the interface. |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 237 | .It Ic require Ar option |
| 238 | Requires the |
| 239 | .Ar option |
| 240 | to be present in all DHCP messages, otherwise the message is ignored. |
| 241 | It can be a variable to be used in |
| 242 | .Xr dhcpcd-run-hooks 8 |
| 243 | or the numerical value. |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 244 | You can specify more options separated by commas, spaces or more require lines. |
| 245 | To enforce that |
| 246 | .Nm dhcpcd |
| 247 | only responds to DHCP servers and not BOOTP servers, you can |
| 248 | .Ic require |
| 249 | .Ar dhcp_message_type . |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 250 | .It Ic script Ar script |
| 251 | Use |
| 252 | .Ar script |
| 253 | instead of the default |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 254 | .Pa /libexec/dhcpcd-run-hooks . |
| 255 | .It Ic ssid Ar ssid |
| 256 | Subsequent options are only parsed for this wireless |
| 257 | .Ar ssid . |
| 258 | .It Ic static Ar value |
| 259 | Configures a static |
| 260 | .Ar value . |
| 261 | If you set |
| 262 | .Ic ip_address |
| 263 | then |
| 264 | .Nm dhcpcd |
| 265 | will not attempt to obtain a lease and just use the value for the address with |
| 266 | an infinite lease time. |
| 267 | .Pp |
| 268 | Here is an example which configures a static address, routes and dns. |
| 269 | .D1 interface eth0 |
| 270 | .D1 static ip_address=192.168.0.10/24 |
| 271 | .D1 static routers=192.168.0.1 |
| 272 | .D1 static domain_name_servers=192.168.0.1 |
| 273 | .Pp |
| 274 | Here is an example for PPP which gives the destination a default route. |
| 275 | It uses the special destination keyword to insert the destination address |
| 276 | into the value. |
| 277 | .D1 interface ppp0 |
| 278 | .D1 static ip_address= |
| 279 | .D1 destination routers |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 280 | .It Ic timeout Ar seconds |
| 281 | The default timeout for waiting for a DHCP response is 30 seconds which may |
| 282 | be too long or too short and can be changed here. |
| 283 | .It Ic userclass Ar string |
| 284 | Tag the DHCP messages with the userclass. |
| 285 | You can specify more than one. |
| 286 | .It Ic vendor Ar code , Ns Ar value |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 287 | Add an encapsulated vendor option. |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 288 | .Ar code |
| 289 | should be between 1 and 254 inclusive. |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 290 | To add a raw vendor string, omit |
| 291 | .Ar code |
| 292 | but keep the comma. |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 293 | Examples. |
| 294 | .Pp |
| 295 | Set the vendor option 01 with an IP address. |
| 296 | .D1 vendor 01,192.168.0.2 |
| 297 | Set the vendor option 02 with a hex code. |
| 298 | .D1 vendor 02,01:02:03:04:05 |
| 299 | Set the vendor option 03 with an IP address as a string. |
| 300 | .D1 vendor 03,\e"192.168.0.2\e" |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 301 | Set un-encapsulated vendor option to hello world. |
| 302 | .D1 vendor ,"hello world" |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 303 | .It Ic vendorclassid Ar string |
Dmitry Shmidt | a3a2260 | 2012-07-23 16:45:46 -0700 | [diff] [blame] | 304 | The default is |
| 305 | dhcpcd-<version>:<os>:<machine>:<platform>. |
| 306 | For example |
| 307 | .D1 dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386 |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 308 | If not set then none is sent. |
Dmitry Shmidt | a3a2260 | 2012-07-23 16:45:46 -0700 | [diff] [blame] | 309 | Some badly configured DHCP servers reject unknown vendorclassids. |
| 310 | To work around it, try and impersonate Windows by using the MSFT vendorclassid. |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 311 | .It Ic waitip |
| 312 | Wait for an address to be assigned before forking to the background. |
| 313 | .It Ic xidhwaddr |
| 314 | Use the last four bytes of the hardware address as the DHCP xid instead |
| 315 | of a randomly generated number. |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 316 | .El |
| 317 | .Sh SEE ALSO |
| 318 | .Xr dhcpcd-run-hooks 8 , |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 319 | .Xr dhcpcd 8 , |
| 320 | .Xr if_nametoindex 3 , |
| 321 | .Xr fnmatch 3 |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 322 | .Sh AUTHORS |
Dmitry Shmidt | e86eee1 | 2011-01-24 16:27:51 -0800 | [diff] [blame] | 323 | .An Roy Marples Aq roy@marples.name |
The Android Open Source Project | f7c5421 | 2009-03-03 19:29:22 -0800 | [diff] [blame] | 324 | .Sh BUGS |
Dmitry Shmidt | a3a2260 | 2012-07-23 16:45:46 -0700 | [diff] [blame] | 325 | Please report them to |
| 326 | .Lk http://roy.marples.name/projects/dhcpcd |