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