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 March 19, 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 @SYSCONFDIR@/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 leasetime Ar seconds 158Request a leasetime of 159.Ar seconds . 160.It Ic metric Ar metric 161Metrics are used to prefer an interface over another one, lowest wins. 162.Nm dhcpcd 163will supply a default metric of 200 + 164.Xr if_nametoindex 3 . 165An extra 100 will be added for wireless interfaces. 166.It Ic noarp 167Don't send any ARP requests. 168This also disables IPv4LL. 169.It Ic nogateway 170Don't install any default routes. 171.It Ic nohook Ar script 172Don't run this hook script. 173Matches full name, or prefixed with 2 numbers optionally ending with 174.Pa .sh . 175.Pp 176So to stop 177.Nm dhcpcd 178from touching your DNS or MTU settings you would do:- 179.D1 nohook resolv.conf, mtu 180.It Ic noipv4ll 181Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP. 182See 183.Rs 184.%T "RFC 3927" 185.Re 186.It Ic noipv6rs 187Disable solicition of IPv6 Router Advertisements. 188.It Ic nolink 189Don't receive link messages about carrier status. 190You should only set this for buggy interface drivers. 191.It Ic option Ar option 192Requests the 193.Ar option 194from the server. 195It can be a variable to be used in 196.Xr dhcpcd-run-hooks 8 197or the numerical value. 198You can specify more options separated by commas, spaces or more option lines. 199.It Ic nooption Ar option 200Remove the option from the DHCP message. 201This should only be used when a DHCP server sends a non requested option 202that should not be processed. 203.It Ic destination Ar option 204If 205.Nm 206detects an address added to a point to point interface (PPP, TUN, etc) then 207it will set the listed DHCP options to the destination address of the 208interface. 209.It Ic profile Ar name 210Subsequent options are only parsed for this profile 211.Ar name . 212.It Ic quiet 213Suppress any dhcpcd output to the console, except for errors. 214.It Ic reboot Ar seconds 215Allow 216.Ar reboot 217seconds before moving to the discover phase if we have an old lease to use. 218The default is 5 seconds. 219A setting if 0 seconds causes 220.Nm dhcpcd 221to skip the reboot phase and go straight into discover. 222.It Ic release 223.Nm dhcpcd 224will release the lease prior to stopping the interface. 225.It Ic require Ar option 226Requires the 227.Ar option 228to be present in all DHCP messages, otherwise the message is ignored. 229It can be a variable to be used in 230.Xr dhcpcd-run-hooks 8 231or the numerical value. 232You can specify more options separated by commas, spaces or more require lines. 233To enforce that 234.Nm dhcpcd 235only responds to DHCP servers and not BOOTP servers, you can 236.Ic require 237.Ar dhcp_message_type . 238.It Ic script Ar script 239Use 240.Ar script 241instead of the default 242.Pa @SCRIPT@ . 243.It Ic ssid Ar ssid 244Subsequent options are only parsed for this wireless 245.Ar ssid . 246.It Ic static Ar value 247Configures a static 248.Ar value . 249If you set 250.Ic ip_address 251then 252.Nm dhcpcd 253will not attempt to obtain a lease and just use the value for the address with 254an infinite lease time. 255.Pp 256Here is an example which configures a static address, routes and dns. 257.D1 interface eth0 258.D1 static ip_address=192.168.0.10/24 259.D1 static routers=192.168.0.1 260.D1 static domain_name_servers=192.168.0.1 261.Pp 262Here is an example for PPP which gives the destination a default route. 263It uses the special destination keyword to insert the destination address 264into the value. 265.D1 interface ppp0 266.D1 static ip_address= 267.D1 destination routers 268.It Ic timeout Ar seconds 269The default timeout for waiting for a DHCP response is 30 seconds which may 270be too long or too short and can be changed here. 271.It Ic userclass Ar string 272Tag the DHCP messages with the userclass. 273You can specify more than one. 274.It Ic vendor Ar code , Ns Ar value 275Add an encapsulated vendor option. 276.Ar code 277should be between 1 and 254 inclusive. 278To add a raw vendor string, omit 279.Ar code 280but keep the comma. 281Examples. 282.Pp 283Set the vendor option 01 with an IP address. 284.D1 vendor 01,192.168.0.2 285Set the vendor option 02 with a hex code. 286.D1 vendor 02,01:02:03:04:05 287Set the vendor option 03 with an IP address as a string. 288.D1 vendor 03,\e"192.168.0.2\e" 289Set un-encapsulated vendor option to hello world. 290.D1 vendor ,"hello world" 291.It Ic vendorclassid Ar string 292Change the default vendorclassid sent from dhcpcd-version. 293If not set then none is sent. 294.It Ic waitip 295Wait for an address to be assigned before forking to the background. 296.It Ic xidhwaddr 297Use the last four bytes of the hardware address as the DHCP xid instead 298of a randomly generated number. 299.El 300.Sh SEE ALSO 301.Xr dhcpcd-run-hooks 8 , 302.Xr dhcpcd 8 , 303.Xr if_nametoindex 3 , 304.Xr fnmatch 3 305.Sh AUTHORS 306.An Roy Marples Aq roy@marples.name 307.Sh BUGS 308Please report them to 309.Lk http://roy.marples.name/projects/dhcpcd 310