HP-UX IPQoS A.01.00 Programmer’s Guide HP-UX 11i v1 and HP-UX 11i v2 (September 2004 or later) Manufacturing Part Number: 5991-0737 October 2005 Printed in the US © Copyright 2005 Hewlett-Packard Development Company, L.P.
Legal Notices The information in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be held liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material.
Contents 1. Overview Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction to HP-UX IPQoS (Background Information) . . . . . . . . . . . . . . . . . . . . . HP-UX IPQoS Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introducing the HP-UX IPQoS API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HP-UX IPQoS API Overview. . . . . . . .
Contents Reporting Problems to HP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 A. Function Calls Session-Related Function Calls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adapter-Related Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Policy-Related Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About This Document This document describes how to use the HP-UX IPQoS API that is included with the HP-UX IPQoS software. 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. Document updates may be issued between editions to correct errors or document product changes.
Publishing History Table 1 Publishing History Details Document Manufacturing Part Number 5991-0737 Operating Systems Supported Title HP-UX IPQoS A.01.00 Programmer’s Guide HP-UX 11i v1 HP-UX 11i v2 (September 2004 or later) Publication Date October 2005 What Is in This Document HP-UX IPQoS A.01.00 Programmer’s Guide is divided into several chapters, and each contains information about the HP-UX IPQoS API.
KeyCap The name of a keyboard key. Note that Return and Enter both refer to the same key. Emphasis Text that is emphasized. Bold Text that is strongly emphasized. Bold The defined use of an important word or phrase. ComputerOut Text displayed by the computer. UserInput Commands and other text that you type. Command A command name or qualified command phrase.
HP Product Documentation Information about HP-UX IPQoS can be found on docs.hp.com at: http://www.docs.hp.com/en/netcom.html#IPQoS Other relevant documents in this collection include: HP-UX IPQoS A.01.00 Release Notes HP-UX IPQoS A.01.
Table 3 RFCs Relevant RFCs Description RFC 2474 Definition of the Differentiated Services Field (DS Field) in the IPv4 and IPv6 headers RFC 2475 An Architecture for Differentiated Services RFC 2597 Assured Forwarding PHB Group RFC 2598 An Expedited Forwarding PHB 9
HP Welcomes Your Comments HP encourages your feedback about this document and is committed to providing documentation that meets your needs. Send comments to: netinfo_feedback@cup.hp.com Include the document title, manufacturing part number, and any comment, error found, or suggestion for improvement you have concerning this document. Also, please include what we did right so we can incorporate it into other documents.
1 Overview This chapter provides an overview of the HP-UX IPQoS API. It provides an introduction to the HP-UX IPQoS product, architecture and API. It also provides a usage overview which includes programmatic requirements, a brief structural overview and functional overview of the API, and also general information on man pages and return codes.
Overview Introduction Introduction This section briefly describes HP-UX IPQoS and its architecture. It also provides an introduction to the HP-UX IPQoS API, including a structural and functional overview. Introduction to HP-UX IPQoS (Background Information) HP-UX IPQoS provides, for outgoing traffic on HP-UX hosts, traffic conditioning (transmission prioritization for specified traffic classes) as well as DSCP (Differentiated Services Code Point) marking and VLAN-priority marking.
Overview Introduction HP-UX IPQoS Architecture Figure 1-1, illustrates a high-level overview of the HP-UX IPQoS architecture. Figure 1-1 Architectural Overview As shown in Figure 1-1, HP-UX IPQoS operates in both user space and kernel space. Also shown in Figure 1-1, HP-UX IPQoS inserts a module between the IP and the DLPI layers, into the STREAMS plumbed by ifconfig. HP-UX IPQoS supports as many network adapters (up to 128) as are configured on the system.
Overview Introduction Introducing the HP-UX IPQoS API The HP-UX IPQoS API allows programmers to write applications that can perform the following tasks: • manipulate the HP-UX IPQoS configuration • traverse the HP-UX IPQoS configuration • obtain HP-UX IPQoS statistics The benefits that the HP-UX IPQoS API offers include the following: — Allows applications to be written that dynamically modify the current configuration. For example, you can write applications to add to existing configurations.
Overview Introduction These manpages are: IpqosAPI (3c), IpqosSession (3c), IpqosAdapter (3c), IpqosPolicy (3c), IpqosFilter (3c), IpqosOverlapFilter (3c) and IpqosStats (3c). See “Manpages” on page 18, for more information on these man pages.
Overview HP-UX IPQoS API Overview HP-UX IPQoS API Overview This section describes general overview information for using the HP-UX IPQoS API. Subsequent chapters in this guide provide more detailed usage information. Programmatic Requirements To use the HP-UX IPQoS API, the application needs to: • have super-user (root) privileges • include the header file: #include • link to the shared library libipqos.
Overview HP-UX IPQoS API Overview Sessions: Every application that uses the HP-UX IPQoS API must start a session. The function used to start a session is IpqosInitSession(). One of the arguments of this function specifies a session type. There are three types of sessions: IPQOS_SESSION_CONFIG (used for active “set” functions), IPQOS_SESSION_READ (used for passive ”get” functions) and IPQOS_SESSION_STATS (used for functions related to obtaining and resetting statistics). Sessions must be terminated.
Overview HP-UX IPQoS API Overview • List Management: Attaching/Deleting/Traversing (Filter, Policy and Adapter) Lists - In this guide: See “Using Lists” on page 26, for more information. - Relevant manpages: IpqosFilter (3c), IpqosPolicy (3c), IpqosAdapter (3c) • Filter Attribute Management: Getting/Setting Filter Attributes.
Overview HP-UX IPQoS API Overview • IpqosAPI (3c): Provides an overview of the HP-UX IPQoS API. It describes the types of tasks programmers can perform with the API. It explains how sessions are used and introduces the HP-UX IPQoS API object classes (IpqosFilter, IpqosPolicy, IpqosAdapter). • IpqosSession (3c): Provides information on functions related to HP-UX IPQoS session management. This includes details on: initiating sessions, committing sessions and aborting sessions.
Overview HP-UX IPQoS API Overview All return codes have a corresponding native-language string representation. The string representation can be obtained from the uint32_t return code by calling the function: const char * IpqosStrerror(uint32_t errCode); The string representation is suitable for use in error messages. See Appendix B, “Return Codes,” on page 49, for a list of return codes and their corresponding mnemonics and message strings.
2 Using the HP-UX IPQoS API This chapter provides an overview of how to use the components that comprise the HP-UX IPQoS API. It discusses the following usage areas: sessions, objects and lists; filter, policy, and adapter objects; and statistics.
Using the HP-UX IPQoS API Using Sessions Using Sessions Every application that uses the HP-UX IPQoS API must use the context of a session. The session-related functions that are part of the API include functions to initiate and set the type of session, get the session type and terminate the session. Once in a session, the application can: configure HP-UX IPQoS filters and policies, read the current HP-UX IPQoS configuration, or obtain HP-UX IPQoS statistics.
Using the HP-UX IPQoS API Using Sessions • Configuration sessions (IPQOS_SESSION_CONFIG): Use to traverse and to make changes to the current HP-UX IPQoS configuration. • Read sessions (IPQOS_SESSION_READ): Use to only traverse the current HP-UX IPQoS configuration. • Statistics sessions (IPQOS_SESSION_STATS): Use to traverse and obtain statistics maintained on the current HP-UX IPQoS configuration.
Using the HP-UX IPQoS API Using Sessions • IPQOS_STATUS_INACTIVE: The filter (or policy) object was created in the current session and is not currently attached to a policy (or adapter) object. • IPQOS_STATUS_ACTIVE_UPON_COMMIT: The filter (or policy) object was created in the current session, is attached to a policy (or adapter) object and will become active in the HP-UX IPQoS kernel module after IpqosCommitSession() is successfully called.
Using the HP-UX IPQoS API Using Objects Using Objects HP-UX IPQoS API “objects” are pointers to opaque structures. There are three types of objects: filters, policies, and adapters. The following sections briefly describe some key considerations about working with objects when using the HP-UX IPQoS API. Creating, Copying and Destroying Objects HP-UX IPQoS API resource management functions exist that create, copy and destroy filters and policies.
Using the HP-UX IPQoS API Using Lists Using Lists When a policy or filter object is part of an active configuration, it exists in a list. Each adapter object may have a list of policy objects and each policy object may have a list of filter objects. Figure 2-1 illustrates how lists are used in the HP-UX IPQoS API.
Using the HP-UX IPQoS API Using Lists Attaching Objects to Lists When an object exists in a list it is said to be attached. When an object is created or copied it is (initially) considered unattached, until it is explicitly attached. To attach a policy or filter to a list, use the following functions: IpqosAttachPolicy(), IpqosAttachFilter(). Restrictions There are two restrictions for attaching a filter object to a list: • The filter must have its name attribute set. The name must be unique.
Using the HP-UX IPQoS API Using Lists To obtain the next object in a list, use the following functions: IpqosGetAdapterListNext(), IpqosGetPolicyListNext(), IpqosGetFilterListNext(). These functions return IPQOS_LIST_EMPTY if the end of the list has been reached, that is, there is no such object. Functions exist that count the number of items in a list. To obtain the count, use the following functions: IpqosGetFilterListCount(), IpqosGetPolicyListCount() and IpqosGetAdapterListCount().
Using the HP-UX IPQoS API Using Lists Deleting Policies and Filters (Detaching From a List) To delete a policy or filter (and effectively detach it from the list) use the following functions: IpqosDeletePolicy(), IpqosDeleteFilter(). If you want to delete all policies (and their associated filters) from an adapter there is a function to accomplish this task called IpqosDeleteAll(). This function has one argument, the adapter (IpqosAdapter).
Using the HP-UX IPQoS API Filter Objects Filter Objects Filter objects define classes of traffic based on a combination of one or more attributes. IP traffic that matches the class of traffic defined by a filter gets processed by the policy that the filter is attached to. A filter can only be attached to multiple policies, but can only be attached to one policy per adapter. A filter is effectively ignored if it is not attached to any policy.
Using the HP-UX IPQoS API Filter Objects A completely overlapping (superset) filter prevents any traffic from matching the other filter and effectively renders the other filter completely ineffective. A partial overlap (intersection) renders the other function partially ineffective. An HP-UX IPQoS configuration with overlapping filters is not recommended. Filters should be redefined to avoid having complete or partial overlap conditions.
Using the HP-UX IPQoS API Policy Objects Policy Objects Policy objects define actions to perform on classes of traffic attached to the policy. A policy must have one or more unique filters attached to it. It is these filters which determine which classes of traffic the policy will govern. A policy is effectively ignored if it is not attached to any adapter.
Using the HP-UX IPQoS API Adapter Objects Adapter Objects Adapter objects are not constructed by the programmer. Instead, every session contains a fixed list of adapter objects managed by the HP-UX IPQoS API based on the list of network adapters that have been configured on the system. Adapter-related functions in the HP-UX IPQoS API allow programmers to access (“get”) values of its attributes, traverse the list of adapters, and traverse the list of policies of an adapter.
Using the HP-UX IPQoS API Statistics Statistics The HP-UX IPQoS API offers functions to obtain and reset statistics on a policy and on one or all of its associated filters. Functions related to statistics must be called from IPQOS_SESSION_STATS type sessions. A function IpqosGetPolicyStats() retrieves the counters for the statistics. Once it is called, functions that get specific counter information can be called (for example, IpqosGetPolicyStatsByteCount()).
3 Troubleshooting This chapter provides some general suggestions for troubleshooting the HP-UX IPQoS API. It includes general tips and how to report problems to HP.
Troubleshooting General Tips General Tips The following list provides basic information to be aware of when using the HP-UX IPQoS API: • To use the HP-UX IPQoS API: — Programs must include the header file: #include — Programs must link to the shared library libipqos.
Troubleshooting Reporting Problems to HP Reporting Problems to HP When reporting problems to HP, include the following information: • A complete description of the problem and any error messages. Include information about: — the error code returned by the function being called — what the code is trying to do — log files (such as /var/adm/syslog/syslog.log) Include a description of what works, as well as what does not work.
Troubleshooting Reporting Problems to HP 38 Chapter 3
A Function Calls This appendix contains several tables, which together provide a complete list of functions available with the HP-UX IPQos API. The functions have been grouped to correspond to the grouping and discussion of these functions in the HP-UX IPQoS API manpages.
Function Calls Session-Related Function Calls Session-Related Function Calls The following table lists the HP-UX IPQoS API function calls related to session management. Refer to the IpqosSession (3c) manpage for detailed information on these functions.
Function Calls Adapter-Related Function Calls Adapter-Related Function Calls The following table lists the HP-UX IPQoS API function calls related to adapters. Refer to the IpqosAdapter (3c) manpage for detailed information on these functions.
Function Calls Policy-Related Function Calls Policy-Related Function Calls The following table lists the HP-UX IPQoS API function calls related to policies. Refer to the IpqosPolicy (3c) manpage for detailed information on these functions.
Function Calls Policy-Related Function Calls Table A-3 Policy-Related Functions (Continued) Description Function set VLAN priority of policy uint32_t IpqosSetPolicyVLANPriority(IpqosPolicy policy, uint8_t vlanPr) attach policy to adapter uint32_t IpqosAttachPolicy(IpqosPolicy policy, IpqosAdapter adapter) delete policy from adapter uint32_t IpqosDeletePolicy(IpqosPolicy policy) delete all policies from adapter uint32_t IpqosDeleteAll(IpqosAdapter adapter) get status of policy uint32_t IpqosGetP
Function Calls Filter-Related Function Calls Filter-Related Function Calls The following table lists the HP-UX IPQoS API function calls related to filters. Refer to the IpqosFilter (3c) manpage for detailed information on these functions.
Function Calls Filter-Related Function Calls Table A-4 Filter-Related Functions (Continued) Description Function get priority of filter uint32_t IpqosGetFilterPriority(IpqosFilter filter, uint32_t * priority) get status of filter uint32_t IpqosGetFilterStatus(IpqosFilter filter, uint32_t * status) set source addresses of filter uint32_t IpqosSetFilterSrcAddresses(IpqosFilter filter, char * addrLow, char * addrHigh) set destination addresses of filter uint32_t IpqosSetFilterDstAddresses(IpqosFilte
Function Calls Filter Overlap-Related Function Calls Filter Overlap-Related Function Calls The following table lists the HP-UX IPQoS API function calls related to filter overlaps. Refer to the IpqosOverlapFilter (3c) manpage for detailed information on these functions.
Function Calls Filter Overlap-Related Function Calls Table A-5 Filter Overlap-Related Functions (Continued) Description checks if DSCP for filter1 overlaps that of filter2 Appendix A Function uint32_t IpqosCheckDSCPOverlap(IpqosFilter filter1, IpqosFilter filter2) 47
Function Calls Statistics-Related Function Calls Statistics-Related Function Calls The following table lists the HP-UX IPQoS API function calls related to statistics. Refer to the IpqosStats (3c) manpage for detailed information on these functions.
B Return Codes This appendix contains information on return codes provided by the HP-UX IPQoS API.
Return Codes Return Codes, Mnemonics and Message Strings Return Codes, Mnemonics and Message Strings Table B-1 provides the HP-UX IPQoS API return codes, accompanied by their respective mnemonics and message strings.
Return Codes Return Codes, Mnemonics and Message Strings Table B-1 Ret # Return Codes with Mnemonics and Message Strings Mnemonic Message String 17 IPQOS_E_NAME_NOT_SET Object name is not set 18 IPQOS_E_VERSION_MISMATCH Version does not match API 19 IPQOS_E_INTERNAL_ERROR Internal error (see syslog for more info) 20 IPQOS_E_IN_SESSION In session already 21 IPQOS_E_SUBSYSTEM_NOT_STARTED Ipqos subsystem has not been started 22 IPQOS_E_IOCTL_ERROR ioctl error ( )
Return Codes Return Codes, Mnemonics and Message Strings 52 Appendix B
C Code Example This appendix contains a simple pseudo-code program that illustrates how to create a simple HP-UX IPQoS configuration.
Code Example Configuration Code Example Configuration Code Example The following pseudo-code example shows how to use the HP-UX IPQoS API to reserve 50% bandwidth on lan0 for traffic with destination port numbers in the range of 80-100.
Code Example Configuration Code Example } /* Create an IpqosPolicy */ result = IpqosCreatePolicy(&ipqosPolicy); checkResult(“IpqosCreatePolicy”,result); /* API mandates name, so give it one */ result = IpqosSetPolicyName(ipqosPolicy,”testPolicy”); checkResult(“IpqosSetPolicyName”,result); /* Set the 50% reservation amount */ result = IpqosSetPolicyReservation(ipqosPolicy,50, IPQOS_VALUE_MODE_RELATIVE); checkResult(“IpqosSetPolicyReservation”,result); /* Attach the policy to the adapter for lan0 */ result =
Code Example Configuration Code Example 56 Appendix C
Index A adapter attributes, 33 adapter objects, 33 adapter-related functions, 41 adapters, 12 architectural overview, 13 attaching a filter object, 27 attaching a policy object, 27 attributes adapter, 25, 33 filter, 25, 30 policy, 25, 32 B benefits of the HP-UX IPQoS API, 14 C code example - traversing a list, 28 copying a filter, 25 copying a policy object, 25 counters for statistics, 34 creating a filter object, 25 creating a policy object, 25 D deleting a filter object, 29 deleting a policy object, 29 de
Index IpqosGetPolicyListHead(), 27, 41 IpqosGetPolicyListNext(), 28, 41 IpqosGetPolicyMax(), 42 IpqosGetPolicyName(), 42 IpqosGetPolicyReservation(), 42 IpqosGetPolicyStats(), 34 IpqosGetPolicyStatus(), 43 IpqosGetPolicyVLANPriority(), 42 IpqosGetSessionType(), 40 IpqosInitSession(), 22, 40 IpqosOverlapFilter(3c), 19 IpqosPolicy(3c), 19 IpqosSession(3c), 19 IpqosSetFilterDSCP(), 45 IpqosSetFilterDstAddresses(), 45 IpqosSetFilterDstPhysAddress(), 45 IpqosSetFilterDstPortNumbers(), 45 IpqosSetFilterName(), 45
Index 59
