Pegasus Enhancement Proposal (PEP)

PEP #: 291 

PEP Type:  Functional

Title: OpenPegasus Support for IPv6: Stage 1

Version: 1.2

Created: 22 Jan 2007

Authors: Jun Feng Liu / Dave Sudlik / Venkateswara Puvvada

Status:  approved

 

Version History:

Version Date Author Change Description
0.1
22 Jan 2007
 Jeff / Dave
Initial Submission
 1.0 04 June 2007  Dave / Venkat
Full rewrite based on initial feedback and some implementation experience.
1.1
11 June 2007
Dave
Updates from first review. This includes:
  • terminology standardization and update (dual stack vs dual IP layer)
  • add information and links on platform support, including clarifying IPv6 support on different versions of Windows
  • change PEGASUS_DISABLE_IPV6 to PEGASUS_ENABLE_IPV6

1.2
14 June 2007
Dave
Updates from Arch review on June 12/13. These updates clarify the distinction between :
  • A "hostname", which can be the name of a host as resolved by a DNS, an IPv4 address in dotted decimal notation, or an IPv6 address with no enclosing brackets.
  • A URL, which can contain a hostname as one of its components. In this case an IPv6 address must be enclosed by brackets, whether it is followed by an optional colon and port number or not.

 


Abstract: OpenPegasus currently only supports connections via the IPv4 Internet Protocol. This PEP describes the changes necessary to add IPv6 support into OpenPegasus.  The Phase 1 Support provided by this PEP is defined to meet a specific required subset of IPv6. A subsequent Phase 2 PEP will provide additional functionality (see Future Work section below).




Definition of the Problem

OpenPegasus currently only supports connections via the IPv4 Internet Protocol. This PEP describes the changes necessary to add IPv6 support into OpenPegasus. Basically, the IPv6 design should meet following requirements:

This PEP does not propose an IPv6-only mode for the CIM Server.

IPv6 support is being driven by the U.S. Federal Government, with a June 30, 2008 target date. For more information see:
http://www.whitehouse.gov/omb/egov/b-1-information.html#IPV6

Terminology

There does not appear to be an industry-standard terminology for describing an IPv4/IPv6 platform implementation, so this PEP will use the following, which comes from the Windows world, since that appears to be where this distinction is most relevant:

Dual Stack Architecture -- An architecture which  has separate protocol components for IPv4 and IPv6. The separate IPv4 and IPv6 protocol components have their own Transport Layer that includes TCP and UDP and framing layer. Windows XP and Windows Server 2003 use a dual stack architecture (refer to https://www.microsoft.com/technet/community/columns/cableguy/cg1005.mspx).

Dual IP Layer Architecture -- An architecture in which both IPv4 and IPv6 share common Transport and Framing layers.  Windows Vista, Windows Server 2008, and Linux (among others) use (or will use) a Dual IP Layer Architecture.

The important distinction between these two Architectures is that in a Dual Stack Architecture, IPv6 connectivity is independent of IPv4 connectivity. This means separate sockets are required for IPv4 and IPv6 connections on Windows XP. However, in a Dual IP Layer Architecture, both IPv4 and IPv6 traffic are supported over an IPv6 connection (ie. with the AF_INET6 address family, applications can accept client requests for either IPv4 or IPv6 nodes or from IPv6 nodes only).

This PEP also makes the distinction between:
Whenever a user inputs the identity of an Internet host, it SHOULD be possible to enter either (1) a host domain name or (2) an IPv4 address in dotted-decimal ("#.#.#.#") form. The host SHOULD check the string syntactically for a dotted-decimal number before looking it up in the Domain Name System.

For IPv6, a hostname will be extended to also include an IPv6 address in the the format normally used, which is up to 8 groups of 4 hexadecimal digits, each group separated by a single colon. There is also an abbreviation allowed that replaces contiguous groups of  zeros (0x0000) with a double colon, but only one double colon is allowed to avoid ambiguity. See RFC 2373 for more details.

In OpenPegasus, this distinction between an IPv6 address specified as a standalone hostname or in a URI is the basis for the syntax that is used. If an IPv6 address is used as a standalone hostname (eg. with the cimperf -h parameter), then it must be specified as up to 8 groups of 4 hex digits separated by colons, as defined by RFC 2373, with no enclosing brackets. If an IPv6 address is used as part of a URI, then it must always be enclosed by brackets (eg. as a host parameter on the CIMObjectPath constructor, the Destination property of a CIM_IndicationHandlerCIMXML object, or as the cimcli location parameter which includes an optional port number).

Platform Support

The following test will check whether your current running kernel supports IPv6:
# test -f /proc/net/if_inet6 && echo "Running kernel is IPv6 ready" (note: maybe this can be used to determine IPv6 support on Linux, see Future Work item #5).

If desired, I will add other platform support information as supplied by platform maintainers.

Proposed Solution

These are the key points that will be addressed by this PEP.
https://[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:5989/cimv2:CIM_RegisteredProfile.InstanceID="acme:1"

In this case, the brackets enclosing the IPv6 address are required, even if the port number is omitted.
These changes to various aspects of Pegasus can be summarized as follows:

IPv6/IPv4 interoperability

These updates to support IPv6 will not affect any existing OpenPegasus users. That is, the IPv6 feature will have the capability to handle both IPv4 and IPv6 client connections. So a CIM Client which connects to an IPv4 interface can continue to work with the IPv6-enabled CIM Server. Indications can be directed to either IPv4 or IPv6 Destinations. The interface between the CIM Server and Providers has no changes, so existing providers can be loaded and invoked correctly with an IPv6-enabled CIM Server.

IPv6 Background Info

An administrator can configure the system running the CIM Server to listen on IPv4 and/or IPv6 interfaces. When the CIM Server binds to the IPv6 wildcard address (in6addr_any), it will accept either IPv4 or IPv6 connections (there is a restriction on Windows XP and Windows Server 2003, which require separate connections for IPv4 and IPv6). The following figure illustrates possible connections to an IPv6-enabled CIM Server.


In this diagram there is both a CIM Client connected via an IPv4 interface and a CIM Client connected via an IPv6 interface. The CIM Server (on the right) is IPv6-enabled and it is running on a "Dual IP Layer Architecture" host. The server has created an IPv6 listening TCP socket that is bound to the IPv6 wildcard address and TCP port 5988.

The wildcard and loopback addresses are different between IPv6 and IPv4. Refer to the following table. If the CIM Server is listening on an IPv6 wildcard address it can receive both IPv6 and IPv4 connections (This, and much of the following discussion, is not true for Windows XP and Windows Server 2003, instead separate connections are required).

 

Feature

IPv4

IPv6

Wildcard address

INADDR_ANY

in6addr_any

Loopback address

INADDR_LOOPBACK (127.0.0.1)

in6addr_loopback
(::1)


When the system (data link tier) receives an IPv4 packet, it detects that the destination socket is an IPv6 socket, and the source IPv4 address in the IPv4 header is converted into the equivalent IPv4-mapped IPv6 address, for example, 9.181.64.75 maps to ::FFFF:9.181.64.75. This mapped address is returned to the IPv6 socket as the client's IPv6 address when accept returns to the server with an IPv4 client connection. All remaining data grams for this connection are IPv4 data grams.

As another scenario, consider the IPv6-enabled CIM Client connecting to a CIM Server through an IPv4 interface.  The CIM Client should use getaddrinfo to look up the IPv6 address. it requests the AF_INET6 address family and sets the AI_V4MAPPED flag in its hints structure.  Since the CIM Server is running on an IPv4-only host and creates an IPv4 listening socket, the CIM Client can get an IPV4-mapped IPv6 address though getaddrinfo. The Client can use the mapped IPv6 address to connect to the IPv4 CIMServer .

Note: An administrator can choose to config the host running the CIM Server with IPv6-only interface(s). In this case a connection from an IPv4 client cannot be made.

The socket() APIs use the address family to create a socket that can utilize IPv6.  The following table shows the difference between the IPv4 and IPv6 address families.

Address Family

Type

Protocol

AF_INET

SOCK_STREAM

TCP

 

SOCK_DGRAM

UDP

 

SOCK_RAW

IP, ICMP

AF_INET6

SOCK_STREAM

TCP

 

SOCK_DGRAM

UDP

 

SOCK_RAW

IPv6, ICMPv6

 

The following table compares the different IPv4 and IPv6-enabled APIs. Client and Server socket API will be modified to support IPv6.



IPv4

IPv6

Comments

Data Structure

AF_INET

AF_INET6

 

 

in_addr

socketaddr_in

in6_addr

sockaddr_in6

 

Name to address Function

inet_aton

inet_addr

inet_pton

inet_pton supports both IPv6 and IPv4

 

inet_ntoa

inet_ntop

inet_ntop supports both IPv6 and IPv4

Address Convert funtion

gethostbyname

gethostbyaddr

getipnodebyname(obsolete)

getipnodebyaddr(obsolete)

getnameinfo

getaddrinfo

gai_strerror

getnameinfo and getaddrinfo support both IPv6 and IPv4. getipnodebyname and getipnodebyaddr are obsolete APIs and are not recommended.


CIM Standards and RFC considerations

DSP0207 (WBEM URI):  This standard describes the WBEM (CIM) customizations to the IETF URI standard.  CIM uses URI to locate CIM objects on the network.  Other CIM standards point to this standard (e.g. CQL standard).  This standard is based on RFC 3986, which allows IPv6 addresses. The spec refers to the RFC standard which defines the detail of the IPv6 URI.  RFC2732 states that IPv6 addresses in URIs shoult be delimited by square brackets [ ] (in OpenPegasus the brackets are required here). for example,
– https://[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:5989/cimv2:CIM_RegisteredProfile.InstanceID="acme:1"

DSP0004 (CIM Infrastructure):  This is the CIM meta-model.  It describes how to create a model (schema), the datatypes, the object structure, qualifiers, etc.  There is a section about Naming which describes the object path but does not specify its format.

DSP0202 (CQL Standard) document references DSP0207 and DSP0004 for object paths, so there is no design impact for the CQL standard. The CQL standard itself does not specify the format of the object path.

DSP0201 (CIM-XML):  This references the other standards, so is not applicable.

DSP0200 (CIM-HTTP):  Pegasus CIMHttpAuthenticatorDelegator and CIMOperationRequestDecoder parse the CIMObject HTTP header.  The CIM-HTTP spec references RFC 2616 (HTTP 1.1) which references RFC 2393. The document that defined the URI for IPv4 is obsolete now, and the latest RFC2732 defined the URI for IPv6.

To summarize, the biggest impact is the IPv6 URI, IPv6 addresses in URIs should be delimited by square brackets [ ] and are required by OpenPegasus.


Command Line Parameter Validation

In order to support both IPv4 and IPv6 connections, a CIM client should accept an IPv6 format IP address. A command line utility like cimcli will need to be updated to parse the input to get the correct host/IP value and port value. For example, IPv4-specific code like this needs to be updated:
            
Uint32 index = opts.location.find (':');
String host = opts.location.subString (0, index);

A new class HostAddress has been introduced to address this problem. It will provide a single point where "host" information can be encapsulated (where the host is identified by a hostname, IPv4 address, or IPv6 address).  All Pegasus code that handles or manipulates host information will be modified to use this new HostAddress class.

This is the list of changes required for external command line interfaces:
In addition, the following non-external command line interfaces and test tools will be updated:
As an example, the following IPv6 address parameters are valid:
The following addresses are invalid:

Connectivity Support

Server Support

The HTTP connection tier must be compatible with both IPv6 and IPv4 systems. On Linux (and other POSIX platforms), Windows Vista, and Windows Server 2008, a "Dual IP Layer Architecture" system is implemented which can support both IPv4 and IPv6 connections using address family AF_INET6 and specifying in6addr_any as the bind address. In this case both IPv4 and IPv6 connections are accepted on the same socket. HTTPAcceptor will be updated to use the IPv6 APIs and structures on these systems.

Client Support

The HTTP connection tier must change to IPv6 format. If the client run on "Dual IP Layer Architecture" system, then it supports both IPv4 and IPv6 connections. It should try both IPv4 and IPv6 connections, since the server may listen on either an IPv4 port or IPv6 port. Protocol family PF_UNSPEC can make the socket accept either an IPv4 or IPv6 connection. With the setting we can get the address list included both IPv4 and IPv6 through getaddrinfo. Then the client connect code can try them one by one till find one that can connect to cimserver succesfully.

Indication Transport Support

CIMXML indication transport depends on HTTPConnector to send indication to remote listener. HTTPConnector is covered by the Client side IPv6 modifications.


Provider considerations

Since the interface between the Pegasus CIM Server and providers is unchanged, all existing providers will continue to get control without modification when the CIM Server is IPv6-enabled. Providers that manipulate host addresses (eg. with CIMObjectPath::getHost()) must be aware of the potential of receiving IPv6 bracketed addresses and handle them correctly.

Compliance with CIM standards and IETF RFCs

CIMObjectPath

According to the CIM specification CIM objects can be located by hostname and namespace. CIMObjectPath code currently parses the host name assuming an IPv4 format, (refer to _parseHostElement and isValidHostname). The logic has to be modified to accept IPv6 format addresses. CIMObjectPath provides the getHost function to return the name of the host. There are areas in the Pegasus code where the value of the host name and port are parsed, and these will be updated to support IPv6.

A sample IPv6 object path should looks like: – https://[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:5959/cimv2:CIM_RegisteredProfile.InstanceID="acme:1"

Indication Subscription

Pegasus Indication Handlers use the "Destination" property to describe the receiver of the indication. The CIMxmlIndicationHandler::handleIndication() code parses the destination to get the hostname and port name. This code will be updated to use the new HostAddress class to encapsulate the IPv4 vs IPv6 logic. The format should follow RFC2732 (Format for Literal IPv6 Addresses in URL's).

A sample IPv6 subscription should looks like: – http://[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:5988/CIMHandle/SimpleConsumer

CIMObject Http Header

The HTTP header contains host information. The following functions check the tag, but they have no validation logic for the host name format, so no changes are required.
    void CIMOperationRequestDecoder::handleHTTPMessage(HTTPMessage* httpMessage)
    void CIMExportRequestDecoder::handleHTTPMessage(HTTPMessage* httpMessage)

According to RFC 2616(HTTP1.1) and RFC2732 (IPv6 URI),  The Host request-header field should follow the format: Host = "Host" ":" host [ ":" port ], and in IPv6 is should looks like Host:[2002:9b5:8255::9b5:8255]:8080 So the encoder of the HTTP header will be updated to follow this standard.

Other Common Support

Boolean System::_acquireIP(const char* hostname, int *af, void *dst) IS CHANGED (including new interface)
Boolean System::getHostIP(const String &hostname, int *af, String &hostIP) IS CHANGED (including new interface)
Boolean System::isLocalHost(const String &hostName) IS CHANGED
Boolean System::isLoopBack(int af, void *binIPAddress) IS NEW
Boolean System::sameHost(const String & hostName) HAS BEEN DELETED

Note that these changes were able to be done in a platform-independent way, so no changes to SystemPOSIX.cpp or SystemWindows.cpp were necessary.

Monitor

void Monitor::initializeTickler() uses the IPv4 loopback address(hard code 127.0.0.1) to initiliaze the ticker server and client. Since the socket is just used by the cimserver to control the moniter loop, no change is necessary here.

SLP Support

The CIM Server supports registering itself with the SLP agent (SA or DA) when it starts up. The registration contains a URL to locate the CIMServer, which is built around an IP address obtained from the Interop control provider through a combination of the System::getHostName() and System::getHostIP() functions. It is expected that this will be an IPv4 address, but if an IPv6 address is returned the Pegasus SLP registration code will be able to handle it (these URLs are actually handled as Strings).

The issue, however, may be in the SLP implementation to support IPv6 addresses. The OpenSLP roadmap indicates this is a "medium" priority item that is currently unassigned (http://openslp.org/roadmap.html). There is no plan to update the Pegasus internal SLP implementation. So this restriction will be documented in the OpenPegasus Readme, and in PEP 292 under the PEGASUS_ENABLE_SLP environment variable and the "slp" config property.

Note: While Pegasus supports registering an IPv6 URL with an SLP agent (SA or DA), you must ensure that the SLP agent you are using supports IPv6 (namely, RFC 3111). As of this writing, OpenSLP does not have this support, and there is no plan to add it to the OpenPegasus internal SLP support. You can get around this restriction by ensuring the system on which the CIM Server is running has a hostname associated with an IPv4 address.

Build Compatibility

The PEGASUS_ENABLE_IPV6 environment variable allows a builder to specify if IPv6 support should be enabled or disabled. If PEGASUS_ENABLE_IPV6 is set to "false", the "old" IPv4 socket APIs will be used. Note that all IPv4 and IPv6 structures and APIs are in the same header files. The following will be added to PEP 292:

PEGASUS_ENABLE_IPV6

Test considerations

The testing goals of this PEP are:

For the last 3 scenarios, the tests will be performed with client and server on separate systems. Existing clients will be used (eg. cimcli, TestClient) with host explicitly specified. Instructions on how to do this will be provided as a separate document.

These tests include, but are not limited to, the following:

Future Work

The section discuss the work that not covered by this PEP, but will be implemented as part of a subsequent PEP.

  1. Update the Pegasus internal SLP agent to support IPv6 URLs.
  2. snmpIndicationHandler needs to be updated. For example, look at snmpDeliverTrap_emanate::deliverTrap(), which supports targetHostFormats of hostname and IPv4 address.
  3. Pegasus has many providers and clients that it uses for test (and other) purposes. Many of these have clients that use connectLocal(). We have made (or will make) an attempt to verify with and convert to IPv6 as many of these as possible (often with minimal to no changes) for IPv6 testing purposes, but some work in this area may remain.
  4. Remote CMPI will continue to use IPv4 addresses when defining the remote namespace, and IPv4 socket APIs when communicating between the broker and remote provider(s). This will be updated as part of the "stage 2" work.
  5. Investigate into whether it is possible to determine at build time if a platform has support for IPv6, and set PEGASUS_ENABLE_IPV6 accordingly.
  6. Investigate into combining platform-specific versions of System::getFullyQualifiedHostName() into a single version that uses getaddrinfo() (similar to what the z/OS version already does).

Rationale

Schedule

Action Planned Actual Comment
PEP Submitted 06/06/2007
 06/06/2007  
PEP Reviewed 06/08/2007
06/08/2007

Code available in branch
06/07/2007
06/08/2007

PEP Approved 06/19/2007


Code Committed 06/26/2007


Discussion

Comments from 1.0 version review:

[ (m_brasher) Are there defined macros on some platforms that tell us whether IPV6 support is present. This may avoid the need to define PEGASUS_DISALBE_IPV6 on platforms that do not support IPV6.
¤53]
A new build option PEGASUS_DISABLE_IPV6 is introduced. By default Peagsus 2.7 will be built with IPv6 support enabled, but this build option is available for platforms that do not support the new IPv6 socket APIs.

[ (r_kumpf) Is this specific to indication delivery via CIM-XML, or does it also include email and SNMP indication delivery?
(dave_sudlik) This is specific to CIM-XML indication delivery. SNMP is listed as a future work item (tag 348) -- the code change to the snmpIndicationHandler is fairly minor, but we don't have time for the testing and still make our 2.6.1 date. It's not a 2.6.1 priority for us, but this is something that we could do for 2.7 for completeness. There is no change required for the email handler. I will update the PEP to clarify our actions regarding indication handlers, and also to clarify which of the 'future work' is planned for a 2.7 'phase 2'.
¤63]
Indications. Support will be added to allow an IPv6 address to be specified in the Destination field of the Handler.

(r_kumpf) How unfortunate that Unix shells will interpret the brackets as a matching expression. In practice, the IPv6 arguments will need to be quoted for protection from the shell.
(dave_sudlik) I *think* that brackets are only recognized as a regular expression set construct wildcard if they contain (aside from alphanumerics) a period, comma or semicolon, or dash or underscore. Since IPv6 bracketed addresses only contain colons, I don't believe they are recognized in this way. At least that's been our experience during testing, no escaping from the shell has been necessary.
(venkat_puvvada) Brackets are only necessory when port is specifiled along with IPv6 address when specified at command line. For example ::ffff:9.12.34.44 or <::ffff:9.12.34.44>:5988 , but both ways are accepted.

[ (k_schopmeyer) Somehow we are going to have to add error checking so that an error like handling IPV6 DA, etc. is caught earlier rather than later in the process.> Also, note that there are today only about two contributors to OpenSLP, Novell and WbemSolutions so we probably need to get a better idea of the whens on this functions availability
(dave_sudlik) There is some error checking, will need to determine what happens if fed an IPv6 address.
¤309]

[ ¤310] Note: While Pegasus supports registering an IPv6 URL with an SLP agent (SA or DA), you must ensure that the SLP agent you are using supports IPv6 (namely, RFC 3111). As of this writing, OpenSLP does not have this support, and there is no plan to add it to the OpenPegasus internal SLP support. You can get around this restriction by ensuring the system on which the CIM Server is running has a hostname associated with an IPv4 address.

[ ¤324] The testing goals of this PEP are:
[ (r_kumpf) Which tests will become part of the automated suite? For tests that must be run manually, it would be great to have instructions on how to run them.
(dave_sudlik) The 'major' ones: TestClient, g11ntest, IndicationStressTest. I asked Venkat to produce a doc describing how he tested. He had previously done 'one-off' updates of the testcases for his tests, but for this set we will modifiy them so that they will test using both IPv4 and IPv6 loopbacks, for example.
¤325]



Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
EMC Corporation; Symantec Corporation; The Open Group.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


 

Template last modified: March 26th 2006 by Martin Kirk
Template version: 1.11