Redhat NETSCAPE ENTERPRISE SERVER NSAPI User Manual

NSAPI Programmer’s Guide

Netscape Enterprise Server

Version 6.0
November 2001
Netscape Communications Corporation ("Netscape") and its licensors retain all ownership rights to the software programs offered by Netscape (referred to h er e in as "Software") and related d oc u m en t at ion. Use of the Software and relat e d doc umentation is governe d by the license agreement for the Software and applicable copyright law.
Your right to copy this documen tatio n is l imited by copyr ight la w. Making un auth orized copies, adaptati ons or compila tio n works is prohibited and constitutes a punishable violation of the law. Netscape may revise thi s documentation from time to time without notice.
THIS DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL NETSCAPE BE LIABLE FOR INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY KIND ARISING FROM ANY ERROR IN THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION ANY LOSS OR INTERRUPTION OF BUSINESS, PROFITS, USE, OR DATA.
The Software and documen t at ion are c opyright © 2001 Sun Microsystems, Inc. P ortions copyright 1999, 2001 Netscape Communications Corpo ration. All rights reserved.
This product includes software developed by Apache Softwa re Foun d at ion (h t tp:// www.apache.org/). Copyri gh t (c ) 1999 The Apache Software Foundation . All right s reserved.
This product includes software developed by the Universit y of California, Berkeley and its con t rib u tors. Copyright (c) 1990, 1993, 1994 The Regents of the U n iv e rsity of California. All rights re se rved.
Netscape and the Netscape N logo are registered trademarks of Netscape Communications Corporation in the United States and other countries. Other N etscape logos, product names and serv ice names are also trademarks of Netsc ape an d m ay b e re gist ere d in some countries. Sun, Sun Microsystems, and the Sun logo, iPlanet, and the iPlanet logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U ni ted States and other countries. Other prod uct an d brand names are trademarks of the ir re spect ive owners.
The downloading, exporting, or reexporting of Netscape software or any underlying information or technology must be in full compliance with all United States and other applicable laws and regulations. Any provision of Netscape software or documentation to the U.S. government is with restricted rights as described in the license agreement for that Software.
Contents
About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Chapter 1 Basics of Server Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
magnus.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
server.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
obj.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
mime.types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Dynamic Reconfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
How the Server Handles Requests from Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
HTTP Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Steps in the Request Handling Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Directives for Handling Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Writing New Server Application Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Chapter 2 Syntax and Use of obj.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Server Instructions in obj.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Summary of the Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
The Object Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Objects that Use the name Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Object that Use the ppath Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Variables Defined in server.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Flow of Control in obj.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
AuthTrans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
NameTrans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
PathCheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
ObjectType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3
Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
AddLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Syntax Rules for Editing obj.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Order of Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Case Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Separators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Quotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Line Continuation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Path Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
About obj.conf Directive Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Chapter 3 Predefined SAFs and the Request Handling Process . . . . . . . . . . . . . . . . . . . . . 45
The bucket Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
AuthTrans Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
basic-auth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
basic-ncsa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
get-sslid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
qos-handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
NameTrans Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
assign-name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
document-root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
home-page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
pfx2dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
redirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
strip-params . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
unix-home . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
PathCheck Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
check-acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
deny-existence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
find-index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
find-links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
find-pathinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
get-client-cert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
load-config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
nt-uri-clean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
ntcgicheck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
require-auth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
set-virtual-index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
ssl-check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
4 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
ssl-logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
unix-uri-clean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
ObjectType Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
force-type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
set-default-type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
shtml-hacktype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
type-by-exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
type-by-extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Service Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
add-footer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
add-header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
append-trailer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
imagemap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
index-common . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
index-simple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
key-toosmall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
list-dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
make-dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
query-handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
remove-dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
remove-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
rename-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
send-cgi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
send-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
send-range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
send-shellcgi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
send-wincgi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
service-dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
shtml_send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
stats-xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
upload-file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
AddLog Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
common-log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
flex-log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
record-useragent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Error Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
send-error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
qos-error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Chapter 4 Creating Custom SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
The SAF Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
SAF Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
pb (parameter block) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
5
sn (session) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
rq (request) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Result Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Creating and Using Custom SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Write the Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Compile and Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Load and Initialize the SAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Instruct the Server to Call the SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Reconfigure the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Test the SAF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Overview of NSAPI C Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Parameter Block Manipulation Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Protocol Utilities for Service SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
File I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Network I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Enterprise ServerUtilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Virtual Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Required Behavior of SAFs for Each Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Init SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
AuthTrans SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
NameTrans SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
PathCheck SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
ObjectType SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Service SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Error SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
AddLog SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
CGI to NSAPI Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Chapter 5 NSAPI Function Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
NSAPI Functions (in Alphabetical Order) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
CALLOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
cinfo_find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
condvar_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
condvar_notify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
condvar_terminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
condvar_wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
crit_enter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
crit_exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
crit_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
crit_terminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
daemon_atrestart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
6 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
fc_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
fc_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
filebuf_buf2sd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
filebuf_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
filebuf_getc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
filebuf_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
filebuf_open_nostat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
FREE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
func_exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
func_find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
log_error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
MALLOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
net_ip2host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
net_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
net_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
netbuf_buf2sd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
netbuf_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
netbuf_getc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
netbuf_grab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
netbuf_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
param_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
param_free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
pblock_copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
pblock_create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
pblock_dup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
pblock_find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
pblock_findval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
pblock_free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
pblock_nninsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
pblock_nvinsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
pblock_pb2env . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
pblock_pblock2str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
pblock_pinsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
pblock_remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
pblock_str2pblock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
PERM_CALLOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
PERM_FREE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
PERM_MALLOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
PERM_REALLOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
PERM_STRDUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
prepare_nsapi_thread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
protocol_dump822 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
protocol_set_finfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
7
protocol_start_response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
protocol_status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
protocol_uri2url . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
protocol_uri2url_dynamic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
REALLOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
request_get_vs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
request_header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
request_stat_path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
request_translate_uri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
session_dns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
session_maxdns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
shexp_casecmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
shexp_cmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
shexp_match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
shexp_valid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
STRDUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
system_errmsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
system_fclose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
system_flock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
system_fopenRO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
system_fopenRW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
system_fopenWA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
system_fread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
system_fwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
system_fwrite_atomic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
system_gmtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
system_localtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
system_lseek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
system_rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
system_ulock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
system_unix2local . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
systhread_attach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
systhread_current . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
systhread_getdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
systhread_newkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
systhread_setdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
systhread_sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
systhread_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
systhread_timerset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
util_can_exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
util_chdir2path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
util_chdir2path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
util_cookie_find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
8 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
util_env_find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
util_env_free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
util_env_replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
util_env_str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
util_getline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
util_hostname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
util_is_mozilla . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
util_is_url . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
util_itoa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
util_later_than . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
util_sh_escape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
util_snprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
util_sprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
util_strcasecmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
util_strftime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
util_strncasecmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
util_uri_escape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
util_uri_is_evil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
util_uri_parse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
util_uri_unescape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
util_vsnprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
util_vsprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
vs_alloc_slot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
vs_get_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
vs_get_default_httpd_object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
vs_get_doc_root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
vs_get_httpd_objset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
vs_get_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
vs_get_mime_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
vs_lookup_config_var . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
vs_register_cb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
vs_set_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
vs_translate_uri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Chapter 6 Examples of Custom SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Examples in the Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
AuthTrans Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Installing the Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
NameTrans Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Installing the Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
PathCheck Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
9
Installing the Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
ObjectType Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Installing the Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Service Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Installing the Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
More Complex Service Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
AddLog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Installing the Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Quality of Service Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Installing the Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Chapter 7 Syntax and Use of magnus.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Init SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Enterprise Servercindex-init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
define-perf-bucket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
dns-cache-init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
flex-init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
flex-rotate-init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
init-cgi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
init-clf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
init-uhome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
load-modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
nt-console-init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
perf-init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
pool-init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
register-http-method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
stats-init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
thread-pool-init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Server Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
ExtraPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
MtaHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
NetSiteRoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
ServerConfigurationFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
ServerID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
ServerRoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
TempDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
TempDirSecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
10 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Language Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
AdminLanguage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
ClientLanguage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
DefaultCharSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
DefaultLanguage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
DNS Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
AsyncDNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
DNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Threads, Processes and Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
ConnQueueSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
HeaderBufferSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
IOTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
KeepAliveThreads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
KeepAliveTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
KernelThreads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
ListenQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
MaxKeepAliveConnections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
MaxProcs (UNIX Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
PostThreadsEarly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
RcvBufSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
RqThrottle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
RqThrottleMin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
SndBufSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
StackSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
StrictHttpHeaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
TerminateTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
ThreadIncrement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
UseNativePoll (UNIX only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Native Thread Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
NativePoolStackSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
NativePoolMaxThreads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
NativePoolMinThreads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
NativePoolQueueSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
CGIExpirationTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
CGIStubIdleTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
CGIWaitPid (UNIX Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
MaxCGIStubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
MinCGIStubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
WincgiTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Error Logging and Statistic Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
ErrorLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
ErrorLogDateFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
11
LogFlushInterval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
LogVerbose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
LogVsId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
PidLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
ACLCacheLifetime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
ACLUserCacheSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
ACLGroupCacheSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
SSLCacheEntries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
SSLClientAuthDataLimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
SSLClientAuthTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
SSLSessionTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
SSL3SessionTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Chunked Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
UseOutputStreamSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
ChunkedRequestBufferSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
ChunkedRequestTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
ChildRestartCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
HTTPVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
MaxRqHeaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Umask (UNIX only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Chapter 8 Virtual Server Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
The server.dtd File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
The server.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Using the Server Manager and Class Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Elements in server.dtd and server.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
SERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
VARS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
LS (Listen Socket) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
CONNECTIONGROUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
SSLPARAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
MIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
ACLFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
VSCLASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
VS (Virtual Server) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
QOSPARAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
USERDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Virtual Server Selection for Request Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
12 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
User Database Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
The Netscape LDAP Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
The Convergence Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
The Domain Component (dc)Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Appendix A Data Structure Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Privatization of Some Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
pblock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
pb_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
pb_param . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Session->client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
stat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
shmem_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
cinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Appendix B MIME Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Determining the MIME Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
How the Type Affects the Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
What Does the Client Do with the MIME Type? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Syntax of the MIME Types File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Sample MIME Types File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Appendix C Wildcard Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Wildcard Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Wildcard Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Appendix D Time Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 5
Appendix E HyperText Transfer Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Request Method, URI, and Protocol Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Request Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Request Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
HTTP Protocol Version, Status Code, and Reason Phrase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Response Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Response Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Buffered Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
13
Appendix F Dynamic Results Caching Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
dr_cache_destroy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
dr_cache_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
dr_cache_refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
dr_net_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
fc_net_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Appendix G Alphabetical List of NSAPI Functions and Macros . . . . . . . . . . . . . . . . . . . . . 333
Appendix H Alphabetical List of Directives in magnus.conf . . . . . . . . . . . . . . . . . . . . . . . . 341
Appendix I Alphabetical List of Pre-defined SAFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
14 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001

About This Book

This book discusses how to use the Netscape® Server Application Programmer's Interface (NSAPI) to build plugins that define Server Application Functions (SAFs) to extend and modify Netscape Enterprise Server. The book also discusses the purpose and use of the configuration files
mime.types, and provides comprehensive lists of the directives and functions that
can be used in these configuration files. It also provides a reference of the NSAPI functions you can use to define new plugins.
This book has the following chapters and appendices:
Chapter 1, “Basics of Server Operation” This chapter discusses how the uses configuration files to perform
initialization tasks and to process client requests.
obj.conf, magnus.conf, server.xml, and
Chapter 2, “Syntax and Use of obj.conf” This chapter goes into detail on the configuration file
discusses the syntax and use of directives in this file, which instruct the server how to process requests.
Chapter 3, “Predefined SAFs and the Request Handling Process” This chapter discusses each of the stages in the request handling process, and
provides an API reference of the Server Application Functions (SAFs) that can be invoked at each stage.
Chapter 4, “Creating Custom SAFs” This chapter discusses how to create your own plugins that define new SAFs to
modify or extend the way the server handles requests.
Chapter 5, “NSAPI Function Reference” This chapter presents a reference of the functions in the Netscape Server
Application Programming Interface (API). You use NSAPI functions to define SAFs.
Chapter 6, “Examples of Custom SAFs”
obj.conf. The chapter
15
This chapter discusses examples of custom SAFs to use at each stage in the request handling proc ess.
Chapter 7, “Syntax and Use of magnus.conf” This appendix discusses the variables you can set in the configuration file
magnus.conf to configure the during initialization.
Chapter 8, “Virtual Server Configuration Files” This appendix discusses the variables you can set in the configuration file
server.xml to configure virtual servers in .
Appendix A, “Data Structure Reference” This appendix discusses some of the commonly used NSAPI data structures.
Appendix B, “MIME Types” This appendix discusses the MIME types file, which maps file extensions to file
types.
Appendix C, “Wildcard Patterns” This appendix lists the wildcard patterns you can use when specifying values
obj.conf, various predefined SAFs, and in some NSAPI functions.
in
Appendix D, “Time Formats” This appendix lists time formats.
Appendix E, “HyperText Transfer Protocol” This appendix gives an overview of HTTP.
Appendix F, “Dynamic Results Caching Func tions” This appendix explains how to create a results caching plugin.
Appendix G, “Alphabetica l List of NSAPI Functions and M acros” Appendix H, “Alphabetical List of Directives in magnus.conf” Appendix I, “Alphabetical List of Pre-defined SAFs”
These appendices provide alphabetical lists for easy lookup of NSAPI functions, predefined SAFs, and variables in
NOTE Throughout this manual, all descriptions specific to UNIX®
descriptions apply to the Linux® operating system as we ll, except where Linux is specifically mentioned.
16 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
magnus.conf.
Chapter 1

Basics of Server Operation

The configuration and behavior of Netscape Enterprise Server is determined by a set of configuration files. You can change the s ettings in these configuration files either by using the Server Manager interface or by manually editing the files.
The configuration file that contains instructions for how the server processes requests from clients is called handling process by adding or changing the instructions in the Netscape Server Application Programming Interface (API) to create new Server Application Functions (SAFs) to use in instructions in
This chapter discusses the configuration files used by the . Then the chapter looks
in more detail at the server’s process for handling requests. The chapter closes by introducing the use of Netscape Server Application Programming Interface (NSAPI) to define new functions to modify the request-handling process.
obj.conf. You can modify and extend the request
obj.conf. You can use
obj.conf.
This chapter has the following sectio ns:
Configuration Files
Dynamic Reconfiguration
How the Server Handles Requests from Clients
Writing New Server Application Functions
17

Configuration Files

Configuration Files
The configuration and operation of the is controlled by configuration files. The configuration files reside in the directory directory contains various configuration files for controlling different components, such as configuring NetShare. The exact number and na mes of con figuration f iles de pends on which components have been enabled or loaded into the server.
However, this directory always contains four configuration files that are essential for the server to operate. These files are:
jsa.conf for configuring server-side JavaScript and netshare.conf for
magnus.conf – contains global server initializ ation information. server.xml – contains initialization information for virtual servers and listen
sockets.
obj.conf – contains instructions for handling requests from clients. mime.types – contains information for determining the content type of
requested resources.
server-root/server-id/config/. This

magnus.conf

This file sets values of variables that configure the server during initialization. The server looks at this file and executes the settings on startup. The server does not look at this file again until it is restarted.
See Chapter 7, “Syntax and Use of magnus.conf” for a list of all the variables and
Init directives that can be set in magnus.conf.

server.xml

This file configures the addresses and ports that the server listens on and assigns virtual server classes and virtual servers to these listen sockets. A ma ster fi le,
server.dtd, defines its format and content.
For more information about how the server uses Chapter 8, “Virtual Server Configuration Files.”
NOTE Virtual servers are not the same thing as server instances. Each
server instance is a completely separate server that contains one or more virtual servers.
18 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
server.dtd and server.xml, see
Configuration Files

obj.conf

This file contains instructions for the server about how to process requests from clients (such as browsers). The server looks at the configuration defined by this file every time it processes a request from a client.
There is one
servers. Whenever this guide refers to “the files or to the
All the They are typically named vsclass
obj.conf file for each virtual server class, or grouping of virtual
obj.conf file,” it refers to all obj.conf
obj.conf file for the virtual server class being described.
obj.conf files are located in the server_root/server_id/config directory.
.obj.conf, where vsclass is the virtual server class
name.
obj.conf file is essential to the operation of the . When you make changes to
The the server through the Server Manager interface, the system automatically updates
obj.conf.
The file
obj.conf contains a series of instructions (directives) that tell the what to
do at each stage in the request-response process. Each directive invokes a Server Application Function (SAF). These functions are written using the Netscape Se rver Application Programming Interface (NSAPI). The comes with a set of pre-defined SAFs, but you can also write your own using NSAPI to create new instructions that modify the way the server handles requests.
For more information about how the server uses
obj.conf, see Chapter 2, “Syntax
and Use of obj.conf.”

mime.types

This file maps file extensions to MIME types to enable the server to determine the content type of a requested resource. For example, requests for resources with
html extensions indicate that the client is requesting an HTML file, while requests
. for resources with file in GIF format.
.gif extensions indicate that the client is requesting an image
For more information about how the server uses “MIME Types.”
mime.types, see Appendix B,
Chapter 1 Basics of Server Operation 19

Dynamic Reconfiguration

Dynamic Reconfiguration
You do not have to restart the server for changes to obj.conf, mime.types,
server.xml, and virtual-server-specific ACL files to take effect. All you need to do
is apply the changes by clicking the Apply link and then clicking the Load Configuration Files button on the Apply Changes screen. If there are errors in installing the new configuration, the previous configuration is restored.
When yo u edit into memory that contains all the information from the dynamically configurable files.
Every new connection references the newest configuration. Once the last session referencing a configuration ends, the now unused old configuration is deleted.
obj.conf and apply the changes, a new configuration is loaded

How the Server Handles Requests from Clients

is a web server that accepts and responds to HyperText Transfer Protocol (HTTP) requests. Browsers like Netscape Communicator communicate using several protocols including HTTP, FTP, and gopher. The handles HTTP specifically.
For more information about the HTTP protocol refer to Appendix E, “HyperText
Transfer Protocol” and also the latest HTTP specification.

HTTP Basics

As a quick summary, the HTTP/1.1 protocol works as follows:
the client (usually a browser) opens a connection to the server and sends a request
the server processes the request, generates a response, and closes the connection if it finds a
The request consists of a line indicating a method such as Resource Identifier (URI) indicating which resource is being requested, and an HTTP protocol version separated by spaces.
This is normally followed by a number of headers, a blank line indicating the end of the headers, and sometimes body data. Headers may provide various information about the request or the client Body data. Headers are typically only sent for POST and PUT methods.
20 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Connection: Close header.
GET or POST, a Universal
How the Server Handles Requests from Clients
The example request shown below would be sent by a Netscape browser to request the server
foo.com to send back the resource in /index.html. In this example, no
body data is sent because the method is GET (the point of the request is to get some data, not to send it.)
GET /index.html HTTP/1.0 User-agent: Mozilla Accept: text/html, text/plain, image/jpeg, image/gif, */* Host: example.com
The server receives the request and processes it. It handles each request individually, although it may process many requests simultaneously. Each request is broken down into a series of steps that together make up the request handling process.
The server generates a response which includes the HTTP protocol version, HTTP status code, and a reason phrase separated by spaces. This is normally followed by a number of headers. The end of the headers is indicated by a blank line. The body data of the response follows. A typical HTTP response might look like this:
HTTP/1.0 200 OK Server: Netscape-Enterprise/6.0 Content-type: text/html Content-length: 83
<HTML> <HEAD><TITLE>Hello World</Title></HEAD> <BODY>Hello World</BODY> </HTML>
The status code and reason phrase tell the client how the server handled the request. Normally the status code 200 is returned indicating that the request was handled successfully and the body data contains the requested item. Other result
codes indicate redirection to another server or the browser’s cache, or various types of HTTP errors such as “404 Not Found.”
Chapter 1 Basics of Server Operation 21
How the Server Handles Requests from Clients

Steps in the Request Handling Process

When the server first starts up it performs some initialization and then waits for an HTTP request from a client (such as a browser). When it receives a request, it first selects a virtual server. For details about how the virtual server is determined, see
“Virtual Server Selection for Request Processing,” on page 295. After the virtual server is selected, the
obj.conf file for the virtual server class
specifies how the request is handled in the following steps:
1. AuthTrans (authorization translation)
verify any authorization information (such as name and password) sent in the request.
2. NameTrans
(name translation)
translate the logical URI into a l ocal file system path.
3. PathCheck (path checking)
check the local file system path for validity and check that the requestor has access privileges to the requested resource on the file system.
4. ObjectType (object typing)
determine the MIME-type (Multi-purpose Internet Mail Encoding) of the requested resource (for example.
5. Service (generate the response)
text/html, image/gif, and so on).
generate and return the response to the client.
6. AddLog (adding log entries)
add entries to log file(s).
7. Error (service)
This step is executed only if an error occurs in the previous steps. If an error occurs, the server logs an error message and aborts the process.
22 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001

Writing New Server Application Functions

Directives for Handling Requests

The file obj.conf contains a series of instructions, known as directives, that tell the what to do at each stage in the request handling process. Each directive invokes a Server Application Function (SAF) with one or more arguments. Each directive applies to a specific stage in the request handling process. The stages are
AuthTrans, NameTrans, PathCheck, ObjectType, Service, an d AddLog.
For example, the following directive applies during the
document-root function with the root argument set to
the
D:/Netscape/Server4/docs. (The document-root function translates the http://server_name/ part of the URL to the document root, which in this example
D:/Netscape/Server4/docs.)
is
NameTrans fn="document-root" root="D:/Netscape/Server4/docs"
The functions invoked by the directives in obj.conf are known as Server Application Functions (SAFs).
NameTrans stage. It calls
Writing New Server Application Functions
The comes with a variety of pre-defined SAFs that you can use to create more directives in provided by the NSAPI. After you write the SAF, you would add a directive to
obj.conf so that your new function gets invoked by the server at the appropriate
time. Each SAF has its own arguments, which are passed to it by the directive in
obj.conf. Every SAF is also passed additional arguments that contain information
about the request (such as what resource was requested and what kind of client requested it) and any other server variables created or modified by SAFs called by previously invoked directives. Each SAF may examine, modify, or create server variables.
obj.conf. You can also write your own SAF using the functions
Each SAF returns a result code which tells the server whether it succeeded, did nothing, or failed.
For more information about
For more information on the pre-defined SAFs, see Chapter 3, “Predefined SAFs and the Request Handling Process.”
For more information on writing your own SAFs, see Chapter 4, “Creating Custom SAFs.”
obj.conf, see Chapter 2, “Syntax and Use of obj.conf.”
Chapter 1 Basics of Server Operation 23
Writing New Server Application Functions
24 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Chapter 2

Syntax and Use of obj.conf

The obj.conf configuration file contains directives that instruct the Netscape Enterprise Server how to handle requests from clients. This chapter discusses server instructions in flow of control in about example directives.
The sections in this chapter are:
Server Instructions in obj.conf
•The Object Tag
obj.conf; the use of Object tags; the use of variables; the
obj.conf; the syntax rules for editing obj.conf; and a note
Variables Defined in server.xml
Flow of Control in obj.conf
Syntax Rules for Editing obj.conf
About obj.conf Directive Examples

Server Instructions in obj.conf

The obj.conf file contains directives that instruct the server how to handle requests received from clients such as browser. These directives appear inside
OBJECT tags.
Each directive calls a function, indicating when to call it and specifying arguments for it.
The syntax of each directive is:
Directive fn=func-name name1="
value1
"...nameN="valueN"
25
Server Instructions in obj.conf
For example:
NameTrans fn="document-root" root="D:/Netscape/Server4/docs" Directive indicates when this instruction is executed during the request handling
process. The value is one of
Service, Error, and AddLog.
AuthTrans, NameTrans, PathCheck, ObjectType,
The value of the to execute. All directives must supply a value for the
fn argument is the name of the Server Application Function (SAF)
fn parameter -- if there’s no
function, the instruction won’t do anything. The remaining parameters are the arguments needed by the function, and they
vary from function to function. Enterprise Server is shipped with a set of built-in server application functions
(SAFs) that you can use to create and modify directives in
obj.conf, as discussed
in Chapter 3, “Predefined SAFs and the Request Handling Process.” You can also define new SAFs, as discussed in Chapter 4, “Creating Custom SAFs.”
magnus.conf file contains Init directive SAFs that initialize the server. For
The more information, see Chapter 7, “Syntax and Use of magnus.conf.”

Summary of the Directives

Here are the categories of server directives and a description of what each does. Each category corresponds to a stage in the request handling process. The section “Flow of Control in obj.conf,” on page 32 explains exactly how the server decides which directive or directives to execute in at each stage.
AuthTrans
• Verifies any authorization information (normally sent in the Authorizat ion
header) provided in the HTTP request and translates it into a user and/or a group. Server access control occurs in two stages. AuthTrans verifies the authenticity of the user. Later, PathCheck tests the user’s access privileges for the requested resource.
AuthTrans fn=basic-auth userfn=ntauth auth-type=basic userdb=none
This example calls the basic-auth function, which calls a custom function (in this case
ntauth, to verify authorization information sent by the client. The
Authorization header is sent as part of the basic server authorization scheme.
26 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Server Instructions in obj.conf
NameTrans Translates the URL specified in the request from a logical URL to a physical file
system path for the requested resource. This may also result in redirection to another site. For example:
NameTrans fn="document-root" root="D:/Netscape/Server4/docs"
This example calls the document-root function with a root argument of
D:/Netscape/Server4/docs. The function document-root function translates
http://server_name/ part of the requested to URL to the document root,
the which in this case is
http://server-name/doc1.html is translated to D:/Netscape/Server4/docs/doc1.html.
PathCheck
D:/Netscape/Server4/docs. Thus a request for
Performs tests on the physical path determined by the NameTrans step. In general, these tests determine whether the path is valid and whether the client is allowed to access the requested resource. For example:
PathCheck fn="find-index" index-names="index.html,home.html"
This example calls the find-index function with an index-names argument of
index.html,home.html. If the requested URL is a directory, this function
instructs the server to look for a file called either
index.html or home.html in
the requested directory.
ObjectType
• Determines the MIME (Multi-purpose Internet Mail Encoding) type of the
requested resource. The MIME type has attributes content type),
encoding and language. The MIME type is sent in the headers
type (which indicates
of the response to the client. The MIME type also helps determine which
Service directive the server should execute.
The resulting type may be:
A common document type such as text/html or image/gif (for example,
the file name extension
An internal server type. Internal types always begin with
magnus-internal.
.gif translates to the MIME type image/gif).
For example:
ObjectType fn="type-by-extension"
This example calls the type-by-extension function which causes the server to determine the MIME type according to the requested resource’s file extension.
Chapter 2 Syntax and Use of obj.conf 27
Server Instructions in obj.conf
Service Generates and sends the response to the client. This involves setting the HTTP
result status, setting up response headers (such as content-type and content-length), and generating and sending the response data. The default response is to invoke the
send-file function to send the contents of the
requested file along with the appropriate header files to the client. The default
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"
Service directive is:
This directive instructs the server to call the send-file function in response to any request whose method is begin with
magnus-internal/. (Note the use of the special characters *~ to
GET, HEAD, or POST, and whose type does not
mean “does not match.”) Another example is:
Service method="(GET|HEAD)" type="magnus-internal/imagemap" fn="imagemap"
In this case, if the method of the request is either GET or HEAD, and the type of the requested resource is
imagemap is called.
AddLog
"magnus-internal/imagemap", the function
Adds an entry to a log file to record information about the transaction. For example:
AddLog fn="flex-log" name="access"
This example calls the flex-log function to log information about the current request in the log file named
access.
Error
• Handles an HTTP error. This directive is invoked if a previous directive results
in an error. Typically the server handles an error by sending a custom HTML document to the user describing the problem and possible solutions.
For example:
Error fn="send-error" reason="Unauthorized" path="D:/netscape/server4/errors/unauthorized.html"
In this example, the server sends the file in
D:/netscape/server4/errors/unauthorized.html whenever a client
requests a resource that it is not authorized to access.
28 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001

The Object Tag

Directives in the obj.conf file are grouped into objects that begin with an
<Object> tag and end with a </Object> tag. The default object provides
instructions to the server about how to process requests by default. Each new
object modifies the default object’s behavior.
Object tag may have a name attribute or a ppath attribute. Either parameter
An may be a wildcard pattern. For example:
<Object name="cgi">
or
<Object ppath="/usr/netscape/server4/docs/private/*">
The server always starts handling a request by processing the directives in the default object. However, the server switches to processing directives in another object after the conditions is true:
The Object Tag
NameTrans stage of the default object if either of the following
The successful
the physical pathname that results from the
ppath attribute of another object
When the server has been alerted to use an object other than the default object, it processes the directives in the other object before processing the directives in the default object. For some steps in the process, the server stops processing directives in that a particular stage (such as the executed, whereas for other stages the server processes all directives in that stage, including the ones in the default object as well as those in the additional object. For more details, see ”“Flow of Control in obj.conf,” on page 32.
NameTrans directive specifies a name argument
NameTrans stage matches the
Service stage) as soon as one is successfully

Objects that Use the name Attribute

If a NameTrans directive in the default object specifies a name argument, the server switches to processing the directives in the object of that name before processing the remaining directives in the default object.
For example, the following
cgi to any request whose URL starts with http://server_name/cgi/.
name
NameTrans directive in the default object assigns the
Chapter 2 Syntax and Use of obj.conf 29
The Object Tag
<Object name="default"> NameTrans fn="pfx2dir" from="/cgi" dir="D:/netscape/server4/docs/mycgi" name="cgi" ... </Object>
When that NameTrans directive is executed, the server starts processing directives in the object named
<Object name="cgi">
more directives...
</Object>
cgi:

Object that Use the ppath Attribute

When the server finishes processing the NameTrans directives in the default object, the logical URL of the request will have been converted to a physical pa thname. If this physical pathname matches the
ppath attribute of another object in obj.conf,
the server switches to processing the directives in that object before processing the remaining ones in the default object.
For example, the following
http://server_name/ part of the requested URL to D:/Netscape/Server4/docs/
NameTrans directive translates the
(which is the document root directory).
<Object name="default"> NameTrans fn="document-root" root="D:/Netscape/Server4/docs" ... </Object>
30 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001

Variables Defined in server.xml

The URL http://server_name/internalplan1.html would be translated to
D:/Netscape/Server4/docs/internalplan1.html. However, suppose that obj.conf contains the following additional object:
<Object ppath="*internal*">
more directives...
</Object>
In this case, the partial path
D:/Netscape/Server4/docs/internalplan1.html. So now the server starts
*internal* matches the path
processing the directives in this object before processing the remaining directives in the default object.
Variables Defined in server.xm l
You can define variables in the server.xml file and reference them in a n obj.conf file. For example, the following
docroot: <!DOCTYPE SERVER SYSTEM "server.dtd" [
<!ATTLIST VARS
docroot CDATA #IMPLIED > ]> ...
<VS id="a.com" connections="maingroup" urlhosts="a.com"
mime="mime1" aclids="std">
<VARS docroot="/u/server6/a/docs" />
</VS>
...
You can reference the variable in obj.conf as follows:
server.xml code defines and uses a variable called
NameTrans fn=document-root root="$docroot"
Using this docroot variable saves you from having to define document roots for virtual server classes in the
obj.conf files. It also allows you to define different
document roots for different virtual servers within the same virtual server class.
Chapter 2 Syntax and Use of obj.conf 31

Flow of Control in obj.conf

NOTE Variable substitution is allowed on ly in an
allowed in any other Enterprise Server configuration files. Any variable referenced in an
server.xml file at the SERVER, VSCLASS, or VS level. Defining
variables with default values at the overriding them in the
For more information, see Chapter 8, “Virtual Server Configuration Files.”
Flow of Control in obj.conf
Before the server can process a request, it must direct the request to the correct virtual server. For details about how the virtual server is determined, see “Virtual Server Selection for Request Processing,” on page 295.
After the virtual server is determined, the server executes the virtual server class to which the virtual server belongs. This section discusses how the server decides which directives to execute in

AuthTrans

obj.conf file. It is not
obj.conf file must be defined in the
SERVER or VSCLASS level and
VS is recommended.
obj.conf file for the
obj.conf.
When the server receives a request, it executes the AuthTrans directives in the default object to check that the client is authorized to access the server.
If there is more than one AuthTrans directive, the server executes them all (unless one of them results in an error). If an error occurs, the server skips all other directives except for
Error directives.

NameTrans

Next, the server executes a NameTrans directive in the default object to map the logical URL of the requested resource to a physical pathname on the server’s file system. The server looks at each until it finds one that can be applied.
If there is more than one considers each directive until one succeeds.
32 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
NameTrans directive in the default object, the server
NameTrans directive in the default object in turn,
Flow of Control in obj.conf
The NameTrans section in the default object must contain exactly one directive that invokes the
http://server_name/part of the requested URL to a physical directory that has
document-root function. This functions translates the
been designated as the server’s document root. For example:
NameTrans fn="document-root" root="D:/Netscape/Server4/docs"
The directive that invokes document-root must be the last directive in the
NameTrans section so that it is executed if no other NameTrans directive is
applicable.
pfx2dir (prefix to directory) function is used to set up additional mappings
The between URLs and directories. For example, the following directive translates the
http://server_name/cgi/ into the directory pathname
URL
D:/netscape/server4/docs/mycgi/: NameTrans fn="pfx2dir" from="/cgi"
dir="D:/netscape/server4/docs/mycgi"
Notice that if this directive appeared after the one that calls document-root, it would never be executed, with the result that the resultant directory pathname would be directive that invokes
D:/netscape/server4/docs/cgi/ (not mycgi). This illustrates why the
document-root must be the last one in the NameTrans
section.
How the Server Knows to Process Other Objects
As a result of executing a NameTrans directive, the server might start processing directives in another object. This happens if the successfully executed specifies a name or generates a partial path that matches the
name or ppath attribute of another object.
If the successful
NameTrans directive assigns a name by specifying a name
argument, the server starts processing directives in the named object (defined with
OBJECT tag) before processing directives in the default object for the rest of the
the request handling proc ess.
For example, the following
cgi to any request whose URL starts with http://server_name/cgi/.
name
<Object name="default"> ... NameTrans fn="pfx2dir" from="/cgi" dir="D:/netscape/server4/docs/mycgi" name="cgi" ... </Object>
NameTrans directive in the default object assigns the
NameTrans directive that was
Chapter 2 Syntax and Use of obj.conf 33
Flow of Control in obj.conf
When that NameTrans directive is executed, the server starts processing directives in the object named
cgi:
<Object name="cgi">
more directives...
</Object>
When a
NameTrans directive has been successfully executed, there will be a
physical pathname associated with the requested resource. If the resultant pathname matches the
ppath (partial path) attribute of another object, the server
starts processing directives in the other object before processing directives in the default object for the rest of the request handling process.
For example, suppose
<Object ppath="*internal*">
more directives...
</Object>
Now suppose the successful the pathname
D:/Netscape/Server4/docs/internalplan1.html. In this case,
the partial path
D:/Netscape/Server4/docs/internalplan1.html. So now the server would
obj.conf contains an object as follows:
NameTrans directive translates the requested URL to
*internal* matches the path
start processing the directives in this object before processing the remaining directives in the default object.

PathCheck

After converting the logical URL of the requested resource to a physical pathname
NameTrans step, the server executes PathCheck directives to verify that the
in the client is allowed to access the requested resource.
If there is more than one
PathCheck directive, the server executes all the directives
in the order in which they appear, unless one of the directives denies access. If access is denied, the server switches to executing directives in the Error section.
34 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Flow of Control in obj.conf
If the NameTrans directive assigned a name or generated a physical pathname that matches the
PathCheck directives in the matching object before applying the directives in the
name or ppath attribute of another object, the server first applies the
default object.

ObjectType

Assuming that the PathCheck directives all approve access, the server next executes the MIME type has three attributes: type, encoding, and language. When the server sends the response to the client, the type, language, and encoding values are transmitted in the headers of the response. The server to determine which the client.
ObjectType directives to determine the MIME type of the request. The
type also frequently helps the
Service directive to execute to generate the response to
If there is more than one
ObjectType directive, the server applies all the directives
in the order in which they appear. However, once a directive sets an attribute of the MIME type, further attempts to set the same attribute are ignored. The reason that
ObjectType directives are applied is that one directive may set one attribute, for
all example
As with the as a result of the the matching object before executing the
type, while another directive sets a different attribute, such as language.
PathCheck directives, if another object has been matched to the request
NameTrans step, the server executes the ObjectType directives in
ObjectType directives in the default
object.
Setting the Type By File Extension
Usually the default way the server figures out the MIME type is by calling the
type-by-extension function. This function instructs the server to look up the
MIME type according to the requested resource’s file extension in the MIME types table. This table was created during virtual server initialization by the MIME types file, (which is usually called
For example, the entry in the MIME types table for the extens ions usually:
type=text/html exts=htm,html
which says that all files that have the extension .htm or .html are text files formatted as HTML and the
mime.types).
.html and.htm is
type is text/html.
Note that if you make changes to the MIME types file, you must reconfigure the server before those changes can take effect.
Chapter 2 Syntax and Use of obj.conf 35
Flow of Control in obj.conf
For more information about MIME types, see Appendix B, “MIME Types.”
Forcing the Type
If no previous ObjectType directive has set the type, and the server does not find a matching file extension in the after recognize the file extension, it is a good idea to force the type to be that the content of the resource is treated as plain text. There are also other situations where you might want to set the type regardless of the file extension, such as forcing all resources in the designated CGI directory to have the MIME type
MIME types table, the type still has no value even
type-by-expression has been executed. Usually if the server does not
text/plain, so
magnus-internal/cgi.
The function that forces the type is
force-type.
For example, the following directives first instruct the server to look in the MIME types table for the MIME type, then if the the file extension was not found in the MIME types table), set the
text/plain.
ObjectType fn="type-by-extension" ObjectType fn="force-type" type="text/plain"
If the server receives a request for a file does not find a mapping for the extension
type attribute. Since the type attribute has not already been set, the second
directive is successful, forcing the
type attribute to text/plain.
The following example illustrates another use of
type is forced to magnus-internal/cgi before the server gets a chance to look in
type attribute has not been set (that is,
type attribute to
abc.dogs, it looks in the MIME types table,
.dogs, and consequently does not set the
force-type. In this example, the
the MIME types table. In this case, all requests for resources in
http://server_name/cgi/ are translated into requests for resources in the
directory request, the server processes processing the ones in the default object. This object has one which forces the
D:/netscape/server4/docs/mycgi/. Since a name is assigned to the
ObjectType directives in the object named cgi before
ObjectType directive,
type to be magnus-internal/cgi.
36 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Flow of Control in obj.conf
NameTrans fn="pfx2dir" from="/cgi" dir="D:/netscape/server4/docs/mycgi" name="cgi" <Object name="cgi"> ObjectType fn="force-type" type="magnus-internal/cgi" Service fn="send-cgi" </Object>
The server continues processing all ObjectType directives including those in the default object, but since the
type attribute has already been set, no other directive
can set it to another value.

Service

Next, the server needs to execute a Service directive to generate the response to send to the client. The server looks at each first one that matches the type, method and query string. If a does not specify type, method, or query string, then the unspecified attribute matches anything.
Service directive in turn, to find the
Service directive
If there is more than one matches the conditions of the request, and ignores all remaining
Service directive, the server applies the first one that
Service
directives. As with the
matched to the request as a result of the
Service directives in the matching object before cons idering the ones in the default
object. If the server successfully executes a object, it will not get round to executing the object, since it only executes one
PathCheck and ObjectType directives, if another object has been
NameTrans step, the server considers the
Service directive in the matching
Service directives in the default
Service directive.
Service Examples
For an example of how Service directives work, consider what happens when the server receives a request for the URL directives executed by the server are in the default object.
The following
D:/netscape/server4/docs/jos.html:
NameTrans fn="document-root" root="D:/Netscape/Server4/docs"
NameTrans directive translates the requested URL to
Assume that the PathCheck directives all succeed.
D:/server_name/jos.html. In this case, all
Chapter 2 Syntax and Use of obj.conf 37
Flow of Control in obj.conf
The following ObjectType directive tells the server to look up the resource’s
The server finds the following entry in the MIME types table, which sets the
The server invokes the following Service directive. The value of the type
MIME type in the MIME types table:
ObjectType fn="type-by-extension"
type attribute to
type=text/html exts=htm,html
parameter matches anything that does not begin with
text/html:
magnus-internal/. (For
a list of all wildcard patterns, see Appendix C, “Wildcard Patterns.”) This directive sends the requested file,
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file""
jos.html, to the client.
For an example that involves using another object, consider what happens when the server receives a request for
http://server_name/servlet/doCalculation.class. This example a ssumes
that servlets have been activated and the directory
D://netscape/server4/docs/servlet/ has been registered as a servlet
directory (that is, the server treats all files in that directory as servlets).
The following
D:netscape/Server4/docs/servlet/doCalculation.class. This directive
also assigns the name
NameTrans fn="pfx2dir" from="/servlet" dir="D:/Netscape/Server4/docs/servlet" name="ServletByExt"
As a result of the directives in the object named
<Object name="ServletByExt"> ObjectType fn="force-type" type="magnus-internal/servlet" Service type="magnus-internal/servlet" fn="NSServletService" </Object>
38 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
NameTrans directive translates the requested URL to
ServletByExt to the request.
name assignment, the server switches to processing the
ServletByExt. This object is defined as:
Flow of Control in obj.conf
•The ServletByExt object has no PathCheck directives, so the server processes
PathCheck directives in the default object. Let’s assume that all PathCheck
the directives succeed.
Next, the server processes the
ServletByExt object. This directive sets the type attribute to
the
magnus-internal/servlet. ObjectType fn="force-type" type="magnus-internal/servlet"
ObjectType directives, starting with the one in
The server continues processing all the ObjectType directives in the default object, but since the
When processing
Service directive in the ServletByExt object which is: Service type="magnus-internal/servlet" fn="NSServletService"
type attribute is already set its value cannot be changed.
Service directives, the server starts by considering the
•The type argument of this directive matches the type value that was set by the
ObjectType directive. So the server goes ahead and executes this Service
directive which calls the
NSServletService function. This function invokes
the requested file as a servlet and sends the output from the servlet as the response to the client. (If the requested resource is not a servlet, an error occurs.)
Since a any other
Service directive that was executed, the server would continue looking at Service directives in the default object.)
Service directive has now been executed, the server does not process
Service directives. (However, if the matching object had not had a
Default Service Directive
There is usually a Service directive that does the default thing (sends a file) if no
Service directive matches a request sent by a browser. This default directive
other should come last in the list of only gets called if no other
Service directive is usually:
Service directives in the default object, to ensure it
Service directives have succeeded. The default
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"
Chapter 2 Syntax and Use of obj.conf 39
Flow of Control in obj.conf
This directive matches requests whose method is GET, HEAD, or POST, which covers nearly virtually all requests sent by browsers. The value of the special pattern-matching characters. For com plete information about the special pattern-matching characters, see Appendix C, “Wildcard Patterns.”
type argument uses
The characters “ so the expression
magnus-internal/.” An asterisk by itself matches anything, so the whole
expression
magnus-internal/.
So if the server has not already executed a directive, it executes the directive so long as the request method is
POST, and the value of the type attribute does not begin with magnus-internal/.
The invoked function is
*~” mean “anything that doesn’t match the following characters,”
*~magnus-internal/ means “anything that doesn’t match
*~magnus-internal/* matches anything that does not begin with
Service directive when it reaches this
GET, HEAD or
send-file, which simply sends the contents of the
requested file to the client.

AddLog

After the server generate the response and sends it to the client, it executes AddLog directives to add entries to the log files.
AddLog directives are executed. The server can add entries to multiple log files.
All Depending on which log files are used and which format they use, the
magnus.conf may need to have directives that initialize the logs. Fo r exa mple, if
in one of the the
AddLog directives calls flex-log, which uses the extended log format,
Init section must contain a directive that invokes flex-init to initial ize the
flexible logging system.
Init section
For more information about init ializing logs, see the discussion of the functions
flex-init and init-clf in Chapter 7, “Syntax and Use of magnus.conf.”

Error

If an error occurs during the request handling process, such as if a PathCheck or
AuthTrans directive denies access to the requested resource, or the requested
resource does not exist, then the server immediately stops executing all other directives and immediately starts executing the
40 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Error directives.

Syntax Rules for Editing obj.conf

Several rules are important in the obj.conf file. Be very careful when editing this file. Simple mistakes can make the server fail to start or operate incorrectly.

Order of Directives

The order of directives is important, since the server executes them in the order they appear in other directives.
PathCheck directives, the order within the PathCheck section is not so
For important, since the server executes all
ObjectType section the order is very important, because if an ObjectType
directive sets an attribute value, no other value. For example, if the default following order (which is the wrong way round), every request would have its
type value set to text/plain, and the server would never have a chance to set the type according to the extension of the requested resource.
obj.conf. The outcome of some directives affect the execution of
PathCheck directives. However, in the
ObjectType directive can change that
ObjectType directives were listed in the
Syntax Rules for Editing obj.conf
ObjectType fn="force-type" type="text/plain" ObjectType fn="type-by-extension"
Similarly, the order of directives in the server executes the first does not execute any others.
Service directive that matches the current request and
Service section is very important. The

Parameters

The number and names of parameters depends on the function. The order of parameters on the line is not important.

Case Sensitivity

Items in the obj.conf file are case-sensitive including function names, parameter names, many parameter values, and path names.
Chapter 2 Syntax and Use of obj.conf 41
Syntax Rules for Editing obj.conf

Separators

The C language allows function names to be composed only of letters, digits, and underscores. You may use the hyphen (-) character in the configu ration file in place of underscore (_) for your C code function names. This is only true for function names.

Quotes

Quotes (") are only required around value strings when there is a space in the string. Otherwise they are optional. Each open-quote must be matched by a close-quote.

Spaces

Spaces are not allowed at the beginning of a line except when continuing the previous line. Spaces are not allowed before or after the equal (=) sign that separates the name and value. Spaces are not allowed at the end of a line or on a blank line.

Line Continuation

A long line may be continued on the next line by beginning the next line with a space or tab.

Path Names

Always use forward slashes (/) rather than back-slashes (\) in path names under Windows NT. Back-slash escapes the next character.

Comments

Comments begin with a pound (#) sign. If you manually add comments to
obj.conf, then use the Server Manager interface to make changes to your server,
the Server Manager will wipe out your comments when it updates
42 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
obj.conf.

About obj.conf Directive Examples

Every line in the obj.conf file begins with one of the following keywords:
AuthTrans NameTrans PathCheck ObjectType Service AddLog Error <Object </Object>
If any line of any example begins with a different word in the manual, the line is wrapping in a way that it does not in the actual file. In some cases this is due to line length limitations imposed by th e PDF and HTML formats of the manuals.
About obj.conf Directive Examples
For example, the following directive is all on one line in the actual
NameTrans fn="pfx2dir" from="/cgi" dir="D:/netscape/server4/docs/mycgi" name="cgi"
obj.conf file:
Chapter 2 Syntax and Use of obj.conf 43
About obj.conf Directive Examples
44 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Chapter 3
Predefined SAFs and the Request
Handling Process
This chapter describes the standard directives and pre-defined Server Application Functions (SAFs) that are used in the server. For a discussion of the use and syntax of chapter, Chapter 2, “Syntax and Use of obj.conf.”
obj.conf file to give instructions to the
obj.conf, see the previous
For a list of magnus.conf.”
This chapter includes functions that are part of the core functionality of Netscape Enterprise Server. It does not include functions that are available only if additional components, such as servlets and server-parsed HTML, are enabled.
This chapter contains a section for each directive which lists all the pre-defined Server Application Functions that can be used with that directive.
The directives are:
AuthTrans Stage
NameTrans Stage
PathCheck Stage
ObjectType Stage
Service Stage
AddLog Stage
Error Stage For an alphabetical list of pre-defined SAFs, see Appendix H, “Alphabetical List of
Directives in magnus.conf.”
Init (initialization) SAFs, see Chapter 7, “Syntax and Use of
45
Table 3-1 lists the SAFs that can be used with each directive.
Table 3-1 Available Server Application Functions (SAFs) Per Directive AuthTrans Stage basic-auth
basic-ncsa get-sslid qos-handler
NameTrans Stage assign-name
document-root home-page pfx2dir redirect strip-params unix-home
PathCheck Stage check-acl
deny-existence find-index find-links find-pathinfo get-client-cert load-config nt-uri-clean ntcgicheck require-auth set-virtual-index ssl-check ssl-logout unix-uri-clean
ObjectType Stage force-type
set-default-type shtml-hacktype type-by-exp type-by-extension
46 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Table 3-1 Available Server Application Functions (SAFs) Per Directive Service Stage add-footer
add-header append-trailer imagemap index-common index-simple key-toosmall list-dir make-dir query-handler remove-dir remove-file rename-file send-cgi send-file send-range send-shellcgi send-wincgi service-dump shtml_send stats-xml upload-file

The bucket Parameter

AddLog Stage common-log
Error Stage send-error
The bucket Parameter
The following performance buckets are predefined in Enterprise Server:
•The
•The
You can define additional performance buckets in the
perf-init and define-perf-bucket functions).
default-bucket records statistics for the functions not associated with
any user-defined or built-in bucket.
all-requests bucket records.perf statistics for all NSAPI SAFs,
including those in the
default-bucket.
flex-log record-useragent
qos-error
magnus.conf file (see the
Chapter 3 Predefined SAFs and the Request Handling Process 47

AuthTrans Stage

You can measure the performance of any SAF in obj.conf by adding a
bucket=bucket-name parameter to the function, for example bucket=cache-bucket.
To list the performance statistics, use the As an alternative, you can use the
performance statistics; use of buckets is optional. For more information about performance buckets, see the Netscape Enterprise Server
Performance Tuning, Sizing, and Scaling Guide.
AuthTrans Stage
AuthTrans stands for Authorization Translation. AuthTrans directives give the
server instructions for checking author ization before allowing a client to access resources. Generally, an with the request are acceptable, but it does not allow or deny access to the request
-- it leaves that to a
The server handles the authorization of client users in two steps.
AuthTrans Directive - validates authorization information sent by the client in
PathCheck Stage - checks that the authorized user is allowed access to the
AuthTrans directives work in conjunction with PathCheck directives.
AuthTrans function checks if the username and password associated
the Authorization header.
requested resource.
service-dump Service function.
stats-xml Service function to generate
PathCheck function.
The authorization process is split into two steps so that multiple authorization schemes can be easily incorporated, as well as providing the flexibility to have resources that record authorization information but do not require it.
AuthTrans functions get the username and password from the headers associated
with the request. When a client initially makes a request, the username and password are unknown so the
AuthTrans functions and PathCheck functions work
together to reject the request, since they can’t validate the usern ame and password. When the client receives the rejection, its usual response is to pop up a dialog box asking for the username and password to enter the appropriate realm, and then the client submits the request again, this time including the username and password in the headers.
If there is more than one
AuthTrans directive in obj.conf, each function is
executed in order until one succeeds in authorizing the user.
48 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
AuthTrans Stage
The following AuthTrans-class functions are described in detail in this section:
basic-auth calls a custom function to verify user name and password.
• Optionally determines the user’s group.
basic-ncsa verifies user name and password against an NCSA-style or
• system DBM database. Optionally determi nes the user’s group.
get-sslid retrieves a string that is unique to the current SSL session and
• stores it as the
qos-handler handles the current quality of service statistics.
ssl-id variable in the Session->client parameter block.
basic-auth
Applicable in AuthTrans-class directives.
basic-auth function calls a custom function to verify authorization
The information sent by the client. The Authorization header is sent as part of the basic server authorization scheme.
This function is usually used in conj unction with the PathCheck-class function
require-auth.
Parameters
auth-type specifies the type of authorization to be used. This should
always be basic.
userdb (optional) specifies the full path and file name of the user
database to be used for us er ver ificati on. Th is param eter wi ll be passed to the user function.
userfn is the name of the user custom function to verify
authorization. This function must have been previously loaded with load-modules. It has the sam e interface as all the SAFs, but it is called with the user name (user), password (pw), user database (userdb), and grou p database (groupdb) if supplied, in the pb parameter. The user function should check the name and password using the database and return REQ_NOACTION if they are not valid. It should return REQ_PROCEED if the name and password are valid. The basic-auth function will then add auth-type,
auth-user (user), auth-db (userdb), and auth-password (pw, Windows NT only) to the rq->vars pblock.
Chapter 3 Predefined SAFs and the Request Handling Process 49
AuthTrans Stage
groupdb (optional) specifies the full path and file name of the user
database. This parameter will be passed to the group function.
groupfn (optional) is the name of the group custom function that
must have been previously loaded with load-modules. It has the same interface as all the SAFs, but it is called with the user name (user), password (pw), user database (userdb), and group database (groupdb) in the pb parameter. It a lso has a ccess to the auth -type, auth-user (user), auth-db (userdb), and auth-password (pw, Windows NT only) parameters in the rq->vars pblock.
The group function should determine the user’s group using the group database, add it to rq->vars as auth-group, and return REQ_PROCEED if found. It should return
REQ_NOACTION if the user’s group is not found.
bucket optional, common to all obj.conf functions
Examples
in magnus.conf:
Init fn=load-modules shlib=/path/to/mycustomauth.so funcs=hardcoded_auth
obj.conf:
in
AuthTrans fn=basic-auth auth-type=basic userfn=hardcoded_auth PathCheck fn=require-auth auth-type=basic realm="Marketing Plans"
See Also
require-auth
50 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
AuthTrans Stage
basic-ncsa
Applicable in AuthTrans-class directives.
basic-ncsa function verifies authorization information sent by the client
The against a database. The Authorization header is sent as part of the basic server authorization scheme.
This function is usually used in conj unction with the PathCheck-class function
require-auth.
Parameters
auth-type specifies the type of authorization to be used. This should
always be basic.
dbm (optional) specifies the full path and base file name of the
user database in the server’s native format. The native format is a system DBM file, which is a hashed file format allowing instan ta neous access to billions of users. If you use
this parameter, don’t use the userfile parameter as well.
userfile (optional) specifies the full path name of the user database
in the NCSA-style HTTPD user file format. This format consists of lines using the format
password is encrypted. If you use this parameter, don’t use
dbm.
grpfile (optional) specifies the NCSA-style HTTPD group file to be
used. Each line of a group file consists of
... userN
bucket optional, common to all obj.conf functions
where each user is separated by spaces.
name:password, where
group:user1 user2
Examples
AuthTrans fn=basic-ncsa auth-type=basic dbm=/netscape/server4/userdb/rs
PathCheck fn=require-auth auth-type=basic realm="Marketing Plans" AuthTrans fn=basic-ncsa auth-type=basic
userfile=/netscape/server4/.htpasswd grpfile=/netscape/server4/.grpfile
PathCheck fn=require-auth auth-type=basic realm="Marketing Plans"
Chapter 3 Predefined SAFs and the Request Handling Process 51
AuthTrans Stage
See Also
require-auth
get-sslid
Applicable in AuthTrans-class directives.
NOTE This function is provided for backward compatibility only. The
functional ity of processing of an SSL connection.
get-sslid function retrieves a string that is unique to the current SSL session,
The and stores it as the
ssl-id variable in the Session->client parameter block.
get-sslid has been incorporated into the standard
If the variable
HTTPS_SESSIONID environment variable.
the
get-sslid function has no parameters and always returns REQ_NOACTION. It
The
ssl-id is present when a CGI is invoked, it is passed to the CGI as
has no effect if SSL is not enabled.
Parameters
bucket optional, common to all obj.conf functions
qos-handler
Applicable in AuthTrans-class directives.
qos-handler function examines the current quality of service statistics for the
The virtual server, virtual server class, and global server, logs the statistics, and enforces the QOS parameters by returning an error. This must be the first
AuthTrans function configured in the default object in order to work properly.
The code for this SAF is one of the examples in Chapter 6, “Examples of Custom SAFs.”
For more information, see the Netscape Enterprise Server Perform a nce Tuning, Sizing, and Scaling Guide.
Parameters
bucket optional, common to all obj.conf functions
52 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Example
AuthTrans fn=qos-handler
See Also
qos-error

NameTrans Stage

NameTrans stands for Name Translation. NameTrans directives translate virtual
URLs to physical directories on your server. For example, the URL
http://www.example.com/some/file.html
could be translated to the full file-system path
/usr/netscape/server4/docs/some/file.html
NameTrans Stage
NameTrans NameTrans directive in an object, the server executes each one in order until one
directives should appear in the default object. If there is more than one
succeeds. The following NameTrans-cla ss functions are described in detail in this section:
assign-name tells the server to process directives in a named object.
document-root translates a URL into a file system path by replacing the
http://server-name/ part of the requested resource with the document root
directory.
home-page translates a request for the server’s root home page (/) to a specific
• file.
pfx2dir translates any URL beginning with a given prefix to a file system
• directory and optionally enables directives in an additional named object.
redirect redirects the client to a different URL.
strip-params removes embedded semicolon-delimited parameters from the path.
unix-home translates a URL to a specified directory within a user’s home
• directory.
Chapter 3 Predefined SAFs and the Request Handling Process 53
NameTrans Stage
assign-name
Applicable in NameTrans-class directives.
assign-name function specifies the name of an object in obj.conf that
The matches the current request. The server then processes the directives in the named object in preference to the ones in the default object.
For example, consider the following directive in the default object:
NameTrans fn=assign-name name=personnel from=/personnel
Let’s suppose the server receives a request for http://server-name/personnel. After processing this
personnel in obj.conf, and continues by processing the directives in the personnel object.
assign-name function always returns REQ_NOACTION.
The
Parameters
from is a wildcard pattern that specifies the path to be affected. name specifies an additional named object in obj.conf whose
NameTrans directive, the server looks for an object named
directives will be applied to this request.
find-pathinfo-forward (optional) makes the server look for the PATHINFO
forward in the path right after the ntrans-base instead of backward from the end of path as the server function assign-name does by default.
The value you assign to this parameter is ignored. If you do not wish to u se this parameter, leave it out.
The find-pathinfo-forward parameter is ig nored if the ntrans-base parameter is not se t in rq->vars. By default, ntrans-base is set.
This feature can improve performa nce for certain U RLs b y reducing the number of stats performed.
54 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
NameTrans Stage
nostat (optional) prevents the server from performing a stat on a
specified URL whenever possible. The effect of nostat="
function assign-name is that the server assumes that a stat on the specified nostat only when the path of the exist on the system, for example, for NSAPI plugin URLs, to improve performance by av oidin g un nec ess ar y stats on those URLs.
When the default PathCheck server functions are used, the server does not stat for the paths /ntrans-base/virtual-path and
ntrans-base/virtual-path/* if ntrans-base is set (the
/
default condition); it does not stat for the URLs /virtual-path and /virtual-path/* if ntrans-base is not set.
bucket optional, common to all obj.conf functions
Example
virtual-path" in the NameTrans
virtual-path will fail. Therefore, use
virtual-path does not
# This NameTrans directive is in the default object. NameTrans fn=assign-name name=personnel from=/a/b/c/pers ... <Object name=personnel> ...additional directives.. </Object>
NameTrans fn="assign-name" from="/perf" find-pathinfo-forward="" name="perf"
NameTrans fn="assign-name" from="/nsfc" nostat="/nsfc" name="nsfc"
document-root
Applicable in NameTrans-class directives.
document-root function specifies the root document directory for the server.
The If the physical path has not been set by a previous
http://server-name/ part of the path is replace by the physical pathname for the
document root.
Chapter 3 Predefined SAFs and the Request Handling Process 55
NameTrans function, the
NameTrans Stage
When the server receives a request for http://server-name/somepath/somefile,
document-root function replaces http://server-name/ with the value of its
the
root parameter. For example, if the document root directory is /usr/netscape/server4/docs, then when the server receives a request for http://server-name/a/b/file.html, the document-root function translates the
pathname to
/usr/netscape/server4/docs/a/b/file.html for the requested
resource. This function alw ays returns
will never be called, so be sure that the directive that invokes
NameTrans directive.
last
REQ_PROCEED. NameTrans directives listed after this
document-root is the
There can be only one root document directory. To specify additional document directories, use the
Parameters
root is the file system path to the server’s root document
bucket optional, common to all obj.conf functions
Examples
NameTrans fn=document-root root=/usr/netscape/server4/docs NameTrans fn=document-root root=$docroot
See also
pfx2dir
pfx2dir function to set up additional path name translations.
directory.
home-page
Applicable in NameTrans-class directives.
home-page function specifies the home page for your server. Whenever a client
The
requests the server’s home page (
56 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
/), they’ll get the document specified.
NameTrans Stage
Parameters
path is the path and name of the home page file. If path starts
with a slash (/), it is assumed to be a full path to a file.
This function sets the server’s path variable and returns REQ_PROCEED. If path is a relative path, it is appended to
the URI and the function returns REQ_NOACTION continuing on to the other NameTrans directives.
bucket optional, common to all obj.conf functions
Examples
NameTrans fn="home-page" path="homepage.html" NameTrans fn="home-page" path="/httpd/docs/home.html"
pfx2dir
Applicable in NameTrans-class directives.
pfx2dir function replaces a directory prefix in the requested URL with a real
The directory name. It also optionally allows you to specif y the name of an object that matches the current request. (See the discussion of
assign-name for details of
using named objects.)
Parameters
from is the URI prefix to convert. It should not have a trailing
slash (/).
dir is the local file system directory path that the prefix is
converted to. It should not have a trailing slash (/).
name (optional) specifies an additional named object in
obj.conf whose directives will be applied to this
request.
Chapter 3 Predefined SAFs and the Request Handling Process 57
NameTrans Stage
find-pathinfo-forward (optional) makes the server look for the PATHINFO
forward in the path right after the ntrans-base instead of backward from the end of path as the server function find-pathinfo does by default.
The value you assign to this parameter is ignored. If you do not wish to u se this parameter, leave it out.
The find-pathinfo-forward parameter is ig nored if the ntrans-base parameter is not se t in rq->vars when the server function find-pathinfo is called. By default, ntrans-base is set.
This feature can improve performa nce for certain U RLs b y reducing the number of stats performed in the server function find-pathinfo.
On Windows NT, this feature can also be used to prevent the PATHINFO from the server URL normalization process (changing ’\’ to ’/’) when the PathCheck server function find-pathinfo is used. Some double-byte characters have hex values that may be parsed as URL separator charac ters such as \ or ~. Using th e find-pathinfo-forward parameter can sometimes prevent incorrect parsing of URLs containing double-byte characters.
bucket optional, common to all obj.conf functions
Examples
In the first example, the URL http://server-name/cgi-bin/resource (such as
http://x.y.z/cgi-bin/test.cgi) is translated to the physical pathname /httpd/cgi-local/resource, (such as /httpd/cgi-local/test.cgi) and the
server also starts processing the directives in the object named
NameTrans fn=pfx2dir from=/cgi-bin dir=/httpd/cgi-local name=cgi
In the second example, the URL
http://x.y.z/icons/happy/smiley.gif) is translated to the physical pathname /users/nikki/images/resource, (such as /users/nikki/images/smiley.gif)
58 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
http://server-name/icons/resource (such as
cgi.
NameTrans Stage
NameTrans fn=pfx2dir from=/icons/happy dir=/users/nikki/images
The third example shows the use of the find-pathinfo-forward parameter. The
http://server-name/cgi-bin/resource is translated to the physical pathname
URL
/export/home/cgi-bin/resource.
NameTrans fn="pfx2dir" find-pathinfo-forward="" from="/cgi-bin" dir="/export/home/cgi-bin" name="cgi"
redirect
Applicable in NameTrans-class directives.
redirect function lets you change URLs and send the updated URL to the
The client. When a client accesses your server with an old path, the server treats the request as a request for the new URL.
Parameters
from specifies the prefix of the requested URI to match. url (maybe optional) specifies a complete URL to return to the
client. If you use this parameter, don’t use url-prefix (and vice-versa).
url-prefix (maybe optional) is the new URL prefix to return to the
client. The from prefix is simply replaced by this URL prefix. If you use this parameter, don’t use url (and vice-versa).
escape (optional) is a flag which tells the server to
util_uri_escape the URL before sending it. It should be yes or no. The default is yes.
bucket optional, common to all obj.conf functions
Examples
In the first example, any request for http://server-name/whatever is translated to a request for
http://tmpserver/whatever.
Chapter 3 Predefined SAFs and the Request Handling Process 59
NameTrans Stage
NameTrans fn=redirect from=/ url-prefix=http://tmpserver
In the second example, any request for http://server-name/toopopular/whatever is translated to a request for http://bigger/better/morepopular/whatever.
NameTrans fn=redirect from=/toopopular url=http://bigger/better/morepopular
strip-params
Applicable in NameTrans-class directives.
strip-params function removes embedded semicolon-delimited parameters
The from the path. For exam ple, a UR I of
/dir1/dir2. When used, the strip-params function should be the first NameTrans directive listed.
/dir1;param1/dir2 would become a path of
Parameters
bucket optional, common to all obj.conf functions
Example
NameTrans fn=strip-params
unix-home
Applicable in NameTrans-class directives. UNIX Only. The
~username) into the user’s home directory on the server’s UNIX machine. You specify a URL prefix that signals user directories. Any request that begins with the prefix is translated to the user’s home directory.
You specify the list of users with either the structure. Each line in the file should have this structure (elements in the file that are not needed are indicated with *):
username:*:*:groupid:*:homedir:*
60 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
unix-home function translates user names (typically of the form
/etc/passwd file or a file with a similar
passwd

PathCheck Stage

If you want the server to scan the password file only once at startup, use the Init-class function
Parameters
from is the URL prefix to translate, usually “/~”. subdir is the subdirectory within the user’s home directory that
pwfile (optional) is the full path and file name of the password file if
name (optional) specifies an additional named object whose
bucket optional, common to all obj.conf functions
Examples
NameTrans fn=unix-home from=/~ subdir=public_html NameTrans fn=unix-home from /~ pwfile=/mydir/passwd
subdir=public_html
init-uhome in magnus.conf.
contains their web documents.
it is different from /etc/passwd.
directives will be applied to this request.
See Also
init-uhome, find-links
PathCheck Stage
PathCheck directives check the local file system path that is returned after the NameTrans step. The path is checked for things such as CGI path information and
for dangerous elements such as restriction is applied.
If there is more than one order.
The following PathCheck-clas s f unctions are described in detail in this section:
check-acl checks an access control list for authorization.
deny-existence indicates that a resource was not found.
find-index locates a default file when a directory is requested.
/./and /../ and //, and then any access
PathCheck directive, each of the functions are executed in
Chapter 3 Predefined SAFs and the Request Handling Process 61
PathCheck Stage
find-links denies access to directories with certain file system links
find-pathinfo locates extra path info beyond the file name for the
• PATH_INFO CGI environment variable.
get-client-cert gets the authenticated client certificate from the SSL3
• session.
load-config finds and loads extra configuration information from a file in the
• requested path
nt-uri-clean denies access to requests with unsafe path names by indicating
• not found.
ntcgicheck looks for a CGI file with a specified extension.
require-auth denies access to unauthorized users or groups.
set-virtual-index specifies a virtual index for a directory.
ssl-check checks the secret keysize.
ssl-logout invalidates the current SSL session in the server's SSL session
• cache.
unix-uri-clean denies access to requests with unsafe path names by
• indicating not found.
check-acl
Applicable in PathCheck-class directives.
check-acl function specifies an Access Control List (ACL) to use to check
The whether the client is allowed to access the requested resource. An a ccess control list contains information about who is or is not allowed to access a resource, and under what conditions access is allowed.
Regardless of the order of are executed first. They cause user authentication to be performed, if required by the specified ACL, and will also update the access control state.
Parameters
acl is the name of an Access Control List. path (optional) is a wildcard pattern that specifies the path for
bucket optional, common to all obj.conf functions
62 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
PathCheck directives in the object, check-acl functions
which to apply the ACL.
PathCheck Stage
Examples
PathCheck fn=check-acl acl="*HRonly*"
deny-existence
Applicable in PathCheck-class directives.
deny-existence function sends a “not found” message when a client tries to
The
access a specified path. The server sends “not found” instead of “forbidd en,” so the user cannot tell whether the path exists or not.
Parameters
path (optional) is a wildcard pattern of the file-system path to
hide. If the path does not match, the function does nothing and returns REQ_NOACTION. If the path is n ot provided, it is assumed to match.
bong-file (optional) specifies a file to send rather than responding
with the “not found” message. It is a full file-system path.
bucket optional, common to all obj.conf functions
Examples
PathCheck fn=deny-existence path=/usr/netscape/server4/docs/private
PathCheck fn=deny-existence bong-file=/svr/msg/go-away.html
find-index
Applicable in PathCheck-class directives.
find-index function investigates whether the requested path is a directory. If
The it is, the function searches for an index file in the directory, and then changes the path to point to the index file. If no index file is found, the server generates a directory listing.
Note that if the file the requested directory is the root directory, then the home page rather than the index page, is returned to the client.
obj.conf has a NameTrans directive that calls home-page, and
Chapter 3 Predefined SAFs and the Request Handling Process 63
PathCheck Stage
The find-index function does nothing if there is a query string, if the HTTP method is not GET, or if the path is that of a valid file.
Parameters
index-names is a comma-separated list of index file names to look for. Use
spaces only if they are part of a file name. Do not include spaces before or after the commas. This list is case-sensitive if the file system is case-sensitive.
bucket optional, common to all obj.conf functions
Examples
PathCheck fn=find-index index-names=index.html,home.html
find-links
Applicable in PathCheck-class directives. UNIX Only. The
find-links function searches the current path for symbolic or
hard links to other directories or file systems. If any are found, an error is returned. This function is normally used for directories that are not trusted (such as user home directories). It prevents someone from pointing to information that should not be made public.
Parameters
disable is a character string of links to disable:
h is hard links
s is soft links
o allows symbolic links from user home directories only if the user owns the target of the link.
dir is the directory to begin checking. If you specify an absolute
path, any request to that path and its subdirector ies is checked for symbolic links. If you specify a partial path, any request containing that partial path is checked for symbolic links. For example, if you use /user/ and a request comes in for some/user/directory, then that directory is checked for symbolic links.
64 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
PathCheck Stage
bucket optional, common to all obj.conf functions checkFileExistence check linked file for existence and abort request with 403
(forbidden) if this check fails.
Examples
PathCheck fn=find-links disable=sh dir=/foreign-dir PathCheck fn=find-links disable=so dir=public_html
See Also
init-uhome, unix-home
find-pathinfo
Applicable in PathCheck-class directives.
find-pathinfo function finds any extra path information after the file name in
The the URL and stores it for use in the CGI environment variable PATH_INFO.
Parameters
bucket optional, common to all obj.conf functions
Examples
PathCheck fn=find-pathinfo PathCheck fn=find-pathinfo find-pathinfo-forward=""
get-client-cert
Applicable in PathCheck-class directives.
get-client-cert function gets the authenticated client certificate from the
The SSL3 session. It can apply to all HTTP methods, or only to those that match a specified pattern. It only works when SSL is enabled on the server.
If the certificate is present or obtained from the SSL3 session, the function returns
REQ_NOACTION, allowing the request to proceed, otherwise it returns REQ_ABORTED
and sets the protocol status to client to be given the
FORBIDDEN status.
403 FORBIDDEN, causing the request to fail and the
Chapter 3 Predefined SAFs and the Request Handling Process 65
PathCheck Stage
Parameters
dorequest controls wh e th er t o a ct u al ly t ry to get the certificate, or jus t t est for its
presence. If dorequest is absent the default value is 0.
• 1 tells the function to redo the SSL3 handshake to get a client certificate, if the server d oes not already h ave the clien t certifica te. This typically causes the client to present a dialog box to the user to select a client certificate . The server may a lready have th e client certificate if it was requested on the initial handshake, or if a cached SSL session has been resumed.
• 0 tells the function not to redo the SSL3 handshake if the server does not already have the client certificate.
If a certificate is obtained from the client and verified successfully by the server, the ASCII base64 encoding of the DER-encoded X.509 certificate is placed in the parameter auth-cert in the Request->vars pblock, and the function returns REQ_PROCEED, allowing the reque s t to p ro c ee d.
require controls whether failure to get a client certificate will abort the HTTP
request. If require is absent the default value is 1.
• 1 tells the function to abort the HTTP request if the client certificate is not present aft er dorequest is handled. In this case, the HTTP status is set to PROTOCOL_FORBIDDEN, and the function returns REQ_ABORTED.
• 0 tells the function to return REQ_NOACTION if the client certificate is not present after dorequest is handled.
method (optional) specifies a wildcard pattern for the HTTP methods for
which the function will be applied. If method is absent, the function is applied to all requests.
bucket optional, common to all obj.conf functions
Examples
# Get the client certificate from the session. # If a certificate is not already associated with the # session, request one. # The request fails if the client does not present a # valid certificate.
PathCheck fn="get-client-cert" dorequest="1"
66 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
PathCheck Stage
load-config
Applicable in PathCheck-class directives.
load-config function searches for configuration files in document directories
The
and adds the file’s contents to the server’s existing configuration. These configuration files (also known as dyn amic configuration files) specify additional access control information for the requested resource. Depending on the rules in the dynamic configuration files, the server might or might not allow the client to access the requested resource.
Each directive that invokes is either stated explicitly through the
load-config is associated with a base directory, which
basedir parameter or derived from the root
directory for the requested resource. The base directory determines two things:
the top-most directory for which requests will invoke this call to the
load-config function.
For example, if the base directory is
D:/netscape/server4/docs/nikki/,
then only requests for resources in this directory or its subdirectories (and their subdirectories and so on) trigger the search for dynamic configuration files. A request for the resource
D:/netscape/server4/docs/somefile.html does
not trigger the search in this case, since the requested resource is in a parent directory of the base directory.
the top-most directory in which the server looks for dynamic configuration files to apply to the requested resource.
If the base directory is
D:/netscape/server4/docs/nikki/, the server starts
its search for dynamic configuration files in this directory. It may or may not also search subdirectories (but never parent directories) depending on other factors.
When you enable dynamic configuration files through the Server Manager interface, the system writes additional objects with
obj.conf file. If you manually add directives that invoke load-config to the
ppath parameters into the
default object (rather than putting them in separate objects), the Server Manager interface might not reflect your changes.
If you manually add
obj.conf, put them in additional objects (created with the <OBJECT> tag) rather
than putting them in the default object. Use the
PathCheck directives that invoke load-config to the file
ppath attribute of the OBJECT tag to
specify the partial pathname for the resources to be affected by the access rules in the dynamic configuration file. The partial pathname can be any pathname that matches a pattern, which can include wildcard characters.
Chapter 3 Predefined SAFs and the Request Handling Process 67
PathCheck Stage
For example, the following <OBJECT> tag specifies that requests for resources in the directory
my.nsconfig.
<Object ppath="D:/netscape/server4/docs/*"> PathCheck fn="load-config" file="my.nsconfig" descend=1 basedir="D:/netscape/server4/docs" </Object>
D:/netscape/server4/docs are subject to the access rules in the file
NOTE If the ppath resolves to a resource or directory that is higher in the
directory tree (or is in a different branch of the tree) than the base directory, the
load-config function is not invoked. This is because
the base directory specifies the highest-level directory for which requests will invoke the
load-config function returns REQ_PROCEED if configuration files were loaded,
The
REQ_ABORTED on error, or REQ_NOACTION when no files are loaded.
load-config function.
Parameters
file (optional) is the name of the dynamic configuration f ile
containing the access rules to be applied to the requested resource. If not provided, the file name is assumed to be
.nsconfig.
disable-types (optional) specifies a wildcard pattern of types to disable for the
base directory, such as magnus-internal/cgi. Requests for resources matching these types are aborted.
descend (optional) if present, specifies that the server should search in
subdirectories of this directory for dynamic configuration files. For example, descend=1 specifies that the server should search subdirectories. No descend parameter specifies that the function should search only the base directory.
68 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
PathCheck Stage
basedir (optional) specifies base directory. This is the highest-level
directory for which requests will invoke the load-config function and is also the directory where the server starts searching for configuration files.
If basedir is not specified, the base directory is assumed to be the root directory that results from translating the requested
resource’s URL to a physical pathname. For example, if the request was for http:// physical file name would be
/document-root/a/b/file.html.
bucket optional, common to all obj.conf functions
Examples
server-name/a/b/file.html, the
In this example, whenever the server receives a request for any resource containing the substring
secret that resides in D:/netscape/server4/docs/nikki/ or a
subdirectory thereof, it searches for a configuration file called
checkaccess.nsconfig.
The server starts the search in the directory and searches subdirectories too. It loads each instance of
D:/netscape/server4/docs/nikki,
checkaccess.nsconfig
that it finds, applying the access control rules contained therein to determine whether the client is allowed to access the requested resource or not.
<Object ppath="*secret*"> PathCheck fn="load-config" file="checkaccess.nsconfig" basedir="D:/netscape/server4/docs/nikki" descend="1" </Object>
nt-uri-clean
Applicable in PathCheck-class directives.
Windows NT Only.
whose physical path contains problems).
Parameters
bucket optional, common to all obj.conf functions
The nt-uri-clean function denies access to any resource
\.\, \..\ or \\ (these are potential security
Chapter 3 Predefined SAFs and the Request Handling Process 69
PathCheck Stage
tildeok if present, allows tilde”~” characters in URIs. This is a potential
security risk on the Windows NT platform, where longfi~1.htm might reference longfilename.htm but does not go through the proper ACL checking. If present, “//”
sequences are allowed.
dotdirok If present, “//” sequences are allowed.
Examples
PathCheck fn=nt-uri-clean
See Also
unix-uri-clean
ntcgicheck
Applicable in PathCheck-class directives. Windows NT Only. The
ntcgicheck function specifies the file name extension to
be added to any file name that does not have an extension, or to be substituted for any file name that has the extension
Parameters
extension is the replacement file extension. bucket optional, common to all obj.conf functions
Examples
PathCheck fn=ntcgicheck extension=pl
See Also
init-cgi, send-cgi, send-wincgi, send-shellcgi
70 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
.cgi.
PathCheck Stage
require-auth
Applicable in PathCheck-class directives.
require-auth function allows access to resources only if the user or group is
The authorized. Before this function is called, an authorization function (such as
basic-auth) must be called in an AuthTrans directive.
If a user was authorized in an
is provided, then the user’s name must match the
auth-group parameter is provided, the authorized user must belong to an
if the authorized group which must ma tch the
Parameters
path (optional) is a wildcard local file system path on which this
function should operate. If no path is provided, the function applies to all paths.
auth-type is the type of HTTP authorization used and must match the
auth-type from the previous authorization function in AuthTrans. Currently, basic is the only authorization type defined.
realm is a string sent to the browser indicating the secure area (or realm)
for which a user name and password are requested.
auth-user (optional) specifies a wildcard l ist of users wh o are all owed ac cess.
If this parameter is not provided, then any user authorized by the authorization function is allowed a c cess.
auth-group (optional) specifies a wildcard list of groups that are allowed
access.
bucket optional, common to all obj.conf functions
AuthTrans directive, and the auth-user parameter
auth-user wildcard value. Also,
auth-user wildcard value.
Examples
PathCheck fn=require-auth auth-type=basic realm="Marketing Plans" auth-group=mktg auth-user=(jdoe|johnd|janed)
See Also
basic-auth, basic-ncsa
Chapter 3 Predefined SAFs and the Request Handling Process 71
PathCheck Stage
set-virtual-index
Applicable in PathCheck-class directives.
set-virtual-index function specifies a virtual index for a directory, which
The determines the URL forwarding. The index can refer to a LiveWire application, a servlet in its own namespace, a Netscape Application Server applogic, a nd so on.
REQ_NOACTION is returned if none of the URIs listed in the from parameter match
the current URI.
virtual-index parameter is missing or if the current URI cannot be found. REQ_RESTART is returned if the current URI matc hes any one of the UR Is mentioned
from parameter or if there is no from parameter.
in the
Parameters
virtual-index is the URI of the content genera to r that act s as an inde x for the
from (optional) is a comma-separated list of URIs for which this
bucket optional, common to all obj.conf functions
REQ_ABORTED is returned if the file specified by the
URI the user enters.
virtual-index is applicable. If from is not specified, the virtual-index always applies.
Examples
# MyLWApp is a LiveWire application PathCheck fn=set-virtual-index virtual-index=MyLWApp
ssl-check
Applicable in PathCheck-class directives. If a restriction is selected that is not consistent with the current cipher settings
under Security Preferences, this function opens a popup dialog which warns that ciphers with larger secret keysizes need to be enabled. This function is designed to be used together with a Client tag to limit access of certain directories to non-exportable browsers.
72 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
PathCheck Stage
The function r eturn s REQ_ NOACTION if SSL is not enabled, or if the secret-keysize parameter is not specified. If the secret keysize for the current session is less than the specified function returns file is specified, the function returns
secret-keysize and the bong-file parameter is not specified, the
REQ_ABORTED with a status of PROTOCOL_FORBIDDEN. If the bong
REQ_PROCEED, and the path variable is set to
the bong filename. Also, when a keysize restriction is not met, the SSL session cache entry for the current session is invalidated, so that a full SSL handshake will occur the next time the same client connects to the server.
Requests that use
ssl-check returns something other than REQ_NOACTION.
Parameters
secret-keysize (optional) is the minimum number of bits required in the
bong-file (optional) is the name of a file (not a URI) to be served if the
bucket optional, common to all obj.conf functions
ssl-check are not cacheable in the accelerator file cache if
secret key.
restriction is not met
ssl-logout
Applicable in PathCheck-class directives.
ssl-logout invalidates the current SSL session in the server’s SSL session cache.
This does not affect the current request, but the next time the client connects, a new SSL session will be created. If SSL is enabled, this function returns after invalidating the session cache entry. If SSL is not enabled, it returns
REQ_NOACTION.
Parameters
bucket optional, common to all obj.conf functions
REQ_PROCEED
unix-uri-clean
Applicable in PathCheck-class directives. UNIX Only. The
physical path contains
unix-uri-clean function denies access to any resource whose
/./, /../ or // (these are potential security problems).
Chapter 3 Predefined SAFs and the Request Handling Process 73

ObjectType Stage

Parameters
bucket optional, common to all obj.conf functions dotdirok If present, “//” sequences are allowed.
Examples
PathCheck fn=unix-uri-clean
See Also
nt-uri-clean
ObjectType Stage
ObjectType directives determine the MIME type of the file to send to the client in
response to a request. MIME attributes currently sent are
language. The MIME type sent to the client as the value of the content-type
header.
type, encoding, and
ObjectType directives also set the type parameter, which is used by Service
directives to determine how to process the request according to what kind of content is being requested.
If there is more than one
ObjectType directive in an object, all the directives are
applied in the order they appear. If a directive sets an attribute and later directives try to set that attribute to something else, the first setting is used and the subsequent ones ignored.
obj.conf file almost always has an ObjectType directive that calls the
The
type-by-extension function. This function instructs the server to look in a
particular file (the MIME types file) to deduce the content type from the extension of the requested resource.
The following
force-type sets the content-type header for the response to a specific type.
74 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
ObjectType-class functions are described in detail in this section:
ObjectType Stage
set-default-type allows you to define a default charset,
content-encoding, and content-language for the response being sent back
to the client.
shtml-hacktype requests that .htm and .html files are parsed for
• server-parsed html commands.
type-by-exp sets the content-type header for the response based on the
• requested path.
type-by-extension sets the content-type header for the response based on the
• files extension and the MIME types database.
force-type
Applicable in ObjectType-class directives.
force-type function assigns a type to requests that do not already have a
The MIME type. This is used to specify a default object type.
Make sure that the directive that calls this function comes last in the list of
ObjectType directives so that all other ObjectType directives have a chance to set
the MIME type first. If there is more than one the directives are applied in the order they appear. If a directive sets an attribute and later directives try to set that attribute to somethi ng else, the first setting is used and the subsequent ones ignored.
ObjectType directive in an object, all
Parameters
type (optional) is the type assigned to a match ing request (the
content-type header).
enc (optional) is the encoding assigned to a matching request (the
content-encoding header).
lang (optional) is the language assigned to a matching request (the
content-language header).
charset (optional) is the character set for the magnus-charset
parameter in rq->srvhdrs. If the browser sent the Accept-charset header or its User-agent is mozilla/1.1 or newer, then append “ ; charset=charset” to c onten t-typ e,
charset is the value of the magnus-charset
where parameter in rq->srvhdrs.
bucket optional, common to all obj.conf functions
Chapter 3 Predefined SAFs and the Request Handling Process 75
ObjectType Stage
Examples
ObjectType fn=force-type type=text/plain ObjectType fn=force-type lang=en_US
See Also
type-by-extension, type-by-exp
set-default-type
Applicable in ObjectType-class directives. This function allows you to define a default
content-language for the response being sent back to the client.
charset, content-encoding, and content-language have not been set for a
If the
charset, content-encoding, and
response, then just before the headers are sent the defaults defined by
set-default-type are used. Note that by placing this function in different objects
obj.conf, you can define different defaults for different parts of the document
in tree.
Parameters
enc (optional) is the encoding assigned to a matching request (the
content-encoding header).
lang (optional) is the language assigned to a matching req uest (the
content-language header).
charset (optional) is the character set for the magnus-charset
parameter in rq->srvhdrs. If the browser sent the Accept-charset header or its User-agent is mozilla/1.1 or newer, then append “; charset=
charset is the value of the magnus-charset
where parameter in rq->srvhdrs.
bucket optional, common to all obj.conf functions
charset” to content-type ,
Example
ObjectType fn="set-default-type" charset="iso_8859-1"
76 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
ObjectType Stage
shtml-hacktype
Applicable in ObjectType-class directives.
shtml-hacktype function changes the content-type of any .htm or .html file
The
magnus-internal/parsed-html and returns REQ_PROCEED. This provides
to backward compatibility with server-side includes f or files with extensions. The function may also check the execute bit for the file on UNIX systems. The use of this function is not recommended.
Parameters
exec-hack (UNIX only, optional) tells the function to change the
content-type only if the execute bit is enabled. The val ue of the parameter is not important. It need only be provided. You may use exec-hack=true.
bucket optional, common to all obj.conf functions
Examples
.htm or .html
ObjectType fn=shtml-hacktype exec-hack=true
type-by-exp
Applicable in ObjectType-class directives.
type-by-exp function matches the current path with a wildcard expression. If
The the two match, the same as
type-by-extension, except you use wildcard patterns for the files or
directories specified in the URLs.
Parameters
exp is the wildcard pattern of paths for which this function is
type (optional) is the type assigned to a matching request (the
enc (optional) is the encoding assigned to a matching request (the
type parameter information is applied to the file. This is the
applied.
content-type header).
content-encoding header).
Chapter 3 Predefined SAFs and the Request Handling Process 77
ObjectType Stage
lang (optional) is the language assigned to a matching request (the
content-language header).
charset (optional) is the character set for the magnus-charset
parameter in rq->srvhdrs. If the browser sent the Accept-charset header or its User-agent is mozilla / 1.1 or newer, then appe nd “; charset=
charset is the value of the magnus-charset
where parameter in rq->srvhdrs.
bucket optional, common to all obj.conf functions
Examples
ObjectType fn=type-by-exp exp=*.test type=application/html
See Also
type-by-extension, force-type
charset” to content- type,
type-by-extension
Applicable in ObjectType-class directives. This function instructs the server to look in a table of MIME type mappings to find
the MIME type of the requested resource according to the extension of the requested resource. The MIME type is added to the back to the client.
The table of MIME type mappings is created by a file, which loads a MIME types file or list and creates th e ma ppings. For more information about
Files.” For more information about MIME types files, see Appendix B, “MIME Types.”
For example, the following two lines are part of a MIME types file:
type=text/html exts=htm,html type=text/plain exts=txt
78 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
server.xml, see Chapter 8, “Virtual Server Configuration
content-type header sent
MIME element in the server.xml

Service Stage

If the extension of the requested resource is htm or html, the type-by-extension file sets the type to
text/plain.
Parameters
bucket optional, common to all obj.conf functions
Examples
ObjectType fn=type-by-extension
See Also
type-by-exp, force-type
text/html. If the extension is .txt, the function sets the type to
Service Stage
The Service class of functions sends the response data to the client.
Service directive has the following optional parameters to determine
Every whether the function is executed. All the optional parameters must match the current request for the function to be executed.
type
• (optional) specifies a wildcard pattern of MIME types for which this function
will be executed. The
Service function to execute.
a
method
(optional) specifies a wildcard pattern of HTTP methods f or which this function will be executed. Common HTTP methods are
query
• (optional) specifies a wildcard pattern of query strings for which this function
will be executed.
magnus-internal/* MIME types are used only to select
GET, HEAD, and POST.
Chapter 3 Predefined SAFs and the Request Handling Process 79
Service Stage
UseOutputStreamSize (optional) determines the default output stream buffer size, in bytes, for data
sent to the client. If this parameter is not specified, the default is
8192 bytes.
NOTE The UseOutputStreamSize parameter can be set to zero in the
obj.conf file to disable output stream buffering. For the magnus.conf file, setting UseOutputStreamSize to zero has no
effect.
flushTimer
• (optional) determines the maximum number of milliseconds between write
operations in which buffering is enabled. If the interval between subsequent write operations is greater than the
flushTimer value for an application,
further buffering is disabled. This is necessary for status monitoring CGI applications that run continuously and generate periodic status update reports. If this parameter is not specified, the default is
ChunkedRequestBufferSize
3000 milliseconds.
(optional) determines the default buffer size, in bytes, for “un-chunking” request data. If this parameter is not specified, the default is
ChunkedRequestTimeout
• (optional) determines the default timeout, in seconds, for “un-chunking”
request data. If this parameter is not specified, the default is
If there is more than one optional wildcard parameters (
For more information about the
ChunkedRequestBufferSize, and ChunkedRequestTimeout parameters, see
“Buffered Streams,” on page 322. The
ChunkedRequestBufferSize, and ChunkedRequestTimeout parameters also have
equivalent
obj.conf parameters override the magnus.conf directives.
magnus.conf directives; see “Chunked Encoding,” on page 277. The
Service-class function, the first one matching the
type, method, and query) is executed.
UseOutputStreamSize, flushTimer,
UseOutputStreamSize,
By default, the server sends the requested file to the client by calling the function. The directive that sets the default is:
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"
80 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
8192 bytes.
60 seconds.
send-file
Service Stage
This directive usually comes last in the set of Service-class directives to give all other Service directives a chance to be invoked. This directive is invoked if the method of the request is
magnus-internal/. Note here that the pattern *~ means “does not match.” For a
GET, HEAD, or POST, and the type does not start with
list of characters that can be used in patterns, see Appendix C, “Wildcard Patterns.”
The following Service-class functions are described in detail in this section:
add-footer appends a footer specified by a filename or URL to a an HTML
• file.
add-header prepends a header specified by a filename or URL to an HTML
• file.
append-trailer appends text to the end of an HTML file.
imagemap handles server-side image maps.
index-common generates a fancy list of the files and directories in a requested
• directory.
index-simple generates a simple list of files and directories in a requested
• directory.
key-toosmall indicates to the client that the provided cer tificate key size is too
• small to accept.
list-dir lists the contents of a directory.
make-dir creates a directory.
query-handler handles the HTML ISINDEX tag.
remove-dir deletes an empty directory.
remove-file deletes a file.
rename-file renames a file.
send-cgi sets up environment variables, launches a CGI program, and sends
• the response to the client.
send-file sends a local file to the client.
send-range sends a range of bytes of a file to the client.
Chapter 3 Predefined SAFs and the Request Handling Process 81
Service Stage
send-shellcgi sets up environment variables, launches a shell CGI program, and sends the response to the client.
send-wincgi sets up environment variables, launches a WinCGI program, and
• sends the response to the client.
service-dump creates a performance report based on collected performance
• bucket data.
shtml_send parses an HTML file for server-parsed html commands.
stats-xml creates a performance report in XML format.
upload-file uploads and saves a file.
add-footer
Applicable in Service-class directives. This function appends a footer to an HTML file that is sent to the client. The footer
is specified either as a filename or a URI -- thus the footer can be dynamically generated. To specify static text as a footer, use the
Parameters
append-trailer function.
file (optional) The pathname to the file containing the
footer. Specify either file or uri. By default the pathname is relative. If the pathname is
absolute, pass the NSIntAbsFilePath parameter as
yes.
uri (optional) A URI pointing to the resource containing
the footer. Specify either file or uri.
NSIntAbsFilePath (optional) if the file parameter is specified, the
NSIntAbsFilePath parameter determines whether
the file name is absolute or relative. The default is relative. Set the value to yes to indicate an absolute file path.
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions
82 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Service Stage
ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
Service type=text/html method=GET fn=add-footer file="footers/footer1.html"
Service type=text/html method=GET fn=add-footer file="D:/netscape/server4/footers/footer1.html" NSIntAbsFilePath="yes"
See Also
append-trailer, add-header
add-header
Applicable in Service-class directives. This function prepends a header to an HTML file that is sent to the client. The
header is specified either as a filename or a URI -- thus the header can be dynamically generated.
Parameters
file (optional) The pathname to the file containing the
header. Specify either file or uri. By default the pathname is relative. If the pathname is
absolute, pass the NSIntAbsFilePath parameter as
yes.
uri (optional) A URI pointing to the resource containing
the header. Specify either file or uri.
NSIntAbsFilePath (optional) if the file parameter is specified, the
NSIntAbsFilePath parameter determines whether
the file name is absolute or relative. The default is relative. Set the value to yes to indicate an absolute file path.
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions
Chapter 3 Predefined SAFs and the Request Handling Process 83
Service Stage
UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
Service type=text/html method=GET fn=add-header file="headers/header1.html"
Service type=text/html method=GET fn=add-footer file="D:/netscape/server4/headers/header1.html" NSIntAbsFilePath="yes"
See Also
add-footer, append-trailer
append-trailer
Applicable in Service-class directives.
append-trailer function sends an HTML file and appends text to the end. It
The only appends text to HTML files. This is typically used for au thor information and copyright text. The date the file was last modified can be inserted.
Returns information after the file name in the URL, or if the file cannot be opened for read-only access.
Parameters
trailer is the text to append to HTML documents. The string
84 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
REQ_ABORTED if a required parameter is missing, if there is extra path
is unescaped with util_uri_unescape before being sent. The text can cont ain HTM L tags an d can be up to 512 characters long after unescaping and inserting the date.
If you use the string :LASTMOD:, which is replaced by the date the file was last modified; you must also specify a time format with timefmt.
Service Stage
timefmt (optional) is a time format string for :LASTMOD:. For
details about time formats refer to Appendix D, “Time
Formats.” If timefmt is not provided, :LASTMOD: will not be replaced with the time.
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
Service type=text/html method=GET fn=append-trailer trailer="<hr><img src=/logo.gif> Copyright 2001"
# Add a trailer with the date in the format: MM/DD/YY Service type=text/html method=GET fn=append-trailer timefmt="%D" trailer="<HR>File last updated on: :LASTMOD:"
See Also
add-footer, add-header
imagemap
Applicable in Service-class directives.
imagemap function responds to requests for imagemaps. Imagemaps are
The images which are divided into multiple areas that each have an associated URL. The information about which URL is associated with which area is stored in a mapping file.
Parameters
type optional, common to all Service-class functions method optional, common to all Service-class functions
Chapter 3 Predefined SAFs and the Request Handling Process 85
Service Stage
query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
Service type=magnus-internal/imagemap method=(GET|HEAD) fn=imagemap
index-common
Applicable in Service-class directives.
index-common function generates a fancy (or common) list of files in the
The requested directory. The list is sorted alphabetically. Files begin ning with a period (.) are not displayed. Each item appears as an HTML link. This function displays more information than
index-simple including the size, date last modified, and
an icon for each file. It may also include a header and/or readme file into the listing.
Init-class function Enterprise Servercindex-init in magnus.conf
The specifies the format for the index list, including where to look for the images.
obj.conf contains a call to index-common in the Service stage, magnus.conf
If must initialize fancy (or common) indexing by invoking
Servercindex-init
during the Init stage.
Indexing occurs when the requested resource is a directory that does not contain an index file or a home page, or no index file or home page has been specified by the functions
The icons displayed are
"text/*" text.gif "image/*" image.gif
86 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
find-index or home-page.
.gif files dependent on the content-type of the file:
Enterprise
Service Stage
"audio/*" sound.gif "video/*" movie.gif "application/octet-stream" binary.gif
directory menu.gif all others unkn own.gif
Parameters
header (optional) is the path (relative to the directory being
indexed) and name of a file (HTML or plain text) which is included at the beginning of the directory listing to introduce the contents of the directory. The file is first tried w ith .html added to the end. If found, it is incorporated near the top of the directory list as HTML. If the file is not found, then it is tried without the .html and incorporated as preformatted plain text (bracketed by <PRE> and).
readme (optional) is the path (relative to the directory being
indexed) and name of a file (HTML or plain text) to append to the directory listing. This file might give more information about the contents of the directory, indicate copyrights, authors, or other informa tion. The file is first tried w ith .html added to the end. If found, it is incorporated at the bottom of the directory list as HTML. If the file is not found, then it is tried without the .html and incorporated as preformatted plain text (enclosed by <PRE> and </PRE>).
type optional, common to all Service-clas s functions method optional, common to all Service-clas s functions query optional, common to all Service-clas s functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class fun c tions ChunkedRequestTimeout optional, common to all Service-clas s functions bucket optional, common to all obj.conf functions
Chapter 3 Predefined SAFs and the Request Handling Process 87
Service Stage
Examples
Service fn=index-common type=magnus-internal/directory method=(GET|HEAD) header=hdr readme=rdme.txt
See Also
Enterprise Servercindex-init, index-simple, find-index, home-page
index-simple
Applicable in Service-class directives.
index-simple function generates a simple index of the files in the requested
The directory. It scans a directory and returns an HTML page to the browser displaying a bulleted list of the files and directories in the directory. The list is sorted alphabetically. Files beginning with a period (.) are not displayed. Each item appears as an HTML link.
Indexing occurs when the requested resource is a directory that does not contain either an index file or a home page, or no index file or home page has been specified by the functions
find-index or home-page.
Parameters
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
Service type=magnus-internal/directory fn=index-simple
88 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Service Stage
See Also
Enterprise Servercindex-init, index-common
key-toosmall
Applicable in Service-class directives.
NOTE This function is provided for backward compatibility only and was
deprecated in iPlanet™ Web Server 4.x. It is replaced by the PathCheck-class SAF
key-toosmall function returns a message to the client specifying that the
The secret key size for SSL communications is too small. This function is designed to be used together with a
Client tag to limit access of certain directories to
non-exportable browsers.
Parameters
type optional, common to all Service-class functions method optional, common to all Service-class functions
ssl-check.
query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
<Object ppath=/mydocs/secret/*> Service fn=key-toosmall </Object>
Chapter 3 Predefined SAFs and the Request Handling Process 89
Service Stage
list-dir
Applicable in Service-class directives.
list-dir function returns a sequence of text lines to the client in response to a
The request whose method is INDEX. The format of the returned lines is:
name type size mimetype
The name field is the name of the file or directory. It is relative to th e directory being indexed. It is URL-encoded, that is, any character might be represented by where
xx is the hexadecimal representation of the character’s ASCII number.
%xx,
The type field is a MIME type such as
directory. A file for which the server doesn’t have a type will be of type unknown.
text/html. Directories will be of type
The size field is the size of the file, in bytes. The mtime field is the numerical representation of the date of last modification of
the file. The number is the number of seconds since the epoch (Jan 1, 1970 00:00 UTC) since the last modification of the file.
When remote file manipulation is enabled in the server, the
Service-class function that calls list-dir for requests whose method is INDEX.
a
Parameters
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
obj.conf file contains
Examples
Service fn=list-dir method="INDEX"
90 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Service Stage
make-dir
Applicable in Service-class directives.
make-dir function creates a directory when the client sends a request whose
The
method is MKDIR. The function can fail if the server can’t write to that directory. When remote file manipulation is enabled in the server, the
Service-class function that invokes make-dir when the request method is MKDIR.
a
Parameters
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
Service fn="make-dir" method="MKDIR"
obj.conf file contains
query-handler
Applicable in Service-class directives.
NOTE This function is provided for backward compatibility only and is
used mainly to support the obsolete ISINDEX tag. If possible, use an HTML form instead.
query-handler function runs a CGI program instead of referencing the path
The requested.
Chapter 3 Predefined SAFs and the Request Handling Process 91
Service Stage
Parameters
path is the full path and file name of the CGI program to
run.
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
Service query=* fn=query-handler path=/http/cgi/do-grep Service query=* fn=query-handler path=/http/cgi/proc-info
remove-dir
Applicable in Service-class directives.
remove-dir function removes a directory when the client sends an request
The whose method is
function will fail if the directory is not empty or if the server doesn’t have the privileges to remove the directory.
When remote file manipulation is enabled in the server, the
Service-class function that invokes remove-dir when the request method is
a
RMDIR.
Parameters
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions
92 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
RMDIR. The directory must be empty (have no files in it). The
obj.conf file contains
Service Stage
flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
Service fn="remove-dir" method="RMDIR"
remove-file
Applicable in Service-class directives.
remove-file function deletes a file when the client sends a request whose
The method is DELETE. It deletes the file indicated by the URL if the user is authorized and the server has the needed file system privileges.
When remote file manipulation is enabled in the server, the
Service-class function that invokes remove-file when the request method is
a
DELETE.
Parameters
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Chapter 3 Predefined SAFs and the Request Handling Process 93
obj.conf file contains
Service Stage
Examples
Service fn="remove-file" method="DELETE"
rename-file
Applicable in Service-class directives.
rename-file function renames a file when the client sends a request with a
The
New-URL header whose method is MOVE. It renames the file indicated by the URL to New-URL within the same directory if the user is authorized and the server has the
needed file system privileges. When remote file manipulation is enabled in the server, the
Service-class function that invokes rename-file when the request method is
a
MOVE.
Parameters
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
Service fn="rename-file" method="MOVE"
obj.conf file contains
94 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Service Stage
send-cgi
Applicable in Service-class directives.
send-cgi function sets up the CGI environment variables, runs a file as a CGI
The program in a new process, and sends the results to the client.
For details about the CGI environment variables and their NSAPI equivalents, refer to section “CGI to NSAPI Conversion,” on page 131.
For additional information about CGI, see the Netscape Enterprise Server
Administrator’s Guide and the Netscape Enterprise Server Programmer’s Guide. There are three ways to change the timing used to flush the CGI buffer:
Adjust the interval between flushes using the
Adjust the buffer size using the
UseOutputStreamSize parameter
flushTimer parameter
Force Enterprise Server to flush its buffer by forcing spaces into the buffer in the CGI script
For more information about
flushTimer and UseOutputStreamSize, see
“Buffered Streams,” on page 322.
Parameters
user (UNIX only) Specifies the name of the user to execute
CGI program s as .
group (UNIX only) Specifies the name of the group to
execute CGI programs as.
chroot (UNIX only) Specifies the directory to chroot to before
execution begins. This is relative to the chroot defined in magnus.conf.
dir (UNIX only) Specifies the directory to chdir to after
chroot but before execution begins.
rlimit_as (UNIX only) Specifies the maximum CGI program
address s pace in bytes. You can supply both current (soft) and maximum (hard) limits, separated by a comma. The soft limit must be listed first. If only one limit is specified, both limits are set to this value.
Chapter 3 Predefined SAFs and the Request Handling Process 95
Service Stage
rlimit_core (UNIX only) Specifies the maximum CGI program
core file size. A value of 0 disables writing cores. You can supply both current (soft) and maximum (hard) limits, separated by a comma. The soft limit must be listed first. If only one limit is specified, bo th limi ts are set to this value.
rlimit_nofile (UNIX only) Specifies the maximum number of file
descriptors for the CGI program. You can supply both current (soft) and maximum (hard) limits, separated by a comma. The soft limit must be listed first. If only one limit is specified, both limits are set to this value.
nice (UNIX only) Accepts an increment that determines the
CGI program’s priority relative to the server. Typically, the server is run with a nice value of 0 and the nice incremen t would be between 0 (the CGI program runs at same priority as server) and 19 (the CGI program runs at much lower priority than server). While it is possible to increase the priority of the CGI program above that of the server by specifying a nice increment of -1, this is not recommended.
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
The following example uses variables defined in the server.xml file for the
send-cgi parameters. For more information about defining variables, see Chapter
8, “Virtual Server Configuration Files.”
96 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Service Stage
<Object name="default"> ... NameTrans fn="pfx2dir" from="/cgi-bin" dir="/home/example.com/public_html/cgi-bin" name="cgi" ... </Object>
<Object name="cgi"> ObjectType fn="force-type" type="magnus-internal/cgi" Service fn="send-cgi" user="$user" group="$group" dir="$dir" chroot="$chroot" nice="$nice" </Object>
send-file
Applicable in Service-class directives.
send-file function sends the contents of the requested file to the client. It
The provides the
Most requests are handled by this function using the following directive (which usually comes last in the list of it acts as a default)
content-type, content-length, and last-modified headers.
Service-class directives in the default object so that
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"
This directive is invoked if the method of the request is GET, HEAD, or POST, and the type does not start with
magnus-internal/. Note here that the pattern *~ means
“does not match.” For a list of characters that can be used in patterns, see Appendix C, “Wildcard Patterns.”
Parameters
nocache (optional) prevents the server from caching responses
to static file requests. For exampl e, you can specify th at files in a particular directory are not to be cached, which is useful for directories where the files change frequently.
The value you assign to this parameter is ignored. If you do not wish to use this parameter, leave it out.
type optional, common to all Service-class functions method optional, common to all Service-class functions
Chapter 3 Predefined SAFs and the Request Handling Process 97
Service Stage
query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
Service type="*~magnus-internal/*" method="(GET|HEAD)" fn="send-file"
In the following example, the server does not cache static files from
/export/somedir/ when requested by the URL prefix /myurl.
<Object name=default> ... NameTrans fn="pfx2dir" from="/myurl" dir="/export/mydir", name="myname" ... Service method=(GET|HEAD|POST) type=*~magnus-internal/* fn=send-file ... </Object> <Object name="myname"> Service method=(GET|HEAD) type=*~magnus-internal/* fn=send-file nocache="" </Object>
98 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Service Stage
send-range
Applicable in Service-class directives. When the client requests a portion of a document, by specifying HTTP byte ranges,
send-range function returns that portion.
the
Parameters
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
Service fn=send-range
send-shellcgi
Applicable in Service-class directives.
Windows NT only.
and sends the results to the client. Shell CGI is a server configuration that lets you run CGI applications using the file associ ations set in Windows NT. For information about shell CGI programs, consult the Netscape Enterprise Server Administrator’s Guide.
Parameters
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions
The send-shellcgi function runs a file as a shell CGI program
Chapter 3 Predefined SAFs and the Request Handling Process 99
Service Stage
UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
Service fn=send-shellcgi Service type=magnus-internal/cgi fn=send-shellcgi
send-wincgi
Applicable in Service-class directives. Windows NT only. The
send-wincgi function runs a file as a Windows CGI
program and sends the results to the client. For information about Windows CGI programs, consult the Netscape Enterprise Server Admi nistrator’s Guide.
Parameters
type optional, common to all Service-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, common to all obj.conf functions
Examples
Service fn=send-wincgi Service type=magnus-internal/cgi fn=send-wincgi
100 Netscape Enterprise Server NSAPI Programmer’s Guide • November 2001
Loading...