671 lines
16 KiB
Groff
671 lines
16 KiB
Groff
.\" $KAME: dhcp6c.conf.5,v 1.30 2005/05/03 06:54:26 jinmei Exp $
|
|
.\"
|
|
.\" Copyright (C) 2002 WIDE Project.
|
|
.\" 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.
|
|
.\" 3. Neither the name of the project nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT 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 PROJECT 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 July 29, 2004
|
|
.Dt DHCP6C.CONF 5
|
|
.Os KAME
|
|
.\"
|
|
.Sh NAME
|
|
.Nm dhcp6c.conf
|
|
.Nd DHCPv6 client configuration file
|
|
.\"
|
|
.Sh SYNOPSIS
|
|
.Pa /usr/local/etc/dhcp6c.conf
|
|
.\"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
file contains configuration information for KAME's DHCPv6 client,
|
|
.Nm dhcp6c .
|
|
The configuration file consists of a sequence of statements terminated
|
|
by a semi-colon (`;').
|
|
Statements are composed of tokens separated by white space,
|
|
which can be any combination of blanks,
|
|
tabs and newlines.
|
|
In some cases a set of statements is combined with a pair of brackets,
|
|
which is regarded as a single token.
|
|
Lines beginning with
|
|
.Ql #
|
|
are comments.
|
|
.Sh Interface specification
|
|
There are some statements that may or have to specify interface.
|
|
Interfaces are specified in the form of "name unit", such as
|
|
.Ar fxp0
|
|
and
|
|
.Ar gif1.
|
|
.\"
|
|
.Sh DHCPv6 options
|
|
Some configuration statements take the description of a DHCPv6 option
|
|
as an argument.
|
|
The followings are the format and description of available DHCPv6
|
|
options.
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo
|
|
.Ic domain-name-servers
|
|
.Xc
|
|
means a Domain Name Server option.
|
|
.It Xo
|
|
.Ic domain-name
|
|
.Xc
|
|
means a domain name option.
|
|
.It Xo
|
|
.Ic ntp-servers
|
|
.Xc
|
|
means an NTP server option.
|
|
As of this writing, the option type for this option is not officially
|
|
assigned.
|
|
.Nm dhcp6c
|
|
will reject this option unless it is explicitly built to accept the option.
|
|
.It Xo
|
|
.Ic sip-server-address
|
|
.Xc
|
|
means a SIP Server address option.
|
|
.It Xo
|
|
.Ic sip-server-domain-name
|
|
.Xc
|
|
means a SIP server domain name option.
|
|
.It Xo
|
|
.Ic nis-server-address
|
|
.Xc
|
|
means a NIS Server address option.
|
|
.It Xo
|
|
.Ic nis-domain-name
|
|
.Xc
|
|
means a NIS domain name option.
|
|
.It Xo
|
|
.Ic nisp-server-address
|
|
.Xc
|
|
means a NIS+ Server address option.
|
|
.It Xo
|
|
.Ic nisp-domain-name
|
|
.Xc
|
|
means a NIS+ domain name option.
|
|
.It Xo
|
|
.Ic bcmcs-server-address
|
|
.Xc
|
|
means a BCMCS Server address option.
|
|
.It Xo
|
|
.Ic bcmcs-server-domain-name
|
|
.Xc
|
|
means a BCMCS server domain name option.
|
|
.It Ic ia-pd Ar ID
|
|
means an IA_PD
|
|
.Pq Identity Association for Prefix Delegation
|
|
option.
|
|
.Ar ID
|
|
is a decimal number of the IAID
|
|
.Pq see below about identity associations .
|
|
.It Ic ia-na Ar ID
|
|
means an IA_PD
|
|
.Pq Identity Association for Non-temporary Addresses
|
|
option.
|
|
.Ar ID
|
|
is a decimal number of the IAID
|
|
.Pq see below about identity associations .
|
|
.It Ic rapid-commit
|
|
means a rapid-commit option.
|
|
.It Ic authentication Ar authname
|
|
means an authentication option.
|
|
.Ar authname
|
|
is a string specifying parameters of the authentication protocol.
|
|
An
|
|
.Ic authentication
|
|
statement for
|
|
.Ar authname
|
|
must be provided.
|
|
.El
|
|
.\"
|
|
.Sh Interface statement
|
|
An interface statement specifies configuration parameters on the
|
|
interface.
|
|
The generic format of an interface statement is as follows:
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo
|
|
.Ic interface Ar interface
|
|
{
|
|
.Ar substatements
|
|
};
|
|
.Xc
|
|
The followings are possible
|
|
.Ar substatements
|
|
in an interface statement.
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo
|
|
.Ic send Ar send-options
|
|
;
|
|
.Xc
|
|
This statement specifies DHCPv6 options to be sent to the server(s).
|
|
Some options can only appear in particular messages according to the
|
|
specification,
|
|
in which case the appearance of the options is limited to be compliant
|
|
with the specification.
|
|
.Pp
|
|
.Ar send-options
|
|
is a comma-separated list of options,
|
|
each of which should be specified as described above.
|
|
Multiple
|
|
.Ic send
|
|
statements can also be specified,
|
|
in which case all the specified options will be sent.
|
|
.Pp
|
|
When
|
|
.Ic rapid-commit
|
|
is specified,
|
|
.Nm dhcp6c
|
|
will include a rapid-commit option in solicit messages and wait for
|
|
an immediate reply instead of advertisements.
|
|
.Pp
|
|
When
|
|
.Ic ia-pd
|
|
is specified,
|
|
.Nm dhcp6c
|
|
will initiate prefix delegation as a requesting router by
|
|
including an IA_PD option with the specified
|
|
.Ar ID
|
|
in solicit messages.
|
|
.Pp
|
|
When
|
|
.Ic ia-na
|
|
is specified,
|
|
.Nm dhcp6c
|
|
will initiate stateful address assignment by
|
|
including an IA_NA option with the specified
|
|
.Ar ID
|
|
in solicit messages.
|
|
.Pp
|
|
In either case, a corresponding identity association statement
|
|
must exist with the same
|
|
.Ar ID .
|
|
.It Ic request Ar request-options ;
|
|
This statement specifies DHCPv6 options to be included in an
|
|
option-request option.
|
|
.Ar request-options
|
|
is a comma-separated list of options,
|
|
which can consist of the following options.
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo
|
|
.Ic domain-name-servers
|
|
.Xc
|
|
requests a list of Domain Name Server addresses.
|
|
.It Xo
|
|
.Ic domain-name
|
|
.Xc
|
|
requests a DNS search path.
|
|
.It Xo
|
|
.Ic ntp-servers
|
|
.Xc
|
|
requests a list of NTP server addresses.
|
|
As of this writing, the option type for this option is not officially
|
|
assigned.
|
|
.Nm dhcp6c
|
|
will reject this option unless it is explicitly built to accept the option.
|
|
.It Xo
|
|
.Ic sip-server-address
|
|
.Xc
|
|
requests a list of SIP server addresses.
|
|
.It Xo
|
|
.Ic sip-domain-name
|
|
.Xc
|
|
requests a SIP server domain name.
|
|
.It Xo
|
|
.Ic nis-server-address
|
|
.Xc
|
|
requests a list of NIS server addresses.
|
|
.It Xo
|
|
.Ic nis-domain-name
|
|
.Xc
|
|
requests a NIS domain name.
|
|
.It Xo
|
|
.Ic nisp-server-address
|
|
.Xc
|
|
requests a list of NIS+ server addresses.
|
|
.It Xo
|
|
.Ic nisp-domain-name
|
|
.Xc
|
|
requests a NIS+ domain name.
|
|
.It Xo
|
|
.Ic bcmcs-server-address
|
|
.Xc
|
|
requests a list of BCMCS server addresses.
|
|
.It Xo
|
|
.Ic bcmcs-domain-name
|
|
.Xc
|
|
requests a BCMCS domain name.
|
|
.It Xo
|
|
.Ic refreshtime
|
|
.Xc
|
|
means an information refresh time option.
|
|
This can only be specified when sent with information-request
|
|
messages;
|
|
.Nm dhcp6c
|
|
will ignore this option for other messages.
|
|
.El
|
|
Multiple
|
|
.Ic request
|
|
statements can also be specified,
|
|
in which case all the specified options will be requested.
|
|
.It Ic information-only ;
|
|
This statement specifies
|
|
.Nm dhcp6c
|
|
to only exchange informational configuration parameters with servers.
|
|
A list of DNS server addresses is an example of such parameters.
|
|
This statement is useful when the client does not need stateful
|
|
configuration parameters such as IPv6 addresses or prefixes.
|
|
.It Ic script Ar \(dqscript-name\(dq ;
|
|
This statement specifies a path to script invoked by
|
|
.Nm dhcp6c
|
|
on a certain condition including when the daemon receives a reply
|
|
message.
|
|
.Ar script-name
|
|
must be the absolute path from root to the script file, be a regular
|
|
file, and be created by the same owner who runs the daemon.
|
|
.El
|
|
.El
|
|
.\"
|
|
.Sh Identity association statement
|
|
Identity association
|
|
.Pq IA
|
|
is a key notion of DHCPv6.
|
|
An IA is uniquely identified in a client by a pair of IA type and
|
|
IA identifier
|
|
.Pq IAID .
|
|
An IA is associated with configuration information dependent on the IA type.
|
|
.Pp
|
|
An identity association statement defines a single IA with some
|
|
client-side configuration parameters.
|
|
Its format is as follows:
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo
|
|
.Ic id-assoc Ar type Op Ar ID
|
|
{
|
|
.Ar substatements
|
|
};
|
|
.Xc
|
|
.Ar type
|
|
is a string for the type of this IA.
|
|
The current implementation supports
|
|
.Ql Ic na
|
|
(non-temporary address allocation)
|
|
.Ql Ic pd
|
|
(prefix delegation) for the IA type.
|
|
.Ar ID
|
|
is a decimal number of IAID.
|
|
If omitted, the value 0 will be used by default.
|
|
.Ar substatements
|
|
is a sequence of statements that specifies configuration parameters
|
|
for this IA.
|
|
Each statement may or may not be specific to the type of IA.
|
|
.Pp
|
|
The followings are possible
|
|
.Ar substatements
|
|
for an IA of type
|
|
.Ic na .
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo
|
|
.Ic address Ar ipv6-address pltime Op Ar vltime ;
|
|
.Xc
|
|
specifies an address and related parameters that the client wants to be
|
|
allocated.
|
|
Multiple addresses can be specified, each of which is described as a
|
|
separate
|
|
.Ic address
|
|
substatement.
|
|
.Nm dhcp6c
|
|
will include all the addresses
|
|
.Pq and related parameters
|
|
in Solicit messages,
|
|
as an IA_NA prefix option encapsulated in the corresponding IA_NA
|
|
option.
|
|
Note, however, that the server may or may not respect the specified
|
|
prefix parameters.
|
|
For parameters of the
|
|
.Ic address
|
|
substatement,
|
|
see
|
|
.Xr dhcp6s.conf 5 .
|
|
.El
|
|
.Pp
|
|
The followings are possible
|
|
.Ar substatements
|
|
for an IA of type
|
|
.Ic pd .
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo
|
|
.Ar prefix_interface_statement
|
|
.Xc
|
|
specifies the client's local configuration of how delegated prefixes
|
|
should be used
|
|
.Pq see below .
|
|
.It Ic prefix Ar ipv6-prefix pltime Op Ar vltime ;
|
|
specifies a prefix and related parameters that the client wants to be
|
|
delegated.
|
|
Multiple prefixes can be specified, each of which is described as a
|
|
separate
|
|
.Ic prefix
|
|
substatement.
|
|
.Nm dhcp6c
|
|
will include all the prefixes
|
|
.Pq and related parameters
|
|
in Solicit messages,
|
|
as an IA_PD prefix option encapsulated in the corresponding IA_PD
|
|
option.
|
|
Note, however, that the server may or may not respect the specified
|
|
prefix parameters.
|
|
For parameters of the
|
|
.Ic prefix
|
|
substatement,
|
|
see
|
|
.Xr dhcp6s.conf 5 .
|
|
.El
|
|
.El
|
|
.\"
|
|
.Sh Prefix interface statement
|
|
A prefix interface statement specifies configuration parameters of
|
|
prefixes on local interfaces that are derived from delegated prefixes.
|
|
A prefix interface statement can only appear as a substatement of
|
|
an identity association statement with the type
|
|
.Ic pd .
|
|
The generic format of an interface statement is as follows:
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo
|
|
.Ic prefix-interface Ar interface
|
|
{
|
|
.Ar substatements
|
|
};
|
|
.Xc
|
|
When an IPv6 prefix is delegated from a DHCPv6 server,
|
|
.Nm dhcp6c
|
|
will assign a prefix on the
|
|
.Ar interface
|
|
unless the interface receives the DHCPv6 message that contains the prefix
|
|
with the delegated prefix and the parameters provided in
|
|
.Ar substatements .
|
|
Possible substatements are as follows:
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo
|
|
.Ic sla-id Ar ID
|
|
;
|
|
.Xc
|
|
This statement specifies the identifier value of the site-level aggregator
|
|
.Pq SLA
|
|
on the interface.
|
|
.Ar ID
|
|
must be a decimal integer which fits in the length of SLA IDs
|
|
.Pq see below .
|
|
For example,
|
|
if
|
|
.Ar ID
|
|
is 1 and the client is delegated an IPv6 prefix 2001:db8:ffff::/48,
|
|
.Nm dhcp6c
|
|
will combine the two values into a single IPv6 prefix,
|
|
2001:db8:ffff:1::/64,
|
|
and will configure the prefix on the specified
|
|
.Ar interface .
|
|
.It Xo
|
|
.Ic sla-len Ar length
|
|
;
|
|
.Xc
|
|
This statement specifies the length of the SLA ID in bits.
|
|
.Ar length
|
|
must be a decimal number between 0 and 128.
|
|
If the length is not specified by this statement,
|
|
the default value 16 will be used.
|
|
.El
|
|
.El
|
|
.\"
|
|
.Sh Authentication statement
|
|
An authentication statement defines a set of authentication parameters
|
|
used in DHCPv6 exchanges with the server(s).
|
|
The format of an authentication statement is as follows:
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo
|
|
.Ic authentication Ar authname
|
|
{
|
|
.Ar substatements
|
|
};
|
|
.Xc
|
|
.Ar authname
|
|
is a string which is unique among all authentication statements in the
|
|
configuration file.
|
|
It will specify a particular set of authentication parameters when
|
|
.Ic authentication
|
|
option is specified in the
|
|
.Ic interface
|
|
statement.
|
|
Possible substatements of the
|
|
.Ic authentication
|
|
statement are as follows:
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo
|
|
.Ic protocol Ar authprotocol
|
|
;
|
|
.Xc
|
|
specifies the authentication protocol.
|
|
Currently, the only available protocol as
|
|
.Ar authprotocol
|
|
is
|
|
.Ic delayed ,
|
|
which means the DHCPv6 delayed authentication protocol.
|
|
.It Xo
|
|
.Ic algorithm Ar authalgorithm
|
|
;
|
|
.Xc
|
|
specifies the algorithm for this authentication.
|
|
Currently, the only available algorithm is HMAC-MD5,
|
|
which can be specified as one of the followings:
|
|
.Ic hmac-md5 ,
|
|
.Ic HMAC-MD5 ,
|
|
.Ic hmacmd5 ,
|
|
or
|
|
.Ic HMACMD5 .
|
|
This substatement can be omitted.
|
|
In this case,
|
|
HMAC-MD5 will be used as the algorithm.
|
|
.It Xo
|
|
.Ic rdm Ar replay-detection-method
|
|
;
|
|
.Xc
|
|
specifies the replay protection method for this authentication.
|
|
Currently, the only available method is
|
|
.Ic monocounter ,
|
|
which means the use of a monotonically increasing counter.
|
|
If this method is specified,
|
|
.Ic dhcp6c
|
|
will use an NTP-format timestamp when it authenticates the message.
|
|
This substatement can be omitted,
|
|
in which case
|
|
.Ic monocounter
|
|
will be used as the method.
|
|
.El
|
|
.El
|
|
.\"
|
|
.Sh Keyinfo statement
|
|
A keyinfo statement defines a secret key shared with the server(s)
|
|
to authenticate DHCPv6 messages.
|
|
The format of a keyinfo statement is as follows:
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo
|
|
.Ic keyinfo Ar keyname
|
|
{
|
|
.Ar substatements
|
|
};
|
|
.Xc
|
|
.Ar keyname
|
|
is an arbitrary string.
|
|
It does not affect client's behavior but is provided for readability
|
|
of log messages.
|
|
Possible substatements of the
|
|
.Ic keyinfo
|
|
statement are as follows:
|
|
.Bl -tag -width Ds -compact
|
|
.It Xo
|
|
.Ic realm Ar \(dqrealmname\(dq
|
|
;
|
|
.Xc
|
|
specifies the DHCP realm.
|
|
.Ar realmname
|
|
is an arbitrary string,
|
|
but is typically expected to be a domain name like \(dqkame.net\(dq .
|
|
.It Xo
|
|
.Ic keyid Ar ID
|
|
;
|
|
.Xc
|
|
specifies the key identifier,
|
|
.Ar ID ,
|
|
as a decimal number.
|
|
A secret key is uniquely identified within the client by the DHCP
|
|
realm and the key identifier.
|
|
.It Xo
|
|
.Ic secret Ar \(dqsecret-value\(dq
|
|
;
|
|
.Xc
|
|
specifies the shared secret of this key.
|
|
.Ar \(dqsecret-value\(dq
|
|
is a base-64 encoded string of the secret.
|
|
.It Xo
|
|
.Ic expire Ar \(dqexpiration-time\(dq
|
|
;
|
|
.Xc
|
|
specifies the expiration time of this key.
|
|
.Ar \(dqexpiration-time\(dq
|
|
should be formatted in one of the followings:
|
|
.Ar yyyy-mm-dd HH:MM ,
|
|
.Ar mm-dd HH:MM ,
|
|
or
|
|
.Ar HH:MM ,
|
|
where
|
|
.Ar yyyy
|
|
is the year with century (e.g., 2004),
|
|
.Ar mm
|
|
is the month,
|
|
.Ar dd
|
|
is the day of the month,
|
|
.Ar HH
|
|
is the hour of 24-hour clock,
|
|
and
|
|
.Ar MM
|
|
is the minute,
|
|
each of which is given as a decimal number.
|
|
Additionally,
|
|
a special keyword
|
|
.Ic forever
|
|
can be specified as
|
|
.Ar expiration-time ,
|
|
which means the key has an infinite lifetime and never expires.
|
|
This substatement can be omitted,
|
|
in which case
|
|
.Ic forever
|
|
will be used by default.
|
|
.El
|
|
.El
|
|
.\"
|
|
.Sh Examples
|
|
The followings are a sample configuration to be delegated an IPv6
|
|
prefix from an upstream service provider.
|
|
With this configuration
|
|
.Nm dhcp6c
|
|
will send solicit messages containing an IA_PD option,
|
|
with an IAID 0,
|
|
on to an upstream PPP link,
|
|
.Ar ppp0 .
|
|
After receiving some prefixes from a server,
|
|
.Nm dhcp6c
|
|
will then configure derived IPv6 prefixes with the SLA ID 1 on a
|
|
local ethernet interface,
|
|
.Ar ne0 .
|
|
Note that the IAID for the
|
|
.Ic id-assoc
|
|
statement is 0 according to the default.
|
|
.Bd -literal -offset
|
|
interface ppp0 {
|
|
send ia-pd 0;
|
|
};
|
|
|
|
id-assoc pd {
|
|
prefix-interface ne0 {
|
|
sla-id 1;
|
|
};
|
|
};
|
|
.Ed
|
|
.Pp
|
|
If a shared secret should be configured in both the client and the
|
|
server for DHCPv6 authentication,
|
|
it would be specified in the configuration file as follows:
|
|
.Bd -literal -offset
|
|
keyinfo kame-key {
|
|
realm "kame.net";
|
|
keyid 1;
|
|
secret "5pvW2g48OHPvkYMJSw0vZA==";
|
|
};
|
|
.Ed
|
|
.Pp
|
|
One easy way of generating a new secret in the base64 format is to
|
|
execute the
|
|
.Xr openssl 1
|
|
command (when available) as follows,
|
|
.Bd -literal -offset
|
|
% openssl rand -base64 16
|
|
.Ed
|
|
.Pp
|
|
and copy the output to the
|
|
.Nm dhcp6c.conf
|
|
file.
|
|
.Pp
|
|
To include an authentication option for DHCPv6 authentication,
|
|
the
|
|
.Ic interface
|
|
statement should be modified and an
|
|
.Ic authentication
|
|
statement should be added as follows:
|
|
.Bd -literal -offset
|
|
interface ppp0 {
|
|
send ia-pd 0;
|
|
send authentication kame;
|
|
};
|
|
|
|
authentication kame {
|
|
protocol delayed;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Bd -literal -offset
|
|
interface fxp0 {
|
|
send ia-na 0;
|
|
};
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr dhcp6s.conf 5
|
|
.Xr dhcp6c 8
|
|
.\"
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
configuration file first appeared in the WIDE/KAME IPv6 protocol
|
|
stack kit.
|