CDDL HEADER START The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] CDDL HEADER END Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. ident "@(#)design.txt 1.4 06/12/04 SMI" DHCPv6 Client High-Level Design This document describes the high-level design and system architectural issues involved in the DHCPv6 Client project. A separate document describes the low-level design, including the internal state machine operation. The overall goal is to add DHCPv6 into the existing Solaris DHCP client support. This means extending the existing utilities as necessary to support the new protocol and its features, and avoiding gratuitous differences where possible. In some respects, DHCPv6 is quite different from IPv4's DHCP, and the design must reflect those differences. Configuration Syntax We would like to allow for configuration of the DHCPv6 client in much the same way as the existing IPv4 DHCP client is configured. This means using /etc/default/dhcpagent. One option would be to create a new "dhcpv6agent" file, and using a separate set of configuration bits there. However, given that these parameters are rarely configured, and that splitting IPv4 and IPv6 configuration interfaces has historically caused confusion, we will simply add a new syntax to the existing file. The syntax is augmented to allow a ".v6" marker to appear between the interface name (if any) and the parameter to be configured. For example, the global IPv4 option request list would (currently) be set like this: PARAM_REQUEST_LIST=1,3,6,12,15,28,43 An individual interface could be configured to omit the pesky hostname option like this: hme0.PARAM_REQUEST_LIST=1,3,6,15,28,43 For DHCPv6, the global request list will be set like this (note the leading dot): .v6.PARAM_REQUEST_LIST=23,24 or on an individual interface like this: hme0.v6.PARAM_REQUEST_LIST=21,22,23,24 Router Advertisements Unlike DHCPv4, DHCPv6 is expected to be invoked by Router Advertisements (RAs), rather than by manual configuration (see RFC 2462). When the system receives an RA with the ``M'' ("managed address configuration") bit set, the system should automatically invoke DHCPv6 on that interface and use it to get an address and other parameters. The ``O'' ("other stateful configuration") bit indicates whether the system should only request data other than an address (e.g., DNS servers) via DHCPv6. If either bit is set, we must run DHCPv6. When triggered by way of RA, we acquire an address lease only if the ``M'' bit is set. In addition, it's expected (per RFC 2462) that DHCPv6 will be invoked if no RAs are received at all on a given interface. Running DHCPv6 ``should'' effectively be the system-wide default for every interface. Note that stateless and stateful address configuration are independent, and both may be used on a given link. The stateless address configuration mechanism is controlled by the ``A'' bit in the Prefix Information option -- see RFC 2461 section 4.6.2. Two design issues to resolve here are that the ``ra_flags'' variable in ndp.c is implemented as a global, when the RFC specifies that it must be per-interface, and that in.ndpd doesn't detect and handle the state where no RAs are received (though it does have comments saying that "something" should happen). Enable/Disable For the in.ndpd client side, a new "StatefulAddrConf" interface variable will be added. This will be a Boolean, like the existing StatelessAddrConf variable, and will default to "true." If a local router tells us via ``M'' or ``O'' bits that we should run DHCPv6, but this variable is set to "false," then we will not invoke DHCPv6. This allows an administrator to refuse to run DHCPv6, if desired. The existing AdvManagedFlag and AdvOtherConfigFlag interface variables already control the ``M'' and ``O'' bits for the in.ndpd server side. DUID and IAID In DHCPv6, two identifiers are used. The DUID is the classical variable-length "opaque" client identifier, and the IAID is a 32 bit integer. Normally, the DUID will be autogenerated (using Type 1) and stored in /etc/dhcp/duid in order to meet the stability requirements of RFC 3315. The IAID will default to the ifIndex number for the physical interface being configured, as that's guaranteed by the kernel to be unique for all physical interfaces. In ordinary use, the same DUID is used on all interfaces, and the IAID identifies a particular physical interface being configured. The user may need to set these values for special purposes, including for software test. In order to allow for that, we will use the existing CLIENT_ID variable in dhcpagent to provide override control of the DUID. The DUID has a known structure, and we will support these types using a comma-separated string, as follows: 1,, Type 1, DUID-LLT. The value is a 16 bit integer (0-65535), and the is either a colon-separated MAC address or the name of a physical interface. The time value required for this format is queried automatically and kept in the /etc/dhcp/duid state file. 2,, Type 2, DUID-EN. The value is a 32 bit integer, and is an even-length string of hexadecimal digits. 3,, Type 3, DUID-LL. This is the same as DUID-LLT, except that a time stamp is not used. *, Any type value 0 or 4-65535 may be used with an even-length hexadecimal string. The new (optional) IAID value will just be a simple integer, chosen by the system, and kept in stable storage. CR 6386331 cites RFC 4361, "Node-specific Client Identifiers for Dynamic Host Configuration Protocol Version Four (DHCPv4)," as a possibility for Solaris. The RFC recommends making the system default to having the same binding association (client ID) for v4 and v6. We can't do this for existing configurations, as it would cause breakage. However, we can use this to enable IPv4 interface alias use of DHCP without requiring a manually-configured Client ID. This is a good step forward, as the system currently prohibits simple configuration of IPv4 interface aliases. Logical Interfaces In the IPv4 DHCP client, each logical interface is independent and is an administrative unit. In addition to the zeroth logical interface (which defaults to the interface MAC address as an identifier), the user may configure specific logical interfaces to run DHCP by specifying a CLIENT_ID in the dhcpagent configuration file. For example: hme0:1.CLIENT_ID=orangutan (As noted above, the explicit CLIENT_ID configuration is no longer required, due to RFC 4361.) DHCPv6 will be different. The zeroth logical interface on an IPv6 interface, unlike IPv4, is always a link-local. It cannot be under DHCP control, which means that DHCPv6 is run only on non-zero logical interfaces. In addition, the DHCPv6 server will send back a list of addresses for the client to configure. In Solaris, each of these addresses requires a separate logical interface. On top of that, stateless address configuration already creates logical interfaces as required (using an "ifconfig addif"-like interface). All of the above means that the logical interface cannot be the administrative unit in DHCPv6. Instead, the administrative unit is known as the "Identity Association," and is a handle for the client identifier, physical interface, and all of the configured addresses. In order to allow for configurable client operation, we need to allow for DUIDs to be assigned as needed, even on a per-interface basis. This may be used to set the global DUID as: .v6.CLIENT_ID= or to set a particular interface to use a given DUID (and make the system appear to be multiple independent clients to a DHCPv6 server): hme0.v6.CLIENT_ID= Note that setting parameters on a single logical interface does not make sense with DHCPv6, thus "hme0:1.v6." isn't a valid selector. It would be possible to support an administrative unit that works in a way analogous to logical interfaces for DHCPv6. To do this, we would need a way to name contexts used for separate DUIDs on a single physical port; perhaps using something like the logical interface naming scheme. However, no known usage case exists for this feature, so it need not be designed in detail now. Control/Status We will augment the existing ifconfig keywords to work with the existing "inet6" keyword. This allows a simple means of querying status and stopping/starting DHCPv6 on an interface without the use of in.ndpd. The existing dhcpinfo command will get a new option to query DHCPv6 parameters. This may be "-v 6". The default will remain IPv4. The dhcpagent -a (adopt) flag will not work for DHCPv6. The boot infrastructure doesn't support IPv6, and the existing adoption logic is complex and largely unnecessary. Apart from this project, steps should be taken to remove that feature. Primary Interface The existing DHCPv4 implementation has a concept of a "primary interface." When dhcpinfo is invoked without specifying a particular interface, the system uses the "primary interface" as the source for that data. While this mechanism is somewhat unsatisfactory in complex environments, we do need to retain this functionality until Network Automagic (NWAM) can supplant it. To this, we will treat a single interface as "primary" for both DHCPv4 and DHCPv6. When a given IPv4 logical interface is marked as "primary," the DHCPv6 session on the same physical interface (if any) will be treated as "primary" as well. If a DHCPv6 interface is marked as primary, then the first DHCPv4 logical interface (if any) will be treated as primary as well. DLPI Because DHCPv6 uses link-local addresses, it's not necessary for the agent to do any raw DLPI processing. None of the existing DLPI processing in dhcpagent will be touched, nor should DLPI support be needed in the future. Client Broadcast All messages sent to a DHCPv6 client are (currently) unicast, so it's not necessary to support a separate broadcast or multicast bound socket, as is currently done for IPv4 DHCP. It's possible that some future extensions to DHCPv6 may need this support. Standalone There is no DHCPv6-based install support, so none of the DHCP support functions need to be placed under $SRC/common. This may be necessary in the future. Snoop Snoop will be enhanced to support DHCPv6 filtering and decoding. Related Projects - Zones There's no IPv4 DHCP support for zones today and little IPv6 support (lacking autoconf). If we support IPv4 DHCP in the future in Zones, then DHCPv6 should also be enhanced to work in Zones. The same issues apply: you will need a separate DUID for each non-global zone. We can use enterprise DUIDs with the zone UUID for this feature. - Stack Instances To the extent that IPv6 autoconfigured (stateless) addressing works with stack instances, DHCPv6 should work without trouble. It's essentially the same set of requirements: we need just a link-local address and a DUID. (Unlike IPv4 DHCP, it does not require raw DLPI access, so it's even simpler.) - Quagga/Zebra If Quagga gets RA sender-side code, then it will have to deal with the existing ``A'' ("autonomous") flag for stateless address autoconfiguration. It should deal with the ``M'' and ``O'' bits in an analogous way. An unclear part is how to make Quagga set these latter two bits automatically when a DHCPv6 server is present and running. It likely should do so to reduce administrative burden (and likelihood of misconfiguration), but the means for doing so are unclear. This project doesn't deliver a DHCPv6 server, so this issue doesn't have to be resolved now. - Jumpstart/Miniroot No support. Neither GRUB nor OBP will be enhanced to support booting the system over IPv6, and until that support is available, there's no reason for DHCPv6 to run when net-booting. Out Of Scope This project delivers only the DHCPv6 functionality itself. It does not enhance other services (such as the name service client) to take advantage of the new features. Future projects should address these issues. Interoperability Several different servers need to be checked out, including WIDE-DHCP, Dibbler, and (if available) ISC's and Cisco's. The WIDE server has been ported to Solaris and the patches have been sent back to the maintainers. Comparisons TBD: need to check how Linux configures DHCPv6. Based on the documentation, it doesn't look like it conforms with the RFCs, because it doesn't seem to be controlled by the RA bits. Instead, it appears to be manually configured. Should also check other vendors (IBM, HP, Microsoft) if possible. Supported RFCs RFC 3315, "Dynamic Host Configuration Protocol for IPv6 (DHCPv6)." RFC 3319, "Dynamic Host Configuration Protocol (DHCPv6) Options for Session Initiation Protocol (SIP) Servers." RFC 3646, "DNS Configuration options for Dynamic Host Configuration Protocol for IPv6 (DHCPv6)." RFC 3736, "Stateless Dynamic Host Configuration Protocol (DHCP) Service for IPv6." RFC 3898, "Network Information Service (NIS) Configuration Options for Dynamic Host Configuration Protocol for IPv6 (DHCPv6)." RFC 4075, "Simple Network Time Protocol (SNTP) Configuration Option for DHCPv6." RFC 4280, "Dynamic Host Configuration Protocol (DHCP) Options for Broadcast and Multicast Control Servers." Drafts And RFCs To Ponder RFC 3633, "IPv6 Prefix Options for Dynamic Host Configuration Protocol (DHCP) version 6." RFC 4076, "Renumbering Requirements for Stateless Dynamic Host Configuration Protocol for IPv6 (DHCPv6)." RFC 4242, "Information Refresh Time Option for Dynamic Host Configuration Protocol for IPv6 (DHCPv6)." RFC 4477, "Dynamic Host Configuration Protocol (DHCP): IPv4 and IPv6 Dual-Stack Issues." RFC 4580, "Dynamic Host Configuration Protocol for IPv6 (DHCPv6) Relay Agent Subscriber-ID Option." RFC 4649, "Dynamic Host Configuration Protocol for IPv6 (DHCPv6) Relay Agent Remote-ID Option." RFC 4701, "A DNS Resource Record (RR) for Encoding Dynamic Host Configuration Protocol (DHCP) Information (DHCID RR)." RFC 4704, "The Dynamic Host Configuration Protocol for IPv6 (DHCPv6) Client Fully Qualified Domain Name (FQDN) Option." draft-ietf-dhc-dhcvp6-leasequery-00.txt, "DHCPv6 Leasequery." draft-ietf-dhc-dhcpv6-reconfigure-rebind-01.txt, "Rebind Capability in DHCPv6 Reconfigure Messages." draft-ietf-dhc-dhcpv6-opt-dnsdomain-03.txt, "Domain Suffix Option for DHCPv6." draft-ietf-dhc-dhcpv6-clarify-auth-01.txt, "Clarifications on DHCPv6 Authentication." draft-ietf-dhc-paa-option-04.txt, "DHCP options for PANA Authentication Agents." draft-ietf-dhc-dhcpv6-agentopt-delegate-01.txt, "DHCPv6 Relay Agent Assignment Notification (RAAN) Option." draft-ietf-dhc-timezone-option-05.txt, "A Timezone Option for DHCP." draft-ietf-dhc-dhcpv6-ero-00.txt, "DHCPv6 Relay Agent Echo Request Option." draft-ietf-dhc-dhcpv6-srsn-option-00.txt, "DHCPv6 Server Reply Sequence Number Option." draft-ietf-nemo-dhcpv6-pd-02.txt, "DHCPv6 Prefix Delegation for NEMO." draft-ram-dhc-dhcpv6-aakey-01.txt, "Authentication, Authorization and key management for DHCPv6." draft-ram-dhc-dhcpv6-diam-app-01.txt, "DHCP Diameter Application." draft-zhao-dhc-dhcpv6-relay-link-selection-00.txt, "DHCPv6 Relay Agent Link Selection(RALS) Option."