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 March 17, 2015 |
| 26 | .Dt DHCPCD 8 |
| 27 | .Os |
| 28 | .Sh NAME |
| 29 | .Nm dhcpcd |
| 30 | .Nd a DHCP client |
| 31 | .Sh SYNOPSIS |
| 32 | .Nm |
| 33 | .Op Fl 46ABbDdEGgHJKLMpqTV |
| 34 | .Op Fl C , Fl Fl nohook Ar hook |
| 35 | .Op Fl c , Fl Fl script Ar script |
| 36 | .Op Fl e , Fl Fl env Ar value |
| 37 | .Op Fl F , Fl Fl fqdn Ar FQDN |
| 38 | .Op Fl f , Fl Fl config Ar file |
| 39 | .Op Fl h , Fl Fl hostname Ar hostname |
| 40 | .Op Fl I , Fl Fl clientid Ar clientid |
| 41 | .Op Fl i , Fl Fl vendorclassid Ar vendorclassid |
| 42 | .Op Fl j , Fl Fl logfile Ar logfile |
| 43 | .Op Fl l , Fl Fl leasetime Ar seconds |
| 44 | .Op Fl m , Fl Fl metric Ar metric |
| 45 | .Op Fl O , Fl Fl nooption Ar option |
| 46 | .Op Fl o , Fl Fl option Ar option |
| 47 | .Op Fl Q , Fl Fl require Ar option |
| 48 | .Op Fl r , Fl Fl request Ar address |
| 49 | .Op Fl S , Fl Fl static Ar value |
| 50 | .Op Fl s , Fl Fl inform Ar address Ns Op Ar /cidr |
| 51 | .Op Fl t , Fl Fl timeout Ar seconds |
| 52 | .Op Fl u , Fl Fl userclass Ar class |
| 53 | .Op Fl v , Fl Fl vendor Ar code , Ar value |
| 54 | .Op Fl W , Fl Fl whitelist Ar address Ns Op Ar /cidr |
| 55 | .Op Fl w |
| 56 | .Op Fl Fl waitip Op 4 | 6 |
| 57 | .Op Fl y , Fl Fl reboot Ar seconds |
| 58 | .Op Fl X , Fl Fl blacklist Ar address Ns Op Ar /cidr |
| 59 | .Op Fl Z , Fl Fl denyinterfaces Ar pattern |
| 60 | .Op Fl z , Fl Fl allowinterfaces Ar pattern |
| 61 | .Op interface |
| 62 | .Op ... |
| 63 | .Nm |
| 64 | .Fl n , Fl Fl rebind |
| 65 | .Op interface |
| 66 | .Nm |
| 67 | .Fl k , Fl Fl release |
| 68 | .Op interface |
| 69 | .Nm |
| 70 | .Fl U, Fl Fl dumplease |
| 71 | .Ar interface |
| 72 | .Nm |
| 73 | .Fl Fl version |
| 74 | .Nm |
| 75 | .Fl x , Fl Fl exit |
| 76 | .Op interface |
| 77 | .Sh DESCRIPTION |
| 78 | .Nm |
| 79 | is an implementation of the DHCP client specified in |
| 80 | .Li RFC 2131 . |
| 81 | .Nm |
| 82 | gets the host information |
| 83 | .Po |
| 84 | IP address, routes, etc |
| 85 | .Pc |
| 86 | from a DHCP server and configures the network |
| 87 | .Ar interface |
| 88 | of the |
| 89 | machine on which it is running. |
| 90 | .Nm |
| 91 | then runs the configuration script which writes DNS information to |
| 92 | .Xr resolvconf 8 , |
| 93 | if available, otherwise directly to |
| 94 | .Pa /etc/resolv.conf . |
| 95 | If the hostname is currently blank, (null) or localhost, or |
| 96 | .Va force_hostname |
| 97 | is YES or TRUE or 1 then |
| 98 | .Nm |
| 99 | sets the hostname to the one supplied by the DHCP server. |
| 100 | .Nm |
| 101 | then daemonises and waits for the lease renewal time to lapse. |
| 102 | It will then attempt to renew its lease and reconfigure if the new lease |
| 103 | changes when the lease beings to expire or the DHCP server sends message |
| 104 | to renew early. |
| 105 | .Pp |
| 106 | If any interface reports a working carrier then |
| 107 | .Nm |
| 108 | will try and obtain a lease before forking to the background, |
| 109 | otherwise it will fork right away. |
| 110 | This behaviour can be modified with the |
| 111 | .Fl b , Fl Fl background |
| 112 | and |
| 113 | .Fl w , Fl Fl waitip |
| 114 | options. |
| 115 | .Pp |
| 116 | .Nm |
| 117 | is also an implementation of the BOOTP client specified in |
| 118 | .Li RFC 951 . |
| 119 | .Pp |
| 120 | .Nm |
| 121 | is also an implementation of the IPv6 Router Solicitor as specified in |
| 122 | .Li RFC 4861 |
| 123 | and |
| 124 | .Li RFC 6106 . |
| 125 | .Pp |
| 126 | .Nm |
| 127 | is also an implementation of the IPv6 Privacy Extensions to AutoConf as |
| 128 | specified in |
| 129 | .Li RFC 4941 . |
| 130 | This feature needs to be enabled in the kernel and |
| 131 | .Nm |
| 132 | will start using it. |
| 133 | .Pp |
| 134 | .Nm |
| 135 | is also an implemenation of the DHCPv6 client as specified in |
| 136 | .Li RFC 3315 . |
| 137 | By default, |
| 138 | .Nm |
| 139 | only starts DHCPv6 when instructed to do so by an IPV6 Router Advertisement. |
| 140 | If no Identity Association is configured, |
| 141 | then a Non-temporary Address is requested. |
| 142 | .Ss Local Link configuration |
| 143 | If |
| 144 | .Nm |
| 145 | failed to obtain a lease, it probes for a valid IPv4LL address |
| 146 | .Po |
| 147 | aka ZeroConf, aka APIPA |
| 148 | .Pc . |
| 149 | Once obtained it restarts the process of looking for a DHCP server to get a |
| 150 | proper address. |
| 151 | .Pp |
| 152 | When using IPv4LL, |
| 153 | .Nm |
| 154 | nearly always succeeds and returns an exit code of 0. |
| 155 | In the rare case it fails, it normally means that there is a reverse ARP proxy |
| 156 | installed which always defeats IPv4LL probing. |
| 157 | To disable this behaviour, you can use the |
| 158 | .Fl L , Fl Fl noipv4ll |
| 159 | option. |
| 160 | .Ss Multiple interfaces |
| 161 | If a list of interfaces are given on the command line, then |
| 162 | .Nm |
| 163 | only works with those interfaces, otherwise |
| 164 | .Nm |
| 165 | discovers available Ethernet interfaces that can be configured. |
| 166 | When |
| 167 | .Nm |
| 168 | is operating on more than one interface, |
| 169 | it is called Master mode. and this behaviour can be forced with the |
| 170 | .Fl M , Fl Fl master |
| 171 | option so that an individual interface can start |
| 172 | .Nm |
| 173 | but only one instance is running. |
| 174 | The |
| 175 | .Nm dhcpcd-ui |
| 176 | project expects dhcpcd to be running this way. |
| 177 | .Pp |
| 178 | If a single interface is given then |
| 179 | .Nm |
| 180 | only works for that interface and runs as a separate instance. |
| 181 | The |
| 182 | .Fl w , Fl Fl waitip |
| 183 | option is enabled in this instance to maintain compatibility with older |
| 184 | versions. |
| 185 | .Pp |
| 186 | Interfaces are preferred by carrier, DHCP lease/IPv4LL and then lowest metric. |
| 187 | For systems that support route metrics, each route will be tagged with the |
| 188 | metric, otherwise |
| 189 | .Nm |
| 190 | changes the routes to use the interface with the same route and the lowest |
| 191 | metric. |
| 192 | See options below for controlling which interfaces we allow and deny through |
| 193 | the use of patterns. |
Samuel Tan | a359582 | 2015-08-13 16:41:21 -0700 | [diff] [blame] | 194 | .Pp |
| 195 | If an interface name is suffixed by an equal-sign, the text following the |
| 196 | equal sign will be used instead of the interface name as the unique identifier |
| 197 | for the DHCP lease file. Doing so allows the caller to specify different |
| 198 | lease files for the same interface (e.g, when switching the same wireless |
| 199 | interface between different 802.11 networks). |
Samuel Tan | d7ed851 | 2015-08-13 16:11:35 -0700 | [diff] [blame] | 200 | .Ss Hooking into events |
| 201 | .Nm |
| 202 | runs |
| 203 | .Pa @SCRIPT@ , |
| 204 | or the script specified by the |
| 205 | .Fl c , Fl Fl script |
| 206 | option. |
| 207 | This script runs each script found in |
| 208 | .Pa @HOOKDIR@ |
| 209 | in a lexical order. |
| 210 | The default installation supplies the scripts |
| 211 | .Pa 01-test , |
| 212 | .Pa 10-mtu , |
| 213 | .Pa 10-wpa_supplicant , |
| 214 | .Pa 15-timezone , |
| 215 | .Pa 20-resolv.conf |
| 216 | and |
| 217 | .Pa 30-hostname . |
| 218 | You can disable each script by using the |
| 219 | .Fl C , Fl Fl nohook |
| 220 | option. |
| 221 | See |
| 222 | .Xr dhcpcd-run-hooks 8 |
| 223 | for details on how these scripts work. |
| 224 | .Nm |
| 225 | currently ignores the exit code of the script. |
| 226 | .Ss Fine tuning |
| 227 | You can fine-tune the behaviour of |
| 228 | .Nm |
| 229 | with the following options: |
| 230 | .Bl -tag -width indent |
| 231 | .It Fl b , Fl Fl background |
| 232 | Background immediately. |
| 233 | This is useful for startup scripts which don't disable link messages for |
| 234 | carrier status. |
| 235 | .It Fl c , Fl Fl script Ar script |
| 236 | Use this |
| 237 | .Ar script |
| 238 | instead of the default |
| 239 | .Pa @SCRIPT@ . |
| 240 | .It Fl D , Fl Fl duid |
| 241 | Generate an |
| 242 | .Li RFC 4361 |
| 243 | compliant clientid. |
| 244 | This requires persistent storage and not all DHCP servers work with it so it |
| 245 | is not enabled by default. |
| 246 | .Nm |
| 247 | generates the DUID and stores it in |
| 248 | .Pa @SYSCONFDIR@/dhcpcd.duid . |
| 249 | This file should not be copied to other hosts. |
| 250 | .It Fl d , Fl Fl debug |
| 251 | Echo debug messages to the stderr and syslog. |
| 252 | .It Fl E , Fl Fl lastlease |
| 253 | If |
| 254 | .Nm |
| 255 | cannot obtain a lease, then try to use the last lease acquired for the |
| 256 | interface. |
| 257 | If the |
| 258 | .Fl p, Fl Fl persistent |
| 259 | option is not given then the lease is used if it hasn't expired. |
| 260 | .It Fl e , Fl Fl env Ar value |
| 261 | Push |
| 262 | .Ar value |
| 263 | to the environment for use in |
| 264 | .Xr dhcpcd-run-hooks 8 . |
| 265 | For example, you can force the hostname hook to always set the hostname with |
| 266 | .Fl e |
| 267 | .Va force_hostname=YES . |
| 268 | .It Fl g , Fl Fl reconfigure |
| 269 | .Nm |
| 270 | will re-apply IP address, routing and run |
| 271 | .Xr dhcpcd-run-hooks 8 |
| 272 | for each interface. |
| 273 | This is useful so that a 3rd party such as PPP or VPN can change the routing |
| 274 | table and / or DNS, etc and then instruct |
| 275 | .Nm |
| 276 | to put things back afterwards. |
| 277 | .Nm |
| 278 | does not read a new configuration when this happens - you should rebind if you |
| 279 | need that functionality. |
| 280 | .It Fl F , Fl Fl fqdn Ar fqdn |
| 281 | Requests that the DHCP server updates DNS using FQDN instead of just a |
| 282 | hostname. |
| 283 | Valid values for |
| 284 | .Ar fqdn |
| 285 | are disable, none, ptr and both. |
| 286 | .Nm |
| 287 | itself never does any DNS updates. |
| 288 | .Nm |
| 289 | encodes the FQDN hostname as specified in |
| 290 | .Li RFC1035 . |
| 291 | .It Fl f , Fl Fl config Ar file |
| 292 | Specify a config to load instead of |
| 293 | .Pa @SYSCONFDIR@/dhcpcd.conf . |
| 294 | .Nm |
| 295 | always processes the config file before any command line options. |
| 296 | .It Fl h , Fl Fl hostname Ar hostname |
| 297 | Sends |
| 298 | .Ar hostname |
| 299 | to the DHCP server so it can be registered in DNS. |
| 300 | If |
| 301 | .Ar hostname |
| 302 | is an empty string then the current system hostname is sent. |
| 303 | If |
| 304 | .Ar hostname |
| 305 | is a FQDN (ie, contains a .) then it will be encoded as such. |
| 306 | .It Fl I , Fl Fl clientid Ar clientid |
| 307 | Send the |
| 308 | .Ar clientid . |
| 309 | If the string is of the format 01:02:03 then it is encoded as hex. |
| 310 | For interfaces whose hardware address is longer than 8 bytes, or if the |
| 311 | .Ar clientid |
| 312 | is an empty string then |
| 313 | .Nm |
| 314 | sends a default |
| 315 | .Ar clientid |
| 316 | of the hardware family and the hardware address. |
| 317 | .It Fl i , Fl Fl vendorclassid Ar vendorclassid |
| 318 | Override the DHCPv4 |
| 319 | .Ar vendorclassid |
| 320 | field sent. |
| 321 | The default is |
| 322 | dhcpcd-<version>:<os>:<machine>:<platform>. |
| 323 | For example |
| 324 | .D1 dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386 |
| 325 | If not set then none is sent. |
| 326 | Some badly configured DHCP servers reject unknown vendorclassids. |
| 327 | To work around it, try and impersonate Windows by using the MSFT vendorclassid. |
| 328 | .It Fl j , Fl Fl logfile Ar logfile |
| 329 | Writes to the specified |
| 330 | .Ar logfile |
| 331 | rather than |
| 332 | .Xr syslog 3 . |
| 333 | The |
| 334 | .Ar logfile |
| 335 | is truncated when opened and is reopened when |
| 336 | .Nm |
| 337 | receives the |
| 338 | .Dv SIGUSR2 |
| 339 | signal. |
| 340 | .It Fl k , Fl Fl release Op Ar interface |
| 341 | This causes an existing |
| 342 | .Nm |
| 343 | process running on the |
| 344 | .Ar interface |
| 345 | to release its lease and de-configure the |
| 346 | .Ar interface . |
| 347 | If no |
| 348 | .Ar interface |
| 349 | is specified then this applies to all interfaces. |
| 350 | If no interfaces are left running, |
| 351 | .Nm |
| 352 | will exit. |
| 353 | .It Fl l , Fl Fl leasetime Ar seconds |
| 354 | Request a specific lease time in |
| 355 | .Ar seconds . |
| 356 | By default |
| 357 | .Nm |
| 358 | does not request any lease time and leaves it in the hands of the |
| 359 | DHCP server. |
| 360 | .It Fl M , Fl Fl master |
| 361 | Start |
| 362 | .Nm |
| 363 | in master mode even if only one interface specified on the command line. |
| 364 | See the Multiple Interfaces section above. |
| 365 | .It Fl m , Fl Fl metric Ar metric |
| 366 | Metrics are used to prefer an interface over another one, lowest wins. |
| 367 | .Nm |
| 368 | will supply a default metic of 200 + |
| 369 | .Xr if_nametoindex 3 . |
| 370 | An extra 100 will be added for wireless interfaces. |
| 371 | .It Fl n , Fl Fl rebind Op Ar interface |
| 372 | Notifies |
| 373 | .Nm |
| 374 | to reload its configuration and rebind the specified |
| 375 | .Ar interface . |
| 376 | If no interface is specified then this applies to all interfaces. |
| 377 | If |
| 378 | .Nm |
| 379 | is not running, then it starts up as normal. |
| 380 | This may also cause |
| 381 | .Xr wpa_supplicant 8 |
| 382 | to reload its configuration for each interface as well. |
| 383 | .It Fl o , Fl Fl option Ar option |
| 384 | Request the DHCP |
| 385 | .Ar option |
| 386 | variable for use in |
| 387 | .Pa @SCRIPT@ . |
| 388 | .It Fl p , Fl Fl persistent |
| 389 | .Nm |
| 390 | normally de-configures the |
| 391 | .Ar interface |
| 392 | and configuration when it exits. |
| 393 | Sometimes, this isn't desirable if, for example, you have root mounted over |
| 394 | NFS or SSH clients connect to this host and they need to be notified of |
| 395 | the host shutting down. |
| 396 | You can use this option to stop this from happening. |
| 397 | .It Fl r , Fl Fl request Op Ar address |
| 398 | Request the |
| 399 | .Ar address |
| 400 | in the DHCP DISCOVER message. |
| 401 | There is no guarantee this is the address the DHCP server will actually give. |
| 402 | If no |
| 403 | .Ar address |
| 404 | is given then the first address currently assigned to the |
| 405 | .Ar interface |
| 406 | is used. |
| 407 | .It Fl s , Fl Fl inform Op Ar address Ns Op Ar /cidr |
| 408 | Behaves like |
| 409 | .Fl r , Fl Fl request |
| 410 | as above, but sends a DHCP INFORM instead of DISCOVER/REQUEST. |
| 411 | This does not get a lease as such, just notifies the DHCP server of the |
| 412 | .Ar address |
| 413 | in use. |
| 414 | You should also include the optional |
| 415 | .Ar cidr |
| 416 | network number in case the address is not already configured on the interface. |
| 417 | .Nm |
| 418 | remains running and pretends it has an infinite lease. |
| 419 | .Nm |
| 420 | will not de-configure the interface when it exits. |
| 421 | If |
| 422 | .Nm |
| 423 | fails to contact a DHCP server then it returns a failure instead of falling |
| 424 | back on IPv4LL. |
| 425 | .It Fl S, Fl Fl static Ar value |
| 426 | Configures a static |
| 427 | .Ar value . |
| 428 | If you set |
| 429 | .Ic ip_address |
| 430 | then |
| 431 | .Nm |
| 432 | will not attempt to obtain a lease and just use the value for the address with |
| 433 | an infinite lease time. |
| 434 | .Pp |
| 435 | Here is an example which configures a static address, routes and dns. |
| 436 | .D1 dhcpcd -S ip_address=192.168.0.10/24 \e |
| 437 | .D1 -S routers=192.168.0.1 \e |
| 438 | .D1 -S domain_name_servers=192.168.0.1 \e |
| 439 | .D1 eth0 |
| 440 | .It Fl t , Fl Fl timeout Ar seconds |
| 441 | Timeout after |
| 442 | .Ar seconds , |
| 443 | instead of the default 30. |
| 444 | A setting of 0 |
| 445 | .Ar seconds |
| 446 | causes |
| 447 | .Nm |
| 448 | to wait forever to get a lease. |
| 449 | If |
| 450 | .Nm |
| 451 | is working on a single interface then |
| 452 | .Nm |
| 453 | will exit when a timeout occurs, otherwise |
| 454 | .Nm |
| 455 | will fork into the background. |
| 456 | .It Fl u , Fl Fl userclass Ar class |
| 457 | Tags the DHCPv4 message with the userclass |
| 458 | .Ar class . |
| 459 | DHCP servers use this to give members of the class DHCP options other than the |
| 460 | default, without having to know things like hardware address or hostname. |
| 461 | .It Fl v , Fl Fl vendor Ar code , Ns Ar value |
| 462 | Add an encapsulated vendor option. |
| 463 | .Ar code |
| 464 | should be between 1 and 254 inclusive. |
| 465 | To add a raw vendor string, omit |
| 466 | .Ar code |
| 467 | but keep the comma. |
| 468 | Examples. |
| 469 | .Pp |
| 470 | Set the vendor option 01 with an IP address. |
| 471 | .D1 dhcpcd \-v 01,192.168.0.2 eth0 |
| 472 | Set the vendor option 02 with a hex code. |
| 473 | .D1 dhcpcd \-v 02,01:02:03:04:05 eth0 |
| 474 | Set the vendor option 03 with an IP address as a string. |
| 475 | .D1 dhcpcd \-v 03,\e"192.168.0.2\e" eth0 |
| 476 | Set un-encapsulated vendor option to hello world. |
| 477 | .D1 dhcpcd \-v ,"hello world" eth0 |
| 478 | .It Fl Fl version |
| 479 | Display both program version and copyright information. |
| 480 | .Nm |
| 481 | then exits before doing any configuration. |
| 482 | .It Fl w |
| 483 | Wait for an address to be assigned before forking to the background. |
| 484 | Does not take an argument, unlike the below option. |
| 485 | .Fl fl waitip |
| 486 | option. |
| 487 | .It Fl Fl waitip Op 4 | 6 |
| 488 | Wait for an address to be assigned before forking to the background. |
| 489 | 4 means wait for an IPv4 address to be assigned. |
| 490 | 6 means wait for an IPv6 address to be assigned. |
| 491 | If no argument is given, |
| 492 | .Nm |
| 493 | will wait for any address protocol to be assigned. |
| 494 | It is possible to wait for more than one address protocol and |
| 495 | .Nm |
| 496 | will only fork to the background when all waiting conditions are satisfied. |
| 497 | .It Fl x , Fl Fl exit Op Ar interface |
| 498 | This will signal an existing |
| 499 | .Nm |
| 500 | process running on the |
| 501 | .Ar interface |
| 502 | to de-configure the |
| 503 | .Ar interface |
| 504 | and exit. |
| 505 | If no interface is specified, then the above is applied to all interfaces. |
| 506 | .Nm |
| 507 | then waits until this process has exited. |
| 508 | .It Fl y , Fl Fl reboot Ar seconds |
| 509 | Allow |
| 510 | .Ar reboot |
| 511 | seconds before moving to the discover phase if we have an old lease to use. |
| 512 | Allow |
| 513 | .Ar reboot |
| 514 | seconds before starting fallback states from the discover phase. |
| 515 | IPv4LL is started when the first |
| 516 | .Ar reboot |
| 517 | timeout is reached. |
| 518 | The default is 5 seconds. |
| 519 | A setting of 0 seconds causes |
| 520 | .Nm |
| 521 | to skip the reboot phase and go straight into discover. |
| 522 | This has no effect on DHCPv6 other than skipping the reboot phase. |
| 523 | .El |
| 524 | .Ss Restricting behaviour |
| 525 | .Nm |
| 526 | will try to do as much as it can by default. |
| 527 | However, there are sometimes situations where you don't want the things to be |
| 528 | configured exactly how the the DHCP server wants. |
| 529 | Here are some options that deal with turning these bits off. |
| 530 | .Bl -tag -width indent |
| 531 | .It Fl 4 , Fl Fl ipv4only |
| 532 | Configure IPv4 only. |
| 533 | .It Fl 6 , Fl Fl ipv6only |
| 534 | Configure IPv6 only. |
| 535 | .It Fl A , Fl Fl noarp |
| 536 | Don't request or claim the address by ARP. |
| 537 | This also disables IPv4LL. |
| 538 | .It Fl B , Fl Fl nobackground |
| 539 | Don't run in the background when we acquire a lease. |
| 540 | This is mainly useful for running under the control of another process, such |
| 541 | as a debugger or a network manager. |
| 542 | .It Fl C , Fl Fl nohook Ar script |
| 543 | Don't run this hook script. |
| 544 | Matches full name, or prefixed with 2 numbers optionally ending with |
| 545 | .Pa .sh . |
| 546 | .Pp |
| 547 | So to stop |
| 548 | .Nm |
| 549 | from touching your DNS or MTU settings you would do:- |
| 550 | .D1 dhcpcd -C resolv.conf -C mtu eth0 |
| 551 | .It Fl G , Fl Fl nogateway |
| 552 | Don't set any default routes. |
| 553 | .It Fl H , Fl Fl xidhwaddr |
| 554 | Use the last four bytes of the hardware address as the DHCP xid instead |
| 555 | of a randomly generated number. |
| 556 | .It Fl J , Fl Fl broadcast |
| 557 | Instructs the DHCP server to broadcast replies back to the client. |
| 558 | Normally this is only set for non Ethernet interfaces, |
| 559 | such as FireWire and InfiniBand. |
| 560 | In most instances, |
| 561 | .Nm |
| 562 | will set this automatically. |
| 563 | .It Fl K , Fl Fl nolink |
| 564 | Don't receive link messages for carrier status. |
| 565 | You should only have to use this with buggy device drivers or running |
| 566 | .Nm |
| 567 | through a network manager. |
| 568 | .It Fl L , Fl Fl noipv4ll |
| 569 | Don't use IPv4LL (aka APIPA, aka Bonjour, aka ZeroConf). |
| 570 | .It Fl O , Fl Fl nooption Ar option |
| 571 | Don't request the specified option. |
| 572 | If no option given, then don't request any options other than those to |
| 573 | configure the interface and routing. |
| 574 | .It Fl Q , Fl Fl require Ar option |
| 575 | Requires the |
| 576 | .Ar option |
| 577 | to be present in all DHCP messages, otherwise the message is ignored. |
| 578 | To enforce that |
| 579 | .Nm |
| 580 | only responds to DHCP servers and not BOOTP servers, you can |
| 581 | .Fl Q |
| 582 | .Ar dhcp_message_type . |
| 583 | .It Fl q , Fl Fl quiet |
| 584 | Quiet |
| 585 | .Nm |
| 586 | on the command line, only warnings and errors will be displayed. |
| 587 | The messages are still logged though. |
| 588 | .It Fl T, Fl Fl test |
| 589 | On receipt of DHCP messages just call |
| 590 | .Pa @SCRIPT@ |
| 591 | with the reason of TEST which echos the DHCP variables found in the message |
| 592 | to the console. |
| 593 | The interface configuration isn't touched and neither are any configuration |
| 594 | files. |
| 595 | The |
| 596 | .Ar rapid_commit |
| 597 | option is not sent in TEST mode so that the server does not lease an address. |
| 598 | To test INFORM the interface needs to be configured with the desired address |
| 599 | before starting |
| 600 | .Nm . |
| 601 | .It Fl U, Fl Fl dumplease Ar interface |
| 602 | Dumps the last lease for the |
| 603 | .Ar interface |
| 604 | to stdout. |
| 605 | .Ar interface |
| 606 | could also be a path to a DHCP wire formatted file. |
| 607 | Use the |
| 608 | .Fl 4 |
| 609 | or |
| 610 | .Fl 6 |
| 611 | flags to specify an address family. |
| 612 | Pass a 2nd |
| 613 | .Fl U, Fl Fl dumplease option to dump a secondary lease, such as |
| 614 | DHCPv6 Prefix Delegation when not being mixed with another IA type. |
| 615 | .It Fl V, Fl Fl variables |
| 616 | Display a list of option codes, the associated variable and encoding for use in |
| 617 | .Xr dhcpcd-run-hooks 8 . |
| 618 | Variables are prefixed with new_ and old_ unless the option number is -. |
| 619 | Variables without an option are part of the DHCP message and cannot be |
| 620 | directly requested. |
| 621 | .It Fl W, Fl Fl whitelist Ar address Ns Op /cidr |
| 622 | Only accept packets from |
| 623 | .Ar address Ns Op /cidr . |
| 624 | .Fl X, Fl Fl blacklist |
| 625 | is ignored if |
| 626 | .Fl W, Fl Fl whitelist |
| 627 | is set. |
| 628 | .It Fl X, Fl Fl blacklist Ar address Ns Op Ar /cidr |
| 629 | Ignore all packets from |
| 630 | .Ar address Ns Op Ar /cidr . |
| 631 | .It Fl Z , Fl Fl denyinterfaces Ar pattern |
| 632 | When discovering interfaces, the interface name must not match |
| 633 | .Ar pattern |
| 634 | which is a space or comma separated list of patterns passed to |
| 635 | .Xr fnmatch 3 . |
| 636 | .It Fl z , Fl Fl allowinterfaces Ar pattern |
| 637 | When discovering interfaces, the interface name must match |
| 638 | .Ar pattern |
| 639 | which is a space or comma separated list of patterns passed to |
| 640 | .Xr fnmatch 3 . |
| 641 | If the same interface is matched in |
| 642 | .Fl Z , Fl Fl denyinterfaces |
| 643 | then it is still denied. |
| 644 | .It Fl Fl nodev |
| 645 | Don't load any |
| 646 | .Pa /dev |
| 647 | management modules. |
| 648 | .El |
| 649 | .Sh 3RDPARTY LINK MANAGEMENT |
| 650 | Some interfaces require configuration by 3rd parties, such as PPP or VPN. |
| 651 | When an interface configuration in |
| 652 | .Nm |
| 653 | is marked as STATIC or INFORM without an address then |
| 654 | .Nm |
| 655 | will monitor the interface until an address is added or removed from it and |
| 656 | act accordingly. |
| 657 | For point to point interfaces (like PPP), a default route to its |
| 658 | destination is automatically added to the configuration. |
| 659 | If the point to point interface is configured for INFORM, then |
| 660 | .Nm |
| 661 | unicasts INFORM to the destination, otherwise it defaults to STATIC. |
| 662 | .Sh NOTES |
| 663 | .Nm |
| 664 | requires a Berkley Packet Filter, or BPF device on BSD based systems and a |
| 665 | Linux Socket Filter, or LPF device on Linux based systems for all IPv4 |
| 666 | configuration. |
| 667 | .Pp |
| 668 | If restricting |
| 669 | .Nm |
| 670 | to a single interface and optionally address family via the command-line |
| 671 | then all futher calls to |
| 672 | .Nm |
| 673 | to rebind, reconfigure or exit need to include the same restrictive flags |
| 674 | so that |
| 675 | .Nm |
| 676 | knows which process to signal. |
| 677 | .Sh FILES |
| 678 | .Bl -ohang |
| 679 | .It Pa @SYSCONFDIR@/dhcpcd.conf |
| 680 | Configuration file for dhcpcd. |
| 681 | If you always use the same options, put them here. |
| 682 | .It Pa @SYSCONFDIR@/dhcpcd.duid |
| 683 | Text file that holds the DUID used to identify the host. |
| 684 | .It Pa @SYSCONFDIR@/dhcpcd.secret |
| 685 | Text file that holds a secret key known only to the host. |
| 686 | .It Pa @SCRIPT@ |
| 687 | Bourne shell script that is run to configure or de-configure an interface. |
| 688 | .It Pa @LIBDIR@/dhcpcd/dev |
| 689 | .Pa /dev |
| 690 | management modules. |
| 691 | .It Pa @HOOKDIR@ |
| 692 | A directory containing bourne shell scripts that are run by the above script. |
| 693 | Each script can be disabled by using the |
| 694 | .Fl C , Fl Fl nohook |
| 695 | option described above. |
| 696 | .It Pa @DBDIR@/dhcpcd\- Ns Ar interface Ns Ar -ssid Ns .lease |
| 697 | The actual DHCP message sent by the server. |
| 698 | We use this when reading the last |
| 699 | lease and use the files mtime as when it was issued. |
| 700 | .It Pa @DBDIR@/dhcpcd\- Ns Ar interface Ns Ar -ssid Ns .lease6 |
| 701 | The actual DHCPv6 message sent by the server. |
| 702 | We use this when reading the last |
| 703 | lease and use the files mtime as when it was issued. |
| 704 | .It Pa @DBDIR@/dhcpcd-rdm.monotonic |
| 705 | Stores the monotonic counter used in the |
| 706 | .Ar replay |
| 707 | field in Authentication Options. |
| 708 | .It Pa @RUNDIR@/dhcpcd.pid |
| 709 | Stores the PID of |
| 710 | .Nm |
| 711 | running on all interfaces. |
| 712 | .It Pa @RUNDIR@/dhcpcd\- Ns Ar interface Ns .pid |
| 713 | Stores the PID of |
| 714 | .Nm |
| 715 | running on the |
| 716 | .Ar interface . |
| 717 | .It Pa @RUNDIR@/dhcpcd.sock |
| 718 | Control socket to the master daemon. |
| 719 | .It Pa @RUNDIR@/dhcpcd.unpriv.sock |
| 720 | Unpriviledged socket to the master daemon, only allows state retrieval. |
| 721 | Control socket to the master daemon. |
| 722 | .It Pa @RUNDIR@/dhcpcd\- Ns Ar interface Ns .sock |
| 723 | Control socket to per interface daemon. |
| 724 | .El |
| 725 | .Sh SEE ALSO |
| 726 | .Xr fnmatch 3 , |
| 727 | .Xr if_nametoindex 3 , |
| 728 | .Xr dhcpcd.conf 5 , |
| 729 | .Xr resolv.conf 5 , |
| 730 | .Xr dhcpcd-run-hooks 8 , |
| 731 | .Xr resolvconf 8 |
| 732 | .Sh STANDARDS |
| 733 | RFC\ 951, RFC\ 1534, RFC\ 2104, RFC\ 2131, RFC\ 2132, RFC\ 2563, RFC\ 2855, |
| 734 | RFC\ 3004, RFC\ 3118, RFC\ 3203, RFC\ 3315, RFC\ 3361, RFC\ 3633, RFC\ 3396, |
| 735 | RFC\ 3397, RFC\ 3442, RFC\ 3495, RFC\ 3925, RFC\ 3927, RFC\ 4039, RFC\ 4075, |
| 736 | RFC\ 4242, RFC\ 4361, RFC\ 4390, RFC\ 4702, RFC\ 4074, RFC\ 4861, RFC\ 4833, |
| 737 | RFC\ 4941, RFC\ 5227, RFC\ 5942, RFC\ 5969, RFC\ 6106, RFC\ 6334, RFC\ 6603, |
| 738 | RFC\ 6704, RFC\ 7217. |
| 739 | .Sh AUTHORS |
| 740 | .An Roy Marples Aq Mt roy@marples.name |
| 741 | .Sh BUGS |
| 742 | Please report them to |
| 743 | .Lk http://roy.marples.name/projects/dhcpcd |