HP WebQoS on HP-UX API Programmer’s Guide Edition 1 HP 9000 Networking Manufacturing Part Number: B8311-90003 E1299 U.S.A. © Copyright 1999, Hewlett-Packard Company.
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.
©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.
Contents 1. About the WebQoS API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 2. Using the WebQoS API wq_get_session_cls() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 Return Value. . . . . .
Contents Multithreaded Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 3. Troubleshooting Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Request Classification Rule Class Error Codes . . . . . . . . . . . . . . . . . . . 28 wq_get_session_cls() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
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.
1 About the WebQoS API 9
About the WebQoS API Overview Overview Using the WebQoS API, an application can reassign the classification rule class of a session and the process group of a process. This allows more fine-tuning of the assigned class(es). WebQoS must be configured to allow these changes to be made. Refer to the Installing and Configuring WebQoS on HP-UX manual for more information about configuring WebQoS.
About the WebQoS API Overview value is effective for subsequent requests for the current session. Figure 1-3 Example — Setting the Process Group Process Groups Medium Low WebQoS API Process B High WebQoS Process A Process Groups High Medium Low 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.
About the WebQoS API Overview 12 Chapter 1
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 Configuring HP WebQoS manual.
Using the WebQoS API There is one header file that must be included in your program (contents of this header file can be found in Appendix A , “Sample Programs, Configuration, and Header Files,” on page 33): • /usr/include/webqosapi.
Using the WebQoS API wq_get_session_cls() wq_get_session_cls() Gets the current request classification 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 configured in WebQoS for this request.
Using the WebQoS API wq_get_session_cls() Return Value wq_get_session_cls() returns a non-negative value representing the request classification rule class or -1 if an error occurred.
Using the WebQoS API wq_set_session_cls() wq_set_session_cls() Sets the request classification rule class of the current request being processed by the NSAPI plug-in application.
Using the WebQoS API wq_set_session_cls() cls Values Use the following values to set the request classification rule class cls: Table 2-3 wq_set_session_cls() cls Values Class of Request Classification Rule cls Value Low WQ_UCLASS_LOW Medium WQ_UCLASS_MED High WQ_UCLASS_HIGH Return Value wq_set_session_cls() returns 0 if it is successful or -1 if an error occurred.
Using the WebQoS API wq_set_session_cls() Example See Appendix A , “Sample Programs, Configuration, and Header Files.
Using the WebQoS API wq_get_proc_cls() wq_get_proc_cls() Gets the process group defined 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
Using the WebQoS API wq_get_proc_cls() Errors If error logging to syslog is enabled, certain errors are logged to a file (you can specify the file 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 configured on the system.
Using the WebQoS API wq_set_proc_cls() wq_set_proc_cls() Sets the process group of the current process. For a multithreaded process, all threads are set to the same specified process group. A process is only allowed to change its process group to the value(s) specified in the file /etc/opt/webqos/svccls.allow. By default, a process cannot change its process group. Refer to the svccls.allow file for an explanation of how to configure this file.
Using the WebQoS API wq_set_proc_cls() 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() 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 configured on the system. WQERR_OTHER If error logging to syslog is enabled (“error” level for all facilities), the error is logged to a file. WQERR_PERMISSION The process does not have permission to change to the specified process group.
3 Troubleshooting 25
Troubleshooting Checklist 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, Configuration, and Header Files,” on page 33. Step 3.
Troubleshooting Request Classification Rule Class Error Codes Request Classification 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 classification rule class error occurred. Action Contact your HP Support Representative.
Troubleshooting Request Classification Rule Class Error Codes Error Code WQERR_PLCY_DISALLOW Description The WebQoS administrator has not configured a policy allowing applications to modify its request classification rule class. Action Contact the WebQoS administrator to configure a policy to allow applications to modify the request classification rule class. Refer to the Configuring HP WebQoS manual for more information about configuring the policy.
Troubleshooting Process Group Error Codes Process Group Error Codes wq_get_proc_cls() Error Code WQERR_NOTREADY Description PRM is not installed or not configured on the system. Action Install and configure 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 file. Action Check the /var/adm/syslog/syslog.log log file for more information.
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 file. Action Check the /var/adm/syslog/syslog.log log file 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 find entry “hp-sca” in /etc/services.
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 file. Action 1. Check the /var/adm/syslog/syslog.log log file 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.
Troubleshooting Process Group Error Codes 32 Chapter 3
A Sample Programs, Configuration, and Header Files The provided sample programs can be used to verify 33
Sample Programs, Configuration, and Header Files Sample Session Class Program Sample Session Class Program #include
Sample Programs, Configuration, and Header Files Sample Process Group Program 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
Sample Programs, Configuration, 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”); /* te
Sample Programs, Configuration, and Header Files svccls.allow Configuration File svccls.allow Configuration File The following is the contents of the /etc/opt/webqos/svccls.allow configuration file. # # 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.
Sample Programs, Configuration, and Header Files webqosapi.h Header File webqosapi.h Header File The following is the contents of the /usr/include/webqosapi.h header file. #ifndef _WEBQOSAPI_H #define _WEBQOSAPI_H /* * $Source: /qos/qosapi/webqosapi.h $ $Revision: 1.21 $ $Date: 1999/02/17 22:48:28 $” * * (C) Copyright 1998, Hewlett-Packard Company, all rights reserved. */ #include
Sample Programs, Configuration, and Header Files webqosapi.
Sample Programs, Configuration, and Header Files webqosapi.
Index A Arguments class, 22 class Values, 23 cls, 17 cls Values, 18 errorcode, 15, 17, 20, 22 scope, 22 socketid, 15, 17 wq_get_proc_cls(), 20 wq_get_session_cls(), 15 wq_set_proc_cls(), 22 wq_set_session_cls(), 17 C Changing Classes Example, 10 Checklist Troubleshooting, 26 class wq_set_proc_cls(), 22 class Values wq_set_proc_cls(), 23 cls wq_set_session_cls(), 17 cls Values wq_set_session_cls(), 18 Configuration File svccls.
Index SSL wq_get_session_cls(), 15 wq_set_session_cls(), 17 Subsequent Service Requests Example, 10 svccls.
Index WQERR_NOTREADY wq_get_proc_cls(), 21, 30 wq_set_proc_cls(), 23, 31 WQERR_NOTROOT wq_set_proc_cls(), 23, 31 WQERR_OTHER wq_get_proc_cls(), 21, 30 wq_set_proc_cls(), 23, 32 WQERR_PERMISSION wq_set_proc_cls(), 23, 32 WQERR_PLCY_DISALLOW wq_set_session_cls(), 18, 28 WQERR_USRCLAS_OTHER wq_get_session_cls(), 16, 28 wq_set_session_cls(), 18, 28 WQERR_WQOS_DISABLED wq_get_session_cls(), 16, 28 wq_set_session_cls(), 18, 28 Index 43
