[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 Jun 30, 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 classid Ar string
Change the default classid sent from dhcpcd-version.
If not set then none is sent.
.It Ic clientid Ar string
Change the default clientid sent from the interface hardware address.
If the string is of the format 01:02:03 then it is encoded as hex.
If not set then none is sent.
.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
.Fl h , -hostname
option must be a FQDN.
.Nm dhcpcd
itself never does any DNS updates.
.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 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 option Ar dhcp-option
Requests the
.Ar dhcp-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 seperated by commas, spaces or more option 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 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"
.El
.Sh SEE ALSO
.Xr dhcpcd-run-hooks 8 ,
.Xr dhcpcd 8
.Sh AUTHORS
.An Roy Marples <roy@marples.name>
.Sh BUGS
Please report them to http://bugs.marples.name
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	.\"
757520c5	25	.Dd Jun 30, 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
d2616b08	46	.It Ic classid Ar string
cf42802e RM	47	Change the default classid sent from dhcpcd-version.
cf42802e RM	48	If not set then none is sent.
d2616b08 RM	49	.It Ic clientid Ar string
	50	Change the default clientid sent from the interface hardware address.
	51	If the string is of the format 01:02:03 then it is encoded as hex.
	52	If not set then none is sent.
	53	.It Ic duid
	54	Generate an
	55	.Rs
	56	.%T "RFC 4361"
	57	.Re
cf42802e RM	58	compliant clientid.
	59	This requires persistent storage and not all DHCP servers work with it so it's
	60	not enabled by default.
d2616b08 RM	61	The duid generated will be held in
	62	.Pa @SYSCONFDIR@/dhcpcd.duid
	63	and should not be copied to other hosts.
ba9dfb7a	64	.It Ic hostname Ar name
35ff0dbb RM	65	Sends specified
35ff0dbb RM	66	.Ar hostname
d2616b08	67	to the DHCP server so it can be registered in DNS. If
35ff0dbb	68	.Ar hostname
d2616b08	69	if a FQDN (ie, contains a .) then it will be encoded as such.
35ff0dbb RM	70	.It Ic fqdn Op none \| ptr \| both
	71	none disables FQDN encoding, ptr just asks the DHCP server to update the PTR
	72	record of the host in DNS whereas both also updates the A record.
1b3bc477 RM	73	The current hostname or the hostname specified using the
	74	.Fl h , -hostname
	75	option must be a FQDN.
	76	.Nm dhcpcd
	77	itself never does any DNS updates.
3adc5520	78	.It Ic interface Ar interface
012fd5d3 RM	79	Subsequent options are only parsed for this
012fd5d3 RM	80	.Ar interface .
ba9dfb7a RM	81	.It Ic leasetime Ar seconds
	82	Request a leasetime of
	83	.Ar seconds .
ba9dfb7a	84	.It Ic noarp
cf42802e RM	85	Don't send any ARP requests.
cf42802e RM	86	This also disables IPv4LL.
ba9dfb7a RM	87	.It Ic nogateway
ba9dfb7a RM	88	Don't install any default routes.
37156a6b RM	89	.It Ic nohook Ar script
37156a6b RM	90	Don't run this hook script.
8276da82 RM	91	Matches full name, or prefixed with 2 numbers optionally ending with
8276da82 RM	92	.Pa .sh .
ba9dfb7a RM	93	.It Ic noipv4ll
	94	Don't attempt to obtain an IPv4LL address if we failed to get one via DHCP.
	95	See
	96	.Rs
	97	.%T "RFC 3927"
	98	.Re
d2616b08 RM	99	.It Ic option Ar dhcp-option
	100	Requests the
	101	.Ar dhcp-option
cf42802e RM	102	from the server.
cf42802e RM	103	It can be a variable to be used in
ee4e620a	104	.Xr dhcpcd-run-hooks 8
cf42802e RM	105	or the numerical value.
cf42802e RM	106	You can specify more seperated by commas, spaces or more option lines.
0aeb350c RM	107	.It Ic script Ar script
	108	Use
	109	.Ar script
	110	instead of the default
	111	.Pa @SCRIPT@ .
d2616b08	112	.It Ic timeout Ar seconds
fedb3da0	113	The default timeout for waiting for a DHCP response is 30 seconds which may
d2616b08 RM	114	be too long or too short and can be changed here.
d2616b08 RM	115	.It Ic userclass Ar string
cf42802e RM	116	Tag the DHCP messages with the userclass.
cf42802e RM	117	You can specify more than one.
757520c5 RM	118	.It vendor Ar code , Ns Ar value
	119	Add an enscapulated vendor option.
	120	.Ar code
	121	should be between 1 and 254 inclusive.
	122	Examples.
	123	.Pp
	124	Set the vendor option 01 with an IP address.
	125	.D1 vendor 01,192.168.0.2
	126	Set the vendor option 02 with a hex code.
	127	.D1 vendor 02,01:02:03:04:05
	128	Set the vendor option 03 with an IP address as a string.
	129	.D1 vendor 03,\e"192.168.0.2\e"
eaa90296	130	.El
ba9dfb7a	131	.Sh SEE ALSO
ee4e620a	132	.Xr dhcpcd-run-hooks 8 ,
ba9dfb7a RM	133	.Xr dhcpcd 8
ba9dfb7a RM	134	.Sh AUTHORS
eaa90296	135	.An Roy Marples <roy@marples.name>
ba9dfb7a RM	136	.Sh BUGS
ba9dfb7a RM	137	Please report them to http://bugs.marples.name