HP HP-UX IPQos User's Guide

Download

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

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.

Warranty

A copy of the specific warranty terms applicable to your Hewlett- Packard product and replacement parts can be obtained from your local Sales and Service Office.

U.S. Government License

Proprietary 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.

Copyright © 1997-2005 Hewlett-Packard Development Company L.P. All rights reserved. Reproduction, adaptation, or translation of this document without prior written permission is prohibited, except as allowed under the copyright laws.

Trademark Notices

UNIX is a registered trademark in the United States and other countries, licensed exclusively through The Open Group.

1. Overview

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Introduction to HP-UX IPQoS (Background Information) . . . . . . . . . . . . . . . . . . . . . 12

HP-UX IPQoS Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Introducing the HP-UX IPQoS API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

HP-UX IPQoS API Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Programmatic Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Structural Overview (How to Use the HP-UX IPQoS API) . . . . . . . . . . . . . . . . . . . . 16

Functional Overview (What You Can Do Using the HP-UX IPQoS API) . . . . . . . . . 17

Manpages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Return Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Restoring Configurations to the Kernel after Reboot . . . . . . . . . . . . . . . . . . . . . . . . . 20

Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2. Using the HP-UX IPQoS API

Using Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Starting a Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Session Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Terminating a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Object Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Using Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Creating, Copying and Destroying Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Object Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Using Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Attaching Objects to Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Traversing Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Deleting Policies and Filters (Detaching From a List) . . . . . . . . . . . . . . . . . . . . . . . . 29

Filter Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Filter Overlap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Policy Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Adapter Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Contents

3. Troubleshooting

General Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Contents

Reporting Problems to HP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

A. Function Calls

Session-Related Function Calls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Adapter-Related Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Policy-Related Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Filter-Related Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Filter Overlap-Related Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Statistics-Related Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

B. Return Codes

Return Codes, Mnemonics and Message Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

C. Code Example

Configuration Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

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. To ensure that you receive the updated or new editions, subscribe to the appropriate product support service. See your HP sales representative for details.

The latest version of this document can be found on line at: http://www.docs.hp.com/en/netcom.html#IPQoS.

Intended Audience

This document is intended for system and network administrators and programmers responsible for configuring, and managing HP-UX IPQoS using the HP-UX IPQoS API. Administrators and programmers are expected to have knowledge of HP-UX and networking concepts, commands and configuration, including knowledge of Transmission Control Protocol/Internet Protocol (TCP/IP).

This document is not a tutorial.

New and Changed Documentation in This Edition

This is the first edition of this document.

Publishing History

Table 1 Publishing History Details

Document

Manufacturing

Part Number

5991-0737 HP-UX IPQoS A.01.00

Programmer’s Guide

Title

Operating Systems

Supported

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.

Chapter 1 Overview Use this chapter to obtain a summary and overview of HP-UX

IPQoS and the HP-UX IPQoS API.

Chapter 2 Using the HP-UX IPQoS API Use this chapter to learn about the

components involved in using the HP-UX IPQoS API.

Chapter 3 Troubleshooting Use this chapter to find some general tips for

troubleshooting the HP-UX IPQoS API.

Appendix A Functions Calls Use this appendix to find a summary reference list of all

functions included with the HP-UX IPQoS API.

Appendix B Return Codes Use this appendix to find a summary reference list of

HP-UX IPQoS API return codes.

Appendix C Code Example Use this appendix to find a code example that illustrates

how to create a simple configuration.

Typographic Conventions

This document uses the following conventions. audit (5) An HP-UX manpage. In this example, audit is the name and 5 is the section

in the HP-UX Reference. On the web and on the Instant Information CD, it may be a hot link to the manpage itself. From the HP-UX command line, you can enter “man audit” or “man 5 audit” to view the manpage.

Book Title The title of a book. On the web and on the Instant Information CD, it may be

a hot link to the book itself.

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.

Variable The name of a variable that you may replace in a command or function or

information in a display that represents several possible values.

[] The contents are optional in formats and command descriptions. If the

contents are a list separated by |, you must choose one of the items.

{} The contents are required in formats and command descriptions. If the

contents are a list separated by |, you must choose one of the items. ... The preceding element may be repeated an arbitrary number of times. | Separates items in a list of choices.

HP-UX Release Name and Release Identifier

Each HP-UX 11i release has an associated release name and release identifier. The uname (1) command with the -r option returns the release identifier. This table shows the releases available for HP-UX 11i.

Table 2 HP-UX 11i Releases

Release

Identifier

B.11.23 HP-UX 11i v2 (September 2004 or later) Intel Itanium and PA RISC

B.11.22 HP-UX 11i v1.6 Intel Itanium

B.11.11 HP-UX 11i v1 PA-RISC

Release Name

Supported Processor

Architecture

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.

Chapter 1 11

Overview

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. An HP-UX IPQoS configuration can be loaded into the kernel either by using ipqosadmin to load a valid configuration file, or through user-applications that utilize the HP-UX IPQoS API included with the product.

An HP-UX IPQoS configuration contains user-supplied definitions of traffic classes (filters) and traffic-handling instructions (policies) that are assigned to configured adapters.

Note the following general properties about filters, policies and adapters:

• The purpose of a filter is to identify a certain class of traffic (based on characteristics such

as transport port number, destination IP address, etc.) on a network interface.

• The purpose of a policy is to define what action to perform on a class of traffic (such as

reserving bandwidth, DiffServ Code Point (DSCP) marking, VLAN priority marking, etc.).

• Adapters represent LAN devices on the system on which HP-UX IPQoS policies can be

enforced.

• A filter can be attached to multiple policies, but can only be attached to one policy per

adapter.

• A filter is meaningful only when it is associated with a policy. Likewise, a policy is only

meaningful when it is associated with an adapter and has one or more filters associated with it.

• An adapter may or may not have policies attached to it. For adapters that do not have any

associated policies, no HP-UX IPQoS controls are performed on their traffic.

For general (non-API specific) information on HP-UX IPQoS refer to the HP-UX IPQoS A.01.00 Administrator’s Guide, which can be found online at:

http://www.docs.hp.com/en/netcom.html#IPQoS

Chapter 112

HP-UX IPQoS Architecture

Figure 1-1, illustrates a high-level overview of the HP-UX IPQoS architecture.

Figure 1-1 Architectural Overview

Overview

Introduction

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.

Chapter 1 13

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. (The HP-UX IPQoS command-line administration utility, ipqosadmin, does not offer additive loads. Using ipqosadmin, the only way to change a configuration is to perform a -load operation, which replaces the configuration.)

— Allows applications to be written that provide alternative output formats than to what the

command-line administration utility, ipqosadmin, provides. For example. you can write an application that produces configuration information in html output format. Refer to /opt/ipqos/examples/htmldump for a programmatic example.

— If you already have existing IPQoS applications, you can leverage them by modifying

them to work with the HP-UX IPQoS API.

As will be discussed in more detail in subsequent sections of this guide, note that:

— The tasks accomplished by HP-UX IPQoS API operations are performed in sessions.

Every HP-UX IPQoS API session begins with the API collecting information about the current configuration since this is required for all three types of tasks the HP-UX IPQoS API performs. Sessions are initiated and include session types that determine what operations are permitted. Sessions are completed either by committing (saving) or by aborting (not saving) the changes made during the session.

— HP-UX IPQoS configurations consist of objects made up of three classes: filter, policy and

adapter. The objects exist in a list structure. Objects are attached to lists, and then the lists can be traversed to read and modify the objects in a configuration.

— HP-UX IPQoS also maintains statistics, in the HP-UX IPQoS kernel module, that are

available to programmers. Statistics are maintained on both filters and policies.

IMPORTANT The manpages associated with the HP-UX IPQoS API complement this guide

and are necessary references to successfully use the HP-UX IPQoS API.

Chapter 114

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.

Chapter 1 15

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 <netinet/ipqos.h>

• link to the shared library libipqos.sl

IMPORTANT HP-UX IPQoS supplies only the 32-bit version of the shared library. Thus,

applications must be 32-bit.

IMPORTANT To use the HP-UX IPQoS API, HP-UX IPQoS must be in one of the ENABLED

states (refer to the HP-UX IPQoS A.01.00 Administrator’s Guide for more information on HP-UX IPQoS states of operation).

Structural Overview (How to Use the HP-UX IPQoS API)

The HP-UX IPQoS API is based on the usage of objects, lists and sessions.

Objects: Objects are pointers to opaque structures. There are three object types: filters, policies and adapters (IpqosFilter, IpqosPolicy, IpqosAdapter respectively). Filter objects and policy objects can be constructed (created, destroyed, attached, deleted and copied) by the programmer. The list of adapter objects is a fixed list that is built by the HP-UX IPQoS API during session initialization. Thus, adapter objects cannot be constructed by the programmer.

All three types of objects have attributes that can be accessed (by using “get” type functions). Filter objects and policy objects can also be modified (using “set” type functions).

Lists: When policy or filter objects are part of an active configuration, they exist in a list. Each adapter object has an attached policy list and each policy object has an attached filter list. Adapter, policy and filter lists can be traversed by the programmer.

Chapter 116

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. There are two ways of terminating a session: committing (saving) or aborting (quitting without saving), using IpqosCommitSession() and IpqosAbortSession(), respectively.

See the relevant sections of Chapter 2, “Using the HP-UX IPQoS API,” on page 21, for more information on how the HP-UX IPQoS API uses objects, lists and sessions.

NOTE The data structures used in HP-UX IPQoS are opaque and need not be an

explicit concern of programmers using the API.

Functional Overview (What You Can Do Using the HP-UX IPQoS API)

There are several types of tasks you can accomplish using the HP-UX IPQoS API functions. There are also several possible ways to group these tasks. The list below groups the tasks in a way that serves the purpose of describing the tasks from a high-level perspective. For example, some common tasks that can be performed on filter and policy objects are discussed together in this guide, to minimize redundancy.

NOTE The HP-UX IPQoS API manpages group the functions slightly differently,

which is appropriate since the purpose of the manpages is to provide detailed reference information. The groupings used in the manpages work best for detailed syntactical descriptions where redundancy is not a concern.

The following list provides broad groups of functional tasks that can be accomplished using the HP-UX IPQoS API. For each grouping, the text indicates where more information can be found in this guide, as well as the relevant manpages to refer to for more information.

• Session Management: Initiating and Terminating Sessions.

- In this guide: See “Using Sessions” on page 22, for more information.

- Relevant manpage: IpqosSession (3c)

• Resource Management: Creating/Destroying/Copying (Filter and Policy) Objects

- In this guide: See “Using Objects” on page 25, for more information.

- Relevant manpages: IpqosFilter (3c), IpqosPolicy (3c)

Chapter 1 17

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.

Attributes are: name, source address(es), destination address(es), source port number(s), destination port number(s), network protocol number, transport protocol number, destination physical address, DSCP(s), priority.

- In this guide: See “Filter Objects” on page 30, for more information.

- Relevant manpage: IpqosFilter (3c)

• Policy Attribute Management: Getting/Setting Policy Attributes.

Attributes are: name, reservation, max, DSCP, VLAN priority.

- In this guide: See “Policy Objects” on page 32, for more information.

- Relevant manpage: IpqosPolicy (3c)

• Adapter Attribute Management: Getting Adapter Attributes.

Attributes are: name, speed, link type, physical address.

- In this guide: See “Adapter Objects” on page 33, for more information.

- Relevant manpage: IpqosAdapter (3c)

• Obtaining/Resetting Policy and Filter Statistics

- In this guide: See “Statistics” on page 34, for more information.

- Relevant manpage: IpqosStats (3c)

• Checking for Overlapping Filters

- In this guide: See “Filter Objects” on page 30, for more information.

- Relevant manpage:IpqosOverlapFilter (3c)

Manpages

This guide only serves as an overview to the HP-UX IPQoS API. To write applications, you will need to reference each of the following manpages, as needed, for detailed descriptions and syntactical information. The manpages associated with the HP-UX IPQoS API are as follows:

Chapter 118

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. It also discusses the three session types available.

• IpqosAdapter (3c): Provides information on functions related to HP-UX IPQOS adapters,

including: obtaining information about adapters, traversing the list of HP-UX IPQoS adapters, and traversing the list of policies associated with adapters. It also includes relevant session-related information.

• IpqosPolicy (3c): Provides information on functions related to HP-UX IPQoS policies,

including: creating policies, assigning and accessing values of policy attributes, associating policies with adapters, and traversing the filter lists of the polices. It also includes relevant session-related information.

• IpqosFilter (3c): Provides information on functions related to HP-UX IPQoS filters,

including: creating filters, assigning and accessing values of filter attributes, and associating filters with policies. It also includes relevant session-related information.

• IpqosOverlapFilter (3c): Provides information on functions related to checking HP-UX

IPQoS filters for overlap conditions.

• IpqosStats (3c): Provides information on functions related to obtaining (and resetting)

statistics on the filters and policies of the HP-UX IPQoS configuration.

Return Codes

Most functions in the HP-UX IPQoS API return a uint32_t value that represents the return code of the function call. When successful, the return code will be the symbolic constant IPQOS_S_SUCCESS.

In some cases, other values will be returned, which may or may not indicate a failure. For example, the list traversal routines may return the value IPQOS_S_LIST_EMPTY. You may receive this value if you are trying to set the traversal to the head of the list, and the list is empty. Or, you may receive this value if you are trying to traverse to the next item in the list and there are no more items in the list.

In general, for “get” functions: A return of IPQOS_E_ATTRIBUTE_NOT_SET signifies that the attribute is not set for the object. A return of IPQOS_S_SUCCESS signifies the attribute is set. Any other return code is an error.

In general, for “set” functions: A return of any value other than IPQOS_S_SUCCESS signifies an error.

Chapter 1 19

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. For more information on IpqosStrerror(), refer to the IpqosSession (3c) manpage.

Restoring Configurations to the Kernel after Reboot

The HP-UX IPQoS API maintains a configuration database that is synchronized with the HP-UX IPQoS configuration loaded in the kernel modules. This allows the HP-UX IPQoS subsystem to restore the last installed configuration whenever it is restarted.

Sample Program

A sample program, “htmldump” is included with HP-UX IPQoS. This purpose of this program is to provide configuration information in an HTML output format. The “htmldump” program can be found under the directory /opt/ipqos/examples. Also, see Appendix C, “Code Example,” on page 53, for a pseudo-code sample that illustrates how to create a simple configuration.

Chapter 120

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.

Chapter 2 21

Using the HP-UX IPQoS API

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.

Starting a Session

Every application that uses the HP-UX IPQoS API must start a session by calling the function:

uint32_t IpqosInitSession(uint32_t version,char * configName,IpqosSessionType sessionType)

The arguments can be described as follows:

— version: the version ID of the HP-UX IPQoS API (this is a #defined constant in the

HP-UX IPQoS header file, in this release it is IPQOS_API_VERSION_ID_1). The version ID scheme allows for the detection of API-application mismatch.

— configName: specify NULL (this argument is for future enhancements and is currently

unused).

— sessionType: specify the type of session being started. Permitted session types are:

IPQOS_SESSION_CONFIG, IPQOS_SESSION_READ, IPQOS_SESSION_STATS.

A return value of IPQOS_S_SUCCESS indicates the session started successfully. Any other return value signifies an error.

When any session type is started, the API first reads the current HP-UX IPQoS configuration stored in the HP-UX IPQoS database. It forms a list of HP-UX IPQoS adapters, where each adapter contains a list of attached HP-UX IPQoS policies, and where each HP-UX IPQoS policy contains a list of attached HP-UX IPQoS filters. It also communicates with the HP-UX IPQoS kernel module.

An application can only have one active session (of any type) at a given time. Thus, to start a new session, the current session (if one exists) must first be terminated. The functions available to terminate a session are discussed in a following section.

Session Types

There are three session types in the HP-UX IPQoS API:

Chapter 222

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.

At any point in time there can only be one IPQOS_SESSION_CONFIG or IPQOS_SESSION_STATS type session running on the system. There can be simultaneous IPQOS_SESSION_READ type sessions, even when an IPQOS_SESSION_CONFIG or IPQOS_SESSION_STATS is open.

Terminating a Session

There are two ways (functions available) to terminate a session:

• Committing (saving) the session (IpqosCommitSession): Use this function to commit

(save) all the configuration actions performed in the session to the HP-UX IPQoS kernel module and update the HP-UX IPQoS database accordingly. (This function can only be called from an IPQOS_SESSION_CONFIG type session.)

If there are no errors, it also closes the session. However, if the function does not return IPQOS_S_SUCCESS, then none of the configuration actions performed in the session are applied (saved) to the configuration in the kernel module or to the database. In this case, programmers are recommended to not re-try the IpqosCommitSession(), but rather to use IpqosAbortSession() to close the session.

• Aborting the session (IpqosAbortSession): Use this function to abort (quit without

saving) a session and close it. If the session is of type IPQOS_SESSION_CONFIG this function will effectively ignore all the configuration actions and leave the configuration in the HP-UX IPQoS kernel module and database unchanged.

NOTE Exiting an application without explicitly calling IpqosCommitSession() or

IpqosAbortSession() is equivalent to having called IpqosAbortSession().

Object Status

To determine if a policy or filter object is currently configured, use the following functions: IpqosGetFilterStatus(), IpqosGetPolicyStatus(). The possible status conditions, and their implications, are:

• IPQOS_STATUS_ACTIVE: The filter (or policy) object is attached to a policy (or adapter)

object, and is currently active in the HP-UX IPQoS kernel module.

Chapter 2 23

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.

• IPQOS_STATUS_INACTIVE_UPON_COMMIT: The filter (or policy) object is attached to a policy

(or adapter) and is active in the HP-UX IPQoS kernel module, but will be deleted after IpqosCommitSession() is successfully called.

These functions are useful in IPQOS_SESSION_CONFIG sessions to distinguish between objects attached or deleted in the current session (and thus pending a commit) versus objects that were previously configured.

Based on object status, there are some restrictions as to allowable functions to call. For example:

• If the object status of a filter or policy object is not IPQOS_STATUS_INACTIVE, you can not

successfully call: IpqosAttachFilter() or IpqosAttachPolicy(). The functions will return the code IPQOS_E_ALREADY_ATTACHED.

• If the object status of a filter or policy object is IPQOS_STATUS_INACTIVE, you can not

successfully call: IpqosDeleteFilter() or IpqosDeletePolicy(). The functions will return the code IPQOS_E_NOT_ATTACHED.

Chapter 224

Using the HP-UX IPQoS API

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. These functions are: IpqosCreateFilter(), IpqosCopyFilter(),

IpqosDestroyFilter(), IpqosCreatePolicy(), IpqosCopyPolicy() and IpqosDestroyPolicy() respectively.

Both the IpqosDestroyFilter() and IpqosDestroyPolicy() functions take an argument that is a pointer to the object. When an object is destroyed, the resources are freed up and its pointer is set to NULL to prevent further use of that pointer.

Adapter objects cannot be created, copied or destroyed. They are managed by the HP-UX IPQoS API based on the list of network adapters that have been configured on the system.

Object Attributes

HP-UX IPQoS API objects have attributes that can be read or modified. All objects, (filter, policy and adapter) have a (required) name attribute that must be unique. Filter and policy objects have a status attribute, which can be one of the following:

IPQOS_STATUS_ACTIVE, IPQOS_STATUS_INACTIVE, IPQOS_STATUS_ACTIVE_UPON_COMMIT, IPQOS_STATUS_INACTIVE_UPON_COMMIT. These indicate the status, taking into account

whether or not the session has been or will be committed, after an action function has been performed.

Filter and policy objects also have attributes that can be read (using “get” functions) or modified (“set” functions). Adapter objects also have attributes, but these can only be read (using “get” functions).

See following sections of this chapter for a complete listing of the attributes associated with filter, policy, and adapter objects.

Chapter 2 25

Using the HP-UX IPQoS API

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.

Figure 2-1 Lists

Chapter 226

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.

• If the filter’s destination physical address attribute is set, the length of the address must

be compatible with the adapter object to which the associated policy object is attached.

There are two restrictions for attaching a policy object to a list:

• The policy must have its name attribute set. The name must be unique.

• If the policy’s reservation bandwidth attribute is set, it must be a value such that the

aggregate reservation of all policy objects attached to an adapter object does not exceed the line speed of the adapter, less 80 Kbps. The 80 Kbps is set aside for classes of traffic that do not match any specified filters.

In the case of VLANs, the aggregate of the reservations of policies of VLANs that are based on the same physical adapter, and the policies of the base adapter itself, cannot exceed the speed of the physical adapter minus the 80Kbps reserved by the implicit default flow.

There are two functions that remove objects from lists. An object can be detached from the list by calling one of the delete functions. The object becomes detached when the session is committed. The object’s memory and resources can be freed by calling one of the destroy functions.

To delete an object its status must not be IPQOS_STATUS_INACTIVE, otherwise the function will return IPQOS_E_NOT_ATTACHED.

To destroy an object its status must be IPQOS_STATUS_INACTIVE, otherwise the function will return the error code IPQOS_E_ALREADY_ATTACHED.

Traversing Lists

As shown in Figure 2-1, the lists are singly-linked and can only be traversed one way. To obtain the object at the head of an object list, use the following functions:

IpqosGetAdapterListHead(), IpqosGetPolicyListHead(), IpqosGetFilterListHead().

Chapter 2 27

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().

Code Example: Traversing An Adapter List

The following code sample illustrates one way to traverse an adapter list. In this example, the count value determines the loop.

The example uses a function QosError(), which terminates the program gracefully after reporting the error. Note that this function is shown for illustrative purposes as part of the example, it is not part of the HP-UX IPQoS API. If you want to use a similar function in your programs, you will need to create one.

IpqosAdapter ipqosAdaptr;

...

result = IpqosGetAdapterListHead(&ipqosAdaptr); while (true) ( uint32_t pcount;

if (result == IPQOS_S_LIST_EMPTY) break; if (result != IPQOS_S_SUCCESS) QosError(__FILE__, __LINE__, result);

result = IpqosGetPolicyListCount(ipqosAdaptr, &pcount); if (result != IPQOS_S_SUCCESS) QosError(__FILE__, __LINE__, result);

if (pcount > 0) //The adapter’s policy list is not empty

...<do something with the policy list here>... }

result = IpqosGetAdapterListNext(&ipqosAdaptr); if (result != IPQOS_S_SUCCESS && result != IPQOS_S_LIST_EMPTY) QosError(__FILE__, __LINE__, result); }

Chapter 228

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). If you want to delete all policies (and their associated filters) from all adapters, specify NULL as the IpqosAdapter argument. In this case, the entire HP-UX IPQoS configuration is deleted, once the session is committed.

Chapter 2 29

Using the HP-UX IPQoS API

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.

Filter-related functions in the HP-UX IPQoS API allow programmers to create filters, assign (“set”) and access (“get”) values of their attributes, and associate filters with policies.

Table 2-1 lists the attributes associated with filter objects.

Table 2-1 Attributes Associated with Filter Objects

Object Type Attributes

Filter unique name

source addresses destination addresses source port numbers destination port numbers network protocol number (0x800 or 0x86DD) transport protocol number (tcp or udp) destination physical address DSCP(s) priority status

Filter Overlap

A filter is said to overlap another filter if:

— both filters are associated with the same adapter — the priority attribute of the filter is of equal or greater priority than the other — the filter defines a set of traffic that is a superset of the traffic defined by the other filter

(complete overlap), or has an intersection with the traffic defined by the other filter (partial overlap)

Chapter 230

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.

The HP-UX IPQoS API has a function IpqosCheckFilterOverlap() to assist with checking for these cases. Refer to the IpqosOverlapFilter (3c) manpage for more detailed information on how to check for overlapping filters.

Chapter 2 31

Using the HP-UX IPQoS API

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.

Policy-related functions in the HP-UX IPQoS API allow programmers to create policies, assign (“set”) and access (“get”) values of their attributes, associate them with adapters, and traverse their filters’ lists.

Table 2-2 lists the attributes associated with policy objects.

Table 2-2 Attributes Associated with Policy Objects

Object Type Attributes

Policy unique name

reservation bandwidth maximum bandwidth DSCP VLAN priority status

Chapter 232

Using the HP-UX IPQoS API

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.

Table 2-3 lists the attributes associated with adapter objects.

Table 2-3 Attributes Associated with Adapter Objects

Object Type Attributes

Adapter unique name (PPA name)

transmission speed link type physical address

NOTE In this release, the link type will always be DL_ETHER.

Chapter 2 33

Using the HP-UX IPQoS API

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()).

From a high-level (pseudo-code) perspective the technique to obtain HP-UX IPQoS statistics for all policies and filters is as follows:

—Start an IPQOS_SESSION_STATS session. This will read the current HP-UX IPQoS

configuration. — Traverse the list of adapters and the policy list of each adapter in the configuration. —Call IpqosGetPolicyStats() for the policy. — Get the specific statistics counters for the policy using the appropriate functions. — Traverse the list of filters for the policy. — Get the statistics counters for the filters using the appropriate functions. Repeat for all policies as needed. Table 2-4 lists the counters maintained by the HP-UX IPQoS kernel module for every active

policy and filter.

Table 2-4 Counters Kept for Statistics

Object Type Counters

Policy Packet Count

Byte Count Dropped Packet Count Dropped Byte Count

Filter Packet Count

Byte Count

Chapter 234

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.

Chapter 3 35

Troubleshooting

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 <netinet/ipqos.h>

— Programs must link to the shared library libipqos.sl

— Programmer must have super-user (root) privileges

• For detailed syntax information refer to one or more of the following HP-UX IPQoS

manpages: IpqosAPI (3c), IpqosSession (3c), IpqosAdapter (3c), IpqosPolicy (3c),

IpqosFilter (3c), IpqosOverlapFilter (3c) and IpqosStats (3c).

• For a list of function return codes and their meaning, refer to Appendix B, “Return

Codes,” on page 49. Identify the cause of the error, and fix the problem accordingly.

• If appropriate, you can use ipqosadmin, the user-interface command utility provided with

HP-UX IPQoS, to obtain information about the configuration. Refer to the ipqosadmin

(1m) manpage for information on how to use ipqosadmin.

• You can continue to use the same general HP-UX networking utilities you typically use to

get useful information on the network. There is nothing new or different about using

these utilities when running and troubleshooting the HP-UX IPQoS API.

Some of the general networking utilities available include: netstat, ifconfig, syslog,

nettl, traceroute, route, ping, and lanadmin. Refer to the respective online manpages

for more information on how to use these utilities and how to interpret output from them.

Public domain utilities such as tcpdump and MRTP (multi-router traffic grapher) can also

provide helpful information about the network. HP includes the tcpdump utility as part of

the HP-UX Internet Express bundle, available on HP Software Depot, at

http://www.hp.com/go/softwaredepot.

Chapter 336

Troubleshooting

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.

• You can look for messages logged by the HP-UX IPQoS API library in

/var/adm/syslog/syslog.log, under the name libipqos.

• HP-UX IPQoS database file(s):

/opt/ipqos/db/ipqosdb.db (and /opt/ipqos/db/ipqosdb.db.bak if it exists)

• If the problem is reproducible, and you suspect errors in API-kernel communications, set

the HP-UX IPQoS loglevel to debug (run, ipqosadmin -loglevel debug) to capture

HP-UX IPQoS kernel module debug messages. Save and include the log file (by default,

messages go to /var/adm/syslog/syslog.log).

Chapter 3 37

Troubleshooting

Reporting Problems to HP

Chapter 338

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.

Appendix A 39

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.

Table A-1 Session-Related Functions

Description Function

initiate a session uint32_t IpqosInitSession (uint32_t version,

char * configName, IpqosSessionType sessionType)

get session type IpqosSessionType IpqosGetSessionType()

commit session uint32_t IpqosCommitSession()

abort session uint32_t IpqosAbortSession()

get description of return code

char * IpqosStrerror(uint32_t errCode)

Appendix A40

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.

Table A-2 Adapter-Related Functions

Description Function

get name of adapter uint32_t IpqosGetAdapterName(IpqosAdapter adapter,

char ** name)

get speed of adapter uint32_t IpqosGetAdapterSpeed(IpqosAdapter adapter,

uint64_t * speed)

get link type of adapter uint32_t IpqosGetAdapterLinkType(IpqosAdapter

adapter, uint32_t * linkType)

get physical address of adapter

get number of entries in adapter list

get first entry in adapter list

get next entry in adapter list

get number of entries in policy list of adapter

get first entry of policy list of adapter

get next entry of policy list of adapter

uint32_t IpqosGetAdapterPhysAddr(IpqosAdapter

adapter, char ** physAddr)

uint32_t IpqosGetAdapterListCount(uint32_t * count)

uint32_t IpqosGetAdapterListHead(IpqosAdapter

* adapter)

uint32_t IpqosGetAdapterListNext(IpqosAdapter

* adapter)

uint32_t IpqosGetPolicyListCount(IpqosAdapter adapter, uint32_t * count)

uint32_t IpqosGetPolicyListHead(IpqosAdapter adapter, IpqosPolicy * policy)

uint32_t IpqosGetPolicyListNext(IpqosAdapter adapter, IpqosPolicy * policy)

Appendix A 41

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.

Table A-3 Policy-Related Functions

Description Function

create policy uint32_t IpqosCreatePolicy(IpqosPolicy * policy)

destroy policy uint32_t IpqosDestroyPolicy(IpqosPolicy * policy)

copy policy uint32_t IpqosCopyPolicy(IpqosPolicy origPolicy,

IpqosPolicy * newPolicy)

get name of policy uint32_t IpqosGetPolicyName(IpqosPolicy policy,

char ** name)

get reservation bandwidth of policy

get max bandwidth of policy

get DSCP of policy uint32_t IpqosGetPolicyDSCP(IpqosPolicy policy,

get VLAN priority of policy

set name of policy uint32_t IpqosSetPolicyName(IpqosPolicy policy,

set reservation bandwidth of policy

set max bandwidth of policy

set DSCP of policy uint32_t IpqosSetPolicyDSCP(IpqosPolicy policy,

uint32_t IpqosGetPolicyReservation( IpqosPolicy policy, uint64_t * res, uint8_t * mode)

uint32_t IpqosGetPolicyMax(IpqosPolicy policy, uint64_t * max, uint8_t * mode)

uint8_t * dscp)

uint32_t IpqosGetPolicyVLANPriority(IpqosPolicy policy, uint8_t * vlanPr)

char * name)

uint32_t IpqosSetPolicyReservation(IpqosPolicy policy, uint64_t res)

uint32_t IpqosSetPolicyMax(IpqosPolicy policy,

uint64_t max,)

uint8_t dscp)

Appendix A42

Table A-3 Policy-Related Functions (Continued)

Description Function

Function Calls

Policy-Related Function Calls

set VLAN priority of policy

attach policy to adapter uint32_t IpqosAttachPolicy(IpqosPolicy policy,

delete policy from adapter

delete all policies from adapter

get status of policy uint32_t IpqosGetPolicyStatus(IpqosPolicy policy,

get filter list count of policy

get filter list head of policy

get next item in filter list of policy

uint32_t IpqosSetPolicyVLANPriority(IpqosPolicy policy, uint8_t vlanPr)

IpqosAdapter adapter)

uint32_t IpqosDeletePolicy(IpqosPolicy policy)

uint32_t IpqosDeleteAll(IpqosAdapter adapter)

uint32_t * status)

uint32_t IpqosGetFilterListCount(IpqosPolicy policy, uint32_t * count)

uint32_t IpqosGetFilterListHead(IpqosPolicy policy, IpqosFilter * filter)

uint32_t IpqosGetFilterListNext(IpqosPolicy policy, IpqosFilter * filter)

Appendix A 43

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.

Table A-4 Filter-Related Functions

Description Function

create filter uint32_t IpqosCreateFilter(IpqosFilter * filter)

destroy filter uint32_t IpqosDestroyFilter(IpqosFilter * filter)

copy filter uint32_t IpqosCopyFilter(IpqosFilter origFilter,

IpqosFilter * newFilter)

get name of filter uint32_t IpqosGetFilterName(IpqosFilter filter,

char ** name)

get source addresses of filter

get destination addresses of filter

get source port numbers of filter

get destination port numbers of filter

get network protocol number of filter

get transport protocol number of filter

get destination physical address of filter

get DSCP of filter uint32_t IpqosGetFilterDSCP(IpqosFilter filter,

uint32_t IpqosGetFilterSrcAddresses(IpqosFilter

filter, char ** addrLow, char ** addrHigh)

uint32_t IpqosGetFilterDstAddresses(IpqosFilter filter, char ** addrLow, char ** addrHigh)

uint32_t IpqosGetFilterSrcPortNumbers(IpqosFilter filter, uint16_t * portLow, uint16_t * portHigh)

uint32_t IpqosGetFilterDstPortNumbers(IpqosFilter filter, uint16_t * portLow, uint16_t ** portHigh)

uint32_t IpqosGetFilterNetProtocol(IpqosFilter filter, uint16_t * netProto)

uint32_t IpqosGetFilterXportProtocol(IpqosFilter filter, uint8_t * xportProto)

uint32_t IpqosGetFilterDstPhysAddress(IpqosFilter

filter, char ** physAddr)

uint8_t * dscpLOW, uint8_t * dscpHigh)

Appendix A44

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

set destination addresses of filter

set source port numbers of filter

set destination port numbers of filter

set network protocol number of filter

set transport protocol number of filter

set destination physical address of filter

set priority of filter uint32_t IpqosSetFilterPriority(IpqosFilter filter,

set name of filter uint32_t IpqosSetFilterName(IpqosFilter filter,

set DSCP of filter uint32_t IpqosSetFilterDSCP(IpqosFilter filter,

uint32_t IpqosSetFilterSrcAddresses(IpqosFilter

filter, char * addrLow, char * addrHigh)

uint32_t IpqosSetFilterDstAddresses(IpqosFilter filter, char * addrLow, char * addrHigh)

uint32_t IpqosSetFilterSrcPortNumbers(IpqosFilter filter, uint16_t portLow, uint16_t portHigh)

uint32_t IpqosSetFilterDstPortNumbers(IpqosFilter filter, uint16_t portLow, uint16_t * portHigh)

uint32_t IpqosSetFilterNetProtocol(IpqosFilter filter, uint16_t netProto)

uint32_t IpqosSetFilterXportProtocol(IpqosFilter filter, uint8_t xportProto)

uint32_t IpqosSetFilterDstPhysAddress(IpqosFilter filter, char * physAddr)

uint32_t priority)

char * name)

uint8_t dscpLOW, uint8_t dscpHigh)

Appendix A 45

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.

Table A-5 Filter Overlap-Related Functions

Description Function

checks if filter1 overlaps filter2

checks if source addresses for filter1 overlap those of filter2

checks if destination addresses for filter1 overlap those of filter2

checks if source port numbers for filter1 overlap those of filter2

checks if destination port numbers for filter1 overlap those for filter2

checks if network protocol for filter1 overlaps that of filter2

checks if transport protocol for filter1 overlaps that of filter2

uint32_t IpqosCheckFilterOverlap(IpqosFilter filter1,

IpqosFilter filter2)

uint32_t IpqosCheckSrcAddressesOverlap(IpqosFilter filter1, IpqosFilter filter2)

uint32_t IpqosCheckDstAddressesOverlap(IpqosFilter filter1, IpqosFilter filter2)

uint32_t IpqosCheckSrcPortNumbersOverlap(IpqosFilter filter1, IpqosFilter filter2)

uint32_t IpqosCheckDstPortNumbersOverlap(IpqosFilter filter1, IpqosFilter filter2)

uint32_t IpqosCheckNetProtocolOverlap(IpqosFilter filter1, IpqosFilter filter2)

uint32_t IpqosCheckXportProtocolOverlap(IpqosFilter

filter1, IpqosFilter filter2)

checks if destination physical address for filter1 overlaps that of filter2

uint32_t IpqosCheckDstPhysAddressOverlap(IpqosFilter filter1, IpqosFilter filter2)

Appendix A46

Filter Overlap-Related Function Calls

Table A-5 Filter Overlap-Related Functions (Continued)

Description Function

Function Calls

checks if DSCP for filter1 overlaps that of filter2

uint32_t IpqosCheckDSCPOverlap(IpqosFilter filter1, IpqosFilter filter2)

Appendix A 47

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.

Table A-6 Statistics-Related Functions

Description Function

Get Statistics Counters of policy (plus all its filters)

Reset Statistics Counters of policy

Get Byte Count statistic of policy

Get Packet Count statistic of policy

Get Dropped Byte Count statistic of policy

Get Dropped Packet Count statistic of policy

Get Byte Count statistic of filter

Get Packet Count statistic of filter

uint32_t IpqosGetPolicyStats(IpqosPolicy policy)

uint32_t IpqosResetPolicyStats(IpqosPolicy policy)

uint32_t IpqosGetPolicyStatsByteCount(IpqosPolicy policy, uint64_t * count)

uint32_t IpqosGetPolicyStatsPacketCount(IpqosPolicy policy, uint64_t * count)

uint32_t IpqosGetPolicyStatsDroppedByteCount(IpqosPolicy policy, uint64_t * count)

uint32_t IpqosGetPolicyStatsDroppedPacketCount(IpqosPolicy policy, uint64_t * count)

uint32_t IpqosGetFilterStatsByteCount(IpqosFilter filter, uint64_t * count)

uint32_t IpqosGetFilterStatsPacketCount(IpqosFilter filter, uint64_t * count)

Appendix A48

B Return Codes

This appendix contains information on return codes provided by the HP-UX IPQoS API.

Appendix B 49

Return Codes

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.

Table B-1 Return Codes with Mnemonics and Message Strings

Ret

0 IPQOS_S_SUCCESS Success

1 IPQOS_E_INVALID_OBJ Object is invalid

2 IPQOS_E_INVALID_MODE Mode is invalid

3 IPQOS_E_BW_RESV_EXCEEDED Adapter’s bandwidth reservation capacity

4 IPQOS_E_NOT_VLAN Adapter is not a VLAN

5 IPQOS_E_ATTRIBUTE_NOT_SET Attribute is not set

6 IPQOS_E_KERN_ALLOC Dynamic memory allocation failed (kernel)

7 IPQOS_E_NAME_NOT_UNIQUE Name is not unique

8 IPQOS_E_BAD_PHY_ADDR Physical address is invalid

9 IPQOS_E_NOMEM Dynamic memory allocation failed

10 IPQOS_E_PARAMERR Parameter error

11 IPQOS_E_LIST_EMPTY List is empty

12 IPQOS_E_PERM Permission denied

Mnemonic Message String

exceeded

13 IPQOS_E_NO_STATS Stats not available for this object

14 IPQOS_E_NOT_ATTACHED Object is not attached

15 IPQOS_E_ALREADY_ATTACHED Object is already attached

16 IPQOS_E_SESSION_TYPE Session type does not allow operation

Appendix B50

Return Codes, Mnemonics and Message Strings

Table B-1 Return Codes with Mnemonics and Message Strings

Return Codes

Ret

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 (<errno_value> <errno_string>)

23 IPQOS_E_DATABASE_BUSY IPQoS database is busy

24 IPQOS_E_NO_OVERLAP No overlap

25 IPQOS_E_OVERLAP_NOT_SET Unset attribute overlap

26 IPQOS_E_OVERLAP_SUPERSET Superset overlap

27 IPQOS_E_OVERLAP_INTERSECTION Intersection overlap

Mnemonic Message String

Appendix B 51

Return Codes

Return Codes, Mnemonics and Message Strings

Appendix B52

C Code Example

This appendix contains a simple pseudo-code program that illustrates how to create a simple HP-UX IPQoS configuration.

Appendix C 53

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.

########## function checkResult(function, result){ if (result != IPQOS_S_SUCCESS){

print “%s returned %d: %s”, function, result, IpqosStrerror(result); IpqosAbortSession(); exit; } else{ return; } }

main(){ /* start a session of type IPQOS_SESSION_CONFIG */ result = IpqosInitSession(IPQOS_API_VERSION_ID_1,NULL, IPQOS_SESSION_CONFIG) checkResult(“IpqosInitSession”,result);

/* look for lan0 in adapter list */ result = IpqosGetAdapterListHead(&ipqosAdapter); while(result != IPQOS_S_LIST_EMPTY){

checkResult(“IpqosGetAdapterListHead/IpqosGetAdapterListNext”, result);

/* get the name of the adapter and compare with lan0 */ result = IpqosGetAdapterName(ipqosAdapter,&adapterName); checkResult(“IpqosGetAdapterName”,result);

if (adapterName == “lan0”) break; /* found it! */

/* continue search */ result = IpqosGetAdapterListNext(&ipqosAdapter); } /* did we find lan0 at all? */ if (result == IPQOS_S_LIST_EMPTY){ print “Error: could not find lan0 in API’s adapter list” exit;

Appendix C54

}

/* 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 = IpqosAttachPolicy(ipqosPolicy,ipqosAdapter); checkResult(“IpqosAttachPolicy”,result);

/* Create an IpqosFilter */ result = IpqosCreateFilter(&ipqosFilter); checkResult(“IpqosCreateFilter”,result);

/* API mandates name, so give it one */ result = IpqosSetFilterName(ipqosFilter,”testFilter”); checkResult(“IpqosSetFilterName”,result);

Code Example

Configuration Code Example

/* Set the dst port number range */ result = IpqosSetFilterDstPortNumbers(ipqosFilter,80,100); checkResult(“IpqosSetFilterDstPortNumbers”,result);

/* Attach the filter to the policy */ result = IpqosAttachFilter(ipqosFilter,ipqosPolicy); checkResult(“IpqosAttachFilter”,result);

/* commit the session! */ result = IpqosCommitSession(); checkResult(“IpqosCommitSession”,result); } #############

Appendix C 55

Code Example

Configuration Code Example

Appendix C56

Index

adapter attributes adapter objects, 33 adapter-related functions, 41 adapters, 12 architectural overview, 13 attaching a filter object, 27 attaching a policy object, 27 attributes

adapter filter, 25, 30 policy, 25, 32

benefits of the HP-UX IPQoS API

code example - traversing a list copying a filter, 25 copying a policy object, 25 counters for statistics, 34 creating a filter object, 25 creating a policy object, 25

deleting a filter object deleting a policy object, 29 destroying a filter object, 25 destroying a policy object, 25 documentation available on HP-UX IPQoS, 8

filter attributes filter object restrictions, 27 filter objects, 30 filter-related functions, 44 filters, 12, 30 functional overview, 17

header file

initiating a session ipqos.h, 16 IPQOS_S_SUCCESS, 19, 22

, 25, 33

, 16

, 33

, 14

, 28

, 29

, 30

, 22

IPQOS_SESSION_CONFIG, 22, 23 IPQOS_SESSION_READ, 22, 23 IPQOS_SESSION_STATS, 22, 23, 34 IPQOS_STATUS_ACTIVE, 23 IPQOS_STATUS_ACTIVE_UPON_COMMI

, 24

IPQOS_STATUS_INACTIVE, 24 IPQOS_STATUS_INACTIVE_UPON_COM

MIT

IpqosAbortSession(), 23, 40 IpqosAdapter(3c), 19 ipqosadmin, 36 IpqosAPI(3c), 19 IpqosAttachFilter(), 27 IpqosAttachPolicy(), 27, 43 IpqosCheckFilterOverlap(), 31 IpqosCommitSession(), 23, 40 IpqosCopyFilter(), 25, 44 IpqosCopyPolicy(), 25, 42 IpqosCreateFilter(), 25, 44 IpqosCreatePolicy(), 25, 42 IpqosDeleteAll(), 29, 43 IpqosDeleteFilter(), 29 IpqosDeletePolicy(), 29, 43 IpqosDestroyFilter(), 25, 44 IpqosDestroyPolicy(), 25, 42 IpqosFilter(3c), 19 IpqosGetAdapterLinkType(), 41 IpqosGetAdapterListCount(), 28, 41 IpqosGetAdapterListHead(), 27, 41 IpqosGetAdapterListNext(), 28, 41 IpqosGetAdapterName(), 41 IpqosGetAdapterPhysAddr(), 41 IpqosGetAdapterSpeed(), 41 IpqosGetFilterDSCP(), 44 IpqosGetFilterDstAddresses(), 44 IpqosGetFilterDstPhysAddress(), 44 IpqosGetFilterDstPortNumbers(), 44 IpqosGetFilterListCount(), 28, 43 IpqosGetFilterListHead(), 27, 43 IpqosGetFilterListNext(), 28, 43 IpqosGetFilterName(), 44 IpqosGetFilterNetProtocol(), 44 IpqosGetFilterPriority(), 45 IpqosGetFilterSrcAddresses(), 44 IpqosGetFilterSrcPortNumbers(), 44 IpqosGetFilterStatus(), 45 IpqosGetFilterXportProtocol(), 44 IpqosGetPolicyDSCP(), 42 IpqosGetPolicyListCount(), 28, 41

, 24

Index

IpqosGetPolicyListHead() 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 IpqosSetFilterNetProtocol(), 45 IpqosSetFilterPriority(), 45 IpqosSetFilterSrcAddresses(), 45 IpqosSetFilterSrcPortNumbers(), 45 IpqosSetFilterXportProtocol(), 45 IpqosSetPolicyDSCP(), 42 IpqosSetPolicyMax(), 42 IpqosSetPolicyName(), 42 IpqosSetPolicyReservation(), 42 IpqosSetPolicyVLANPriority(), 43 IpqosStats(3c), 19 IpqosStrerror(), 20, 40

leverage existing IPQoS applications libipqos.sl, 16 list usage in the HP-UX IPQoS API, 16, 26

manipulate a configuration manpages, 8, 15, 18

object attributes object status, 23 object usage in the HP-UX IPQoS API, 16, 25 objects

adapters filters, 30 policies, 32

, 25

, 33

, 27, 41

, 14

/opt/ipqos/examples, 20 overlapping filters, 30

policies policy attributes, 32 policy object restrictions, 27 policy objects, 32 policy-related functions, 42

reporting problems return codes, 19 RFCs (relevant to HP-UX IPQoS), 8

sample program session types, 22 session usage in the HP-UX IPQoS API, 17,

session-related functions, 40 shared library, 16 statistics, 14, 34

tasks performed by HP-UX IPQoS API tasks performed by the HP-UX IPQoS API,

tcpdump, 36 terminating a session, 23 that, 25 traverse a configuration, 14 traversing a list - code example, 28 traversing lists, 27 troubleshooting, 36

/var/adm/syslog/syslog.log

, 12, 32

, 37

, 20

, 14

, 37

Index

HP HP-UX IPQos User's Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

About This Document

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

Programmatic Requirements

Structural Overview (How to Use the HP-UX IPQoS API)

Functional Overview (What You Can Do Using the HP-UX IPQoS API)

Manpages

Return Codes

Restoring Configurations to the Kernel after Reboot

Sample Program

2 Using the HP-UX IPQoS API

Using Sessions

Starting a Session

Session Types

Terminating a Session

Object Status

Using Objects

Creating, Copying and Destroying Objects

Object Attributes

Using Lists

Attaching Objects to Lists

Restrictions

Traversing Lists

Code Example: Traversing An Adapter List

Deleting Policies and Filters (Detaching From a List)

Filter Objects

Filter Overlap

Policy Objects

Adapter Objects

Statistics

3 Troubleshooting

General Tips

Reporting Problems to HP

A Function Calls

Session-Related Function Calls

Adapter-Related Function Calls

Policy-Related Function Calls

Filter-Related Function Calls

Filter Overlap-Related Function Calls

Statistics-Related Function Calls

B Return Codes

Return Codes, Mnemonics and Message Strings

C Code Example

Configuration Code Example