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

.\" Copyright 2006-2008 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 November 17, 2008
.Dt DHCPCD.CONF 5 SMM
.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 background
Background immediately.
This is useful for startup scripts which don't disable link messages for
carrier status.
.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 we send a default
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 hostname Ar name
Sends specified
.Ar hostname 
to the DHCP server so it can be registered in DNS. If
.Ar hostname
if 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.
The current hostname or the hostname specified using the
.Ic hostname
option must be a FQDN.
.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 .
.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.
.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.
.It Ic script Ar script
Use
.Ar script
instead of the default
.Pa @SCRIPT@ .
.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.
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"
.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 <roy@marples.name>
.Sh BUGS
Please report them to http://roy.marples.name/projects/dhcpcd
Commit	Line	Data
ba9dfb7a RM	1	.\" Copyright 2006-2008 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	.\"
c989b023	25	.Dd November 17, 2008
ba9dfb7a RM	26	.Dt DHCPCD.CONF 5 SMM
	27	.Sh NAME
	28	.Nm dhcpcd.conf
	29	.Nd dhcpcd configuration file
	30	.Sh DESCRIPTION
	31	Although
	32	.Nm dhcpcd
	33	can do everything from the command line, there are cases where it's just easier
cf42802e RM	34	to do it once in a configuration file.
cf42802e RM	35	Most of the options found in
ba9dfb7a	36	.Xr dhcpcd 8
cf42802e RM	37	can be used here.
	38	The first word on the line is the option and the rest of the line is the value.
	39	Leading and trailing whitespace for the option and value are trimmed.
	40	You can escape characters in the value using the \\ character.
967194ef RM	41	.Pp
967194ef RM	42	Blank lines and lines starting with # are ignored.
ba9dfb7a RM	43	.Pp
	44	Here's a list of available options:
	45	.Bl -tag -width indent
ba97e494 RM	46	.It Ic allowinterfaces Ar pattern
	47	When discovering interfaces, the interface name must match
	48	.Ar pattern
	49	which is a space or comma separated list of patterns passed to
	50	.Xr fnmatch 3 .
	51	If the same interface is matched in
	52	.Ic denyinterfaces
	53	then it is still denied.
	54	.It Ic denyinterfaces Ar pattern
	55	When discovering interfaces, the interface name must not match
	56	.Ar pattern
	57	which is a space or comma separated list of patterns passed to
	58	.Xr fnmatch 3 .
bac03ede RM	59	.It Ic background
	60	Background immediately.
	61	This is useful for startup scripts which don't disable link messages for
	62	carrier status.
d2616b08	63	.It Ic clientid Ar string
c989b023 RM	64	Send the
c989b023 RM	65	.Ar clientid .
d2616b08	66	If the string is of the format 01:02:03 then it is encoded as hex.
c989b023 RM	67	For interfaces whose hardware address is longer than 8 bytes we send a default
c989b023 RM	68	clientid of the hardware family and the hardware address.
d2616b08 RM	69	.It Ic duid
	70	Generate an
	71	.Rs
	72	.%T "RFC 4361"
	73	.Re
cf42802e RM	74	compliant clientid.
	75	This requires persistent storage and not all DHCP servers work with it so it's
	76	not enabled by default.
d2616b08 RM	77	The duid generated will be held in
	78	.Pa @SYSCONFDIR@/dhcpcd.duid
	79	and should not be copied to other hosts.
ba9dfb7a	80	.It Ic hostname Ar name
35ff0dbb RM	81	Sends specified
35ff0dbb RM	82	.Ar hostname
d2616b08	83	to the DHCP server so it can be registered in DNS. If
35ff0dbb	84	.Ar hostname
d2616b08	85	if a FQDN (ie, contains a .) then it will be encoded as such.
35ff0dbb RM	86	.It Ic fqdn Op none \| ptr \| both
	87	none disables FQDN encoding, ptr just asks the DHCP server to update the PTR
	88	record of the host in DNS whereas both also updates the A record.
1b3bc477	89	The current hostname or the hostname specified using the
a26af491	90	.Ic hostname
1b3bc477 RM	91	option must be a FQDN.
	92	.Nm dhcpcd
	93	itself never does any DNS updates.
e837a670 RM	94	.Nm dhcpcd
	95	encodes the FQDN hostname as specified in
	96	.Li RFC1035 .
3adc5520	97	.It Ic interface Ar interface
012fd5d3 RM	98	Subsequent options are only parsed for this
012fd5d3 RM	99	.Ar interface .
ba9dfb7a RM	100	.It Ic leasetime Ar seconds
	101	Request a leasetime of
	102	.Ar seconds .
065125d4 RM	103	.It Ic metric Ar metric
	104	Metrics are used to prefer an interface over another one, lowest wins.
	105	.Nm dhcpcd
	106	will supply a default metic of 200 +
	107	.Xr if_nametoindex 3 .
	108	An extra 100 will be added for wireless interfaces.
ba9dfb7a	109	.It Ic noarp
cf42802e RM	110	Don't send any ARP requests.
cf42802e RM	111	This also disables IPv4LL.
ba9dfb7a RM	112	.It Ic nogateway
ba9dfb7a RM	113	Don't install any default routes.
37156a6b RM	114	.It Ic nohook Ar script
37156a6b RM	115	Don't run this hook script.
8276da82 RM	116	Matches full name, or prefixed with 2 numbers optionally ending with
8276da82 RM	117	.Pa .sh .
ba9dfb7a RM	118	.It Ic noipv4ll
	119	Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP.
	120	See
	121	.Rs
	122	.%T "RFC 3927"
	123	.Re
a26af491 RM	124	.It Ic nolink
	125	Don't receive link messages about carrier status.
	126	You should only set this for buggy interface drivers.
cc45fbd7	127	.It Ic option Ar option
d2616b08	128	Requests the
cc45fbd7	129	.Ar option
cf42802e RM	130	from the server.
cf42802e RM	131	It can be a variable to be used in
ee4e620a	132	.Xr dhcpcd-run-hooks 8
cf42802e	133	or the numerical value.
cc45fbd7	134	You can specify more options seperated by commas, spaces or more option lines.
a2a9a498 RM	135	.Ic reboot Ar seconds
	136	Allow
	137	.Ar reboot
	138	seconds before moving to the discover phase if we have an old lease to use.
	139	The default is 10 seconds.
	140	A setting if 0 seconds causes
	141	.Nm dhcpcd
	142	to skip the reboot phase and go straight into discover.
2662d519 RM	143	.It Ic release
	144	.Nm dhcpcd
	145	will release the lease prior to stopping the interface.
cc45fbd7 RM	146	.It Ic require Ar option
	147	Requires the
	148	.Ar option
	149	to be present in all DHCP messages, otherwise the message is ignored.
	150	It can be a variable to be used in
	151	.Xr dhcpcd-run-hooks 8
	152	or the numerical value.
	153	You can specify more options seperated by commas, spaces or more require lines.
0aeb350c RM	154	.It Ic script Ar script
	155	Use
	156	.Ar script
	157	instead of the default
	158	.Pa @SCRIPT@ .
d2616b08	159	.It Ic timeout Ar seconds
fedb3da0	160	The default timeout for waiting for a DHCP response is 30 seconds which may
d2616b08 RM	161	be too long or too short and can be changed here.
d2616b08 RM	162	.It Ic userclass Ar string
cf42802e RM	163	Tag the DHCP messages with the userclass.
cf42802e RM	164	You can specify more than one.
bac03ede	165	.It Ic vendor Ar code , Ns Ar value
757520c5 RM	166	Add an enscapulated vendor option.
	167	.Ar code
	168	should be between 1 and 254 inclusive.
	169	Examples.
	170	.Pp
	171	Set the vendor option 01 with an IP address.
	172	.D1 vendor 01,192.168.0.2
	173	Set the vendor option 02 with a hex code.
	174	.D1 vendor 02,01:02:03:04:05
	175	Set the vendor option 03 with an IP address as a string.
	176	.D1 vendor 03,\e"192.168.0.2\e"
bac03ede RM	177	.It Ic vendorclassid Ar string
	178	Change the default vendorclassid sent from dhcpcd-version.
	179	If not set then none is sent.
eaa90296	180	.El
ba9dfb7a	181	.Sh SEE ALSO
ee4e620a	182	.Xr dhcpcd-run-hooks 8 ,
ba97e494	183	.Xr dhcpcd 8 ,
065125d4	184	.Xr if_nametoindex 3 ,
ba97e494	185	.Xr fnmatch 3
ba9dfb7a	186	.Sh AUTHORS
eaa90296	187	.An Roy Marples <roy@marples.name>
ba9dfb7a	188	.Sh BUGS
56d212f2	189	Please report them to http://roy.marples.name/projects/dhcpcd