[thirdparty/dhcpcd.git] / dhcpcd.conf.5.in

.\" Copyright (c) 2006-2009 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 September 1, 2009
.Dt DHCPCD.CONF 5 SMM
.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 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 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 .
.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 clientid.
This requires persistent storage and not all DHCP servers work with it so it's
not enabled by default.
The duid generated will be held in
.Pa @SYSCONFDIR@/dhcpcd.duid
and should not be copied to other hosts.
.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 fqdn Op none | ptr | both
none disables FQDN encoding, ptr just asks the DHCP server to update the PTR
record of the host in DNS whereas both also updates the A record.
.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 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 metic of 200 +
.Xr if_nametoindex 3 .
An extra 100 will be added for wireless interfaces.
.It Ic noarp
Don't send any ARP requests.
This also disables IPv4LL.
.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 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 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 options seperated by commas, spaces or more option lines.
.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
Supress 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 10 seconds.
A setting if 0 seconds causes
.Nm dhcpcd
to skip the reboot phase and go straight into discover.
.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 seperated 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
The default timeout for waiting for a DHCP response is 30 seconds which may
be too long or too short and can be changed here.
.It Ic userclass Ar string
Tag the DHCP messages with the userclass.
You can specify more than one.
.It Ic vendor Ar code , Ns Ar value
Add an enscapulated 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-encapulated vendor option to hello world.
.D1 vendor ,\e"hello world\e"
.It Ic vendorclassid Ar string
Change the default vendorclassid sent from dhcpcd-version.
If not set then none is sent.
.El
.Sh SEE ALSO
.Xr dhcpcd-run-hooks 8 ,
.Xr dhcpcd 8 ,
.Xr if_nametoindex 3 ,
.Xr fnmatch 3
.Sh AUTHORS
.An Roy Marples Aq roy@marples.name
.Sh BUGS
Please report them to http://roy.marples.name/projects/dhcpcd
Commit	Line	Data
601fb3d5	1	.\" Copyright (c) 2006-2009 Roy Marples
ba9dfb7a RM	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	.\"
95d6dcfa	25	.Dd September 1, 2009
ba9dfb7a	26	.Dt DHCPCD.CONF 5 SMM
918338f2	27	.Os
ba9dfb7a RM	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
cf42802e RM	35	to do it once in a configuration file.
cf42802e RM	36	Most of the options found in
ba9dfb7a	37	.Xr dhcpcd 8
cf42802e RM	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.
967194ef RM	42	.Pp
967194ef RM	43	Blank lines and lines starting with # are ignored.
ba9dfb7a RM	44	.Pp
	45	Here's a list of available options:
	46	.Bl -tag -width indent
ba97e494 RM	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 .
6f767217 RM	60	.It Ic arping Ar address Op address
6f767217 RM	61	.Nm dhcpcd
ff021b0b	62	will arping each address in order before attempting DHCP.
6f767217 RM	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
bac03ede RM	72	.It Ic background
	73	Background immediately.
	74	This is useful for startup scripts which don't disable link messages for
	75	carrier status.
6f767217	76	.It Ic blacklist Ar address Ns Op /cidr
ce6b39df	77	Ignores all packets from
6f767217	78	.Ar address Ns Op /cidr .
bf80d526 RM	79	.It Ic whitelist Ar address Ns Op /cidr
	80	Only accept packets from
	81	.Ar address Ns Op /cidr .
	82	.Ic blacklist
	83	is ignored if
	84	.Ic whitelist
	85	is set.
6bfd88f1 RM	86	.It Ic env Ar value
	87	Push
	88	.Ar value
	89	to the environment for use in
	90	.Xr dhcpcd-run-hooks 8 .
	91	For example, you can force the hostname hook to always set the hostname with
	92	.Ic env
	93	.Va force_hostname=YES .
d2616b08	94	.It Ic clientid Ar string
c989b023 RM	95	Send the
c989b023 RM	96	.Ar clientid .
d2616b08	97	If the string is of the format 01:02:03 then it is encoded as hex.
3faba9e6 RM	98	For interfaces whose hardware address is longer than 8 bytes, or if the
	99	.Ar clientid
	100	is an empty string then
	101	.Nm dhcpcd
	102	sends a default
	103	.Ar clientid
	104	of the hardware family and the hardware address.
d2616b08 RM	105	.It Ic duid
	106	Generate an
	107	.Rs
	108	.%T "RFC 4361"
	109	.Re
cf42802e RM	110	compliant clientid.
	111	This requires persistent storage and not all DHCP servers work with it so it's
	112	not enabled by default.
d2616b08 RM	113	The duid generated will be held in
	114	.Pa @SYSCONFDIR@/dhcpcd.duid
	115	and should not be copied to other hosts.
ff021b0b RM	116	.It Ic fallback Ar profile
	117	Fallback to using this profile if DHCP fails.
	118	This allows you to configure a static profile instead of using ZeroConf.
ba9dfb7a	119	.It Ic hostname Ar name
35d02ae6	120	Sends
ff021b0b	121	.Ar hostname
35d02ae6 RM	122	to the DHCP server so it can be registered in DNS.
35d02ae6 RM	123	If
35ff0dbb	124	.Ar hostname
35d02ae6 RM	125	is an empty string then the current system hostname is sent.
	126	If
	127	.Ar hostname
	128	is a FQDN (ie, contains a .) then it will be encoded as such.
35ff0dbb RM	129	.It Ic fqdn Op none \| ptr \| both
	130	none disables FQDN encoding, ptr just asks the DHCP server to update the PTR
	131	record of the host in DNS whereas both also updates the A record.
1b3bc477 RM	132	.Nm dhcpcd
1b3bc477 RM	133	itself never does any DNS updates.
e837a670 RM	134	.Nm dhcpcd
	135	encodes the FQDN hostname as specified in
	136	.Li RFC1035 .
3adc5520	137	.It Ic interface Ar interface
012fd5d3 RM	138	Subsequent options are only parsed for this
012fd5d3 RM	139	.Ar interface .
ba9dfb7a RM	140	.It Ic leasetime Ar seconds
	141	Request a leasetime of
	142	.Ar seconds .
065125d4 RM	143	.It Ic metric Ar metric
	144	Metrics are used to prefer an interface over another one, lowest wins.
	145	.Nm dhcpcd
	146	will supply a default metic of 200 +
	147	.Xr if_nametoindex 3 .
	148	An extra 100 will be added for wireless interfaces.
ba9dfb7a	149	.It Ic noarp
cf42802e RM	150	Don't send any ARP requests.
cf42802e RM	151	This also disables IPv4LL.
ba9dfb7a RM	152	.It Ic nogateway
ba9dfb7a RM	153	Don't install any default routes.
37156a6b RM	154	.It Ic nohook Ar script
37156a6b RM	155	Don't run this hook script.
8276da82 RM	156	Matches full name, or prefixed with 2 numbers optionally ending with
8276da82 RM	157	.Pa .sh .
fc7ee231 RM	158	.Pp
	159	So to stop
	160	.Nm dhcpcd
	161	from touching your DNS or MTU settings you would do:-
	162	.D1 nohook resolv.conf, mtu
ba9dfb7a RM	163	.It Ic noipv4ll
	164	Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP.
	165	See
	166	.Rs
	167	.%T "RFC 3927"
	168	.Re
a26af491 RM	169	.It Ic nolink
	170	Don't receive link messages about carrier status.
	171	You should only set this for buggy interface drivers.
cc45fbd7	172	.It Ic option Ar option
d2616b08	173	Requests the
cc45fbd7	174	.Ar option
cf42802e RM	175	from the server.
cf42802e RM	176	It can be a variable to be used in
ee4e620a	177	.Xr dhcpcd-run-hooks 8
cf42802e	178	or the numerical value.
cc45fbd7	179	You can specify more options seperated by commas, spaces or more option lines.
2063c6f9 RM	180	.It Ic nooption Ar option
	181	Remove the option from the DHCP message.
	182	This should only be used when a DHCP server sends a non requested option
	183	that should not be processed.
1abffd5b RM	184	.It Ic destination Ar option
	185	If
	186	.Nm
	187	detects an address added to a point to point interface (PPP, TUN, etc) then
	188	it will set the listed DHCP options to the destination address of the
	189	interface.
6f767217 RM	190	.It Ic profile Ar name
	191	Subsequent options are only parsed for this profile
	192	.Ar name .
1abffd5b	193	.It Ic quiet
f19b6499	194	Supress any dhcpcd output to the console, except for errors.
1abffd5b	195	.It Ic reboot Ar seconds
a2a9a498 RM	196	Allow
	197	.Ar reboot
	198	seconds before moving to the discover phase if we have an old lease to use.
	199	The default is 10 seconds.
	200	A setting if 0 seconds causes
	201	.Nm dhcpcd
	202	to skip the reboot phase and go straight into discover.
2662d519 RM	203	.It Ic release
	204	.Nm dhcpcd
	205	will release the lease prior to stopping the interface.
cc45fbd7 RM	206	.It Ic require Ar option
	207	Requires the
	208	.Ar option
	209	to be present in all DHCP messages, otherwise the message is ignored.
	210	It can be a variable to be used in
	211	.Xr dhcpcd-run-hooks 8
	212	or the numerical value.
	213	You can specify more options seperated by commas, spaces or more require lines.
02d339e3 RM	214	To enforce that
	215	.Nm dhcpcd
	216	only responds to DHCP servers and not BOOTP servers, you can
	217	.Ic require
	218	.Ar dhcp_message_type .
0aeb350c RM	219	.It Ic script Ar script
	220	Use
	221	.Ar script
	222	instead of the default
	223	.Pa @SCRIPT@ .
c53cf4ef RM	224	.It Ic ssid Ar ssid
	225	Subsequent options are only parsed for this wireless
	226	.Ar ssid .
91a44b91 RM	227	.It Ic static Ar value
	228	Configures a static
	229	.Ar value .
	230	If you set
	231	.Ic ip_address
	232	then
	233	.Nm dhcpcd
	234	will not attempt to obtain a lease and just use the value for the address with
	235	an infinite lease time.
	236	.Pp
	237	Here is an example which configures a static address, routes and dns.
	238	.D1 interface eth0
	239	.D1 static ip_address=192.168.0.10/24
	240	.D1 static routers=192.168.0.1
	241	.D1 static domain_name_servers=192.168.0.1
1abffd5b RM	242	.Pp
	243	Here is an example for PPP which gives the destination a default route.
	244	It uses the special destination keyword to insert the destination address
	245	into the value.
	246	.D1 interface ppp0
	247	.D1 static ip_address=
	248	.D1 destination routers
d2616b08	249	.It Ic timeout Ar seconds
fedb3da0	250	The default timeout for waiting for a DHCP response is 30 seconds which may
d2616b08 RM	251	be too long or too short and can be changed here.
d2616b08 RM	252	.It Ic userclass Ar string
cf42802e RM	253	Tag the DHCP messages with the userclass.
cf42802e RM	254	You can specify more than one.
bac03ede	255	.It Ic vendor Ar code , Ns Ar value
757520c5 RM	256	Add an enscapulated vendor option.
	257	.Ar code
	258	should be between 1 and 254 inclusive.
95d6dcfa RM	259	To add a raw vendor string, omit
	260	.Ar code
	261	but keep the comma.
757520c5 RM	262	Examples.
	263	.Pp
	264	Set the vendor option 01 with an IP address.
	265	.D1 vendor 01,192.168.0.2
	266	Set the vendor option 02 with a hex code.
	267	.D1 vendor 02,01:02:03:04:05
	268	Set the vendor option 03 with an IP address as a string.
	269	.D1 vendor 03,\e"192.168.0.2\e"
95d6dcfa RM	270	Set un-encapulated vendor option to hello world.
95d6dcfa RM	271	.D1 vendor ,\e"hello world\e"
bac03ede RM	272	.It Ic vendorclassid Ar string
	273	Change the default vendorclassid sent from dhcpcd-version.
	274	If not set then none is sent.
eaa90296	275	.El
ba9dfb7a	276	.Sh SEE ALSO
ee4e620a	277	.Xr dhcpcd-run-hooks 8 ,
ba97e494	278	.Xr dhcpcd 8 ,
065125d4	279	.Xr if_nametoindex 3 ,
ba97e494	280	.Xr fnmatch 3
ba9dfb7a	281	.Sh AUTHORS
760f7628	282	.An Roy Marples Aq roy@marples.name
ba9dfb7a	283	.Sh BUGS
56d212f2	284	Please report them to http://roy.marples.name/projects/dhcpcd