HP HP-UX IPQos User's Guide

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

+ 41 hidden pages