HP WebQoS User's Guide

Download

HP WebQoS on HP-UX

API Programmer’s Guide

Edition 1

HP 9000 Networking

Manufacturing Part Number: B8311-90003

E1299

U.S.A.

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 ﬁtness 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 speciﬁc warranty terms applicable to your Hewlett- Packard product and replacement parts can be obtained from your local Sales and Service Ofﬁce.

Restricted Rights Legend. Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 for DOD agencies, and subparagraphs (c) (1) and (c) (2) of the Commercial Computer Software Restricted Rights clause at FAR 52.227-19 for other agencies.

HEWLETT-PACKARD COMPANY 3000 Hanover Street Palo Alto, California 94304 U.S.A.

Use of this manual and ﬂexible disk(s) or tape cartridge(s) supplied for this pack is restricted to this product only. Additional copies of the programs may be made for security and back-up purposes only. Resale of the programs in their present form or with alterations, is expressly prohibited.

Reproduction, adaptation, or translation of this document without prior written permission is prohibited, except as allowed under the copyright laws.

This software is based in part on the Fourth Berkeley Software Distribution under license from the Regents of the University of California.

©copyright 1980, 1984, 1986 Novell, Inc. ©copyright 1986-1992 Sun Microsystems, Inc. ©copyright 1985-86, 1988 Massachusetts Institute of Technology. ©copyright 1989-93 The Open Software Foundation, Inc. ©copyright 1986 Digital Equipment Corporation. ©copyright 1990 Motorola, Inc. ©copyright 1990, 1991, 1992 Cornell University ©copyright 1989-1991 The University of Maryland ©copyright 1988 Carnegie Mellon University Trademark Notices. UNIX is a registered trademark in the United

States and other countries, licensed exclusively through X/Open Company Limited.

X Window System is a trademark of the Massachusetts Institute of Technology.

OSF/Motif is a trademark of the Open Software Foundation, Inc. in the U.S. and other countries.

Contents

1. About the WebQoS API

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

2. Using the WebQoS API

wq_get_session_cls() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

Return Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

wq_set_session_cls() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

cls Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

Return Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

wq_get_proc_cls(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Return Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Multithreaded Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

wq_set_proc_cls() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

class Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

Return Value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

Contents

Multithreaded Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

3. Troubleshooting

Checklist. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Request Classiﬁcation Rule Class Error Codes . . . . . . . . . . . . . . . . . . . 28

wq_get_session_cls() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

wq_set_session_cls() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Process Group Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

wq_get_proc_cls() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

wq_set_proc_cls(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Sample Session Class Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Sample Process Group Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

svccls.allow Conﬁguration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

webqosapi.h Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Printing History

The manual printing date and part number indicate its 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 manual part number will change when extensive changes are made.

Manual updates may be issued between editions to correct errors or document product changes. To ensure that you receive the updated or new editions, you should subscribe to the appropriate product support service. See your HP sales representative for details.

First Edition: December 1999 (HP-UX Release 11.0)

1 About the WebQoS API

About the WebQoS API

Overview

Using the WebQoS API, an application can reassign the classiﬁcation rule class of a session and the process group of a process. This allows more ﬁne-tuning of the assigned class(es). WebQoS must be conﬁgured to allow these changes to be made. Refer to the Installing and Conﬁguring WebQoS on HP-UX manual for more information about conﬁguring WebQoS.

The following ﬁgures show how the WebQoS API can be used to change the class of a classiﬁcation rule and process group. The ﬁrst two ﬁgures represent a single session.

Figure 1-1 Example — Initial Service Request

WebQoS

Initial Service Request

medium class classiﬁcation rule

Web Server

In Figure 1-1, “Example — Initial Service Request,” the initial service request is made by a client (for example, a browser). WebQoS sets the request classiﬁcation rule class to medium and passes the request to the web server. The web server passes the request to the application which then sets the request classiﬁcation rule class to high for this request.

Figure 1-2 Example — Subsequent Service Requests

WebQoS

high class

Subsequent Service Requests

classiﬁcation rule

Web Server

In Figure 1-2, “Example — Subsequent Service Requests,” subsequent requests during this WebQoS session use the high request classiﬁcation rule class set by the application. The application can change the request classiﬁcation rule class value one or more times during the session. This

medium class classiﬁcation rule

high class classiﬁcation rule

Plug-In

10 Chapter1

value is effective for subsequent requests for the current session.

Figure 1-3 Example — Setting the Process Group

Process Groups

About the WebQoS API

Overview

Process Groups

Process A

Process B

WebQoS

In Figure 1-3, “Example — Setting the Process Group,”two processes are assigned different process groups by WebQoS: Process A is assigned medium and Process B is assigned low. Process A requests that it be moved to the high process group. The WebQoS administrator must have conﬁgured the svccls.allow conﬁguration ﬁle to allow a process to change its process group.

High

Medium

Low

WebQoS API

High

Medium

Low

Chapter 1 11

About the WebQoS API

Overview

12 Chapter1

2 Using the WebQoS API

The WebQoS API is installed with the WebQoS software. For more information about installing the WebQoS API, refer to the Installing and Conﬁguring HP WebQoS manual.

Using the WebQoS API

There is one header ﬁle that must be included in your program (contents of this header ﬁle can be found in Appendix A , “Sample Programs, Conﬁguration, and Header Files,” on page 33):

• /usr/include/webqosapi.h There are four function calls available:

• wq_get_session_cls() — gets the current classiﬁcation rule class

of the current request being processed by the NSAPI plug-in application

• wq_set_session_cls() — sets the classiﬁcation rule class of the

current request being processed by the NSAPI plug-in application

• wq_get_proc_cls() — gets the process group deﬁned for the

current process or thread

• wq_set_proc_cls() — sets the process group of the current process When compiling your applications, you must link to one or two libraries:

• libqosapi_rq.sl — If you use wq_get_session_cls() or

wq_set_session_cls(), use -lqosapi_rq to link to this library.

• libqosapi_pr.sl and libprmext.sl — If you use

wq_get_proc_cls() or wq_set_proc_cls(), use -lqosapi_pr

-L/opt/prm/lib -lprmext to link to these libraries.

14 Chapter2

Using the WebQoS API

wq_get_session_cls()

Gets the current request classiﬁcation rule class of the current request being processed by the NSAPI plug-in application.

To use this function, WebQoS must be enabled and either

• SSL is not used and cookies are enabled, OR

• client connections must be persistent. If SSL is used and/or cookies are disabled and client connections are not

persistent, the value returned corresponds to the policy conﬁgured in WebQoS for this request.

The request classiﬁcation rule class value returned may have been set by a plug-in application (using wq_set_session_cls()) or may have been conﬁgured using the WebQoS management user interface.

This function is thread safe.

Synopsis

#include <webqosapi.h> int wq_get_session_cls(int socketid, int *errorcode)

Link using -lqosapi_rq

Arguments

socketid The socket ﬁle descriptor corresponding to the remote

client connecting to the web server.

errorcode The error code returned when the return value is -1.

Refer to “Errors” in this section for a list of error codes.

Chapter 2 15

Using the WebQoS API

wq_get_session_cls()

Return Value

wq_get_session_cls() returns a non-negative value representing the request classiﬁcation rule class or -1 if an error occurred.

Table 2-1 wq_get_session_cls() Return Values

Return Values Condition or

Class of Request Classiﬁcation Rule

-1 Error WQ_UCLASS_LOW Low WQ_UCLASS_MED Medium WQ_UCLASS_HIGH High

Errors

When an error occurs, errorcode is set to one of the following:

Table 2-2 wq_get_session_cls() Error Codes

Error Code Description

WQERR_INVALD_SOCKID A bad socketid value was passed to

wq_get_session_cls().

WQERR_USRCLAS_OTHER An internal request classiﬁcation rule class

error occurred.

WQERR_WQOS_DISABLED WebQoS is disabled and cannot provide the

request classiﬁcation rule information.

Example

See Appendix A , “Sample Programs, Conﬁguration, and Header Files,” on page 33 for an example.

16 Chapter2

Using the WebQoS API

wq_set_session_cls()

Sets the request classiﬁcation rule class of the current request being processed by the NSAPI plug-in application.

To successfully use this function, The WebQoS Administrator must conﬁgure WebQoS to allow the application to modify the request classiﬁcation rule class (refer to the Installing and Conﬁguring HP WebQoS manual for more information), WebQoS must be enabled, and either

• SSL is not used and cookies are enabled, OR

• client connections must be persistent. If SSL is used and/or cookies are disabled and client connections are not

persistent, the request classiﬁcation rule class set using this function is effective for the current request only (it will not be effective for subsequent requests).

This function is thread safe.

Synopsis

#include <webqosapi.h> int wq_set_service_cls(int socketid, uint32_t cls, int *errorcode)

Link using -lqosapi_rq

Arguments

socketid The socket ﬁle descriptor corresponding to the remote

client connecting to the web server.

cls The request classiﬁcation rule class to which the

application sets the request. This request classiﬁcation rule class is set for the next and subsequent client requests. Refer to “cls Values” for a list of request classiﬁcation rule class values.

errorcode The error code returned when the return value is -1.

Refer to “Errors” in this section for a list of error codes.

Chapter 2 17

Using the WebQoS API

wq_set_session_cls()

cls Values

Use the following values to set the request classiﬁcation rule class cls:

Table 2-3 wq_set_session_cls() cls Values

Class of Request Classiﬁcation Rule

Low WQ_UCLASS_LOW Medium WQ_UCLASS_MED High WQ_UCLASS_HIGH

cls Value

Return Value

wq_set_session_cls() returns 0 if it is successful or -1 if an error occurred.

Errors

When an error occurs, errorcode is set to one of the following:

Table 2-4 wq_set_session_cls() Error Codes

Error Code Description

WQERR_INVAL_USER_CLS The value provided for cls is not a deﬁned request

classiﬁcation rule class.

WQERR_INVALD_SOCKID A bad socketid value was passed to

wq_set_session_cls().

WQERR_PLCY_DISALLOW The WebQoS administrator has not conﬁgured a

policy allowing applications to modify its request classiﬁcation rule class.

WQERR_USRCLAS_OTHER An internal request classiﬁcation rule class error

occurred.

WQERR_WQOS_DISABLED WebQoS is disabled and cannot set the request

classiﬁcation rule class.

18 Chapter2

Using the WebQoS API

wq_set_session_cls()

Example

See Appendix A , “Sample Programs, Conﬁguration, and Header Files.”

Chapter 2 19

Using the WebQoS API

wq_get_proc_cls()

Gets the process group deﬁned for the current process or thread. This function is intended for processes that are separate from http

daemons, such as cgi-bin. Plug-In applications that are expected to run as http daemon threads (such as NSAPI plug-ins) should not link to libqosapi_pr.sl.

Synopsis

#include <webqosapi.h> int wq_get_proc_cls(int *errorcode)

Link using -lqosapi_pr -L/opt/prm/lib -lprmext

Arguments

errorcode The error code set when the return value is -1. Refer to

“Errors” in this section for a list of error codes.

Return Value

wq_get_proc_cls() returns a non-negative value representing the process group or -1 if an error occurred.

Table 2-5 wq_get_proc_cls() Return Values

wq_get_proc_cls()

Return Value

-1 Error WQ_SVCCLS_LOW Low WQ_SVCCLS_MED Medium WQ_SVCCLS_HIGH High WQ_SVCCLS_OTHER Other WQ_SVCCLS_ROOT PRM_SYS class; accessible by root only

20 Chapter2

Condition or Process Group

Errors

If error logging to syslog is enabled, certain errors are logged to a ﬁle (you can specify the ﬁle in /etc/syslog.conf). Refer to the syslog(3C) and syslogd(1M) man pages for information about enabling logging.

When an error occurs, errorcode is set to one of the following:

Table 2-6 wq_get_proc_cls() Error Codes

Error Code Description

WQERR_NOTREADY PRM is not installed or not conﬁgured on the system. WQERR_OTHER If error logging to syslog is enabled (“error” levelfor

all facilities), the error is logged to a ﬁle.

Multithreaded Applications

For HP-UX 10.20 (supports user-level threads only), all user-level threads within one process are in the same process group. wq_get_proc_cls() returns the same value when called from any of the threads of a process.

Using the WebQoS API

wq_get_proc_cls()

For HP-UX 11.0 (supports 1x1 kernel threads), a thread in user space corresponds to a kernel thread (also known as a Light Weight Process, LWP). LWPs may belong to different process groups. wq_get_proc_cls() may return different values within the same process. Currently, WebQoS cannot move a thread from one process group to another. Therefore, all threads in a process are in the same process group.

This function is thread safe.

Example

See Appendix A , “Sample Programs, Conﬁguration, and Header Files,” on page 33 for an example.

Chapter 2 21

Using the WebQoS API

wq_set_proc_cls()

Sets the process group of the current process. For a multithreaded process, all threads are set to the same speciﬁed process group.

A process is only allowed to change its process group to the value(s) speciﬁed in the ﬁle /etc/opt/webqos/svccls.allow. By default, a process cannot change its process group. Refer to the svccls.allow ﬁle for an explanation of how to conﬁgure this ﬁle. A copy of this ﬁle can be found in Appendix A , “Sample Programs, Conﬁguration, and Header Files,” on page 33.

Synopsis

#include <webqosapi.h> int wq_set_proc_cls(uint32_t class, uint32_t scope, int *errorcode)

Link using -lqosapi_pr -L/opt/prm/lib -lprmext

Arguments

class The process group to which the application sets the

process to be in. Refer to “class Values” for a list of process group values.

scope Speciﬁes scope of the function, which can be the entire

process or a thread. Currently, only the entire process can be set (using WQ_SCOPE_PROCESS). For more information about multithreaded applications, refer to “Multithreaded Applications” in this section.

errorcode The error code set when the return value is -1. Refer to

“Errors” in this section for a list of error codes.

22 Chapter2

class Values

wq_set_proc_cls() can pass the following values:

Table 2-7 wq_set_proc_cls() class Values

Process Group class Value

Low WQ_SVCCLS_LOW Medium WQ_SVCCLS_MED High WQ_SVCCLS_HIGH Other WQ_SVCCLS_OTHER PRM_SYS class; accessible by root only WQ_SVCCLS_ROOT

Return Value

wq_set_proc_cls() returns 0 if it is successful or -1 if an error occurred.

Using the WebQoS API

wq_set_proc_cls()

Errors

When an error occurs, errorcode is set to one of the following:

Table 2-8 wq_set_proc_cls() Error Codes

Error Code Description

WQERR_BADSCOPE The value provided for scope is not deﬁned.

Currently, WQ_SCOPE_PROCESS is the only deﬁned value.

WQERR_BADSVCCLASS The value provided for class is not a deﬁned

process group.

WQERR_CONNECT Problems connecting to the SCA process. If error

logging to syslog is enabled, the errors are logged to a ﬁle.

Chapter 2 23

Using the WebQoS API

wq_set_proc_cls()

Table 2-8 wq_set_proc_cls() Error Codes

Error Code Description

WQERR_NOTROOT The process attempted to set the process group to

a value that can only be accessed by root.

WQERR_NOTREADY PRM is not installed or not conﬁgured on the

system.

WQERR_OTHER If error logging to syslog is enabled (“error” level

for all facilities), the error is logged to a ﬁle.

WQERR_PERMISSION The process does not have permission to change

to the speciﬁed process group. Make sure that the /etc/opt/webqos/svccls.allow ﬁle is conﬁgured and is not corrupt.

Multithreaded Applications

For HP-UX 10.20 (supports user-level threads only), all user-level threads within one process are in the same process group. wq_set_proc_cls() ignores scope and moves the entire process to the speciﬁed process group.

For HP-UX 11.0 (supports 1x1 kernel threads), a thread in user space corresponds to a kernel thread (also known as a Light Weight Process, LWP). LWPs may belong to different process groups. Currently, WebQoS cannot move a thread from one process group to another. Therefore, all threads in a process are in the same process group. Set scope to WQ_SCOPE_PROCESS to move all threads in a process to the speciﬁed process group.

This function is NOT thread safe. Although it can be called from a multithreaded process, the application must ensure that the function is

not called by more than one thread at a time.

Example

See Appendix A , “Sample Programs, Conﬁguration, and Header Files,” on page 33 for an example.

24 Chapter2

3 Troubleshooting

Troubleshooting

Checklist

Run through the following steps to isolate your problem.

Step 1. Check the errorcode returned by the function. A description of the

errorcode and actions to take are listed in this chapter.

Step 2. Verify the parameters, values, and declarations by running the sample

programs provided in Appendix A , “Sample Programs, Conﬁguration, and Header Files,” on page 33.

Step 3. For request classiﬁcation rule class errors, check the

/var/opt/webqos/logs/qoslog and the /var/opt/webqos/logs/acclog ﬁle.

For process group errors, check the /var/adm/syslog/syslog.log ﬁle.

Step 4. Verify that WebQoS is enabled. From the WebQoS management user

interface:

1. Select the system on which WebQoS should be running.

2. Choose File from the menu bar.

3. Conﬁrm that Enable WebQoS on a System is selected.

Step 5. Verify that the WebQoS administrator has allowed the application to set

the request classiﬁcation rule class. Toverify that the application can set the request classiﬁcation rule class,

from the WebQoS management user interface:

1. Select the site whose conﬁguration you want to verify.

2. Select Edit.

3. Select the Classification Rules tab.

4. Check that the policy includes Application sets the request

priority. This must be included.

Step 6. Verify that the WebQoS administrator has allowed the application to set

the process group. To verify that the application can set the process group, check that the

/etc/opt/webqos/svccls.allow ﬁle has been changed to allow the user to modify the process group.

26 Chapter3

Request Classiﬁcation Rule Class Error Codes

wq_get_session_cls()

Error Code WQERR_INVALD_SOCKID Description A bad socketid value was passed. Action Check that the socketid you received from the function is valid.

Error Code WQERR_USRCLAS_OTHER Description An internal request classiﬁcation rule class error occurred. Action Contact your HP Support Representative.

Error Code WQERR_WQOS_DISABLED

Troubleshooting

Description WebQoS is disabled and cannot get or set the request classiﬁcation rule class information. Action Enable WebQoS. WebQoS must be enabled before the functions will run. Refer to the

Installing and Conﬁguring WebQoS manual for more information about enabling WebQoS.

wq_set_session_cls()

Error Code WQERR_INVAL_USER_CLS Description The value provided for cls is not a deﬁned request classiﬁcation rule class. Action Use one of the pre-deﬁned request classiﬁcation rules deﬁned in

/usr/include/webqosapi.h. Currently, WebQoS does not support the customization of request classiﬁcation rule class deﬁnitions.

Error Code WQERR_INVALD_SOCKID Description A bad socketid value was passed. Action Check that the socketid you are passing is valid.

Chapter 3 27

Troubleshooting

Request Classiﬁcation Rule Class Error Codes

Error Code WQERR_PLCY_DISALLOW Description The WebQoS administrator has not conﬁgured a policy allowing applications to modify

its request classiﬁcation rule class.

Action Contact the WebQoS administrator to conﬁgure a policy to allow applications to modify

the request classiﬁcation rule class. Refer to the Conﬁguring HP WebQoS manual for more information about conﬁguring the policy.

Error Code WQERR_USRCLAS_OTHER Description An internal request classiﬁcation rule class error occurred. Action Contact your HP Support Representative.

Error Code WQERR_WQOS_DISABLED Description WebQoS is disabled and cannot get or set the request classiﬁcation rule class information. Action Enable WebQoS. WebQoS must be enabled before the functions will run. Refer to the

Installing and Conﬁguring WebQoS manual for more information about enabling WebQoS.

28 Chapter3

Troubleshooting

Process Group Error Codes

wq_get_proc_cls()

Error Code WQERR_NOTREADY Description PRM is not installed or not conﬁgured on the system. Action Install and conﬁgure PRM on the system.

Error Code WQERR_OTHER Description If error logging to syslog is enabled (“error” level for all facilities), the error is logged to

the /var/adm/syslog/syslog.log log ﬁle.

Action Check the /var/adm/syslog/syslog.log log ﬁle for more information. If error

logging is not enabled, enable it and try running your application again to generate error messages.

wq_set_proc_cls()

Error Code WQERR_BADSCOPE Description The value provided for scope is not deﬁned. WQ_SCOPE_PROCESS is the only deﬁned

value that can be used.

Action scope can only be set to WQ_SCOPE_PROCESS.

Error Code WQERR_BADSVCCLASS Description The value provided for class is not a deﬁned process group. Action Use one of the pre-deﬁned process group values deﬁned in

/usr/include/webqosapi.h. Currently, WebQoS does not support the customization of process group deﬁnitions.

Chapter 3 29

Troubleshooting

Process Group Error Codes

Error Code WQERR_CONNECT Description Problems connecting to the SCA process. If error logging to syslog is enabled, the errors

are logged to the /var/adm/syslog/syslog.log log ﬁle.

Action Check the /var/adm/syslog/syslog.log log ﬁle for more information. If error

logging is not enabled, enable it and try running your application again to generate error messages.

Possible errors in syslog.log include:

• cannot ﬁnd entry “hp-sca” in /etc/services. Action: Add the entry hp-sca 19411/tcp to the /etc/services ﬁle.

• connect to SCA fails. The sca process is not running or is not responding. Action: Run the following commands:

— /opt/webqos/vin/sca_stop — /opt/webqos/vin/sca_start

• Other Action: Contact your HP Support Representative.

Error Code WQERR_NOTROOT Description The process attempted to set the process group to a value that can only be accessed by

root.

Action Set the process group to another value; or make sure the process setting the process group

is a root process.

Error Code WQERR_NOTREADY Description PRM is not installed or not conﬁgured on the system. Action Run the following command:

prmconfig -ie -f /etc/opt/webqos/QP_prmconf

30 Chapter3

Troubleshooting

Process Group Error Codes

Error Code WQERR_OTHER Description If error logging to syslog is enabled (“error” level for all facilities), the error is logged to

the /var/adm/syslog/syslog.log log ﬁle.

Action 1. Check the /var/adm/syslog/syslog.log log ﬁle for more information. If

error logging is not enabled, enable it and try running your application again to generate error messages.

2. Check that /etc/opt/webqos/svccls.allow exists and is readable by the process that is failing.

3. Make sure /etc/opt/webqos/svccls.allow does not contain a line longer than 1024 bytes and is not corrupted.

4. Contact your HP Support Representative for any other problems.

Error Code WQERR_PERMISSION Description The process does not have permission to change to the speciﬁed process group. Action Make sure that the /etc/opt/webqos/svccls.allow ﬁle is conﬁgured and is not

corrupt. Also, verify the effective user ID of the process.

Chapter 3 31

Troubleshooting

Process Group Error Codes

32 Chapter3

A Sample Programs,

Conﬁguration, and Header Files

The provided sample programs can be used to verify

Sample Programs, Conﬁguration, and Header Files

Sample Session Class Program

#include <webqosapi.h>

NSAPI_PUBLIC int WQClassExample(pblock *pb, Session *sn, Request *rq) { int retval = 0; int socketid; int errorcode = 0; uint32_t userClass;

/* Other business logic */

<code>

/* Time to show WebQoS Session Class example */

memcpy(&socketid, sn->csd, sizeof(int)); userClass = WQ_UCLASS_HIGH; retval = wq_set_session_cls(socketid, userClass, &errorcode); if (!retval) {

/* Verify the Session Class setting */

retval = wq_get_session_cls(socketid, &errorcode);

if (retval != WQ_UCLASS_HIGH)

printf(“ wq_set_session_cls: Error %d”, errorcode);

else

printf(“ wq_set_session_cls: Success “); } }

34 AppendixA

Sample Programs, Conﬁguration, and Header Files

Sample Process Group Program

/* * test_sc: generic main() to call wq_set_proc_cls/wq_get_proc_cls * * usage: * *test_sc svc_cls [-t] * * arguments: * *svc_clst = target service class *-t = tracing on * * exit value: * *new (current) service class: 0-3, 99 *error: 100 */

#include <webqosapi.h>

#define ERR_RET 100 #define TR if (tr_on) #define USAGE printf(“usage: %s svc_cls [-t]\n”, argv[0])

#ifdef __STDC__ main(in argc, char **argv) #else main(argc, argv) int argc; int **argv; #endif

{

int ret; int cls; int newcls; int err; int tr_on = 0;

Appendix A 35

Sample Programs, Conﬁguration, and Header Files

Sample Process Group Program

switch (argc) { case 1:

USAGE; exit(ERR_RET);

case 2:

cls = atoi(argv[1]); break;

case 3:

tr_on = 1; cls = atoi(argv[1]); break;

default:

USAGE; exit(ERR_RET);

}

TR printf(“target cls = %d\n”, cls); TR printf(“original class: %d\n”, wq_get_proc_cls(&err));

ret = wq_set_proc_cls(cls, WQ_SCOPE_PROCESS, &err); if (ret == -1) {

TR printf(“FAIL: ret=%d err%d\n”, ret, err);

exit(ERR_RET); } TR printf(“wq_set_proc_cls succeeds\n”);

/* test if class has indeed been set as requested */ newcls = wq_get_proc_cls(&err); TR printf(“class is now %d\n”, newcls); if (cls != newcls) {

printf(“FAILURE: wq_set_proc_cls succeeded, but class is not changed!\n”);

TR system(“ps -efP|grep test_sc|grep -v grep”); }

exit(newcls);

}

36 AppendixA

Sample Programs, Conﬁguration, and Header Files

svccls.allow Conﬁguration File

The following is the contents of the /etc/opt/webqos/svccls.allow conﬁguration ﬁle.

# # Service classes that a process is allowed to move to # # Line syntax: #user_name:class [class [... [class]]] # # Valid class values are: #OTHER, low, medium, high # # Class values are case-sensitive with one exception: “other” can # be used in place of OTHER. # # Wild cards: # user_name can be replaced by *, thus allowing any user to move # to the listed service classes # # class can be replaced by *, thus allowing a given process # to be moved to any class defined by WebQoS # # Comments must start with a # in the first column. # # By default, no processes are allowed to be moved. For # security reasons, the WebQoS administrator has to list the # allowed users in this file, explicitly. # # Examples: # # www:high medium low # www2:medium low # *:OTHER

Appendix A 37

Sample Programs, Conﬁguration, and Header Files

webqosapi.h Header File

The following is the contents of the /usr/include/webqosapi.h header ﬁle.

#ifndef _WEBQOSAPI_H #define _WEBQOSAPI_H

/* *

$Source: /qos/qosapi/webqosapi.h $ $Revision: 1.21 $ $Date: 1999/02/17 22:48:28 $”

#include <inttypes.h> /* for uint32_t */

# ifdef __cplusplus extern “C” { # endif /* __cplusplus */

/* Service (AKA Processing) classes */ #define WQ_SVCCLS_OTHER 0 #define WQ_SVCCLS_LOW 1 #define WQ_SVCCLS_MED 2 #define WQ_SVCCLS_HIGH 3 #define WQ_SVCCLS_ROOT 99 /* PRM_SYS, only for root */

/* User (AKA Session) classes */ #define WQ_UCLASS_LOW 1 #define WQ_UCLASS_MED 2 #define WQ_UCLASS_HIGH 3

/* Service (AKA Processing) class errors codes */ #define WQERR_OTHER (-1) /* generic error - see log file */ #define WQERR_NOTREADY (-2) /* not installed, not config’d, etc */ #define WQERR_CONNECT (-3) /* connection problem - see log file */ #define WQERR_PERMISSION (-4) /* permission denied in svccls.allow */ #define WQERR_BADSVCCLASS (-5) /* invalid service class argument */ #define WQERR_BADSCOPE (-6) /* invalid scope argument */ #define WQERR_NOTROOT (-7) /* only root can move to this class */

/* User (AKA Session) class error codes */ #define WQERR_WQOS_DISABLED (-20) /* WebQoS is disabled */

38 AppendixA

Sample Programs, Conﬁguration, and Header Files

webqosapi.h Header File

#define WQERR_INVALD_SOCKID (-21) /* bad socket id parameter */ #define WQERR_USRCLAS_OTHER (-22) /* other user class error */ #define WQERR_PLCY_DISALLOW (-23) /* admin disallow app usr cls modifcn*/ #define WQERR_INVAL_USR_CLS (-24) /* app provided invalid usr cls param*/

/* scope argument value for wq_set_proc_cls() */ #define WQ_SCOPE_PROCESS 1

#if defined(__STDC__) || defined(__cplusplus) extern int wq_get_session_cls(int socketid, int *errorcode); extern int wq_set_session_cls(int socketid, uint32_t cls,int *errorcode); extern int wq_get_proc_cls(int *errorcode); extern int wq_set_proc_cls(uint32_t cls, uint32_t scope, int *errorcode); #else extern int wq_get_session_cls(); extern int wq_set_session_cls(); extern int wq_get_proc_cls(); extern int wq_set_proc_cls(); #endif

# ifdef __cplusplus } # endif /* __cplusplus */

#endif /* _WEBQOSAPI_H */

Appendix A 39

Sample Programs, Conﬁguration, and Header Files

webqosapi.h Header File

40 AppendixA

Index

Arguments

class

, 22

class Values cls

, 17

cls Values errorcode scope socketid wq_get_proc_cls() wq_get_session_cls() wq_set_proc_cls() wq_set_session_cls()

Changing Classes

Example

Checklist

Troubleshooting

class

wq_set_proc_cls()

class Values

wq_set_proc_cls()

cls

wq_set_session_cls()

cls Values

wq_set_session_cls()

Conﬁguration File

svccls.allow

wq_get_session_cls() wq_set_session_cls()

Error Codes

Troubleshooting wq_get_proc_cls() wq_get_session_cls() wq_set_proc_cls() wq_set_session_cls() WQERR_BADSCOPE WQERR_BADSVCCLASS

, 23

, 18

, 15, 17, 20, 22

, 22

, 15, 17

, 20

, 15

, 22

, 17

, 10

, 26

, 22 , 23

, 17 , 18

, 37

, 15 , 17

, 28, 30

, 21, 30

, 16, 28

, 23, 30

, 18, 28

, 30

WQERR_CONNECT WQERR_INVAL_USER_CLS

WQERR_INVALD_SOCKID

16, 28

WQERR_NOTREADY WQERR_NOTROOT WQERR_OTHER WQERR_PERMISSION WQERR_PLCY_DISALLOW

WQERR_USRCLAS_OTHER

WQERR_WQOS_DISABLED

errorcode

wq_get_proc_cls() wq_get_session_cls() wq_set_proc_cls() wq_set_session_cls()

Example

Changing Classes Initial Service Request Process Process Group Request ClassiﬁcationRule Subsequent Service Requests

wq_get_proc_cls() wq_get_session_cls() wq_set_proc_cls() wq_set_session_cls()

Header File

Initial Service Request

Example

libprmext.sl

, 11

, 14, 38

, 10

, 14, 20, 22

, 31

, 30, 31

, 31

, 30, 32

, 32

, 20

, 15

, 22

, 17

, 10

, 11

, 35

, 34

, 35

, 34

libqosapi_pr.sl libqosapi_rq.sl

Library

, 10

libprmext.sl libqosapi_pr.sl libqosapi_rq.sl Linking

Linking

Library wq_get_proc_cls()

wq_get_session_cls() wq_set_proc_cls()

wq_set_session_cls()

Log Files

Process

Example wq_get_proc_cls() wq_set_proc_cls()

Process Group

Conﬁguration File Example Setting svccls.allow

Request Classiﬁcation Rule

Example Setting

Return Value

wq_get_proc_cls() wq_get_session_cls() wq_set_proc_cls() wq_set_session_cls()

scope

wq_set_proc_cls()

socketid

wq_get_session_cls() wq_set_session_cls()

, 14

, 26

, 11

, 27

, 10

, 26

, 14, 20, 22

, 14, 15, 17

, 14, 20, 22

, 14, 15, 17

, 20

, 15

, 22

, 17

, 21

, 24

, 37

, 20

, 16

, 23

, 18

, 22

, 15 , 17

Index 41

Index

SSL

wq_get_session_cls() wq_set_session_cls()

Subsequent Service Requests

Example svccls.allow Synopsis

wq_get_proc_cls()

wq_get_session_cls()

wq_set_proc_cls()

wq_set_session_cls()

Threads

wq_get_proc_cls()

wq_get_session_cls()

wq_set_proc_cls()

wq_set_session_cls() Troubleshooting

Checking Log Files

Checklist

Process Group Setting

Request Classiﬁcation Rule

Service Class Error Codes

Verifying WebQoS is Enabled

WebQoS

Enabling WebQoS API

Overview webqosapi.h wq_get_proc_cls()

Arguments

Error Codes

errorcode

Example

Linking

, 10

, 27, 37

, 26

Error Codes Setting

, 26

, 10

, 14, 38

, 20

, 21, 30

, 20

, 35

, 20

, 15 , 17

, 20

, 15

, 22

, 17

, 21

, 15

, 24

, 17

, 26

, 27

, 28

, 14, 20

, 30

Process Return Value Synopsis Threads WQERR_NOTREADY WQERR_OTHER

wq_get_session_cls()

Arguments Cookies Error Codes errorcode Example Linking Return Value socketid SSL Synopsis Threads WQERR_INVALD_SOCKID

WQERR_USRCLAS_OTHER WQERR_WQOS_DISABLED

WQ_SCOPE_PROCESS wq_set_proc_cls()

Arguments class

class Values Error Codes errorcode Example Linking Process Return Value scope Synopsis Threads WQ_SCOPE_PROCESS

WQERR_BADSCOPE WQERR_BADSVCCLASS

, 21

, 20

, 21

, 15

, 16, 28

, 15

, 34

, 15

, 16

, 15

16, 28 16, 28 16, 28

, 22

, 23 , 23, 30

, 22

, 35

, 22

, 24

, 23

, 22

, 24

, 21, 30

, 14, 15

, 14, 22

, 21, 30

, 22, 24

, 22,

, 23, 30

,23,

WQERR_CONNECT WQERR_NOTREADY WQERR_NOTROOT WQERR_OTHER WQERR_PERMISSION

wq_set_session_cls()

Arguments cls

, 17

cls Values Cookies Error Codes errorcode Example Linking Return Value socketid SSL

Synopsis Threads WQERR_INVAL_USER_CLS

WQERR_INVALD_SOCKID

WQERR_PLCY_DISALLOW WQERR_USRCLAS_OTHER WQERR_WQOS_DISABLED

WQERR_BADSCOPE

wq_set_proc_cls()

WQERR_BADSOCPE

wq_set_proc_cls()

WQERR_BADSVCCLASS

wq_set_proc_cls()

WQERR_CONNECT

wq_set_proc_cls()

WQERR_INVAL_USER_CLS

wq_set_session_cls()

WQERR_INVALD_SOCKID

wq_get_session_cls() wq_set_session_cls()

, 17

, 18

, 17

, 18, 28

, 17

, 34

, 17

, 18

, 17

18, 28 18, 28 18, 28 18, 28 18, 28

, 23, 31

, 23, 32

, 23,

, 14, 17

, 30 , 23 , 23, 30 , 23, 31

, 18, 28

, 16, 28

, 18, 28

42 Index

Index

WQERR_NOTREADY

wq_get_proc_cls() wq_set_proc_cls()

WQERR_NOTROOT

wq_set_proc_cls()

WQERR_OTHER

wq_get_proc_cls() wq_set_proc_cls()

WQERR_PERMISSION

wq_set_proc_cls()

WQERR_PLCY_DISALLOW

wq_set_session_cls()

WQERR_USRCLAS_OTHER

wq_get_session_cls() wq_set_session_cls()

WQERR_WQOS_DISABLED

wq_get_session_cls() wq_set_session_cls()

, 21, 30

, 23, 31 , 23, 31

, 21, 30

, 23, 32 , 23, 32

, 18, 28

, 16, 28

, 18, 28

, 16, 28

, 18, 28

Index 43

HP WebQoS User's Guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Overview

2 Using the WebQoS API

Synopsis

Arguments

Return Value

Errors

Example

Synopsis

Arguments

Return Value

Errors

Example

Synopsis

Arguments

Return Value

Errors

Multithreaded Applications

Example

Synopsis

Arguments

class Values

Return Value

Errors

Multithreaded Applications

Example

3 Troubleshooting

Checklist

Process Group Error Codes

Sample Session Class Program

Sample Process Group Program

webqosapi.h Header File