Samuel Tan | d7ed851 | 2015-08-13 16:11:35 -0700 | [diff] [blame] | 1 | .\" Copyright (c) 2006-2015 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 April 6, 2015 |
| 26 | .Dt DHCPCD.CONF 5 |
| 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 authprotocol Ar protocol Ar algorithm Ar rdm |
| 73 | Authenticate DHCP messages. |
| 74 | See the Supported Authentication Protocols section. |
| 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. |
| 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. |
| 99 | .It Ic background |
| 100 | Background immediately. |
| 101 | This is useful for startup scripts which don't disable link messages for |
| 102 | carrier status. |
| 103 | .It Ic blacklist Ar address Ns Op /cidr |
| 104 | Ignores all packets from |
| 105 | .Ar address Ns Op /cidr . |
| 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. |
| 113 | .It Ic bootp |
| 114 | Be a BOOTP client. |
| 115 | Basically, this just doesn't send a DHCP Message Type option and will only |
| 116 | interact with a BOOTP server. |
| 117 | All other DHCP options still work. |
| 118 | .It Ic broadcast |
| 119 | Instructs the DHCP server to broadcast replies back to the client. |
| 120 | Normally this is only set for non Ethernet interfaces, |
| 121 | such as FireWire and InfiniBand. |
| 122 | In most cases, |
| 123 | .Nm dhcpcd |
| 124 | will set this automatically. |
| 125 | .It Ic controlgroup Ar group |
| 126 | Sets the group ownership of |
| 127 | .Pa @RUNDIR@/dhcpcd.sock |
| 128 | so that users other than root can connect to |
| 129 | .Nm dhcpcd . |
| 130 | .It Ic debug |
| 131 | Echo debug messages to the stderr and syslog. |
| 132 | .It Ic dev Ar value |
| 133 | Load the |
| 134 | .Ar value |
| 135 | .Pa /dev |
| 136 | management module. |
| 137 | .Nm dhcpcd |
| 138 | will load the first one found to work, if any. |
| 139 | .It Ic env Ar value |
| 140 | Push |
| 141 | .Ar value |
| 142 | to the environment for use in |
| 143 | .Xr dhcpcd-run-hooks 8 . |
| 144 | For example, you can force the hostname hook to always set the hostname with |
| 145 | .Ic env |
| 146 | .Va force_hostname=YES . |
| 147 | Or set which driver |
| 148 | .Xr wpa_supplicant 8 |
| 149 | should use with |
| 150 | .Ic env |
| 151 | .Va wpa_supplicant_driver=nl80211 |
| 152 | .Pp |
| 153 | If the hostname is set, will be will set to the FQDN if possible as per |
| 154 | RFC 4702 section 3.1. |
| 155 | If the FQDN option is missing, |
| 156 | .Nm dhcpcd |
| 157 | will still try and set a FQDN from the hostname and domain options for |
| 158 | consistency. |
| 159 | To override this, set |
| 160 | .Ic env |
| 161 | .Va hostname_fqdn=[YES|NO|SERVER] . |
| 162 | A value of server means just what the server says, don't manipulate it. |
| 163 | This could lead to an inconsistent hostname on a DHCPv4 and DHCPv6 network |
| 164 | where the DHCPv4 hostname is short and the DHCPv6 has an FQDN. |
| 165 | DHCPv6 has no hostname option. |
| 166 | .It Ic clientid Ar string |
| 167 | Send the |
| 168 | .Ar clientid . |
| 169 | If the string is of the format 01:02:03 then it is encoded as hex. |
| 170 | For interfaces whose hardware address is longer than 8 bytes, or if the |
| 171 | .Ar clientid |
| 172 | is an empty string then |
| 173 | .Nm dhcpcd |
| 174 | sends a default |
| 175 | .Ar clientid |
| 176 | of the hardware family and the hardware address. |
| 177 | .It Ic duid |
| 178 | Generate an |
| 179 | .Rs |
| 180 | .%T "RFC 4361" |
| 181 | .Re |
| 182 | compliant DHCP Unique Identifier. |
| 183 | If persistent storage is available then a DUID-LLT (link local address + time) |
| 184 | is generated, otherwise DUID-LL is generated (link local address). |
| 185 | This, plus the IAID will be used as the |
| 186 | .Ic clientid . |
| 187 | The DUID-LLT generated will be held in |
| 188 | .Pa @SYSCONFDIR@/dhcpcd.duid |
| 189 | and should not be copied to other hosts. |
| 190 | .It Ic iaid Ar iaid |
| 191 | Set the Interface Association Identifier to |
| 192 | .Ar iaid . |
| 193 | This option must be used in an |
| 194 | .Ic interface |
| 195 | block. |
| 196 | This defaults to the last 4 bytes of the hardware address assigned to the |
| 197 | interface. |
| 198 | Each instance of this should be unique within the scope of the client and |
| 199 | .Nm dhcpcd |
| 200 | warns if a conflict is detected. |
| 201 | If there is a conflict, it is only a problem if the conflicted IAIDs are |
| 202 | used on the same network. |
| 203 | .It Ic dhcp |
| 204 | Enable DHCP on the interface, on by default. |
| 205 | .It Ic dhcp6 |
| 206 | Enable DHCPv6 on the interface, on by default. |
| 207 | .It Ic ipv4 |
| 208 | Enable IPv4 on the interface, on by default. |
| 209 | .It Ic ipv6 |
| 210 | Enable IPv6 on the interface, on by default. |
| 211 | .It Ic persistent |
| 212 | .Nm dhcpcd |
| 213 | normally de-configures the interface and configuration when it exits. |
| 214 | Sometimes, this isn't desirable if, for example, you have root mounted over |
| 215 | NFS or SSH clients connect to this host and they need to be notified of |
| 216 | the host shutting down. |
| 217 | You can use this option to stop this from happening. |
| 218 | .It Ic fallback Ar profile |
| 219 | Fallback to using this profile if DHCP fails. |
| 220 | This allows you to configure a static profile instead of using ZeroConf. |
| 221 | .It Ic hostname Ar name |
| 222 | Sends |
| 223 | .Ar hostname |
| 224 | to the DHCP server so it can be registered in DNS. |
| 225 | If |
| 226 | .Ar hostname |
| 227 | is an empty string then the current system hostname is sent. |
| 228 | If |
| 229 | .Ar hostname |
| 230 | is a FQDN (ie, contains a .) then it will be encoded as such. |
| 231 | .It Ic hostname_short |
| 232 | Sends the short hostname to the DHCP server instead of the FQDN. |
| 233 | This is useful because DHCP servers will not register the FQDN in their |
| 234 | DNS if the domain part does not match theirs. |
| 235 | .Pp |
| 236 | Also, see the |
| 237 | .Ic env |
| 238 | option above to control how the hostname is set on the host. |
| 239 | .It Ic ia_na Op Ar iaid Op / address |
| 240 | Request a DHCPv6 Normal Address for |
| 241 | .Ar iaid . |
| 242 | .Ar iaid |
| 243 | defaults to the |
| 244 | .Ic iaid |
| 245 | option as described above. |
| 246 | You can request more than one ia_na by specifying a unique |
| 247 | .Ar iaid |
| 248 | for each one. |
| 249 | .It Ic ia_ta Op Ar iaid |
| 250 | Request a DHCPv6 Temporary Address for |
| 251 | .Ar iaid . |
| 252 | You can request more than one ia_ta by specifying a unique |
| 253 | .Ar iaid |
| 254 | for each one. |
| 255 | .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 |
| 256 | Request a DHCPv6 Delegated Prefix for |
| 257 | .Ar iaid . |
| 258 | This option must be used in an |
| 259 | .Ic interface |
| 260 | block. |
| 261 | Unless a |
| 262 | .Ar sla_id |
| 263 | of 0 is assigned, a reject route is installed for the Delegated Prefix to |
| 264 | stop unallocated addresses being resolved upstream. |
| 265 | If no |
| 266 | .Ar interface |
| 267 | is given then we will assign a prefix to every other interface with a |
| 268 | .Ar sla_id |
| 269 | equivalent to the interface index assigned by the OS. |
| 270 | Otherwise addresses are only assigned for each |
| 271 | .Ar interface |
| 272 | and |
| 273 | .Ar sla_id . |
| 274 | Each assigned address will have a suffix of 1. |
| 275 | You cannot assign a prefix to the requesting interface unless the |
| 276 | DHCPv6 server supports |
| 277 | .Li RFC6603 |
| 278 | Prefix Exclude Option. |
| 279 | .Nm dhcpcd |
| 280 | has to be running for all the interfaces it is delegating to. |
| 281 | A default |
| 282 | .Ar prefix_len |
| 283 | of 64 is assumed, unless the maximum |
| 284 | .Ar sla_id |
| 285 | does not fit. |
| 286 | In this case |
| 287 | .Ar prefix_len |
| 288 | is increased to the highest multiple of 8 that can accommodate the |
| 289 | .Ar sla_id . |
| 290 | .Ar sla_id |
| 291 | is an integer and is added to the prefix which must fit inside |
| 292 | .Ar prefix_len |
| 293 | less the length of the delegated prefix. |
| 294 | .Ar sla_id can be 0 only if the Delegated Prefix is assigned to one interface. |
| 295 | You can specify multiple |
| 296 | .Ar interface / |
| 297 | .Ar sla_id / |
| 298 | .Ar prefix_len |
| 299 | per |
| 300 | .Ic ia_pd , |
| 301 | space separated. |
| 302 | IPv6RS should be disabled globally when requesting a Prefix Delegation. |
| 303 | .Pp |
| 304 | In the following example eth0 is the externally facing interface to be |
| 305 | configured for both IPv4 and IPv6. |
| 306 | The DHCPv4 server will provide us with an IPv4 address and a default route. |
| 307 | The DHCPv6 server is going to provide us with an IPv6 address, a default |
| 308 | route and a /64 subnet to be delegated to the internal interface. |
| 309 | The eth1 interface will be automatically configured |
| 310 | for IPv6 using the first address (::1) from the delegated prefix. |
| 311 | .Xr rtadvd 8 |
| 312 | can be used with an empty configuration file on eth1 to provide automatic |
| 313 | IPv6 address configuration for the internal network. |
| 314 | .Bd -literal -indent |
| 315 | noipv6rs # disable routing solicitation |
| 316 | denyinterfaces eth2 # Don't touch eth2 at all |
| 317 | interface eth0 |
| 318 | ipv6rs # enable routing solicitation get the |
| 319 | # default IPv6 route |
| 320 | ia_na 1 # request an IPv6 address |
| 321 | ia_pd 2 eth1/0 # get a /64 and assign it to eth1 |
| 322 | .Ed |
| 323 | .It Ic ia_pd_mix |
| 324 | To be RFC compliant, |
| 325 | .Nm dhcpcd |
| 326 | cannot mix Prefix Delegation with other DHCPv6 address types in the same |
| 327 | session. |
| 328 | This has a number of issues: additional DHCP traffic and potential collisions |
| 329 | between options. |
| 330 | .Ic ia_pd_mix |
| 331 | enables |
| 332 | .Li draft-ietf-dhc-dhcpv6-stateful-issues-06 |
| 333 | support so that Prefix Delegation can be mixed with other address types in |
| 334 | the same session. |
| 335 | .It Ic ipv4only |
| 336 | Only configure IPv4. |
| 337 | .It Ic ipv6only |
| 338 | Only confgiure IPv6. |
| 339 | .It Ic fqdn Op disable | ptr | both |
| 340 | ptr just asks the DHCP server to update the PTR |
| 341 | record of the host in DNS whereas both also updates the A record. |
| 342 | disable will disable the FQDN option. |
| 343 | The default is both. |
| 344 | .Nm dhcpcd |
| 345 | itself never does any DNS updates. |
| 346 | .Nm dhcpcd |
| 347 | encodes the FQDN hostname as specified in |
| 348 | .Li RFC1035 . |
| 349 | .It Ic interface Ar interface |
| 350 | Subsequent options are only parsed for this |
| 351 | .Ar interface . |
| 352 | .It Ic ipv6ra_autoconf |
| 353 | Generate SLAAC addresses for each Prefix advertised by a |
| 354 | Router Advertisement message with the Auto flag set. |
| 355 | On by default. |
| 356 | .It Ic ipv6ra_noautoconf |
| 357 | Disables the above option. |
| 358 | .It Ic ipv6ra_fork |
| 359 | By default, when |
| 360 | .Nm dhcpcd |
| 361 | receives an IPv6 RA, |
| 362 | .Nm dhcpcd |
| 363 | will only fork to the background if the RA contains at least one unexpired |
| 364 | RDNSS option and a valid prefix or no DHCPv6 instruction. |
| 365 | Set this option so to make |
| 366 | .Nm dhcpcd |
| 367 | always fork on an RA. |
| 368 | .It Ic ipv6ra_own |
| 369 | Disables kernel IPv6 Router Advertisment processing so dhcpcd can manage |
| 370 | addresses and routes. |
| 371 | .It Ic ipv6ra_own_default |
| 372 | Each time dhcpcd receives an IPv6 Router Adveristment, dhcpcd will manage |
| 373 | the default route only. |
| 374 | This allows dhcpcd to prefer an interface for outbound traffic based on metric |
| 375 | and/or user selection rather than the kernel. |
| 376 | .It Ic ipv6ra_accept_nopublic |
| 377 | Some IPv6 routers advertise themselves as a default router without any |
| 378 | public prefixes or managed addresses. |
| 379 | Generally, this is incorrect behaviour and |
| 380 | .Nm dhcpcd |
| 381 | will ignore the advertisement unless this option is turned on. |
| 382 | .It Ic ipv6rs |
| 383 | Enables IPv6 Router Advertisment solicitation. |
| 384 | This is on by default, but is documented here in the case where it is disabled |
| 385 | globally but needs to be enabled for one interface. |
| 386 | .It Ic leasetime Ar seconds |
| 387 | Request a leasetime of |
| 388 | .Ar seconds . |
| 389 | .It Ic logfile Ar logfile |
| 390 | Writes to the specified |
| 391 | .Ar logfile |
| 392 | rather than |
| 393 | .Xr syslog 3 . |
| 394 | The |
| 395 | .Ar logfile |
| 396 | is truncated when opened and is reopened when |
| 397 | .Nm dhcpcd |
| 398 | receives the |
| 399 | .Dv SIGUSR2 |
| 400 | signal. |
| 401 | .It Ic metric Ar metric |
| 402 | Metrics are used to prefer an interface over another one, lowest wins. |
| 403 | .Nm dhcpcd |
| 404 | will supply a default metric of 200 + |
| 405 | .Xr if_nametoindex 3 . |
| 406 | An extra 100 will be added for wireless interfaces. |
| 407 | .It Ic noalias |
| 408 | Any pre-existing IPv4 addresses existing address will be removed from the |
| 409 | interface when adding a new IPv4 address. |
| 410 | .It Ic noarp |
| 411 | Don't send any ARP requests. |
| 412 | This also disables IPv4LL. |
| 413 | .It Ic noauthrequired |
| 414 | Don't require authentication even though we requested it. |
| 415 | .It Ic nodev |
| 416 | Don't load |
| 417 | .Pa /dev |
| 418 | management modules. |
| 419 | .It Ic nodhcp |
| 420 | Don't start DHCP or listen to DHCP messages. |
| 421 | This is only useful when allowing IPv4LL. |
| 422 | .It Ic nodhcp6 |
| 423 | Don't start DHCPv6 or listen to DHCPv6 messages. |
| 424 | Normally DHCPv6 is started by a RA instruction or configuration. |
| 425 | .It Ic nogateway |
| 426 | Don't install any default routes. |
| 427 | .It Ic gateway |
| 428 | Install a default route if available (default). |
| 429 | .It Ic nohook Ar script |
| 430 | Don't run this hook script. |
| 431 | Matches full name, or prefixed with 2 numbers optionally ending with |
| 432 | .Pa .sh . |
| 433 | .Pp |
| 434 | So to stop |
| 435 | .Nm dhcpcd |
| 436 | from touching your DNS or MTU settings you would do:- |
| 437 | .D1 nohook resolv.conf, mtu |
| 438 | .It Ic noipv4 |
| 439 | Don't attempt to configure an IPv4 address. |
| 440 | .It Ic noipv4ll |
| 441 | Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP. |
| 442 | See |
| 443 | .Rs |
| 444 | .%T "RFC 3927" |
| 445 | .Re |
| 446 | .It Ic noipv6 |
| 447 | Don't attmept to configure an IPv6 address. |
| 448 | .It Ic noipv6rs |
| 449 | Disable solicitation and receipt of IPv6 Router Advertisements. |
| 450 | .It Ic nolink |
| 451 | Don't receive link messages about carrier status. |
| 452 | You should only set this for buggy interface drivers. |
| 453 | .It Ic option Ar option |
| 454 | Requests the |
| 455 | .Ar option |
| 456 | from the server. |
| 457 | It can be a variable to be used in |
| 458 | .Xr dhcpcd-run-hooks 8 |
| 459 | or the numerical value. |
| 460 | You can specify more |
| 461 | .Ar option Ns s |
| 462 | separated by commas, spaces or more |
| 463 | .Ic option |
| 464 | lines. |
| 465 | Prepend dhcp6_ to |
| 466 | .Ar option |
| 467 | to request a DHCPv6 option. |
| 468 | DHCPv4 options are mapped to DHCPv6 where applicable. |
| 469 | .It Ic nooption Ar option |
| 470 | Remove the option from the DHCP message. |
| 471 | This should only be used when a DHCP server sends a non requested option |
| 472 | that should not be processed. |
| 473 | .It Ic destination Ar option |
| 474 | If |
| 475 | .Nm |
| 476 | detects an address added to a point to point interface (PPP, TUN, etc) then |
| 477 | it will set the listed DHCP options to the destination address of the |
| 478 | interface. |
| 479 | .It Ic profile Ar name |
| 480 | Subsequent options are only parsed for this profile |
| 481 | .Ar name . |
| 482 | .It Ic quiet |
| 483 | Suppress any dhcpcd output to the console, except for errors. |
| 484 | .It Ic reboot Ar seconds |
| 485 | Allow |
| 486 | .Ar reboot |
| 487 | seconds before moving to the DISCOVER phase if we have an old lease to use |
| 488 | and moving from DISCOVER to IPv4LL if no reply. |
| 489 | The default is 5 seconds. |
| 490 | A setting of 0 seconds causes |
| 491 | .Nm dhcpcd |
| 492 | to skip the REBOOT phase and go straight into DISCOVER. |
| 493 | This is desirable for mobile users because if you change from network A to |
| 494 | network B and they use the same subnet and the address from network A isn't |
| 495 | in use on network B, then the DHCP server will remain silent even if authorative |
| 496 | which means |
| 497 | .Nm dhcpcd |
| 498 | will timeout before moving back to the DISCOVER phase. |
| 499 | .It Ic release |
| 500 | .Nm dhcpcd |
| 501 | will release the lease prior to stopping the interface. |
| 502 | .It Ic require Ar option |
| 503 | Requires the |
| 504 | .Ar option |
| 505 | to be present in all DHCP messages, otherwise the message is ignored. |
| 506 | It can be a variable to be used in |
| 507 | .Xr dhcpcd-run-hooks 8 |
| 508 | or the numerical value. |
| 509 | You can specify more options separated by commas, spaces or more require lines. |
| 510 | To enforce that |
| 511 | .Nm dhcpcd |
| 512 | only responds to DHCP servers and not BOOTP servers, you can |
| 513 | .Ic require |
| 514 | .Ar dhcp_message_type . |
| 515 | This isn't an exact science though because a BOOTP server can send DHCP like |
| 516 | options. |
| 517 | .It Ic reject Ar option |
| 518 | Reject a DHCP message that contains the |
| 519 | .Ar option . |
| 520 | This is useful when you cannot use |
| 521 | .Ic require |
| 522 | to select / de-select BOOTP messages. |
| 523 | .It Ic script Ar script |
| 524 | Use |
| 525 | .Ar script |
| 526 | instead of the default |
| 527 | .Pa @SCRIPT@ . |
| 528 | .It Ic ssid Ar ssid |
| 529 | Subsequent options are only parsed for this wireless |
| 530 | .Ar ssid . |
| 531 | .It Ic slaac Op Ar hwaddr | Ar private |
| 532 | Selects the interface identifier used for SLAAC generated IPv6 addresses. |
| 533 | If |
| 534 | .Ar private |
| 535 | is used, a RFC7217 address is generated. |
| 536 | .It Ic static Ar value |
| 537 | Configures a static |
| 538 | .Ar value . |
| 539 | If you set |
| 540 | .Ic ip_address |
| 541 | then |
| 542 | .Nm dhcpcd |
| 543 | will not attempt to obtain a lease and just use the value for the address with |
| 544 | an infinite lease time. |
| 545 | .Pp |
| 546 | Here is an example which configures a static address, routes and dns. |
| 547 | .D1 interface eth0 |
| 548 | .D1 static ip_address=192.168.0.10/24 |
| 549 | .D1 static routers=192.168.0.1 |
| 550 | .D1 static domain_name_servers=192.168.0.1 |
| 551 | .Pp |
| 552 | Here is an example for PPP which gives the destination a default route. |
| 553 | It uses the special destination keyword to insert the destination address |
| 554 | into the value. |
| 555 | .D1 interface ppp0 |
| 556 | .D1 static ip_address= |
| 557 | .D1 destination routers |
| 558 | .It Ic timeout Ar seconds |
| 559 | Timeout after |
| 560 | .Ar seconds , |
| 561 | instead of the default 30. |
| 562 | A setting of 0 |
| 563 | .Ar seconds |
| 564 | causes |
| 565 | .Nm dhcpcd |
| 566 | to wait forever to get a lease. |
| 567 | If |
| 568 | .Nm dhcpcd |
| 569 | is working on a single interface then |
| 570 | .Nm dhcpcd |
| 571 | will exit when a timeout occurs, otherwise |
| 572 | .Nm dhcpcd |
| 573 | will fork into the background. |
| 574 | If using IPv4LL then |
| 575 | .Nm dhcpcd |
| 576 | start the IPv4LL process after the timeout and then wait a little longer |
| 577 | before really timing out. |
| 578 | .It Ic userclass Ar string |
| 579 | Tag the DHCPv4 messages with the userclass. |
| 580 | You can specify more than one. |
| 581 | .It Ic vendor Ar code , Ns Ar value |
| 582 | Add an encapsulated vendor option. |
| 583 | .Ar code |
| 584 | should be between 1 and 254 inclusive. |
| 585 | To add a raw vendor string, omit |
| 586 | .Ar code |
| 587 | but keep the comma. |
| 588 | Examples. |
| 589 | .Pp |
| 590 | Set the vendor option 01 with an IP address. |
| 591 | .D1 vendor 01,192.168.0.2 |
| 592 | Set the vendor option 02 with a hex code. |
| 593 | .D1 vendor 02,01:02:03:04:05 |
| 594 | Set the vendor option 03 with an IP address as a string. |
| 595 | .D1 vendor 03,\e"192.168.0.2\e" |
| 596 | Set un-encapsulated vendor option to hello world. |
| 597 | .D1 vendor ,"hello world" |
| 598 | .It Ic vendorclassid Ar string |
| 599 | Set the DHCP Vendor Class. |
| 600 | DHCPv6 has it's own option as shown below. |
| 601 | The default is |
| 602 | dhcpcd-<version>:<os>:<machine>:<platform>. |
| 603 | For example |
| 604 | .D1 dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386 |
| 605 | If not set then none is sent. |
| 606 | Some badly configured DHCP servers reject unknown vendorclassids. |
| 607 | To work around it, try and impersonate Windows by using the MSFT vendorclassid. |
| 608 | .It Ic vendclass Ar en Ar data |
| 609 | Add the DHCPv6 Vendor Indetifying Vendor Class with the IANA assigned Enterprise |
| 610 | Number |
| 611 | .Ar en |
| 612 | with the |
| 613 | .Ar data . |
| 614 | This option can be set more than once to add more data, but the behaviour, |
| 615 | as per |
| 616 | .Xr RFC 3925 |
| 617 | is undefined if the Enterprise Number differs. |
| 618 | .It Ic waitip Op 4 | 6 |
| 619 | Wait for an address to be assigned before forking to the background. |
| 620 | 4 means wait for an IPv4 address to be assigned. |
| 621 | 6 means wait for an IPv6 address to be assigned. |
| 622 | If no argument is given, |
| 623 | .Nm |
| 624 | will wait for any address protocol to be assigned. |
| 625 | It is possible to wait for more than one address protocol and |
| 626 | .Nm |
| 627 | will only fork to the background when all waiting conditions are satisfied. |
| 628 | .It Ic xidhwaddr |
| 629 | Use the last four bytes of the hardware address as the DHCP xid instead |
| 630 | of a randomly generated number. |
| 631 | .El |
| 632 | .Ss Defining new options |
| 633 | DHCP allows for the use of custom options. |
| 634 | Each option needs to be started with the |
| 635 | .Ic define |
| 636 | or |
| 637 | .Ic define6 |
| 638 | directive. |
| 639 | This can optionally be followed by both |
| 640 | .Ic embed |
| 641 | or |
| 642 | .Ic encap |
| 643 | options. |
| 644 | Both can be specified more than once and |
| 645 | .Ic embed |
| 646 | must come before |
| 647 | .Ic encap . |
| 648 | .Bl -tag -width indent |
| 649 | .It Ic define Ar code Ar type Ar variable |
| 650 | Defines the DHCP option |
| 651 | .Ar code |
| 652 | of |
| 653 | .Ar type |
| 654 | with a name of |
| 655 | .Ar variable |
| 656 | exported to |
| 657 | .Xr dhcpcd-run-hooks 8 . |
| 658 | .It Ic define6 Ar code Ar type Ar variable |
| 659 | Defines the DHCPv6 option |
| 660 | .Ar code |
| 661 | of |
| 662 | .Ar type |
| 663 | with a name of |
| 664 | .Ar variable |
| 665 | exported to |
| 666 | .Xr dhcpcd-run-hooks 8 , |
| 667 | with a prefix of |
| 668 | .Va _dhcp6 . |
| 669 | .It Ic vendopt Ar code Ar type Ar variable |
| 670 | Defines the Vendor-Identifying Vendor Options. |
| 671 | The |
| 672 | .Ar code |
| 673 | is the IANA Enterprise Number which will unqiuely describe the encapsulated |
| 674 | options. |
| 675 | .Ar type |
| 676 | is normally |
| 677 | .Ar encap . |
| 678 | .Ar variable |
| 679 | names the Vendor option to be exported. |
| 680 | .It Ic embed Ar type Ar variable |
| 681 | Defines an embedded variable within the defined option. |
| 682 | The length is determined by the |
| 683 | .Ar type . |
| 684 | If the |
| 685 | .Ar variable |
| 686 | is not the same as defined in the parent option, |
| 687 | it is prefixed with the parent |
| 688 | .Ar variable |
| 689 | first with an underscore. |
| 690 | .It Ic encap Ar code Ar type Ar variable |
| 691 | Defines an encapsulated variable within the defined option. |
| 692 | The length is determined by the |
| 693 | .Ar type . |
| 694 | If the |
| 695 | .Ar variable |
| 696 | is not the same as defined in the parent option, |
| 697 | it is prefixed with the parent |
| 698 | .Ar variable |
| 699 | first with an underscore. |
| 700 | .El |
| 701 | .Ss Type prefix |
| 702 | These keywords come before the type itself, to describe it more fully. |
| 703 | You can use more than one, but they must appear in the order listed below. |
| 704 | .Bl -tag -width -indent |
| 705 | .It Ic request |
| 706 | Requests the option by default without having to be specified in user |
| 707 | configuration |
| 708 | .It Ic norequest |
| 709 | This option cannot be requested, regardless of user configuration |
| 710 | .It Ic index |
| 711 | The option can appear more than once and will be indexed. |
| 712 | .It Ic array |
| 713 | The option data is split into a space separated array, each element being |
| 714 | the same type. |
| 715 | .El |
| 716 | .Ss Types to define |
| 717 | The type directly affects the length of data consumed inside the option. |
| 718 | Any remaining data is normally discarded. |
| 719 | Lengths can be specified for string and binhex types, but this is generally |
| 720 | with other data embedded afterwards in the same option. |
| 721 | .Bl -tag -width indent |
| 722 | .It Ic ipaddress |
| 723 | An IPv4 address, 4 bytes |
| 724 | .It Ic ip6address |
| 725 | An IPv6 address, 16 bytes |
| 726 | .It Ic string Op : Ic length |
| 727 | A NVT ASCII string of printable characters. |
| 728 | .It Ic byte |
| 729 | A byte |
| 730 | .It Ic int16 |
| 731 | A signed 16bit integer, 2 bytes |
| 732 | .It Ic uint16 |
| 733 | An unsigned 16bit integer, 2 bytes |
| 734 | .It Ic int32 |
| 735 | A signed 32bit integer, 4 bytes |
| 736 | .It Ic uint32 |
| 737 | An unsigned 32bit integer, 4 bytes |
| 738 | .It Ic flag |
| 739 | A fixed value (1) to indicate that the option is present, 0 bytes |
| 740 | .It Ic domain |
| 741 | A RFC 3397 encoded string |
| 742 | .It Ic dname |
| 743 | A RFC 1035 validated string |
| 744 | .It Ic binhex Op : Ic length |
| 745 | Binary data expressed as hexadecimal |
| 746 | .It Ic embed |
| 747 | Contains embedded options (implies encap as well) |
| 748 | .It Ic encap |
| 749 | Contains encapsulated options (implies embed as well) |
| 750 | .It Ic option |
| 751 | References an option from the global definition |
| 752 | .El |
| 753 | .Ss Example definition |
| 754 | .D1 # DHCP option 81, Fully Qualified Domain Name, RFC4702 |
| 755 | .D1 define 81 embed fqdn |
| 756 | .D1 embed byte flags |
| 757 | .D1 embed byte rcode1 |
| 758 | .D1 embed byte rcode2 |
| 759 | .D1 embed domain fqdn |
| 760 | .Pp |
| 761 | .D1 # DHCP option 125, Vendor Specific Information Option, RFC3925 |
| 762 | .D1 define 125 encap vsio |
| 763 | .D1 embed uint32 enterprise_number |
| 764 | .D1 # Options defined for the enterprise number |
| 765 | .D1 encap 1 ipaddress ipaddress |
| 766 | .Ss Supported Authentication Protocols |
| 767 | .Bl -tag -width -indent |
| 768 | .It Ic token |
| 769 | Sends and expects the token with the secretid 0 and realm of "" in each message. |
| 770 | .It Ic delayedrealm |
| 771 | Delayed Authentication. |
| 772 | .Nm dhcpcd |
| 773 | will send an authentication option with no key or MAC. |
| 774 | The server will see this option, and select a key for |
| 775 | .Nm , writing the |
| 776 | .Ar realm |
| 777 | and |
| 778 | .Ar secretid |
| 779 | in it. |
| 780 | .Nm dhcpcd |
| 781 | will then look for a non-expired token with a matching realm and secretid. |
| 782 | This token is used to authenicate all other messages. |
| 783 | .It Ic delayed |
| 784 | Same as above, but without a realm. |
| 785 | .El |
| 786 | .Ss Supported Authentication Algorithms |
| 787 | If none specified, |
| 788 | .Ic hmac-md5 |
| 789 | is the default. |
| 790 | .Bl -tag -width -indent |
| 791 | .It Ic hmac-md5 |
| 792 | .El |
| 793 | .Ss Supported Replay Detection Mechanisms |
| 794 | If none specified, |
| 795 | .Ic monotonic |
| 796 | is the default. |
| 797 | If this is changed from what was previously used, |
| 798 | or the means of calculating or storing it is broken then the DHCP server |
| 799 | will probably have to have its notion of the clients Replay Detection Value |
| 800 | reset. |
| 801 | .Bl -tag -width -indent |
| 802 | .It Ic monocounter |
| 803 | Read the number in the file |
| 804 | .Pa @DBDIR@/dhcpcd-rdm.monotonic |
| 805 | and add one to it. |
| 806 | .It Ic monotime |
| 807 | Create a NTP timestamp from the system time. |
| 808 | .It Ic monotonic |
| 809 | Same as |
| 810 | .Ic monotime . |
| 811 | .El |
| 812 | .Sh SEE ALSO |
| 813 | .Xr fnmatch 3 , |
| 814 | .Xr if_nametoindex 3 , |
| 815 | .Xr dhcpcd 8 , |
| 816 | .Xr dhcpcd-run-hooks 8 |
| 817 | .Sh AUTHORS |
| 818 | .An Roy Marples Aq Mt roy@marples.name |
| 819 | .Sh BUGS |
| 820 | Please report them to |
| 821 | .Lk http://roy.marples.name/projects/dhcpcd |