dhcpcd.conf.5.in

   1 .\" Copyright (c) 2006-2009 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 18, 2009
  26 .Dt DHCPCD.CONF 5 SMM
  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 background
  73 Background immediately.
  74 This is useful for startup scripts which don't disable link messages for
  75 carrier status.
  76 .It Ic blacklist Ar address Ns Op /cidr
  77 Ignores all packets from
  78 .Ar address Ns Op /cidr .
  79 .It Ic clientid Ar string
  80 Send the
  81 .Ar clientid .
  82 If the string is of the format 01:02:03 then it is encoded as hex.
  83 For interfaces whose hardware address is longer than 8 bytes, or if the
  84 .Ar clientid
  85 is an empty string then
  86 .Nm dhcpcd
  87 sends a default
  88 .Ar clientid
  89 of the hardware family and the hardware address.
  90 .It Ic duid
  91 Generate an
  92 .Rs
  93 .%T "RFC 4361"
  94 .Re
  95 compliant clientid.
  96 This requires persistent storage and not all DHCP servers work with it so it's
  97 not enabled by default.
  98 The duid generated will be held in
  99 .Pa @SYSCONFDIR@/dhcpcd.duid
 100 and should not be copied to other hosts.
 101 .It Ic fallback Ar profile
 102 Fallback to using this profile if DHCP fails.
 103 This allows you to configure a static profile instead of using ZeroConf.
 104 .It Ic hostname Ar name
 105 Sends specified
 106 .Ar hostname
 107 to the DHCP server so it can be registered in DNS. If
 108 .Ar hostname
 109 if a FQDN (ie, contains a .) then it will be encoded as such.
 110 .It Ic fqdn Op none | ptr | both
 111 none disables FQDN encoding, ptr just asks the DHCP server to update the PTR
 112 record of the host in DNS whereas both also updates the A record.
 113 .Nm dhcpcd
 114 itself never does any DNS updates.
 115 .Nm dhcpcd
 116 encodes the FQDN hostname as specified in
 117 .Li RFC1035 .
 118 .It Ic interface Ar interface
 119 Subsequent options are only parsed for this
 120 .Ar interface .
 121 .It Ic leasetime Ar seconds
 122 Request a leasetime of
 123 .Ar seconds .
 124 .It Ic metric Ar metric
 125 Metrics are used to prefer an interface over another one, lowest wins.
 126 .Nm dhcpcd
 127 will supply a default metic of 200 +
 128 .Xr if_nametoindex 3 .
 129 An extra 100 will be added for wireless interfaces.
 130 .It Ic noarp
 131 Don't send any ARP requests.
 132 This also disables IPv4LL.
 133 .It Ic nogateway
 134 Don't install any default routes.
 135 .It Ic nohook Ar script
 136 Don't run this hook script.
 137 Matches full name, or prefixed with 2 numbers optionally ending with
 138 .Pa .sh .
 139 .Pp
 140 So to stop
 141 .Nm dhcpcd
 142 from touching your DNS or MTU settings you would do:-
 143 .D1 nohook resolv.conf, mtu
 144 .It Ic noipv4ll
 145 Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP.
 146 See
 147 .Rs
 148 .%T "RFC 3927"
 149 .Re
 150 .It Ic nolink
 151 Don't receive link messages about carrier status.
 152 You should only set this for buggy interface drivers.
 153 .It Ic option Ar option
 154 Requests the
 155 .Ar option
 156 from the server.
 157 It can be a variable to be used in
 158 .Xr dhcpcd-run-hooks 8
 159 or the numerical value.
 160 You can specify more options seperated by commas, spaces or more option lines.
 161 .It Ic destination Ar option
 162 If
 163 .Nm
 164 detects an address added to a point to point interface (PPP, TUN, etc) then
 165 it will set the listed DHCP options to the destination address of the
 166 interface.
 167 .It Ic profile Ar name
 168 Subsequent options are only parsed for this profile
 169 .Ar name .
 170 .It Ic quiet
 171 Supress any dhcpcd output to the console, except for errors.
 172 .It Ic reboot Ar seconds
 173 Allow
 174 .Ar reboot
 175 seconds before moving to the discover phase if we have an old lease to use.
 176 The default is 10 seconds.
 177 A setting if 0 seconds causes
 178 .Nm dhcpcd
 179 to skip the reboot phase and go straight into discover.
 180 .It Ic release
 181 .Nm dhcpcd
 182 will release the lease prior to stopping the interface.
 183 .It Ic require Ar option
 184 Requires the
 185 .Ar option
 186 to be present in all DHCP messages, otherwise the message is ignored.
 187 It can be a variable to be used in
 188 .Xr dhcpcd-run-hooks 8
 189 or the numerical value.
 190 You can specify more options seperated by commas, spaces or more require lines.
 191 To enforce that
 192 .Nm dhcpcd
 193 only responds to DHCP servers and not BOOTP servers, you can
 194 .Ic require
 195 .Ar dhcp_message_type .
 196 .It Ic script Ar script
 197 Use
 198 .Ar script
 199 instead of the default
 200 .Pa @SCRIPT@ .
 201 .It Ic ssid Ar ssid
 202 Subsequent options are only parsed for this wireless
 203 .Ar ssid .
 204 .It Ic static Ar value
 205 Configures a static
 206 .Ar value .
 207 If you set
 208 .Ic ip_address
 209 then
 210 .Nm dhcpcd
 211 will not attempt to obtain a lease and just use the value for the address with
 212 an infinite lease time.
 213 .Pp
 214 Here is an example which configures a static address, routes and dns.
 215 .D1 interface eth0
 216 .D1 static ip_address=192.168.0.10/24
 217 .D1 static routers=192.168.0.1
 218 .D1 static domain_name_servers=192.168.0.1
 219 .Pp
 220 Here is an example for PPP which gives the destination a default route.
 221 It uses the special destination keyword to insert the destination address
 222 into the value.
 223 .D1 interface ppp0
 224 .D1 static ip_address=
 225 .D1 destination routers
 226 .It Ic timeout Ar seconds
 227 The default timeout for waiting for a DHCP response is 30 seconds which may
 228 be too long or too short and can be changed here.
 229 .It Ic userclass Ar string
 230 Tag the DHCP messages with the userclass.
 231 You can specify more than one.
 232 .It Ic vendor Ar code , Ns Ar value
 233 Add an enscapulated vendor option.
 234 .Ar code
 235 should be between 1 and 254 inclusive.
 236 Examples.
 237 .Pp
 238 Set the vendor option 01 with an IP address.
 239 .D1 vendor 01,192.168.0.2
 240 Set the vendor option 02 with a hex code.
 241 .D1 vendor 02,01:02:03:04:05
 242 Set the vendor option 03 with an IP address as a string.
 243 .D1 vendor 03,\e"192.168.0.2\e"
 244 .It Ic vendorclassid Ar string
 245 Change the default vendorclassid sent from dhcpcd-version.
 246 If not set then none is sent.
 247 .El
 248 .Sh SEE ALSO
 249 .Xr dhcpcd-run-hooks 8 ,
 250 .Xr dhcpcd 8 ,
 251 .Xr if_nametoindex 3 ,
 252 .Xr fnmatch 3
 253 .Sh AUTHORS
 254 .An Roy Marples Aq roy@marples.name
 255 .Sh BUGS
 256 Please report them to http://roy.marples.name/projects/dhcpcd