HP-UX IPv6 Porting Guide HP-UX 11i v3 Manufacturing Part Number : B2355-91069 E0207 United States © Copyright 2007 Hewlett-Packard Company L.P. All rights reserved.
Legal Notices © Copyright 2004 Hewlett-Packard Development Company, L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice.
About This Document This document is intended to help HP-UX BSD Sockets Application Programmers port IPv4 network applications to IPv6. The document printing date and part number indicate the document’s current edition. The printing date will change when a new edition is printed. Minor changes may be made at reprint without changing the printing date. The document part number will change when extensive changes are made.
What’s In This Docuent The guide is organized as follows: 1 Introduction 2 IPv6 Addressing 3 Data Structure Changes 4 Migrating Applications from IPv4 to IPv6 5 Overview of IPv6 and IPv4 Call Set-up 6 Function Calls Converting Names to Addresses 7 Function Calls Converting IP addresses to Names 8 Reading Error Messages 9 Freeing Memory 10 Converting Binary and Text Addresses 11 Testing for Scope and Type of IPv6 addresses using Macros 12 Identifying Local Interface Names and Indexes 13 Configuring or Queryi
Table 1 HP-UX 11i Releases (Continued) Release Identifier Release Name Supported Processor Architecture B.11.22 HP-UX 11i v1.6 Intel® Itanium® B.11.20 HP-UX 11i v1.5 Intel® Itanium® B.11.11 HP-UX 11i v1 PA-RISC Related Documents HP Documentation Additional information about HP-UX IPv6 transport can be found within docs.hp.com in the networking and communications collection under IPv6 at: http://www.docs.hp.com/hpux/netcom/index.
HP Welcomes Your Comments HP welcomes your comments concerning this document. HP is committed to providing documentation that meets your needs. Please send comments to: netinfo_feedback@cup.hp.com Please include document title, manufacturing part number, and any comment, error found, or suggestion for improvement you have concerning this document. Also, please tell us what you like, so we can incorporate it into other documents.
1 Introduction This chapter provides a brief introduction, including comments about existing IPv4 applications, transitioning to IPv6, and some general terminology.
Introduction Why IPv6 Now? Why IPv6 Now? In the last five years, the Internet has transformed the way people live. The Internet’s tremendous growth rate greatly exceeded any futurist’s predictions, including the Internet Protocol (IP) architect’s plans from twenty years ago. IP version 4 (IPv4) provided ample addresses for network growth throughout the 1980s, but the address-supply is now low outside the United States.
Introduction Does implementing IPv6 require a complete transition from IPv4? Does implementing IPv6 require a complete transition from IPv4? No. Networks can migrate to IPv6 gradually, using transition mechanisms defined by IPv6 Protocol Specifications. IPv4 and IPv6 will coexist for a long time. IPv6 Protocol Specifications provide two major transition mechanisms: Dual Stack: Dual-stack hosts have both IPv4 and IPv6 interfaces configured and can communicate with both IPv4 and IPv6 hosts.
Introduction Terminology Terminology This section provides brief definitions of some common general IP and IPv6 terms. General IP Terminology Node: A device that implements IP (either IPv4 or IPv6 or both). Router: A node that forwards IP packets not explicitly addressed to itself. Host: Any node that is not a router. Link: A logical connection between two nodes. Here, a link is the layer below IP such as Ethernet, PPP, or ATM networks.
2 IPv6 Addressing This chapter describes basic IPv6 addressing information.
IPv6 Addressing Types of IPv6 addresses Types of IPv6 addresses IPv6 supports both single-destination (unicast) and multiple-destination (multicast) addresses. Addresses comprise three different scopes. IPv6 Address scope Link-local: An IPv6 address used over one local link; assigned during autoconfiguration. Global: An IPv6 address used throughout the Internet. An IPv6 node always has a link-local address. It may have one or more global addresses.
IPv6 Addressing Comparing IPv4 and IPv6 Addresses Comparing IPv4 and IPv6 Addresses IPv4 addresses are 32-bit addresses represented as four dotted-decimal octets Example: 10.1.3.7 IPv6 Addresses are 128-bit records represented as eight fields of up to four hexadecimal digits. A colon separates each field (:).
IPv6 Addressing Comparing IPv4 and IPv6 Addresses Table 2-1 (Continued) ::ffff:10.9.8.7 Combined hex and decimal format IPv6 addresses are classless, using Classless Internet Domain Registry CIDR format. The prefix follows the IPv6 address (”/”) and denotes the size of a subnet.
IPv6 Addressing IPv6 Address Types IPv6 Address Types Unicast Address Figure 2-2 Unicast Address Unicast addresses usually comprise a 64-bit prefix and a 64-bit interface ID. Figure 2-3 Unicast Prefix The 64-bit interface ID must be unique on the link. An interface ID often includes the interface Link-Layer Address. IPv6 Loopback Address The loopback interface uses the IPv6 loopback address for self-testing, by sending IP datagrams to itself.
IPv6 Addressing IPv6 Address Types Link-local Unicast Address The LAN segment is the scope of a Link-local Address, and is used for address autoconfiguration and neighbor discovery. Figure 2-4 Link-Local Unicast Address IPv6 Multicast Addresses IPv6 multicast addresses resemble IPv4 multicast addresses, but have an explicit field for address-scope.
IPv6 Addressing IPv6 Address Types Figure 2-5 Multicast Address Format Some Well-know Multicast Addresses FF02::1 All nodes (link-local) FF02::2 All routers (link-local) FF02::9 All Routing Information Protocol next generation (RIPng) routers (link-local) IPv6 Wildcard Addresses In IPv4, an application can let the system choose which source IP address to bind to a socket by specifying a wildcard address: the symbolic constant INADDR_ANY in the bind() function call.
IPv6 Addressing IPv6 Address Types NOTE • Only use the constant during initialization. For assignment, use the global variable named in6addr_any, of the type in6_addr structure. For example: Header file extern const struct in6_addr in6addr_any; struct sockaddr_in6 sin6; … sin6.
3 Data Structure Changes Chapter 3 13
Data Structure Changes IP Address Structure IP Address Structure Header file
Data Structure Changes Socket Address structure for 4.3BSD-based HP-UX Socket Address structure for 4.3BSD-based HP-UX Header file IPv4 Structure struct sockaddr_in { short sin_family; /*AF_INET */ u_short sin_port; /* transport layer port number */ struct in_addr sin_addr; /* IPv4 */ char sin_zero[8]; /* Unused */ }; IPv6 Structure struct sockaddr_in6 { sa_family_t sin6_family; /*AF_INET6 */ in_port_t sin6_port; /* transport layer port number.
Data Structure Changes Generic Socket Address Structure Generic Socket Address Structure Header file struct sockaddr_storage The sockaddr_storage data structure simplifies writing portable code across multiple address families and platforms. This data structure provides the following flexibility and consistency. • One simple addition to the sockets API that can help application writers is the struct sockaddr_storage structure.
4 Migrating Applications from IPv4 to IPv6 HP-UX supports two standard IPv4/IPv6 interoperability methods: Chapter 4 17
Migrating Applications from IPv4 to IPv6 IPv4/IPv6 Dual Stack • IPv4/IPv6 Dual-Stack • Tunneling: allows two IPv6 nodes to communicate by encapsulating IPv6 packets within IPv4 packets and routing them over an IPv4 network. IPv4/IPv6 Dual Stack HP-UX IPv6 supports a dual IPv4/IPv6 protocol stack. The Dual-Stack does not affect existing IPv4 source or binary files. Legacy IPv4-to-IPv4 applications follow existing code paths through the IPv4 module.
5 Overview of IPv4 and IPv6 Call Set-up This chapter provides an overview of the call set-up process for IPv4 and IPv6.
Overview of IPv4 and IPv6 Call Set-up Using AF_INET Socket for IPv4 UDP Communications Using AF_INET Socket for IPv4 UDP Communications Figure 5-1 1. Application calls gethostbyname() and passes the host name, host1. 2. The search finds host1 in the Name Service database and gethostbyname() returns the IPv4 address 1.2.3.4. 3. The application calls the socket() function to open an IPv4 AF_INET socket. 4. The application calls the send () function to the 1.2.3.4 address. 5.
Overview of IPv4 and IPv6 Call Set-up Using AF_INET6 Socket to Send IPv4 UDP Communications Using AF_INET6 Socket to Send IPv4 UDP Communications You can use the AF_INET6 socket for both IPv6 and IPv4 communications; IPv6 uses the POSIX function call getaddrinfo() rather than the IPv4 gethostbyname() function call. For IPv4 communications, create an AF_INET6 socket and pass it a sockaddr_in6 structure that contains an IPv4-mapped IPv6 address (for example, ::FFFF:1.2.3.4).
Overview of IPv4 and IPv6 Call Set-up Using AF_INET6 Socket to Send IPv4 UDP Communications 2. The search finds the IPv4 address 1.2.3.4 for host2 in the Name Service database. 3. Because getaddrinfo() had the AI_V4MAPPED flag set, the function returns the IPv4 –mapped address ::FFFF:1.2.3.4. 4. The application calls the socket() function to open an IPv6 AF_INET6 socket. 5. The application calls the sendto() function toward the ::FFFF:1.2.3.4 address. 6.
Overview of IPv4 and IPv6 Call Set-up Using AF_INET6 Socket to Receive IPv4 Communications Using AF_INET6 Socket to Receive IPv4 Communications An IPv6 application using an AF_INET6 socket can accept TCP connection requests from a remote IPv4 application. The example below is contrived to demonstrate an incoming IPv4 packet destined for an application’s IPv6 socket. In this overview diagram, an incoming IPv4 packet requests connection to an IPv6 socket.
Overview of IPv4 and IPv6 Call Set-up Using AF_INET6 Socket to Receive IPv4 Communications Here type is 0800, so the Ethernet driver strips-off the Ethernet header and passes the IPv4 packet to the IPv4/IP module. The IPv4/IP protocol stack passes the information and the IPv4-mapped IPv6 address (::FFFF:1.2.3.4) to the socket layer. 3. The application calls accept() to accept the remote connection request. The application was already listening on an established IPv6 socket. 4.
Overview of IPv4 and IPv6 Call Set-up Using AF_INET6 Socket for IPv6 Communications Using AF_INET6 Socket for IPv6 Communications For IPv6 communications, create an AF_INET6 socket and pass it a sockaddr_in6 structure that contains an IPv6 address that is not an IPv4-mapped IPv6 address (for example, 2fee:1212::200:2bff:fe2d:0c2c). The diagram below shows the sequence of events for an application that uses an AF_INET6 socket to send IPv6 packets. Figure 5-4 1.
Overview of IPv4 and IPv6 Call Set-up Using AF_INET6 Socket for IPv6 Communications 2. The search finds an IPv6 address for host6 in the hosts database, then getaddrinfo returns the IPv6 address 2fee:1212::200:2bff:fe2d:0c2c. 3. The application opens an AF_INET6 socket. 4. The application sends information to the 2fee:1212::200:2bff:fe2d:0c2c address. 5. The socket layer passes the information and address to the UDP module. 6.
6 Function Calls Converting Names to Addresses The existing gethostbyname() function still looks up IPv4 addresses for particular host names.
Function Calls Converting Names to Addresses IPv4-mapped.
Function Calls Converting Names to Addresses getaddrinfo(3N) getaddrinfo(3N) getaddrinfo() is a nodename-to-address and servicename-to-port-number function call. The protocol-independent function call complies with POSIX 1003.1g Draft 6.6 (1997). For more information refer to the getaddrinfo(3N) man page.
Function Calls Converting Names to Addresses getaddrinfo(3N) NOTE 30 Initialize the entire addrinfo data structure to zero before assigning hint values to ai_flags, ai_family, ai_socktype, or ai_protocol.
Function Calls Converting Names to Addresses getipnodebyname(3N) getipnodebyname(3N) An application program calls the getipnodebyname() function to performs lookups for IPv4/IPv6 hosts. NOTE Starting with HP-UX 11i v2, the getipnodebyname() function is entering OBSOLESCENCE, and will be OBSOLETED in a future HP-UX release. Therefore, it is recommended the getnameinfo() function be used instead.
Function Calls Converting Names to Addresses getipnodebyname(3N) 32 Chapter 6
7 Function Calls Converting IP addresses to Names The existing gethostbyaddr() function still looks up IPv4 host names for particular addresses.
Function Calls Converting IP addresses to Names IPv4-mapped.
Function Calls Converting IP addresses to Names getnameinfo(3N) getnameinfo(3N) The getnameinfo() function takes a socket-address structure and returns a node name or service name. Header Files #include #include Syntax int getnameinfo(const struct sockaddr *sa, socklen_t salen, char *host, size_t hostlen, char *serv, size_t servlen, int flags); The getnameinfo() function translates a socket address to a node name and service location.
Function Calls Converting IP addresses to Names getnameinfo(3N) • NI_NUMERICSERV: If set, getnameinfo() returns only service’s port number. • NI_NUMERICSCOPE: If set, getnameinfo() returns the numeric form of the scope-ID. It is ignored if the sa parameter is not an IPv6 address. • NI_DGRAM: If set, service is a datagram service (SOCK_DGRAM). Default: service is a stream service (SOCK_STREAM). This distinguishes between services for TCP and UDP that share port numbers (for example, 512 to 514).
Function Calls Converting IP addresses to Names getipnodebyaddr(3N) getipnodebyaddr(3N) The IPv6 getipnodebyaddr() function call improves upon the IPv4 gethostbyaddr() by adding an error number parameter. NOTE Starting with the HP-UX 11i v2 release, the getipnodebyaddr() function is entering OBSOLESCENCE, and will be OBSOLETED in a future HP-UX release. Therefore, it is recommended the getaddrinfo() function be used instead. Header Files #include #include
Function Calls Converting IP addresses to Names getipnodebyaddr(3N) How getipnodebyaddr() processes IPv4-compatible IPv6 addresses If af is AF_INET6, len equals 16, and the IPv6 address is an IPv4-mapped or an IPv4-compatible IPv6 address, then: 1. skip the first 12 bytes of the IPv6 address. 2. set af to AF_INET. 3. set len to 4. If af is AF_INET, lookup the name for the given IPv4 address; that is, query for a PTR record in the in-addr.arpa domain.
8 Reading Error Messages The IPv6 functions getipnodebyaddr(), getipnodebyname(), getaddrinfo(), and getnameinfo() return errors in a thread-safe structure. The gai_strerror() function call returns a character string describing the error code passed into it.
Reading Error Messages Header Files Header Files #include Syntax char *gai_strerror(int ecode); Parameters ecode: One of the EAI_xxx values defined in RFC 25333, “Basic Socket Extensions for IPv6”. The return value points to a string describing the error. If ecode is not one of the EAI_xxx values, the function returns a pointer to a string indicating an unknown error.
9 Freeing Memory The four IPv6 name and address conversion function calls all dynamically allocate memory. IPv6 provides two function calls to free memory.
Freeing Memory Freeing Memory from getaddrinfo() and getnameinfo() Function Calls Freeing Memory from getaddrinfo() and getnameinfo() Function Calls The function call freeaddrinfo() frees the memory of one or more addrinfo() structures returned by the getaddrinfo() or getnameinfo() functions. Header Files #include Syntax void freeaddrinfo(struct addrinfo *ai); Parameters *ai: pointer to the structure addrinfo.
10 Converting Binary and Text Addresses The IPv4 function calls convert IPv4 addresses as follows: Chapter 10 43
Converting Binary and Text Addresses Converting a Text Address to Binary The inet_aton() or inet_addr() functions convert dotted-decimal string (such as 10.9.8.7) to 32-bit binary in network byte order. inet_ntoa() converts 32-bit network byte order binary into dotted-decimal string (such as 10.9.8.7). Two new IPv6 functions convert both IPv4 and IPv6 addresses.
11 Testing for Scope and Type of IPv6 addresses using Macros Use the following macros to verify IPv6 address types. The first seven macros return true if the address is of the specified type, or false otherwise.
Testing for Scope and Type of IPv6 addresses using Macros address is a multicast address of the specified scope, or return false if the address is either not a multicast address or not of the specified scope. NOTE int int int int int int int IN6_IS_ADDR_LINKLOCAL and IN6_IS_ADDR_SITELOCAL return true only for the link-local scope or site-local scope IPv6 unicast addresses. These two macros do not return true for IPv6 multicast addresses of either link-local scope or site-local scope.
12 Identifying Local Interface Names and Indexes The IPv6 sockets API uses an interface index (a small positive integer) to identify the local interface joined to a multicast group. Interfaces are normally known by names such as "lan0”.
Identifying Local Interface Names and Indexes Name-to-Index On HP-UX implementations, when the system configures an interface, the kernel assigns a unique positive integer value (called the interface index) to that interface. These small positive integers start at one. Interface numbering is not necessarily contiguous.
Identifying Local Interface Names and Indexes Index-to-Name Index-to-Name The second function maps an interface index into its corresponding name. Header Files #include Syntax char *if_indextoname(unsigned int ifindex, char *ifname); The ifname parameter must point to a buffer at least IF_NAMESIZE bytes large. The function returns to ifname the interface name of the specified index. (IF_NAMESIZE is also defined in
Identifying Local Interface Names and Indexes Freeing Memory The if_nameindex() function acquires memory dynamically for the array of if_nameindex structures and for if_name’s interface names. The if_freenameindex() function frees that memory. Freeing Memory The if_freenameindex() function frees the dynamic-memory allocated by if_nameindex(). Header Files #include
13 Configuring or Querying an Interface using IPv6 ioctl() Function Calls Certain IPv4 applications need detailed configuration information for a network interface of a node.
Configuring or Querying an Interface using IPv6 ioctl() Function Calls calls, as defined in /usr/include/sys/ioctl.h, to determine the characteristics of the network interfaces and their attributes. All of the IPv4 SIOC* ioctl() function calls use the struct ifreq data structure (defined in /usr/include/net/if.h) as one of the arguments for the SIOC* ioctl() function calls. However, the ifreq data structure defined for IPv4 is not large enough to hold an IPv6 address.
14 Verifying IPv6 Installation The following code fragment shows how an application can determine programmatically whether IPv6 is implemented on HP-UX. An application can check the existence of the /dev/ip6 device file at compile-time and/or run-time to determine whether IPv6 APIs and the IPv6 stack are on the system.
Verifying IPv6 Installation APIs. if ((fd = open("dev/ip6", O_RDWR)) == -1) /* * /dev/ip6 failed to open., Therefore the IPv6 product *is not installed on the system. An application should use the * existing IPv4 code. */ ... else /* * dev/ip6 exists, so the IPv6 product is probably installed. * IPv6 APIs can handle both IPv4 and IPv6 traffic */ NOTE 54 Starting with HP-UX 11i v2, IPv6 is automatically included in HP-UX.
15 Sample Client/Server Programs The following code fragments are based on the same IPv4 client/server sample programs shipped in the HP-UX 11i v2 /usr/lib/demos/networking/socket directory.
Sample Client/Server Programs The client requests a service called example. Add an entry to the client’s /etc/services file for example. Assign any unused port number, such as 22375, to the service example for a port address. The host running the server must also have the same port number assigned to example in the server’s /etc/services file.
Sample Client/Server Programs IPv4 TCP Client Code Fragment IPv4 TCP Client Code Fragment This code fragment is part of the same IPv4 client program that ships in the HP-UX 11i IPv6 /usr/lib/demos/networking/socket directory. The client requests a service called “example.” Add an entry to the /etc/services for “example”. Assign any unused port number, such as 22375, to the service “example” for a port address.
Sample Client/Server Programs IPv4 TCP Client Code Fragment perror(argv[0]); fprintf(stderr, "%s: unable to connect to remote\n", argv[0]); exit(1); } 58 Chapter 15
Sample Client/Server Programs IPv6 TCP Client using getipnodebyname() IPv6 TCP Client using getipnodebyname() This code fragment is part of an example IPv6 client program that ships in the HP-UX 11i v2 /usr/lib/demos/networking/socket/af_inet6 directory, rewritten using the getipnodebyname() function call.
Sample Client/Server Programs IPv6 TCP Client Using getaddrinfo() for Name/Service Lookup IPv6 TCP Client Using getaddrinfo() for Name/Service Lookup This fragment of an IPv6 TCP Client is a port of the preceding IPv6 client, using getaddrinfo() rather than gethostbyname(). struct addrinfo *res, *ainfo; struct addrinfo hints; /* clear out hints */ memset ((char *)&hints, 0, sizeof(hints)); hints.
Sample Client/Server Programs IPv4 TCP Server Code Fragment IPv4 TCP Server Code Fragment This code fragment is part of the same example IPv4 server program that ships in the HP-UX 11i v2 /usr/lib/demos/networking/socket directory. struct sockaddr_in6 peeraddr_in6; /* for peer socket address */ sp = getservbyname ("example", "tcp"); if (sp == NULL) { fprintf(stderr, "%s: example not found in /etc/services\n",argv[0]); exit(1); } myaddr_in.sin_port = sp->s_port; /* Create the listen socket.
Sample Client/Server Programs IPv6 TCP Server using getaddrinfo() for Service Address Lookup IPv6 TCP Server using getaddrinfo() for Service Address Lookup This code fragment is part of the example IPv6 server program that ships in the HP-UX 11i v2 /usr/lib/demos/networking/socket/af_inet6 directory, rewritten using the getaddrinfo() function call. struct addrinfo *ainfo, *res; struct addrinfo hints; /* zero-out the hints before assignment */ memset (&hints, 0, sizeof(hints)); . hints.
Sample Client/Server Programs IPv6 TCP Server using getaddrinfo() for Service Address Lookup fprintf(stderr, "%s: unable to listen on socket\n", argv[0]); close(ls); exit(1); } Chapter 15 63
Sample Client/Server Programs IPv6 TCP Server using getaddrinfo() for Service Address Lookup 64 Chapter 15
A IPv4 to IPv6 Quick Reference Guide This guide is for Socket Application programmers who primarily want to know which source code symbols and functions require alteration to support IPv6.
IPv4 to IPv6 Quick Reference Guide Do Existing IPv4-to-IPv4 Applications Require Changes? Do Existing IPv4-to-IPv4 Applications Require Changes? No. Current IPv4 applications remain unchanged. Modify applications only to take advantage of new IPv6 features.
IPv4 to IPv6 Quick Reference Guide Summary: Source Code Symbols and Function Changes Summary: Source Code Symbols and Function Changes The following tables cover changes in the source code symbols and functions that Socket Application programmers need to be aware of when porting code to support IPv6.
IPv4 to IPv6 Quick Reference Guide Summary: Source Code Symbols and Function Changes Watch for hard-coded data structure sizes Watch for sizeof(struct sockaddr_in) = sizeof(struct sockaddr) = 16 in pre-ported applications. The IPv6 address data structure sockaddr_in6 is larger than the traditional sockaddr_in data structure. Multicast and IPv4 Options Table A-2 Multicast and IPv4 Options IPv4 IPv6 IN_CLASSA IN_CLASSB IN_CLASSC IN_CLASSD None. IPv6 addressing is classless.
IPv4 to IPv6 Quick Reference Guide Summary: Source Code Symbols and Function Changes IPv6 Multicast Options Table A-6 IPv6 Multicast Options IPv4 IPv6 IP_MULTICAST_IF IP_MULTICAST_TTL IP_MULTICAST_LOOP IP_ADD_MEMBERSHIP IP_DROP_MEMBERSHIP IPV6_MULTICAST_IF IPV6_MULTICAST_HOPS IPV6_MULTICAST_LOOP IPV6_JOIN_GROUP IPV6_LEAVE_GROUP NOTE Comments When setting the getsockopt() and setsockopt() level parameter, use IPPROTO_IPV6 level for all IPV6_* options listed here.
IPv4 to IPv6 Quick Reference Guide Summary: Source Code Symbols and Function Changes Types of Service Options Table A-8 IP_TOS Types of Service Options Still under discussion by IETF IPng working group.
