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:
- Source
and binary compatible with
existing IPv4 clients and providers.
- New
support for IPv6 clients.
- Seamless
IPv6/IPv4 interoperability
- Compliance
with CIM standards and
IETF RFCs.
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:
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:
- A "hostname", which was
originally defined by RFC 952 and updated in RFC 1123 (section 2.1),
and states:
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.
- A URI (including URLs),
which has a component that is a hostname as defined above. If the
hostname component of a URI is an IPv6 address, then it must be
enclosed in brackets ( '[' and ']' ). See RFC 2396 (base) and RFC 2732
(IPv6 update) 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
- (Windows Platform info received
from: https://www.microsoft.com/technet/network/ipv6/ipv6faq.mspx)
- IPv6 is not supported on Windows
2000, Windows 98, and older versions of Windows.
- IPv6 is supported on Windows
Server 2003 and Windows XP with SP1 or SP2.
- IPv6 is installed, enabled,
and preferred by default in Windows Vista and Windows Server 2008. If
desired, you can completely disable IPv4 and use Windows Vista
computers in an IPv6-only networking environment. Note that with this
PEP, you can not disable IPv4 support in the CIM Server, and it will
not run in an IPv6-only networking environment. However, it will
run on a system that only has IPv6 network interfaces defined, as long
as the IPv4 support is still available.
- To build OpenPegasus with
IPv6 enabled, you need:
- Microsoft Platform Software
Development Kit (SDK), January 2000 or later (available from the MSDN
Web site).
- Microsoft Visual C++ version 6.0
or later.
- A computer running Windows
Server 2003, Windows XP with SP2, or Windows XP with SP1, with IPv6
installed (to install, use ipv6.exe, enter with no parameters for
syntax). Or Windows Vista (IPv6 installed and enabled by default) or
Windows Server 2008 (still in beta as of this writing).
- Linux (from http://tldp.org/HOWTO/html_single/Linux+IPv6-HOWTO/):
Modern Linux distributions
already contain IPv6-ready kernels, the
IPv6 capability is generally compiled as a module, but it's possible
that this module is not loaded automatically on startup.
Note:
you shouldn't anymore use kernel series 2.2.x, because it's not
IPv6-up-to-date anymore. Also the IPv6 support in series 2.4.x is no
longer improved according to definitions in latest RFCs. It's recommend
to use series 2.6.x now.
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.
- A new build option PEGASUS_ENABLE_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. A question
was raised as to whether it
would be possible to determine at build time if IPv6 support is
available and set the PEGASUS_ENABLE_IPV6 macro accordingly. I have not
been able to find a standard way to do this. It might be possible if,
for example, a known IPv6 definition is supplied as a macro on all
platforms. This will not be addressed in this PEP, but has been added
as a future work item.
- Add support for the new IPv6 wildcard address (in6addr_any),
which will be used by the server to bind to any IPv4 or IPv6 connection
from any network interface. Note
that this is not true on Windows XP, which instead requires separate
socket connections for IPv4 and IPv6.
- Support for new IPv6 loopback ("::1"). Since the CIM Server
will always be enabled to accept IPv4 connections (either alone or in
conjunction with IPv6), existing internal usage of the IPv4 loopback
(127.0.0.1) does not need to be changed (eg. Monitor tickle socket).
Command line utilities that allow a hostname or URI to be specified,
as well as
the Client connect() APIs, will continue to support the IPv4 loopback,
and will also support the IPv6 loopback.
- If IPv6 is enabled, the new IPv6 socket APIs will be used:
inet_pton(), inet_ntop(), getnameinfo(), getaddrinfo(). These APIs
support both IPv4 and IPv6. This
is true for all platforms.
- The CIMObjectPath class will be modified to support "bracketed"
IPv6
addresses in the WBEM URI. See the section CIM
Standards and RFC Considerations. So, for example, the following
will be allowed if IPv6 is enabled:
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.
- The HTTP header currently allows for a host name to be specified,
but no validation is done on it.
- The CIMxmlIndicationHandler
will be updated for CIM-XML indication delivery to allow a URI
containing an IPv6 address (with
required enclosing brackets) to be specified in the Destination
property
of a CIM_IndicationHandlerCIMXML object.
- The snmpIndicationHandler
will not be updated by this PEP, see Future Work
item #2.
- No changes to the
EmailListenerDestination or SystemLogListenerDestination handlers is
required.
- Providers may receive CIMObjectPaths that have an IPv6 bracketed
address in the URI. If necessary, these providers will need to be
updated to handle this. There are no changes to any Provider interface.
- CIMListener and
DynamicListener -- changes to HTTP* classes for IPv6 will bring
along
IPv6 support. The only consideration is that if an IPv6 destination
address is
specified in Handler, then the corresponding Listener must be built
with IPv6 enabled.
- Export Server -- changes to HTTP* classes for IPv6 will bring
along IPv6 support.
- Testing. Existing automated tests will be unchanged, and should
continue to work. New IPv6 tests will be created. More details below in
the "Testing" section.
- In this phase of the IPv6 support, there are no changes to the
SLP functionality. More details below.
These changes to various aspects of Pegasus can be summarized as
follows:
- Use new IPv6 socket structures and APIs, which provide support
for both IPv4 and IPv6.
- Where IP addresses can be
specified as a hostname, update to allow "non-bracketed" IPv6 addresses
to be accepted.
- Where IP addresses can be specified as part of a URI, update to
allow "bracket"
IPv6 addresses to be accepted.
- Where Pegasus code handles or manipulates host information, use a
new HostAddress class, which encapsulates all aspects of working with a
hostname or IP address (IPv4 or IPv6).
- Provide sufficient testing to cover all aspects of IPv6 support
(including IPv4 compatibility and disabling IPv6).
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:
- cimauth -- no change
- cimconfig -- no change
- cimmof -- no change
- cimprovider -- no change
- cimreparchive -- no change
- cimserver -- no change
- cimsub -- no change
- cimtrust -- no change
- cimuser -- no change
- osinfo -- the '-h' option will be updated to allow a
non-bracketed IPv6 address as a hostname
- wbemexec -- the '-h' option will be updated to allow a
non-bracketed IPv6 address as a hostname
In addition, the following
non-external command line interfaces and test tools will be updated:
- cimcli -- the '-l' option will be updated to allow a bracketed
IPv6 address as a location, followed by an optional colon and port
number (note that at some future time we may wish to migrate cimcli to
separate hostname and port options)
- cimperf -- the '-h' option will be updated to allow a
non-bracketed IPv6 address as a hostname
- TestG11n -- the host parameter(s) will be updated to allow a
bracketed IPv6 address as a location, followed by an optional colon and
port number
- TestClient -- the host parameter(s) will be updated to allow a
bracketed IPv6 address as a location, followed by an optional colon and
port number
As an example, the following
IPv6 address parameters are valid:
- cimcli -l
[2001:db8::1428:57ab]:5988 ns //
correct, the IPv6 address in URI-format must be
delimited by square brackets [ ]
- cimcli -l [3FFE:1::130] ns
//
correct format, square brackets [ ] are required even if port is not
specified
- cimcli -l 9.181.64.130:5988 ns
//
correct, IPv4 address does not require []
- cimcli -l 9.181.64.130 ns
- cimcli -l myHost.acme.com:5988
ns //
correct, host domain name does not require [ ]
- cimcli -l myHost ns
- cimperf -h
2001:db8::1428:57ab
// correct, the IPv6 address as a hostname must not be enclosed by
square brackets [ ]
The following addresses are
invalid:
- cimcli -l 3FFE:1::130:5988 ns
// invalid, the IPv6 address in URI-format must be delimited by square
brackets [ ]
- cimcli -l [hostname] ns
// invalid, host domain name does not require []
- cimcli -l [9.181.64.130]
ns
// invalid, IPv4 addresses do not require []
- cimperf -h
[2001:db8::1428:57ab]
// invalid, the IPv6 address as a hostname must not be enclosed by [ ]
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.
- Note: On Windows XP and Windows Server
2003, where a "Dual Stack Architecture" is employed, separate IPv4 and
IPv6 connections are required. This code will be conditionally compiled
for these platforms.
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
- HTTPAcceptor and HTTPAcceptorRep
constructors, HTTPAcceptor _bind() and _acceptConnection() methods
- HTTPConnector
_MakeAddress() and connect() methods
- System.cpp:
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.
- Code that has hardcoded
"127.0.0.1" or "0x7F000001" addresses to represent
localhost will be evaluated and updated to use the new HostAddress
class.
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
Description: This variable can be used to specify
whether IPv6 support should be included in OpenPegasus. When
this variable is set to "false", support for IPv6 socket APIs and
structures is
disabled, and the CIM Server will not accept connections to or from
IPv6 network interfaces. When
this variable is set to "true", the newer IPv6 socket APIs and
structures will be used, and must be supported on that platform.
Default Value: true
Recommended Value (Development Build): true
Recommended Value (Release Build): true
Required: No
Test
considerations
The testing goals of this PEP are:
- Add various Unit Tests (CIMObjectPath support for IPv6 addresses,
for example).
- No regression of automated tests. Some automated tests will
be add to connect to the IPv6 loopback (::1). These include
TestClient,
IndicationStressTestProvider, g11ntests,
TestProviders/MethodTestProvider, and all CMPI tests in TestProviders.
- Manual tests using
IPv4 network interfaces.
- Manual using IPv4
network interfaces where the IP address is
represented in IPv6 format (ie. ::FFFF:aaa.bbb.ccc.ddd).
- Manual using IPv6
network interfaces.
- Add specific command line
interface tests to check for correct handling of brackets on IPv6
addresses as hostnames (no brackets) or URIs (brackets required).
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:
- Test
CIMServer with IPv6 wildcard address. This is the default setting
of the CIM Server when enabled for IPv6, in which case the CIM Server
can accept both
IPv6 and IPv4 connections. Verify that the CIM Server
works with old IPv4 clients and new IPv6 clients.
- Testing
CIMServer with IPv4 enabled and IPv6
disabled (build with PEGASUS_ENABLE_IPV6 set to "false").
- Test
indications delivered to IPv6 destination.
- Run
existing SLP tests with IPv4 hostname.
- Run
MCCA_TestAssocProvider in "IPv6" configuration (tests
ManagedClient).
- Verify the operation of SLP with
hostname associated with an IPv4 address. Confirm proper error message
(if possible) from SLP when an IPv6 address is passed.
Future
Work
The section
discuss the work that not covered by this PEP, but will be implemented
as part of a subsequent PEP.
- Update
the Pegasus internal SLP agent to support IPv6 URLs.
- snmpIndicationHandler
needs to be updated. For example, look at
snmpDeliverTrap_emanate::deliverTrap(), which supports
targetHostFormats of hostname and IPv4 address.
- 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.
- 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.
- Investigate into whether it is possible
to determine at build time if a platform has support for IPv6, and set
PEGASUS_ENABLE_IPV6 accordingly.
- 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