diff options
Diffstat (limited to 'dhcpcd/dhcpcd.conf.5.in')
| -rw-r--r-- | dhcpcd/dhcpcd.conf.5.in | 704 |
1 files changed, 704 insertions, 0 deletions
diff --git a/dhcpcd/dhcpcd.conf.5.in b/dhcpcd/dhcpcd.conf.5.in new file mode 100644 index 00000000..888b3c14 --- /dev/null +++ b/dhcpcd/dhcpcd.conf.5.in @@ -0,0 +1,704 @@ +.\" Copyright (c) 2006-2014 Roy Marples +.\" All rights reserved +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 29, 2014 +.Dt DHCPCD.CONF 5 +.Os +.Sh NAME +.Nm dhcpcd.conf +.Nd dhcpcd configuration file +.Sh DESCRIPTION +Although +.Nm dhcpcd +can do everything from the command line, there are cases where it's just easier +to do it once in a configuration file. +Most of the options found in +.Xr dhcpcd 8 +can be used here. +The first word on the line is the option and the rest of the line is the value. +Leading and trailing whitespace for the option and value are trimmed. +You can escape characters in the value using the \\ character. +.Pp +Blank lines and lines starting with # are ignored. +.Pp +Here's a list of available options: +.Bl -tag -width indent +.It Ic allowinterfaces Ar pattern +When discovering interfaces, the interface name must match +.Ar pattern +which is a space or comma separated list of patterns passed to +.Xr fnmatch 3 . +If the same interface is matched in +.Ic denyinterfaces +then it is still denied. +.It Ic denyinterfaces Ar pattern +When discovering interfaces, the interface name must not match +.Ar pattern +which is a space or comma separated list of patterns passed to +.Xr fnmatch 3 . +.It Ic arping Ar address Op address +.Nm dhcpcd +will arping each address in order before attempting DHCP. +If an address is found, we will select the replying hardware address as the +profile, otherwise the ip address. +Example: +.Pp +.D1 interface bge0 +.D1 arping 192.168.0.1 +.Pp +.D1 profile 192.168.0.1 +.D1 static ip_address=192.168.0.10/24 +.It Ic authprotocol Ar protocol Ar algorithm Ar rdm +Authenticate DHCP messages. +See the Supported Protocols section. +.It Ic authtoken Ar secretid Ar realm Ar expire Ar key +Define a shared key for use in authentication. +.Ar realm can be "" to for use with the +.Ar delayed +prptocol. +.Ar expire +is the date the token expires and should be formatted "yyy-mm-dd HH:MM". +You can use the keyword +.Ar forever +or +.Ar 0 +which means the token never expires. +.It Ic background +Background immediately. +This is useful for startup scripts which don't disable link messages for +carrier status. +.It Ic blacklist Ar address Ns Op /cidr +Ignores all packets from +.Ar address Ns Op /cidr . +.It Ic whitelist Ar address Ns Op /cidr +Only accept packets from +.Ar address Ns Op /cidr . +.Ic blacklist +is ignored if +.Ic whitelist +is set. +.It Ic broadcast +Instructs the DHCP server to broadcast replies back to the client. +Normally this is only set for non Ethernet interfaces, +such as FireWire and InfiniBand. +In most cases, +.Nm dhcpcd +will set this automatically. +.It Ic dev Ar value +Load the +.Ar value +.Pa /dev +management module. +.Nm dhcpcd +will load the first one found to work, if any. +.It Ic env Ar value +Push +.Ar value +to the environment for use in +.Xr dhcpcd-run-hooks 8 . +For example, you can force the hostname hook to always set the hostname with +.Ic env +.Va force_hostname=YES . +.Pp +If the hostname is set, will be will set to the FQDN if possible as per +RFC 4702 section 3.1. +If the FQDN option is missing, +.Nm dhcpcd +will still try and set a FQDN from the hostname and domain options for +consistency. +To override this, set +.Ic env +.Va hostname_fqdn=[YES|NO|SERVER] . +A value of server means just what the server says, don't manipulate it. +This could lead to an inconsistent hostname on a DHCPv4 and DHCPv6 network +where the DHCPv4 hostname is short and the DHCPv6 has an FQDN. +DHCPv6 has no hostname option. +.It Ic clientid Ar string +Send the +.Ar clientid . +If the string is of the format 01:02:03 then it is encoded as hex. +For interfaces whose hardware address is longer than 8 bytes, or if the +.Ar clientid +is an empty string then +.Nm dhcpcd +sends a default +.Ar clientid +of the hardware family and the hardware address. +.It Ic duid +Generate an +.Rs +.%T "RFC 4361" +.Re +compliant DHCP Unique Identifier. +If persistent storage is available then a DUID-LLT (link local address + time) +is generated, otherwise DUID-LL is generated (link local address). +This, plus the IAID will be used as the +.Ic clientid . +The DUID-LLT generated will be held in +.Pa @SYSCONFDIR@/dhcpcd.duid +and should not be copied to other hosts. +.It Ic iaid Ar iaid +Set the Interface Association Identifier to +.Ar iaid . +This option must be used in an +.Ic interface +block. +This defaults to the last 4 bytes of the hardware address assigned to the +interface. +Each instance of this should be unique within the scope of the client and +.Nm dhcpcd +warns if a conflict is detected. +If there is a conflict, it is only a problem if the conflicted IAIDs are +used on the same network. +.It Ic persistent +.Nm dhcpcd +normally de-configures the interface and configuration when it exits. +Sometimes, this isn't desirable if, for example, you have root mounted over +NFS or SSH clients connect to this host and they need to be notified of +the host shutting down. +You can use this option to stop this from happening. +.It Ic fallback Ar profile +Fallback to using this profile if DHCP fails. +This allows you to configure a static profile instead of using ZeroConf. +.It Ic hostname Ar name +Sends +.Ar hostname +to the DHCP server so it can be registered in DNS. +If +.Ar hostname +is an empty string then the current system hostname is sent. +If +.Ar hostname +is a FQDN (ie, contains a .) then it will be encoded as such. +.It Ic hostname_short +Sends the short hostname to the DHCP server instead of the FQDN. +This is useful because DHCP servers will not register the FQDN in their +DNS if the domain part does not match theirs. +.Pp +Also, see the +.Ic env +option above to control how the hostname is set on the host. +.It Ic ia_na Op Ar iaid +Request a DHCPv6 Normal Address for +.Ar iaid . +.Ar iaid +defaults to the +.Ic iaid +option as described above. +You can request more than one ia_na by specifying a unique +.Ar iaid +for each one. +.It Ic ia_ta Op Ar iaid +Request a DHCPv6 Temporary Address for +.Ar iaid . +You can request more than one ia_ta by specifying a unique +.Ar iaid +for each one. +.It Ic ia_pd Op Ar iaid Op Ar interface Op / Ar sla_id Op / Ar prefix_len +Request a DHCPv6 Delegated Prefix for +.Ar iaid . +This option must be used in an +.Ic interface +block. +If no +.Ar interface +is given then we will assign a prefix to every other interface with a unique +.Ar sla_id +for each, starting from 0. +Otherwise addresses are only assigned for each +.Ar interface +and +.Ar sla_id . +You cannot assign a prefix to the requesting interface. +.Nm dhcpcd +has to be running for all the interfaces it is delegating to. +A default +.Ar prefix_len +of 64 is assumed. +.Ar sla_id +is an integer and is added to the prefix which must fit inside +.Ar prefix_len +less the length of the delegated prefix. +You can specify multiple +.Ar interface / +.Ar sla_id / +.Ar prefix_len +per +.Ic ia_pd , +space separated. +IPv6RS should be disabled globally when requesting a Prefix Delegation like so: +.Pp +.D1 noipv6rs +.D1 # Don't touch eth3 at all +.D1 denyinterfaces eth3 +.Pp +.D1 interface eth0 +.D1 ia_pd 1 eth1/0 eth2/1 +.Pp +.D1 # Disable automatic address configuration for eth1 +.D1 # eth1 still gets a delegated prefix +.D1 interface eth1 +.D1 noipv4 +.D1 noipv6 +.It Ic ipv4only +Only configure IPv4. +.It Ic ipv6only +Only confgiure IPv6. +.It Ic fqdn Op disable | ptr | both +ptr just asks the DHCP server to update the PTR +record of the host in DNS whereas both also updates the A record. +disable will disable the FQDN option. +The default is both. +.Nm dhcpcd +itself never does any DNS updates. +.Nm dhcpcd +encodes the FQDN hostname as specified in +.Li RFC1035 . +.It Ic interface Ar interface +Subsequent options are only parsed for this +.Ar interface . +.It Ic ipv6ra_fork +By default, when +.Nm dhcpcd +receives an IPv6 RA, +.Nm dhcpcd +will only fork to the background if the RA contains at least one unexpired +RDNSS option. +Set this option so to make +.Nm dhcpcd +always fork on an RA. +.It Ic ipv6ra_own +Disables kernel IPv6 Router Advertisment processing so dhcpcd can manage +addresses and routes. +This does not work reliably on any BSD system, probably due to kernel issues. +.It Ic ipv6ra_own_default +Each time dhcpcd receives an IPv6 Router Adveristment, dhcpcd will manage +the default route only. +This allows dhcpcd to prefer an interface for outbound traffic based on metric +and/or user selection rather than the kernel. +This does work reliably on BSD systems. +.It Ic ipv6rs +Enables IPv6 Router Advertisment solicitation. +This is on by default, but is documented here in the case where it is disabled +globally but needs to be enabled for one interface. +.It Ic leasetime Ar seconds +Request a leasetime of +.Ar seconds . +.It Ic metric Ar metric +Metrics are used to prefer an interface over another one, lowest wins. +.Nm dhcpcd +will supply a default metric of 200 + +.Xr if_nametoindex 3 . +An extra 100 will be added for wireless interfaces. +.It Ic noalias +IPv4 addresses added will overwrite a pre-existing address instead of working +alongside. +.It Ic noarp +Don't send any ARP requests. +This also disables IPv4LL. +.It Ic noauthrequired +Don't require authentication even though we requested it. +.It Ic nodev +Don't load +.Pa /dev +management modules. +.It Ic nodhcp +Don't start DHCP or listen to DHCP messages. +This is only useful when allowing IPv4LL. +.It Ic nodhcp6 +Don't start DHCPv6 or listen to DHCPv6 messages. +Normally DHCPv6 is started by a RA instruction or configuration. +.It Ic nogateway +Don't install any default routes. +.It Ic nohook Ar script +Don't run this hook script. +Matches full name, or prefixed with 2 numbers optionally ending with +.Pa .sh . +.Pp +So to stop +.Nm dhcpcd +from touching your DNS or MTU settings you would do:- +.D1 nohook resolv.conf, mtu +.It Ic noipv4 +Don't attempt to configure an IPv4 address. +.It Ic noipv4ll +Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP. +See +.Rs +.%T "RFC 3927" +.Re +.It Ic noipv6 +Don't attmept to configure an IPv6 address. +.It Ic noipv6rs +Disable solicitation and receipt of IPv6 Router Advertisements. +.It Ic nolink +Don't receive link messages about carrier status. +You should only set this for buggy interface drivers. +.It Ic option Ar option +Requests the +.Ar option +from the server. +It can be a variable to be used in +.Xr dhcpcd-run-hooks 8 +or the numerical value. +You can specify more +.Ar option Ns s +separated by commas, spaces or more +.Ic option +lines. +Prepend dhcp6_ to +.Ar option +to request a DHCPv6 option. +DHCPv4 options are mapped to DHCPv6 where applicable. +.It Ic nooption Ar option +Remove the option from the DHCP message. +This should only be used when a DHCP server sends a non requested option +that should not be processed. +.It Ic destination Ar option +If +.Nm +detects an address added to a point to point interface (PPP, TUN, etc) then +it will set the listed DHCP options to the destination address of the +interface. +.It Ic profile Ar name +Subsequent options are only parsed for this profile +.Ar name . +.It Ic quiet +Suppress any dhcpcd output to the console, except for errors. +.It Ic reboot Ar seconds +Allow +.Ar reboot +seconds before moving to the DISCOVER phase if we have an old lease to use. +The default is 5 seconds. +A setting of 0 seconds causes +.Nm dhcpcd +to skip the REBOOT phase and go straight into DISCOVER. +This is desirable for mobile users because if you change from network A to +network B and they use the same subnet and the address from network A isn't +in use on network B, then the DHCP server will remain silent even if authorative +which means +.Nm dhcpcd +will timeout before moving back to the DISCOVER phase. +.It Ic release +.Nm dhcpcd +will release the lease prior to stopping the interface. +.It Ic require Ar option +Requires the +.Ar option +to be present in all DHCP messages, otherwise the message is ignored. +It can be a variable to be used in +.Xr dhcpcd-run-hooks 8 +or the numerical value. +You can specify more options separated by commas, spaces or more require lines. +To enforce that +.Nm dhcpcd +only responds to DHCP servers and not BOOTP servers, you can +.Ic require +.Ar dhcp_message_type . +.It Ic script Ar script +Use +.Ar script +instead of the default +.Pa @SCRIPT@ . +.It Ic ssid Ar ssid +Subsequent options are only parsed for this wireless +.Ar ssid . +.It Ic static Ar value +Configures a static +.Ar value . +If you set +.Ic ip_address +then +.Nm dhcpcd +will not attempt to obtain a lease and just use the value for the address with +an infinite lease time. +.Pp +Here is an example which configures a static address, routes and dns. +.D1 interface eth0 +.D1 static ip_address=192.168.0.10/24 +.D1 static routers=192.168.0.1 +.D1 static domain_name_servers=192.168.0.1 +.Pp +Here is an example for PPP which gives the destination a default route. +It uses the special destination keyword to insert the destination address +into the value. +.D1 interface ppp0 +.D1 static ip_address= +.D1 destination routers +.It Ic timeout Ar seconds +Timeout after +.Ar seconds , +instead of the default 30. +A setting of 0 +.Ar seconds +causes +.Nm dhcpcd +to wait forever to get a lease. +If +.Nm dhcpcd +is working on a single interface then +.Nm dhcpcd +will exit when a timeout occurs, otherwise +.Nm dhcpcd +will fork into the background. +If using IPv4LL then +.Nm dhcpcd +start the IPv4LL process after the timeout and then wait a little longer +before really timing out. +.It Ic userclass Ar string +Tag the DHCPv4 messages with the userclass. +You can specify more than one. +.It Ic vendor Ar code , Ns Ar value +Add an encapsulated vendor option. +.Ar code +should be between 1 and 254 inclusive. +To add a raw vendor string, omit +.Ar code +but keep the comma. +Examples. +.Pp +Set the vendor option 01 with an IP address. +.D1 vendor 01,192.168.0.2 +Set the vendor option 02 with a hex code. +.D1 vendor 02,01:02:03:04:05 +Set the vendor option 03 with an IP address as a string. +.D1 vendor 03,\e"192.168.0.2\e" +Set un-encapsulated vendor option to hello world. +.D1 vendor ,"hello world" +.It Ic vendorclassid Ar string +Set the DHCP Vendor Class. +DHCPv6 has it's own option as shown below. +The default is +dhcpcd-<version>:<os>:<machine>:<platform>. +For example +.D1 dhcpcd-5.5.6:NetBSD-6.99.5:i386:i386 +If not set then none is sent. +Some badly configured DHCP servers reject unknown vendorclassids. +To work around it, try and impersonate Windows by using the MSFT vendorclassid. +.It Ic vendclass Ar en Ar data +Add the DHCPv6 Vendor Indetifying Vendor Class with the IANA assigned Enterprise +Number +.Ar en +with the +.Ar data . +This option can be set more than once to add more data, but the behaviour, +as per +.Xr RFC 3925 +is undefined if the Enterprise Number differs. +.It Ic waitip Op 4 | 6 +Wait for an address to be assigned before forking to the background. +4 means wait for an IPv4 address to be assigned. +6 means wait for an IPv6 address to be assigned. +If no argument is given, +.Nm +will wait for any address protocol to be assigned. +It is possible to wait for more than one address protocol and +.Nm +will only fork to the background when all waiting conditions are satisfied. +.It Ic xidhwaddr +Use the last four bytes of the hardware address as the DHCP xid instead +of a randomly generated number. +.El +.Ss Defining new options +DHCP allows for the use of custom options. +Each option needs to be started with the +.Ic define +or +.Ic define6 +directive. +This can optionally be followed by both +.Ic embed +or +.Ic encap +options. +Both can be specified more than once and +.Ic embed +must come before +.Ic encap . +.Bl -tag -width indent +.It Ic define Ar code Ar type Ar variable +Defines the DHCP option +.Ar code +of +.Ar type +with a name of +.Ar variable +exported to +.Xr dhcpcd-run-hooks 8 . +.It Ic define6 Ar code Ar type Ar variable +Defines the DHCPv6 option +.Ar code +of +.Ar type +with a name of +.Ar variable +exported to +.Xr dhcpcd-run-hooks 8 , +with a prefix of +.Va _dhcp6 . +.It Ic vendopt Ar code Ar type Ar variable +Defines the Vendor-Identifying Vendor Options. +The +.Ar code +is the IANA Enterprise Number which will unqiuely describe the encapsulated +options. +.Ar type +is normally +.Ar encap . +.Ar variable +names the Vendor option to be exported. +.It Ic embed Ar type Ar variable +Defines an embedded variable within the defined option. +The length is determined by the +.Ar type . +If the +.Ar variable +is not the same as defined in the parent option, +it is prefixed with the parent +.Ar variable +first with an underscore. +.It Ic encap Ar code Ar type Ar variable +Defines an encapsulated variable within the defined option. +The length is determined by the +.Ar type . +If the +.Ar variable +is not the same as defined in the parent option, +it is prefixed with the parent +.Ar variable +first with an underscore. +.El +.Ss Type prefix +These keywords come before the type itself, to describe it more fully. +You can use more than one, but they must appear in the order listed below. +.Bl -tag -width -indent +.It Ic request +Requests the option by default without having to be specified in user +configuration +.It Ic norequest +This option cannot be requested, regardless of user configuration +.It Ic index +The option can appear more than once and will be indexed. +.It Ic array +The option data is split into a space seperated array, each element being +the same type. +.El +.Ss Types to define +The type directly affects the length of data consumed inside the option. +Any remaining data is normally discarded. +Lengths can be specified for string and binhex types, but this is generally +with other data embedded afterwards in the same option. +.Bl -tag -width indent +.It Ic ipaddress +An IPv4 address, 4 bytes +.It Ic ip6address +An IPv6 address, 16 bytes +.It Ic string Op : Ic length +A shell escaped string (binary data escaped as octal) +.It Ic byte +A byte +.It Ic int16 +A signed 16bit integer, 2 bytes +.It Ic uint16 +An unsigned 16bit integer, 2 bytes +.It Ic int32 +A signed 32bit integer, 4 bytes +.It Ic uint32 +An unsigned 32bit integer, 4 bytes +.It Ic flag +A fixed value (1) to indicate that the option is present, 0 bytes +.It Ic domain +A RFC 3397 encoded string +.It Ic binhex Op : Ic length +Binary data expressed as hexadecimal +.It Ic embed +Contains embedded options (implies encap as well) +.It Ic encap +Contains encapsulated options (implies embed as well) +.It Ic option +References an option from the global definition +.El +.Ss Example definition +.D1 # DHCP option 81, Fully Qualified Domain Name, RFC4702 +.D1 define 81 embed fqdn +.D1 embed byte flags +.D1 embed byte rcode1 +.D1 embed byte rcode2 +.D1 embed domain fqdn +.Pp +.D1 # DHCP option 125, Vendor Specific Information Option, RFC3925 +.D1 define 125 encap vsio +.D1 embed uint32 enterprise_number +.D1 # Options defined for the enterprise number +.D1 encap 1 ipaddress ipaddress +.Ss Supported protocols +.Bl -tag -width -indent +.It Ic token +Sends and expects the token with the secretid 0 in each message. +.It Ic delayedrealm +Delayed Authentication. +.Nm dhcpcd +will send an authentication option with no key or MAC. +The server will see this option, and select a key for +.Nm , writing the +.Ar realm +and +.Ar secretid +in it. +.Nm dhcpcd +will then look for a non-expired token with a matching realm and secretid. +This token is used to authenicate all other messages. +.It Ic delayed +Same as above, but without a realm. +.El +.Ss Supported algorithms +If none specified, +.Ic hmac-md5 +is the default. +.Bl -tag -width -indent +.It Ic hmac-md5 +.El +.Ss Supported Replay Detection Mechanisms +If none specified, +.Ic monotonic +is the default. +.Bl -tag -width -indent +.It Ic monotonic +.El +.Sh SEE ALSO +.Xr fnmatch 3 , +.Xr if_nametoindex 3 , +.Xr dhcpcd 8 , +.Xr dhcpcd-run-hooks 8 +.Sh AUTHORS +.An Roy Marples Aq Mt roy@marples.name +.Sh BUGS +When configuring DHCPv6 you can only select one IA type. +I can't think of a use case where you would want different types, +so if you have one then please bring it up for discussion on the +.Aq Mt dhcpcd-discuss@marples.name +mailing list. +.Pp +Please report them to +.Lk http://roy.marples.name/projects/dhcpcd |