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