imported KAME-DHCPv6 snapshot at 20051201KAME_20051201

1 files changed, 626 insertions, 0 deletions

diff --git a/dhcp6c.conf.5 b/dhcp6c.conf.5
new file mode 100644
index 0000000..259d8d7
--- /dev/null
+++ b/dhcp6c.conf.5
@@ -0,0 +1,626 @@
+.\"	$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/v6/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 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-server-domain-name
+.Xc
+requests a SIP server 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.
+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.
+.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.