--- dhcpagent.1m.orig Thu Oct 26 11:58:15 2006 +++ dhcpagent.1m.new Fri Nov 3 12:38:13 2006 @@ -27,14 +27,20 @@ this reason, dhcpagent must run as a daemon, terminating only when the client machine powers down. - The dhcpagent daemon is controlled through ifconfig(1M) in + For IPv4, the dhcpagent daemon is controlled through + ifconfig(1M) in much the same way that the init(1M) daemon is controlled by telinit(1M). dhcpagent can be invoked as a user process, albeit one requiring root privileges, but this is not neces- sary, as ifconfig(1M) will start it automatically. + For IPv6, the dhcpagent daemon is invoked automatically by + in.ndpd(1M). It may also be controlled through + ifconfig(1M), if necessary. + When invoked, dhcpagent enters a passive state while it - awaits instructions fromifconfig(1M). When it receives a + awaits instructions from ifconfig(1M) or in.ndpd(1M). + When it receives a command to configure an interface, it starts DHCP. Once DHCP is complete, dhcpagent may be queried for the values of the various network parameters. In addition, if DHCP was used to @@ -42,12 +48,27 @@ is configured and brought up. When a lease is obtained, it is automatically renewed as necessary. If the lease cannot be renewed, dhcpagent will take the interface down at the - end of the lease. If the configured interface is found to be + end of the lease. + + For IPv4, if the configured interface is found to be unplumbed, marked down, or to have a different IP address, subnet mask, or broadcast address from those obtained from DHCP, the interface is abandoned by DHCP control. - In addition to DHCP, dhcpagent also supports BOOTP. See RFC + For IPv6, dhcpagent automatically plumbs and unplumbs + logical interfaces as necessary for the IPv6 addresses + supplied by the server. The IPv6 prefix length (netmask) is + not set by the DHCPv6 protocol, but is instead set by + in.ndpd(1M) using prefix information obtained by Router + Advertisements. If any of the logical interfaces created by + dhcpagent is unplumbed, marked down, or configured with a + different IP address, it will be abandoned by DHCP control. + If the link-local interface is unplumbed, then all addresses + configured by DHCP on that physical interface will be + removed. + + In addition to DHCP, dhcpagent also supports BOOTP (IPv4 + only). See RFC 951, Bootstrap Protocol. Configuration parameters obtained from a BOOTP server are treated identically to those received from a DHCP server, except that the IP address @@ -55,8 +76,9 @@ DHCP also acts as a mechanism to configure other information needed by the client, for example, the domain name and - addresses of routers. Aside from the IP address, netmask, - broadcast address and default router, the agent does not + addresses of routers. Aside from the IP address, and for + IPv4 alone, the netmask, broadcast address and default + router, the agent does not @@ -87,7 +109,8 @@ parameters in the case where no specific interface is requested. See dhcpinfo(1) and ifconfig(1M) for details. - The dhcpagent daemon can be configured to request a particu- + For IPv4, the dhcpagent daemon can be configured to request + a particu- lar host name. See the REQUEST_HOSTNAME description in the FILES section. When first configuring a client to request a host name, you must perform the following steps as root to @@ -98,7 +121,8 @@ # reboot All DHCP packets sent by dhcpagent include a vendor class - identifier (RFC 2132, option code 60). This identifier is + identifier (RFC 2132, option code 60; RFC 3315, option + code 16). This identifier is the same as the platform name returned by the uname -i com- mand, except: @@ -185,10 +209,11 @@ /etc/dhcp/eventhook, the dhcpagent deamon will automatically run that program when any of the following events occur: - BOUND + BOUND and BOUND6 - This event occurs during interface configuration. The - event program is invoked when dhcpagent receives the ACK + These events occur during interface configuration. The + event program is invoked when dhcpagent receives the + DHCPv4 ACK or DHCPv6 Reply @@ -203,51 +228,101 @@ - reply from the DHCP server for the lease request of an - address, indicating successful configuration. + message from the DHCP server for the lease request of an + address, indicating successful initial configuration of + the interface. (See also the INFORM and INFORM6 events, + which occur when configuration parameters are obtained + without address leases.) - EXTEND + EXTEND and EXTEND6 - This event occurs during lease extension. The event pro- - gram is invoked just after dhcpagent receives the ACK - reply from the DHCP server for the renew request. + These events occur during lease extension. The event pro- + gram is invoked just after dhcpagent receives the + DHCPv4 ACK or DHCPv6 Reply + from the DHCP server for the DHCPv4 REQUEST (renew) + message or the DHCPv6 Renew or Rebind message. + Note that with DHCPv6, the server may choose to remove + some addresses, add new address leases, and ignore + (allow to expire) still other addresses in a given Reply + message. The EXTEND6 event occurs when a Reply is + received that leaves one or more address leases still + valid, even if the Reply message does not extend the + lease for any address. The event program is invoked + just before any addresses are removed, but just after + any new addresses are added. Those to be removed will + be marked with the IFF_DEPRECATED flag. - EXPIRE + EXPIRE and EXPIRE6 - This event occurs during lease expiration. The event + These events occur during lease expiration. For + DHCPv4, the event program is invoked just before the leased address is removed from an interface and the interface is marked as - down. + down. For DHCPv6, the event program is invoked just + before the last remaining leased addresses are removed + from the interface. + DROP and DROP6 - DROP - - This event occurs during the period when an interface is + These events occur during the period when an interface is dropped. The event program is invoked just before the - interface is removed from DHCP control. + interface is removed from DHCP control. If the + interface has been abandoned due the user unplumbing the + interface, then this event will occur after the user's + action has taken place. The interface may not be + present. + INFORM and INFORM6 - RELEASE + These events occur when an interface acquires new or + updated configuration information from a DHCP server via + the DHCPv4 INFORM or the DHCPv6 Information-Request + message. These messages are sent using ifconfig(1M) + "dhcp inform" or when the DHCPv6 Router Advertisement + ``O'' bit is set and the ``M'' bit is not set. Thus, + these events occur when the DHCP client does not obtain + an IP address lease from the server, and instead obtains + only configuration parameters. + + LOSS6 + + This event occurs during lease expiration when one or + more valid leases still remain. The event program is + invoked just before expired addresses are removed. + Those being removed will be marked with the + IFF_DEPRECATED flag. + + Note that this event is not associated with the receipt + of the Reply message, occurs only when one or more valid + leases remain, and occurs only with DHCPv6. If all + leases have expired, then the EXPIRE6 event occurs + instead. + + + RELEASE and RELEASE6 + This event occurs during the period when a leased address is released. The event program is invoked just before dhcpagent relinquishes the address on an inter- - face and sends the RELEASE packet to the DHCP server. + face and sends the DHCPv4 RELEASE or DHCPv6 Release + packet to the DHCP server. - The system does not provide a default event program. The - file /etc/dhcp/eventhook is owned by the root and its mode - must be 755. + The system does not provide a default event program. The + file /etc/dhcp/eventhook must be owned by user "root" and + its mode must be 755. The event program will be passed two arguments, the inter- - face name and the event name, respectively. + face name and the event name, respectively. For DHCPv6, the + interface name is the name of the physical interface. The event program can use the dhcpinfo(1) utility to fetch additional information about the interface. While the event @@ -282,7 +357,7 @@ OPTIONS The following options are supported: - -a Adopt a configured interface. This option is for + -a Adopt a configured IPv4 interface. This option is for use with diskless DHCP clients. In the case of diskless DHCP, DHCP has already been performed on the network interface providing the operating sys- @@ -371,9 +446,16 @@ "BOUND") echo "Address acquired from server " `/sbin/dhcpinfo -i $1 ServerID` ;; + "BOUND6") + echo "Addresses acquired from server " \ + `/sbin/dhcpinfo -v6 -i $1 ServerID` + ;; "EXTEND") echo "Lease extended for " `'sbin/dhcpinfo -i $1 LeaseTim`" seconds" ;; + "EXTEND6") + echo "New lease information obtained on $i" + ;; "EXPIRE" | "DROP" | "RELEASE") ;; @@ -385,6 +467,7 @@ FILES /etc/dhcp/if.dhc + /etc/dhcp/if.dh6 Contains the configuration for interface. The mere @@ -403,21 +486,43 @@ existence of this file does not imply that the confi- guration is correct, since the lease may have expired. + On start-up, dhcpagent confirms the validity of the + address using REQUEST (for DHCPv4) or Confirm (DHCPv6). + /etc/dhcp/duid + /etc/dhcp/iaid + Contains persistent storage for DUID (DHCP Unique + Identifier) and IAID (Identity Association Identifier) + values. The format of these files is undocumented, and + applications should not read from or write to them. + + /etc/default/dhcpagent Contains default values for tunable parameters. All values may be qualified with the interface they apply to by prepending the interface name and a period (".") to - the interface parameter name. The parameters include: + the interface parameter name. + To configure IPv6 parameters, the string ".v6" is placed + between the interface name (if any) and the parameter + name. For example, to set the global IPv6 parameter + request list, use ".v6.PARAM_REQUEST_LIST". To set the + CLIENT_ID (DUID) on hme0, use "hme0.v6.CLIENT_ID". + + The parameters include: + RELEASE_ON_SIGTERM Indicates that a RELEASE rather than a DROP should be performed on managed interfaces when the agent - terminates. + terminates. Release causes the client to discard + the lease, and the server to make the address + available again. Drop causes the client to record + the lease in /etc/dhcp/interface.dhc or + /etc/dhcp/interface.dh6 for later use. @@ -425,7 +530,9 @@ OFFER_WAIT Indicates how long to wait between checking for - valid OFFERs after sending a DISCOVER. + valid OFFERs after sending a DISCOVER. For DHCPv6, + sets the time to wait between checking for valid + Advertisements after sending a Solicit. @@ -432,13 +539,58 @@ CLIENT_ID Indicates the value that should be used to uniquely - identify the client to the server. By default, the - value is interpreted as an NVT ASCII string, but you - can prepend 0x to the value to indicate a binary - string. Thus, "Sun" and "0x53756E" are equivalent. + identify the client to the server. This value may + take one of three basic forms: + decimal,data... + 0xHHHHH... + "string...." + The first form is an RFC 3315 DUID. This is legal + for both IPv4 DHCP and DHCPv6. For IPv4, an RFC + 4361 Client ID is constructed from this value. In + this first form, the format of "data..." depends on + the decimal value. The following formats are + defined for this first form: + 1,hwtype,time,lla + + Type 1, DUID-LLT. The hwtype value is an + integer in the range 0-65535, and indicates the + type of hardware. The time value is the number + of seconds since midnight, January 1st, 2000 + UTC, and may be omitted to use the current + system time. The lla value is either a + colon-separated MAC address or the name of a + physical interface. If the name of an interface + is used, the hwtype value may be omitted. For + example: 1,,,hme0 + + 2,enterprise,hex... + + Type 2, DUID-EN. The enterprise value is an + integer in the range 0-4294967295, and + represents the SMI Enterprise number for an + organization. The hex string is an even-length + sequence of hexadecimal digits. + + 3,hwtype,lla + + Type 3, DUID-LL. This is the same as DUID-LLT + (type 1), except that a time stamp is not used. + + *, + + Any other type value (0 or 4-65535) may be used + with an even-length hexadecimal string. + + The second and third forms of CLIENT_ID are legal + for IPv4 only. These both represent raw Client ID + (without RFC 4361), in hex or NVT ASCII string + format. Thus, "Sun" and "0x53756E" are equivalent. + + + PARAM_REQUEST_LIST Specifies a list of comma-separated integer values @@ -449,7 +601,7 @@ REQUEST_HOSTNAME Indicates the client requests the DHCP server to map - the client's leased IP address to the host name + the client's leased IPv4 address to the host name associated with the network interface that performs DHCP on the client. The host name must be specified in the /etc/hostname.interface file for the relevant @@ -473,6 +625,7 @@ where hostname is the host name requested. + This option works with DHCPv4 only. @@ -491,7 +644,7 @@ |_____________________________|_____________________________| | Availability | SUNWcsr | |_____________________________|_____________________________| - | Interface Stability | Evolving | + | Interface Stability | Committed | |_____________________________|_____________________________| @@ -507,17 +660,22 @@ Droms, R., Dynamic Host Configuration Protocol, RFC 2131, Network Working Group, March 1997. -NOTES - The dhcpagent daemon can be used on logical interfaces just - as with physical interfaces. However, each logical interface - must first be configured with a unique client id by setting - the /etc/default/dhcpagent CLIENT_ID parameter (see descrip- - tion above). + Lemon, T. and B. Sommerfeld. RFC 4361, Node-specific Client + Identifiers for Dynamic Host Configuration Protocol Version + Four (DHCPv4). Nominum and Sun Microsystems. February + 2006. - For example, inserting the entry: + Droms, R. RFC 3315, Dynamic Host Configuration Protocol for + IPv6 (DHCPv6). Cisco Systems. July 2003. - hme0:1.CLIENT_ID=orangutan +NOTES + The dhcpagent daemon can be used on IPv4 logical interfaces just + as with physical interfaces. When used on a logical + interface, the daemon automatically constructs a Client ID + value based on the DUID and IAID values, according to RFC + 4361. The /etc/default/dhcpclient CLIENT_ID value, if any, + overrides this automatic identifier. @@ -533,16 +691,19 @@ - ...in /etc/default/dhcpagent will cause dhcpagent to use the - client id orangutan when managing the lease for hme0:1. As - with physical interfaces, the /etc/hostname.hme0:1 and + As + with physical IPv4 interfaces, the /etc/hostname.hme0:1 and /etc/dhcp.hme0:1 files must also be created in order for hme0:1 to be automatically plumbed and configured at boot. - In addition, unlike physical interfaces, dhcpagent does not + In addition, unlike physical IPv4 interfaces, dhcpagent does not add or remove default routes associated with logical inter- faces. + With DHCPv6, the link-local interface must be configured + using /etc/hostname6.hme0 in order for DHCPv6 to run on hme0 + at boot time. The logical interfaces for each address are + plumbed by dhcpagent automatically.