Redhat NETSCAPE ENTERPRISE SERVER User Manual

NSAPI Programmer’s Guide

Netscape Enterprise Server

Version 6.1

April2002 (Draft)

NetscapeCommunications Corporation ("Netscape")and its licensorsretain all ownership rights to the software programsoffered by Netscape (referred to herein as "Software") a nd related documentation. Use of the Software and related documentation is governed by the license agreement for the Software and applicable copyright law.

Your rightto copy this documentation is limited by copyright law. Making unauthorized copies, adaptationsor compilationworks is prohibitedand constitutes a punishable violation of the law. Netscapemay revisethis 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.

Netscapeand the Netscape N logo are registered trademarksof Netscape Communications Corporation in theUnited States and other countries. Other Netscape logos, product names and servicenames are also trademarks of Netscape and may b e registered 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 United States and other countries. Other product and brand names are trademarks of their respective 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 N etscape software or documentation to the U.S. government is with restricted rights as described in the license agreement for that Software.

Contents

AboutThisBook ...............................................................15

WheretoFindRelatedInformation ....................................................... 17

Chapter 1 BasicsofServerOperation............................................19

ConfigurationFiles ..................................................................... 20

magnus.conf ........................................................................ 20

server.xml ..........................................................................20

obj.conf ............................................................................ 21

mime.types ......................................................................... 21

DynamicReconfiguration ............................................................... 22

HowtheServerHandlesRequestsfromClients ............................................ 22

HTTPBasics ........................................................................ 22

StepsintheRequestHandlingProcess .................................................24

DirectivesforHandlingRequests ...................................................... 25

WritingNewServerApplicationFunctions ................................................ 25

Chapter 2 SyntaxandUseofobj.conf............................................27

ServerInstructionsinobj.conf............................................................ 27

SummaryoftheDirectives............................................................ 28

The<Object>Tagandthe<Client>Tag ...................................................31

TheObjectTag ...................................................................... 31

ObjectsthatUsethenameAttribute ................................................. 32

ObjectthatUsetheppathAttribute.................................................. 32

TheClientTag ...................................................................... 33

VariablesDefinedinserver.xml .......................................................... 34

FlowofControlinobj.conf .............................................................. 35

AuthTrans.......................................................................... 35

NameTrans ......................................................................... 35

HowtheServerKnowstoProcessOtherObjects ......................................36

PathCheck.......................................................................... 37

ObjectType .........................................................................38

SettingtheTypeByFileExtension .................................................. 38

ForcingtheType..................................................................39

Service .............................................................................40

ServiceExamples .................................................................40

DefaultServiceDirective...........................................................42

AddLog . . . .........................................................................43

Error............................................................................... 43

SyntaxRulesforEditingobj.conf ......................................................... 44

OrderofDirectives .................................................................. 44

Parameters .........................................................................44

CaseSensitivity .....................................................................44

Separators ..........................................................................45

Quotes .............................................................................45

Spaces .............................................................................45

LineContinuation ................................................................... 45

PathNames.........................................................................45

Comments..........................................................................45

Aboutobj.confDirectiveExamples .......................................................46

Chapter 3 Predefined SAFs and the Request Handling Process ..................... 47

ThebucketParameter................................................................... 49

AuthTransStage .......................................................................50

basic-auth ..........................................................................51

basic-ncsa ..........................................................................53

get-sslid ............................................................................54

qos-handler.........................................................................54

NameTransStage ......................................................................55

assign-name ........................................................................56

document-root ...................................................................... 57

home-page .........................................................................58

pfx2dir .............................................................................59

redirect ............................................................................ 61

strip-params ........................................................................63

unix-home.......................................................................... 64

PathCheckStage .......................................................................65

check-acl ...........................................................................65

deny-existence ......................................................................66

find-index ..........................................................................67

find-links...........................................................................67

4 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

find-pathinfo ....................................................................... 68

get-client-cert ....................................................................... 69

load-config ......................................................................... 70

nt-uri-clean ......................................................................... 73

ntcgicheck .......................................................................... 74

require-auth ........................................................................ 74

set-virtual-index..................................................................... 75

ssl-check ........................................................................... 76

ssl-logout........................................................................... 77

unix-uri-clean....................................................................... 77

ObjectTypeStage....................................................................... 78

force-type .......................................................................... 78

set-default-type ..................................................................... 79

shtml-hacktype...................................................................... 80

type-by-exp......................................................................... 81

type-by-extension ................................................................... 82

ServiceStage ..........................................................................83

add-footer ..........................................................................86

add-header ......................................................................... 87

append-trailer....................................................................... 88

imagemap .......................................................................... 89

index-common ......................................................................90

index-simple........................................................................92

key-toosmall ........................................................................ 93

list-dir .............................................................................94

make-dir ........................................................................... 95

query-handler.......................................................................95

remove-dir ......................................................................... 96

remove-file ......................................................................... 97

rename-file ......................................................................... 98

send-cgi ............................................................................99

send-file...........................................................................101

send-range ........................................................................103

send-shellcgi.......................................................................103

send-wincgi ....................................................................... 104

service-dump ......................................................................105

shtml_send ........................................................................106

stats-xml ..........................................................................107

upload-file.........................................................................108

AddLog Stage . . . ..................................................................... 109

common-log .......................................................................109

flex-log............................................................................ 110

record-useragent ................................................................... 111

ErrorStage ...........................................................................112

send-error ......................................................................... 112

qos-error ..........................................................................113

Chapter 4 CreatingCustomSAFs ............................................. 115

TheSAFInterface .....................................................................116

SAFParameters.......................................................................116

pb(parameterblock)................................................................ 116

sn(session) ........................................................................117

rq(request) ........................................................................117

ResultCodes ......................................................................... 119

CreatingandUsingCustomSAFs .......................................................119

WritetheSourceCode ..............................................................120

CompileandLink .................................................................. 121

IncludeDirectoryandnsapi.hFile..................................................121

Libraries ........................................................................121

LinkerCommandsandOptionsforGeneratingaSharedObject ........................122

AdditionalLinkerFlags...........................................................122

CompilerFlags ..................................................................123

LoadandInitializetheSAF ..........................................................124

InstructtheServertoCalltheSAFs ...................................................124

ReconfiguretheServer .............................................................. 126

TesttheSAF .......................................................................126

OverviewofNSAPICFunctions ........................................................ 127

ParameterBlockManipulationRoutines ............................................... 127

Protocol Utilities for Service SAFs . . ..................................................128

MemoryManagement............................................................... 128

FileI/O ...........................................................................129

NetworkI/O ......................................................................129

Threads ...........................................................................129

Enterprise ServerUtilities . . . .........................................................130

VirtualServer ......................................................................131

RequiredBehaviorofSAFsforEachDirective............................................. 131

InitSAFs .......................................................................... 132

AuthTransSAFs.................................................................... 133

NameTransSAFs ...................................................................134

PathCheckSAFs.................................................................... 134

ObjectTypeSAFs ................................................................... 134

ServiceSAFs .......................................................................134

ErrorSAFs......................................................................... 135

AddLog SAFs . . .................................................................... 135

CGItoNSAPIConversion ..............................................................135

6 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Chapter 5 NSAPI Function Reference . . .........................................139

NSAPIFunctions(inAlphabeticalOrder) ................................................139

CALLOC .......................................................................... 140

cinfo_find ......................................................................... 140

condvar_init ....................................................................... 141

condvar_notify..................................................................... 142

condvar_terminate ................................................................. 142

condvar_wait ...................................................................... 143

crit_enter .......................................................................... 143

crit_exit ........................................................................... 144

crit_init ........................................................................... 144

crit_terminate ......................................................................145

daemon_atrestart ................................................................... 145

fc_open ...........................................................................146

fc_close ........................................................................... 147

filebuf_buf2sd .....................................................................147

filebuf_close .......................................................................148

filebuf_getc ........................................................................ 148

filebuf_open .......................................................................149

filebuf_open_nostat................................................................. 149

FREE ............................................................................. 150

func_exec.......................................................................... 151

func_find.......................................................................... 151

log_error .......................................................................... 152

MALLOC .........................................................................153

net_ip2host ........................................................................154

net_read...........................................................................154

net_write .......................................................................... 155

netbuf_buf2sd .....................................................................155

netbuf_close ....................................................................... 156

netbuf_getc ........................................................................ 156

netbuf_grab........................................................................ 157

netbuf_open .......................................................................157

param_create ...................................................................... 158

param_free ........................................................................158

pblock_copy ....................................................................... 159

pblock_create ...................................................................... 159

pblock_dup........................................................................160

pblock_find........................................................................160

pblock_findval .....................................................................161

pblock_free ........................................................................ 161

pblock_nninsert .................................................................... 162

pblock_nvinsert ....................................................................162

pblock_pb2env ..................................................................... 163

pblock_pblock2str ..................................................................163

pblock_pinsert .....................................................................164

pblock_remove..................................................................... 165

pblock_str2pblock ..................................................................165

PERM_CALLOC ................................................................... 166

PERM_FREE.......................................................................166

PERM_MALLOC...................................................................167

PERM_REALLOC ..................................................................168

PERM_STRDUP....................................................................168

prepare_nsapi_thread............................................................... 169

protocol_dump822.................................................................. 170

protocol_set_finfo .................................................................. 170

protocol_start_response ............................................................. 171

protocol_status..................................................................... 172

protocol_uri2url .................................................................... 173

protocol_uri2url_dynamic ........................................................... 173

REALLOC......................................................................... 174

request_get_vs ..................................................................... 175

request_header..................................................................... 175

request_stat_path...................................................................176

request_translate_uri................................................................177

session_dns........................................................................ 177

session_maxdns ....................................................................178

shexp_casecmp.....................................................................179

shexp_cmp ........................................................................179

shexp_match.......................................................................180

shexp_valid........................................................................ 181

STRDUP .......................................................................... 181

system_errmsg .....................................................................182

system_fclose ......................................................................182

system_flock.......................................................................183

system_fopenRO ................................................................... 183

system_fopenRW...................................................................184

system_fopenWA .................................................................. 184

system_fread ......................................................................185

system_fwrite ......................................................................185

system_fwrite_atomic............................................................... 186

system_gmtime ....................................................................187

system_localtime ...................................................................187

system_lseek....................................................................... 188

system_rename ....................................................................189

system_ulock ......................................................................189

8 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

system_unix2local .................................................................. 189

systhread_attach ...................................................................190

systhread_current .................................................................. 190

systhread_getdata .................................................................. 191

systhread_newkey .................................................................. 191

systhread_setdata .................................................................. 192

systhread_sleep .................................................................... 192

systhread_start.....................................................................193

systhread_timerset ................................................................. 193

util_can_exec ......................................................................194

util_chdir2path.....................................................................194

util_chdir2path.....................................................................195

util_cookie_find .................................................................... 195

util_env_find ......................................................................196

util_env_free.......................................................................196

util_env_replace....................................................................197

util_env_str........................................................................ 197

util_getline ........................................................................198

util_hostname...................................................................... 198

util_is_mozilla .....................................................................199

util_is_url ......................................................................... 199

util_itoa ...........................................................................200

util_later_than .....................................................................200

util_sh_escape .....................................................................201

util_snprintf .......................................................................201

util_sprintf ........................................................................202

util_strcasecmp ....................................................................202

util_strftime ....................................................................... 203

util_strncasecmp ...................................................................204

util_uri_escape ..................................................................... 204

util_uri_is_evil .....................................................................205

util_uri_parse ...................................................................... 205

util_uri_unescape ..................................................................206

util_vsnprintf ...................................................................... 206

util_vsprintf ....................................................................... 207

vs_alloc_slot .......................................................................208

vs_get_data........................................................................ 208

vs_get_default_httpd_object ......................................................... 209

vs_get_doc_root.................................................................... 209

vs_get_httpd_objset................................................................. 210

vs_get_id ..........................................................................210

vs_get_mime_type..................................................................211

vs_lookup_config_var............................................................... 211

vs_register_cb......................................................................212

vs_set_data ........................................................................212

vs_translate_uri ....................................................................213

Chapter 6 ExamplesofCustomSAFs .......................................... 215

ExamplesintheBuild.................................................................. 216

AuthTransExample ...................................................................217

Installing the Example . .............................................................217

SourceCode .......................................................................218

NameTransExample ..................................................................219

Installing the Example . .............................................................220

SourceCode .......................................................................221

PathCheckExample ................................................................... 223

Installing the Example . .............................................................223

SourceCode .......................................................................224

ObjectTypeExample...................................................................226

Installing the Example . .............................................................227

SourceCode .......................................................................227

ServiceExample ...................................................................... 228

Installing the Example . .............................................................229

SourceCode .......................................................................229

MoreComplexServiceExample ...................................................... 231

AddLog Example . ....................................................................232

Installing the Example . .............................................................232

SourceCode .......................................................................232

QualityofServiceExamples ............................................................ 234

Installing the Example . .............................................................234

SourceCode .......................................................................234

Chapter 7 SyntaxandUseofmagnus.conf...................................... 241

InitSAFs .............................................................................242

cindex-init ......................................................................... 243

define-perf-bucket ..................................................................245

dns-cache-init ......................................................................246

flex-init ...........................................................................246

flex-rotate-init......................................................................251

init-cgi ............................................................................253

init-clf............................................................................. 254

init-uhome ........................................................................ 255

load-modules ......................................................................255

nt-console-init......................................................................256

perf-init ...........................................................................257

10 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

pool-init...........................................................................257

stats-init...........................................................................260

thread-pool-init .................................................................... 261

ServerInformation ....................................................................262

ExtraPath.......................................................................... 262

MtaHost .......................................................................... 263

NetSiteRoot........................................................................263

ServerConfigurationFile .............................................................263

ServerID ..........................................................................263

ServerRoot ........................................................................263

ServerString ....................................................................... 264

TempDir ..........................................................................264

TempDirSecurity ................................................................... 264

User ..............................................................................265

LanguageIssues ...................................................................... 265

AdminLanguage ...................................................................266

ClientLanguage ....................................................................266

DefaultCharSet.....................................................................266

DefaultLanguage ...................................................................266

DNSLookup .........................................................................267

AsyncDNS ........................................................................267

DNS ..............................................................................267

Threads,ProcessesandConnections ..................................................... 268

Concurrency.......................................................................269

ConnQueueSize ....................................................................269

HeaderBufferSize................................................................... 270

IOTimeout......................................................................... 270

KeepAliveThreads.................................................................. 270

KeepAliveTimeout .................................................................270

KernelThreads .....................................................................271

ListenQ ........................................................................... 271

MaxKeepAliveConnections ..........................................................271

MaxProcs(UNIXOnly)..............................................................271

PostThreadsEarly................................................................... 272

RcvBufSize ........................................................................ 272

RqThrottle.........................................................................272

RqThrottleMin .....................................................................273

SndBufSize ........................................................................273

StackSize ..........................................................................273

StrictHttpHeaders ..................................................................273

TerminateTimeout.................................................................. 273

ThreadIncrement ................................................................... 274

UseNativePoll(UNIXonly) ..........................................................274

NativeThreadPools................................................................... 274

NativePoolStackSize ................................................................ 275

NativePoolMaxThreads .............................................................275

NativePoolMinThreads .............................................................275

NativePoolQueueSize ............................................................... 275

CGI .................................................................................275

CGIExpirationTimeout ..............................................................276

CGIStubIdleTimeout................................................................ 276

CGIWaitPid(UNIXOnly) ...........................................................276

MaxCGIStubs ......................................................................277

MinCGIStubs ...................................................................... 277

WincgiTimeout ....................................................................277

ErrorLoggingandStatisticCollection....................................................277

ErrorLog ..........................................................................278

ErrorLogDateFormat................................................................278

LogFlushInterval ...................................................................279

LogVerbose........................................................................279

LogVsId........................................................................... 279

PidLog ............................................................................279

StatsUpdateInterval................................................................. 280

ACL .................................................................................280

ACLCacheLifetime ................................................................. 280

ACLUserCacheSize .................................................................281

ACLGroupCacheSize ...............................................................281

Security .............................................................................. 281

CRLAgeCheck ..................................................................... 282

CRLFile ...........................................................................282

CRLUpdateCritical ................................................................. 284

Revocation ........................................................................284

Security ...........................................................................284

SSLCacheEntries ...................................................................285

SSLClientAuthDataLimit ............................................................285

SSLClientAuthTimeout.............................................................. 285

SSLSessionTimeout ................................................................. 285

SSL3SessionTimeout ................................................................286

ChunkedEncoding....................................................................286

UseOutputStreamSize............................................................... 286

ChunkedRequestBufferSize ..........................................................287

ChunkedRequestTimeout ........................................................... 287

Miscellaneous ........................................................................288

ChildRestartCallback ............................................................... 288

HTTPVersion ......................................................................288

12 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

MaxRqHeaders .................................................................... 288

Umask(UNIXonly)................................................................. 289

Chapter 8 VirtualServerConfigurationFiles .....................................291

Theserver.dtdFile .................................................................... 291

Theserver.xmlFile .................................................................... 292

Variables ..........................................................................294

FormatofaVariable .............................................................295

TheidVariable ..................................................................295

VariablesUsedintheInterface..................................................... 295

VariableEvaluation .............................................................. 296

UsingtheServerManagerandClassManager..........................................296

Elementsinserver.dtdandserver.xml ................................................... 297

SERVER........................................................................... 297

VARS .............................................................................297

LS(ListenSocket)................................................................... 298

CONNECTIONGROUP .............................................................299

SSLPARAMS ......................................................................300

MIME.............................................................................301

ACLFILE ..........................................................................303

VSCLASS..........................................................................303

VS(VirtualServer)..................................................................304

QOSPARAMS .....................................................................305

USERDB .......................................................................... 306

VirtualServerSelectionforRequestProcessing ........................................... 306

UserDatabaseSelection................................................................307

TheNetscapeLDAPSchema............................................................308

TheConvergenceTree .............................................................. 308

TheDomainComponent(dc)Tree ....................................................309

Appendix A DataStructureReference...........................................311

PrivatizationofSomeDataStructures.................................................... 312

session............................................................................... 312

pblock ............................................................................... 313

pb_entry ............................................................................. 313

pb_param ............................................................................314

Session->client........................................................................ 314

request .............................................................................. 314

stat..................................................................................315

shmem_s.............................................................................316

cinfo.................................................................................316

Appendix B MIMETypes ..................................................... 319

Introduction..........................................................................319

DeterminingtheMIMEType ........................................................... 320

HowtheTypeAffectstheResponse ..................................................... 320

WhatDoestheClientDowiththeMIMEType? ...........................................321

SyntaxoftheMIMETypesFile.......................................................... 322

SampleMIMETypesFile............................................................... 322

Appendix C WildcardPatterns ................................................ 325

WildcardPatterns .....................................................................325

WildcardExamples....................................................................326

Appendix D TimeFormats ................................................... 327

Appendix E HyperTextTransferProtocol ....................................... 329

Compliance ..........................................................................329

Requests .............................................................................330

RequestMethod,URI,andProtocolVersion............................................330

RequestHeaders ...................................................................330

RequestData.......................................................................331

Responses............................................................................ 331

HTTPProtocolVersion,StatusCode,andReasonPhrase ................................ 331

ResponseHeaders ..................................................................333

ResponseData ..................................................................... 333

BufferedStreams ......................................................................334

Appendix F Dynamic Results Caching Functions ................................ 337

dr_cache_destroy................................................................... 338

dr_cache_init ......................................................................339

dr_cache_refresh ................................................................... 339

dr_net_write ....................................................................... 340

fc_net_write ....................................................................... 342

Appendix G Alphabetical List of Directives in magnus.conf . . ...................... 345

Appendix H AlphabeticalListofPre-definedSAFs ............................... 351

Index ....................................................................... 357

14 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

About This Book

This book discusses how to use the Netscape® Server Application P rogrammer's Interface (NSAPI) to build plugins that define Server Application Functions (SAFs) to extend and modi fy Netscape Enterprise Server. The bo ok also discusses the purpose and use of the configuration files and

mime.types, and provides comprehensive lists of the directives and functions

that c a n be used in these configuration files. It also provides a reference of the NSAPI functions you can use to define new plug ins.

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 a n d to process client requests.

obj.conf, magnus.conf,server.xml,

• Chapter 2, “Syn tax 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 thatdefine new SAFs to

modify or extend the way the server handles requests.

• Chapter 5, “NSAPI Function Reference”

obj.conf.Thechapter

This chapter presents a reference of the functions in the Netscape Server Application Programming Interface (API). You use N SAPI functions to define SAFs.

• Chapter 6, “Examples of Custom SAFs” This chapter discusses examples of custom SAFs to use at each stage in the

request handling process.

• Chapter 7, “Syntax and Use of magnus.conf” This appendix discusses the variables you can s et in the configuration fil e

magnus.conf to config ure the during initialization.

• Chapter 8, “Vir tual Server Configuration Files” This appendix discusses the variables you can s et in the configuration fil e

server.xml to configure virtual servers in .

• Appendix A, “Data Structure Reference” This appendix d iscusses 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 Pat terns” This appendix lists the wildcard patterns you can use when specifying values

obj.conf, various predefined SAFs, and in some NSAPI functions.

• Appendix D, “Time Formats” This appendix lists time formats.

• Appendix E, “HyperText T ransfer Protocol” This appendix gives an overview of HTTP.

• Appendix F, “Dynamic Results Caching Functions” This appendix ex plains how to create a results caching plugin.

• Appendix G, “A lphabetical List of NSAPI Functions and Macros” Appendix G, “ Alphabetical List of Directives in magnus.conf” Appendix H, “ Alphabetical List of Pre-defined SAFs”

These appendices provide alphabetical lists for easy lookup of NSAPI functions, predefined SAFs, and variables in

16 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

magnus.conf.

NOTE Throughout this manual, all descriptions specific to UNIX®

descriptions apply to the Linux® operating system as well, ex cept where Linux is specifically mentioned.

Where to Find Related Information

AdditionalEnterpriseServer documentationincludes:

• Netscape Enterprise Server Installation and Migration Guide

• Netscape Enterprise Server Performance Tuning, Sizing, and Scaling Guide

• Netscape Enterpri se Server Administrator’s Guide

• Netscape Enterprise Server Programmer’s Guide

• Netscape Enterprise Server Programmer’s Guide to Servlets

• Netscape Enterprise Server Release Notes You can find Enterprise Server documentation online in PDF and HTML formats

at:

Where to Find Related Information

http://enterprise.netscape.com/docs

About This Book 17

Where to Find Related Information

18 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Chapter 1

Basics of Server Operation

The configuration and behavior of Netscape Enterprise Server is determined by a set of configurationfiles. You can change the settings in these configurationfiles either by using the Server Manager interface or by manu ally 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 fo r handling requests. The chapter closes by introducing the use of Netscape Server Applicat ion Programming Interface (NSAPI) to define new functions to modify the request-handling process.

obj.conf. You can modify and extend the request

obj.conf.Youcanuse

obj.conf.

This chapter has the following sect ions:

• Configuration Files

• Dynamic Reconfiguration

• How the S er ver Handles Requests from Clients

• Writing New Server Application Functions

Configuration Files

The configuration and operation of the is controlled by configuration files. The configuration file s reside in the directory directory contains various configuration files for controlling different components, such as configuring NetShare. The exact number and names of c onfiguration files d epends on which c o mponents have been enabled or loaded in to 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 initialization information. server.xml – contains initialization information for virtual servers and listen

sockets.

obj.conf – contains instructio ns f or 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 serverlooksatthisfileandexecutesthesettingsonstartup.Theserverdoesnot 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 classe s and virtual servers to the se listen sockets. A master file,

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.

20 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

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 serv er looks at the configuration defined by this file every time it processes a request from a client.

There is one servers. Wh enever this guide refers to “the

obj.conf file for each virtual server class, or grouping of virtual

obj.conf file,” it refers to all obj.conf

filesortotheobj.conf file for the virtual server class being described. All the

They are typically named vsclass

obj.conf files are located in the server_root/server_id/config directory.

.obj.conf,wherevsclass is the virtual server class

name. The

obj.conf file is essential to the operation of the . When you make changes to

the server through the Server Manager interface, the system automatically updates

obj.conf.

The file

obj.conf cont ains 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 Server 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 C hapter 2, “Syntax

and Use of obj.conf.”

mime.types

This file maps file ex tensions to MIME types to enab le 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 21

Dynamic Reconfiguration

You do not have to restart the server for changes to obj.conf, mime.types,

server.xml, and virtua l-server-specific ACL files to take effect. All you need to do

is apply the changes b y c licking 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 you edit into memory that contains all the information from the dynamically configurable files.

Every new connection r eferences the newest configuration. Once the last ses sion referencing a configurationends, the now unused old configuration i s 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 NetscapeCommunicator communicate using several protocols including HTTP, FTP, and gopher. The handles HTTP specifically.

For more information abo ut the HTTP protocol refer to Appendix E, “HyperText Transfer Protocol” and also the latest HT TP specification.

HTTP Basics

As a quick summary, the HTTP/1.1 protocol works as follows:

• theclient (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 m a y provide various information about the request or the client Body data. Headers are typically only sentforPOSTandPUTmethods.

22 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Connection: Close header.

GET or POST,aUniversal

How the Server Handles Requests from Clients

The example request shown below would be sent b y a Netscape browser to request the server

foo.com to send back the resource in /index.html.Inthisexample,no

bodydata is sent becausethe method is GET (thep oint of the request isto 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 pro cess many requests simultaneo usly. Each request is broken down into a series of steps that together make up the request handling process.

The server gen erates a response which includes the HTTP proto col 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 t he body data contains the requeste d i tem. Other result codes indicate redirection to another server or the browser’scache, or various types of HTTP errors such as “404 Not Found.”

Chapter 1 Basics of Server Operation 23

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 h ow the virtual server is determined, see “Virtual Server Selection for Request Processing,” on page 306.

After t he virtual server is selected, t he

obj.conf file for the virtual server class

specifies how the re qu est 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 local 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 t he previous steps. If an error occurs, the server logs an error message and aborts the pr ocess.

24 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Writing New Server Application Functions

Directives for Handling Requests

The file obj.conf containsa 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) wit h one or more arguments. Eac h directive applies to a specific s tag e in the request handling process. The stages are

AuthTrans, NameTrans, PathCheck, ObjectType, Service,andAddLog.

For example, the following directive applie s during the the

document-root function with the root argument set to D:/Netscape/Servers/docs. (The document-rootfunction translates the http://server_name/ partof the URL to the document root, which in this example

D:/Netscape/Servers/docs.)

NameTrans fn="document-root" root="D:/Netscape/Servers/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 t he 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 r equested and what kind of client requested it) and any other server variables created or modified by SAFs called by previously invoked directives. Each S A F 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 yourown SAFs, see Chapter 4, “Creating Custom

SAFs.”

obj.conf, see Chapter 2,“Syntax and Use of obj.conf.”

Chapter 1 Basics of Server Operation 25

Writing New Server Application Functions

26 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Chapter 2

Syntax and Use of obj.conf

The obj.conf configuration file contains direct ives that instruct the N etscape Enterprise Server how to handle requests from clients. This ch apter discusses server instructions in flow of control in about example directives.

The sections in this chapter are:

• ServerInstructions in obj.conf

• The <Object> Tag and the <Client> Tag

obj.conf;theuseofObject tags;theuseofvariables;the

obj.conf; the syntax rules for editing obj.conf;andanote

• Variables Defin ed in server.xml

• Flow of Control in obj.conf

• Syntax Rules for Editing obj.c onf

• About obj.conf Directive Examples

Server Instructions in obj.conf

The obj.conf file contai ns directives that instruct the server how to handle requests received from clients such as browser. These directives appear inside

OBJECT tags.

Each directive call s 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"

Server Instructions in obj.conf

For example:

NameTrans fn="document-root" root="D:/Netscape/Servers/docs" Directive indicates when this instruction is executed during the request handling

process. The value is one of

Service, Error,andAddLog.

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 App lication 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 t o 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,asdiscussed

in Chapter 3, “Predefined SAFs and the Request Ha ndling Process.” You can also define new SAFs, as discussed in Chapter 4, “C reating Custom SAFs.”

The

magnus.conf file contains Init directive SAFs that initialize the server. For

more information, see Chapter 7, “Syntax and Use of magnus.conf.”

Summary of the D irectives

Here are the categories of server directives and a description of what each does. Each category correspondsto a stage in the request handling process. The section “Flow of Control in obj.conf,” on page 35 exp lains exactly how the server decides which directive o r directives to execute in at each s t age.

•

AuthTrans

Verifies any authorization information (normally sent in the Authorization 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’saccess 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, toverify authorization information sent by the client. The

Authorization header is sent as part of the basic server authorization scheme.

28 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Server Instructions in obj.conf

• NameTrans

Translates the URL specified in the request from a logical URL to a physical file system path fo r the requested resource. This may also result in redirection to anothersite.Forexample:

NameTrans fn="document-root" root="D:/Netscape/Servers/docs"

This example calls the document-root function with a root argument of

D:/Netscape/Servers/docs. The functio n document-root function translates

the

http://server_name/ part of the requested to URL to the document root,

whichinthiscaseis

http://server-name/doc1.html is translated to D:/Netscape/Servers/docs/doc1.html.

•

PathCheck

D:/Netscape/Servers/docs.Thusarequestfor

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 exam ple:

PathCheck fn="find-index" index-names="index.html,home.html"

This example calls the find-index functionwith 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 (Mu lti-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 hea ders

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 m ay be:

❍ Acommon 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 29

Server Instructions in obj.conf

• Service Generates and sends the responseto 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,orPOST,andwhosetype 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,andthetypeof the requested resource is

imagemap is called.

•

AddLog

"magnus-internal/imagemap",thefunction

Adds an entry to a log file to record information about the transaction. For example:

AddLog fn="flex-log" name="access"

This ex ample calls the flex-log function to log information about the current request in the log file named

•

Error

access.

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/servers/errors/unauthorized.html"

In this ex amp le, the server sends the file in

D:/netscape/servers/errors/unauthorized.html whenever a client

requests a resource that it is not authorized to access.

30 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

The <Object> Tag and the <Client> Tag

This section discusses the use of <Object> and <Client> tags in the file obj.conf.

<Object> tags group together directives that apply to requests for particular

resources, while received from particular clients.

•TheObjectTag

•TheClientTag

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

may be a wildcard pattern. For example:

<Client> tags group together directives t hat apply to requests

The server always starts handling a request by processing the directives in the default object. However, the server switches to processing d irectives in another object after the conditions is true:

• The successful

• the physical pathname that results from the

ppath attribute of another object

When the s erver has been alerted to use an object other than the default object, it processes the di rectives 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 35.

NameTrans stageofthedefaultobjectifeitherofthefollowing

NameTrans direc tive specifies a name argument

NameTrans stage m atches the

Service stage)as soon as one is successfully

Chapter 2 Syntax and Use of obj.conf 31

The <Object> Tag and the <Client> Tag

Objects that Use the name Attribute

If a NameTrans directive in the default object specifies a name argument, the server switches to pro cessing the directives in the object of that name before processing the remaining directives in the default o bject.

For example, the following name

cgi to any request whose URL starts with http://server_name/cgi/.

<Object name="default"> NameTrans fn="pfx2dir" from="/cgi" dir="D:/netscape/servers/docs/mycgi" name="cgi" ... </Object>

NameTrans directive in the default object assigns the

When that NameTrans directive is executed, the server starts processing directives in the object named

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 pathname. If this physical pathname matches the the server sw itches to processing the directives in that object before processing the remaining ones in the default object.

ppath attribute of another object in obj.conf,

For example, the following

http://server_name/ part of the requested URL to D:/Netscape/Servers/docs/

NameTrans directive translates the

(which is the d ocument root directory).

<Object name="default"> NameTrans fn="document-root" root="D:/Netscape/Servers/docs" ... </Object>

32 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

The <Object> Tag and the <Client> Tag

The URL http://server_name/internalplan1.html would be translated to

D:/Netscape/Servers/docs/internalplan1.html. However, suppose that obj.conf contains the following additional object:

more directives...

</Object>

In this case, the partial path

D:/Netscape/Servers/docs/internalplan1.html. So now the server starts

*internal* matches the path

processing the directives in this object befo re processing the remaining directives in the default object.

The Client Tag

The <Client> tag can be used within an object to limit the execution of a set of directives to requests received from specific clients. Directives listed between a pair of

<Client> </Client> tags are executed only if information in the client request

matches the parameter value specified by the A

<Client> tag accepts the parameters ip, dns,orhost. Use one and only one of

these parameters to specify the client information to match.

Table 2-1 <Client>Tag Parameters

Parameter Description

ip The IP address of the client. dns The DNS name of the clie nt. urlhost

The DNS name of the virtual server requested by the client. This value is provided in the client request. This is how virtual servers were defined in earlier versions of Enterprise Server. See the Netscape Enterprise Server Ad ministrator’s Guide for information on how Netscape recommends implementing virtual servers in Enterprise S erver 6.1.

<Client> tag.

Host header of the

Youcanusewildcardstospecify<Client> tag parameter values. For ex ample:

Chapter 2 Syntax and Use of obj.conf 33

Variables Defined in server.xml

See “Wildcard Patterns,” on page 325 for more information on wildcards. You can also use wildcards to specify a “negative” match, one that excludes clients

that match the parameter value specified in the following combination of the

<Client> tag and the AddLog directive tells

Enterprise Server to log access requests from all clients except those that come from the specified subne t.

<Client ip="~192.95.251.*"> AddLog fn="flex-log" name="access" </Client>

Using the ~ wildcard to specify the valu e o f the ip parameter negates the expression, so Enterprise Server will exclude clients from the from the access log.

Variables Defined in server.xml

You can define variables in the server.xmlfile and reference them i n an obj.conf file. For example, the following server.xml code defines and uses a variable called

docroot:

<Client> tag. For example, the

192.95.251. subnet

<!DOCTYPE SERVER SYSTEM "server.dtd" [ <!ATTLIST VARS

docroot CDATA #IMPLIED

> ]> ...

<VS id="a.com" connections="maingroup" urlhosts="a.com"

mime="mime1" aclids="std">

</VS>

...

You can reference the variable in obj.conf as follows:

NameTrans fn=document-root root="$docroot"

Using this docroot variable saves you from h aving 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.

34 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Flow of Control in obj.conf

NOTE Variable substitution is allowed only in an

allowed in any other Enterprise Server configuration files. Any variable referenced in an

server.xml file at the SERVER, VSCLASS,orVS level. Defining

variables with default values at the overriding t hem in the

Formoreinformation,seeChapter8,“VirtualServerConfigurationFiles.”

Flow of Control in obj.conf

Before the server can process a request, it must direct the request to the correct virtual s erver. For details about how t he virtual server is determined, see “Virtual Server Selection for Request Processing,” on page 306.

After t he virtual server is determined, the server executes the virtual server class to which the virtual server belongs. This section discusses how the server d ecides which directives to execute in

AuthTrans

obj.conf file. It is not

obj.conf file m ust 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 m ore 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 ser ver’s file system. The server looks at each untilitfindsonethatcanbeapplied.

If there is more than one considers each directive until one succeeds.

NameTrans directivein the default object, the server

NameTrans directiveinthedefaultobjectinturn,

Chapter 2 Syntax and Use of obj.conf 35

Flow of Control in obj.conf

The NameTrans section in the default object must contain exactly one directive that invokes the

http://server_name/par t of the requested URL to a physical directory that has

been designated as the server’s document root. For example:

NameTrans fn="document-root" root="D:/Netscape/Servers/docs"

The directive that invokes document-root must be the last directive in the

NameTrans sectionsothatitisexecutedifnootherNameTrans directive is

applicable. The

between URLs and d irectories. For example, the fo llowing directive translates the URL

D:/netscape/servers/docs/mycgi/: NameTrans fn="pfx2dir" from="/cgi"

dir="D:/netscape/servers/docs/mycgi"

Notice that if this directive appeared after the one tha t ca lls document-root,it would never be ex ecuted, with the result that the resultant directory pathname would be directive that invokes section.

document-root function. This functions translates the

pfx2dir (prefix to directory) function is used to s et up additional mappings

http://server_name/cgi/ into the directory pathname

D:/netscape/servers/docs/cgi/ (not mycgi). This illustrates why the

document-root must be the last one in the NameTrans

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 argument, the server starts processing directives i n the named object (defined with the

OBJECT tag) before processing directives in the default object for the rest of the

request handling process. For example, the following

name

cgi to any request whose URL starts with http://server_name/cgi/.

<Object name="default"> ... NameTrans fn="pfx2dir" from="/cgi" dir="D:/netscape/servers/docs/mycgi" name="cgi" ... </Object>

36 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

NameTrans directive assigns a name by specifying a name

NameTrans directive in the default object assigns the

NameTrans directive that was

Flow of Control in obj.conf

When that NameTrans directive is executed, the server starts processing directives in the object named

more directives...

</Object>

cgi:

When a

NameTrans directive has been successfully executed, there will be a

physical pathname associated with the requestedresource. If the resultant pathname matches the

ppath (partial path) attribute of another object, the server

starts proc essing directives in the o t her object before processing directives in the defaultobjectfortherestoftherequesthandlingprocess.

For example, suppose

more directives...

</Object>

Now suppose the successful the pathname

D:/Netscape/Servers/docs/internalplan1.html.Inthiscase,

the partial path

D:/Netscape/Servers/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 i n the default object.

PathCheck

After converting the logical URL of the requested resource to a physical pathname in the

NameTrans step, the server executes PathCheck directives to verify that the

client is allowed to access the requested r esource. Ifthereismorethanone

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.

Chapter 2 Syntax and Use of obj.conf 37

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

default object.

ObjectType

Assuming that the PathCheck directives all approve access, the server next executes the MIME type has three at tributes: type, encoding, and language. When the server sends the response to the client, the type, language, and encoding v alues are transmittedin the headers of the response. The serverto determine which the client.

name or ppath attribute of another object, the server fir s t applies the

ObjectType directives to determine the MIME type of the request. The

type also freq ue ntly helps the

Service directive to execute to generate the response to

If there is more than one

ObjectType directive, the server applies all the d ire ctives

in the order in which they appear. However, once a directivesets an attribute of the MIME type, further attempts to set the same attribute are ignored. The reason that all

ObjectType directives are applied is that one directive may set one attribute, for

example As with the

as a result of the the matching o bject before executing the

type, while another directive sets a different attribute, such as language.

PathCheck directives, if another o bject has been matched tothe request

NameTrans step, the server executes the ObjectType directivesin

ObjectType dire ctives 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 extensions usually:

type=text/html exts=htm,html

which says that all file s that have the extension .htm or .html are text files formatted as HTML and the

mime.types).

.html and.htmis

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.

38 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

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

type-by-expression has been executed. Usually if t he server does not

recognize the file extension, it is a g ood idea to force the type to be that t he content of the resource is treated as plain text. There are also other situations w here you might want to set the t ype regardless of the file extension, such as forcing all resour ces in the designated CGI dire ctory to have the MIME type

magnus-internal/cgi.

MIME types table, the type still has no value even

text/plain,so

The function thatforces the type is

force-type.

For example, the following directives first instruct the server to look in the MIME types table for the MIME typ e, then if the the file ex tension 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 translatedinto r equests for resources in the

directory request, the server processes processing the ones in the default object. This o b j ect has one which forces the

D:/netscape/servers/docs/mycgi/. Since a name i s assigned to the

ObjectType directives in the object named cgi before

ObjectType directive,

type to be magnus-internal/cgi.

Chapter 2 Syntax and Use of obj.conf 39

Flow of Control in obj.conf

The server continuesprocessing all ObjectType directives including those in the default object, but since the 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.

NameTrans fn="pfx2dir" from="/cgi" dir="D:/netscape/servers/docs/mycgi" name="cgi" <Object name="cgi"> ObjectType fn="force-type" type="magnus-internal/cgi" Service fn="send-cgi" </Object>

type attribute has already been set, no other directive

Service d irective in turn, to find the

Service directive

If there is more than one

Service directive, the server applies the first one that

matches the conditions of the request, and ignores all remaining directives.

As with the

PathCheck and ObjectType directives, if another object has been

matchedtotherequestasaresultofthe

Service directives in the matching object before considering the ones in the default

object. If the server successfully executes a object,itwillnotgetroundtoexecutingthe object, since it only executes one

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.

• Thefollowing

D:/netscape/servers/docs/jos.html:

NameTrans fn="document-root" root="D:/Netscape/Servers/docs"

NameTrans directive translates the requested URL to

•AssumethatthePathCheck directives all succeed.

40 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

D:/server_name/jos.html.Inthiscase,all

Service

NameTrans step, the server considers the

Service directive in the matching

Service directives in the default

Flow of Control in obj.conf

• Thefollowing ObjectType directivetellstheservertolookuptheresource’s MIME type in the MIME types table:

ObjectType fn="type-by-extension"

• The server finds the following entry in the MIME types table, which sets t he type attribute to

type=text/html exts=htm,html

text/html:

• The server invokes t he following Service directive. The value of the type parameter matches anything that does not begin with magnus-internal/.(For a list o f 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 assumes

that servlets have been activated and the directory

D://netscape/servers/docs/servlet/ has been registered as a s ervlet

directory (that is, the server treats all filesin that directory as servlets).

• Thefollowing

D:netscape/Servers/docs/servlet/doCalculation.class.Thisdirective

also assigns the name

NameTrans fn="pfx2dir" from="/servlet" dir="D:/Netscape/Servers/docs/servlet" name="ServletByExt"

•Asaresultofthe directives i n the object named

<Object name="ServletByExt"> ObjectType fn="force-type" type="magnus-internal/servlet" Service type="magnus-internal/servlet" fn="NSServletService" </Object>

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:

Chapter 2 Syntax and Use of obj.conf 41

Flow of Control in obj.conf

•TheServletByExt object has no PathCheck directives, so the server processes the

PathCheck directives in the default object. Let’s assume that all PathCheck

directives succeed .

• Next, the server processes the the

ServletByExt object. This directive sets the type attribute to

magnus-internal/servlet. ObjectType fn="force-type" type="magnus-internal/servlet"

ObjectType directives, starting with the one in

The server continuesprocessing all the ObjectTypedirectives in the default object, but since the

•Whenprocessing

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

•Thetype argument of this directive matches the type valuethatwassetbythe

ObjectType directive. So the server goes ahead and executes this Service

directive which calls the NSServletService functio n. This function invokes the requested file as a servlet and sends t he 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 d efault 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 other

Service directive matches a request sent by a browser. This default d ir ective

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 d irectives have succeeded. The default

Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"

42 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Flow of Control in obj.conf

This directive matches requests whose method is GET, HEAD,orPOST, which covers nearly virtually all requests sent by browsers. The value of the

type argument uses

special pattern-matching characters. For complete in formation about the special pattern-matching characters, see Appendix C, “W ildcard Patterns.”

The characters “ so the expression

magnus-internal/.” An asterisk by itse lf matches anything, so the who le

expression

magnus-internal/.

So if the server has not already executed a directive, it executes the directive so long as t he request method is

POST,andthevalueofthetype 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 thatdoes n ot 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 execute s AddLog directives to add entries to the log files.

All

AddLog directives are executed. The server can add entries to multiple log files.

Depending on which log files are us ed and which format they use, the in

magnus.conf may need to have directives that initialize the logs. For example, if

one of the the

AddLog directives ca lls flex-log, whi ch uses the extended log format,

Init sectio n must contain a directive that invokes flex-init to initialize the

flexible logging syste m.

Init section

For more information about initializing 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 a c cess to the requested resource, or the requested

resource does not exist, then the server immediately stops executing all other directives and immediately starts executing t he

Error directives.

Chapter 2 Syntax and Use of obj.conf 43

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 op erate incorrectly.

Order of Directives

The order o f directives is important, since the server executes them in the order they appear in other directives.

For

PathCheck directives, the order within the PathCheck section is not so

important, s ince the server executes all

ObjectType section the order is very important, because if an ObjectType

directive sets an attribute value, no other ObjectType directive can change that value. For example, if the default following order (which is the wrong way round), every request w o uld have its

type value set to text/plain, and the server woul d nev e r 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 dire ctives were listed in the

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.

44 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Syntax Rules for Editing obj.conf

Separators

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

Quotes

Quotes (") are only req u ired around value strings when there is a space in the string. Otherwise they are optional. Each open-quote must be m a tched 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 beg inning the next line with a space or tab.

Path Names

Always use forwardslashes (/) rather than bac k- slashes (\)inpathnamesunder Windows NT/Windows 2000. 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 i t updates

Chapter 2 Syntax and Use of obj.conf 45

obj.conf.

About obj.confDirective Examples

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 n ot in the actual file. In some cases this is due to line length limitations imposed by the PDF and HTML formats of the manuals.

For example, the following directive is all on one line in the actual

NameTrans fn="pfx2dir" from="/cgi" dir="D:/netscape/servers/docs/mycgi" name="cgi"

obj.conf file:

46 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

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,seetheprevious

For a list of magnus.conf.”

This chapter includes functions that are part of the core functionality of N etscape Enterprise Server. It do es not include functions that are available only if additional components, such a s servlets and server-parsed HTML, ar e enabled.

This chapter co ntains a section for ea ch directive which lists al l 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 G , “Alphabetical List of

Directives in magnus.conf.”

Init (initialization) SAFs, see Chapter 7, “Syntax and U se of

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

48 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

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 per formance buckets are predefined in Enterprise Server:

•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 o r 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 49

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 buc kets 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 authorization b efore allowing a client to access resources. Generally, an with the req uest are acceptable, but it do es 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 Direct ive - validates authoriz ation 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 Serv ice function.

stats-xml Service function to generate

PathCheck function.

The authorization process is split into two steps so that multiple authorization schemes can be eas ily incorporated, as well as providing the flexibility t o 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. W hen a client initially makes a request, t he username and password are unknown so the

AuthTrans functions and PathCheck functionswork

together to reject the request, since they can’t validate the username 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 appr opriate realm, and then the client submits the request again, this time includ ing the username and password in the headers.

If there is more than one

AuthTrans directivein obj.conf,eachfunctionis

executed in order until one succeeds in authorizing the user.

50 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

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 passwo rd.

Optionally determines the user’s group.

•

basic-ncsa verifies user name and password against an NCSA-style or

system DB M database. Optionally determines 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 t he current quality of service statistics.

ssl-id variable in the Session->client parameter block.

basic-auth

Applicable in AuthTrans-class directives. The

basic-auth function calls a custom function to verify aut horization

information sent by the client . The Authorization header is sent as part of the basic server aut horization scheme.

This function is usually used in conjunction 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 f or user verification.This parameter will 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 same interfaceas all the SAFs, but it is called w ith the user name (user), password (pw),user database(userdb), and groupdatabase (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/Windows 2000 only) to the rq->vars pblock.

Chapter 3 Predefined SAFs and the Request Handling Process 51

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 g r oup custom function that

must ha ve 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)inthepb parameter.It also hasaccess to the auth-type, auth-user (user), auth-db (userdb), and auth-password(pw, Windows NT/Windows 2000 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_NOACTIONif 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:

AuthTrans fn=basic-auth auth-type=basic userfn=hardcoded_auth PathCheck fn=require-auth auth-type=basic realm="Marketing Plans"

See Also

require-auth

52 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

AuthTrans Stage

basic-ncsa

Applicable in AuthTrans-class directives. The

basic-ncsa function verifies authorization information sent by the client

against a database. The Authorization header is sent as part of the basic server authorization scheme.

This function is usually used in conjunction 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 instantaneous 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’tuse

dbm.

name:password,where

grpfile (optional) specifies the NCSA-style HTTPD group file to be

used. Each lin e of a g r oup file consists of

... userN

bucket optional, common to all obj.conf functions

Examples

AuthTrans fn=basic-ncsa auth-type=basic dbm=/netscape/servers/userdb/rs

PathCheck fn=require-auth auth-type=basic realm="Marketing Plans" AuthTrans fn=basic-ncsa auth-type=basic

userfile=/netscape/servers/.htpasswd grpfile=/netscape/servers/.grpfile

PathCheck fn=require-auth auth-type=basic realm="Marketing Plans"

where eac h user is separated by spaces.

Chapter 3 Predefined SAFs and the Request Handling Process 53

group:user1 user2

AuthTrans Stage

See Also

require-auth

get-sslid

Applicable in AuthTrans-class directives.

NOTE This function is provided for backward compatibility only. The

functionality of processing of an SSL connection.

get-sslid function retrievesa stringthat is unique to the current SSL session,

The andstoresitasthe

ssl-id variable in the Session->client parameter block.

get-sslid has been incorporated into the standard

If the variable the

HTTPS_SESSIONID environment variable.

The

get-sslid functionhasnoparametersandalwaysreturnsREQ_NOACTION.It

ssl-id is present when a CGI is invoked, it is passed to the CGI as

hasnoeffectifSSLisnotenabled.

Parameters

bucket optional, common to all obj.conf functions

qos-handler

Applicable in AuthTrans-class directives. The

qos-handler function examines the current quality of service statistics for 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 functionconfigured in thedefault object in order to work properly.

ThecodeforthisSAFisoneoftheexamplesinChapter6,“ExamplesofCustom SAFs.”

For more information,see the Netscape Enterpris e Server Performance Tuning, Sizing, and Scaling Guide.

Parameters

bucket optional, common to all obj.conf functions

54 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

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/servers/docs/some/file.html

NameTrans Stage

NameTrans NameTrans directiveinanobject,theserverexecuteseachoneinorderuntilone

directives should appear in the default object. If there is more than one

succeeds. The following NameTrans-class 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 t r anslates any URL beginning with a g iven prefix to a file system

directory and optionally enables directives in an additiona l named object.

•

redirect redirects the client to a different URL.

• strip-params rem oves embedded semicolon-delimited parameters from t he path.

•

unix-home translates a URL to a specified directory w ithin a user’s home

directory.

Chapter 3 Predefined SAFs and the Request Handling Process 55

NameTrans Stage

assign-name

Applicable in NameTrans-class directives. The

assign-name function specifies the name of an object in obj.conf that

matches the current request. The server then processes the directives in the named object in p reference to the ones in the default object.

For example, consider the following directive in the de fault object:

NameTrans fn=assign-name name=personnel from=/personnel

Let’s s uppo se 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.

The

assign-name function always returns REQ_NOACTION.

Parameters

from is a wildcard p attern that specifies the path to b e 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 use this pa rameter, leave it out.

The find-pathinfo-forward parameter is ignored if the ntrans-base parameter is not set in rq->vars.By default, ntrans-base is set.

This feature can improve performance for certain URLs by reducing the number of stats performed.

56 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

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 avoiding unnecessary 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-pathand /virtual-path/* if ntrans-ba se is not

set.

bucket optional, common to all obj.conf functions

Example

# 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"

virtual-path" in the NameTrans

virtual-pathwill fail. Therefore, use

virtual-path does not

document-root

Applicable in NameTrans-class directives. The

document-root function specifies the root documentdirectory for the server.

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 t he

document root.

Chapter 3 Predefined SAFs and the Request Handling Process 57

NameTrans function, the

NameTrans Stage

When the server receives a request for http://server-name/somepath/somefile, the

document-root function replaces http://server-name/ with the value of its root parameter.For example, if the document root directoryis /usr/netscape/servers/docs, thenwhen the serverreceives a request for http://server-name/a/b/file.html,thedocument-root function translates the

pathname to

/usr/netscape/servers/docs/a/b/file.html for the requested

resource. This function always returns

will never be called, so be sure that the dire ctive that invokes last

NameTrans directive.

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/servers/docs NameTrans fn=document-root root=$docroot

See Also

init-uhome, find-links

64 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

PathCheck Stage

PathCheck directives c heck the local file system path that is returned after the NameTrans step. The path is checked for things such as CGI path i nformation and

for dangerous elements such as restriction is applied.

PathCheck Stage

/./and /../ and //, and then any access

Ifthereismorethanone

PathCheck directive, each of the functions are executed in

order. The followin g PathCheck-class functions 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.

•

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 deni es 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.

Chapter 3 Predefined SAFs and the Request Handling Process 65

PathCheck Stage

The check-acl function specifies an Access Control List (ACL) to use to check whether the client is allowedto access the requested resource. An access control list containsinformationaboutwhoisorisnotallowedtoaccessaresource,andunder what conditions access is allowed.

Regardless of the order of

PathCheck directives in the object, check-acl functions

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 isthenameofanAccessControlList. path (optional) is a wildcard pattern that specifies the path for

which to apply the ACL.

bucket optional, common to all obj.conf functions

Examples

PathCheck fn=check-acl acl="*HRonly*"

deny-existence

Applicable in PathCheck-class directives. The

deny-existence function sends a “not found” message when a client tries to

access a specifiedpath. The server sends “not found” instead of “forbidden,” 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 not provided, it is assumed to match.

bong-file (optional) specifies a file to sen d rather than responding

with the “not found” message. It is a full file-system path.

bucket optional, common to all obj.conf functions

66 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

PathCheck Stage

Examples

PathCheck fn=deny-existence path=/usr/netscape/servers/docs/private

PathCheck fn=deny-existence bong-file=/svr/msg/go-away.html

find-index

Applicable in PathCheck-class directives. The

find-index function inve stigates whether the requested path is a directory. If

it is, the function searche s 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

obj.conf has a NameTrans directive that calls home-page,and

the requested directory is the root directory, then the home page rather than the index page, is returned to the client.

The

find-index function do es 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, commonto all obj.conf functions

Examples

PathCheck fn=find-index index-names=index.html,home.html

find-links

Applicable in PathCheck-class directives.

Chapter 3 Predefined SAFs and the Request Handling Process 67

PathCheck Stage

UNIX Only. The find-links function searches the current path for symbolic or hard links to other directories or file s y stems. 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 pathand itssubdirectories is checked for symb olic links. If you specify a partial path, any request containingt hat partial path is checked for symbolic links. For example, if you use /user/ and a request comes in for some/user/directory, then that directoryis checked for

symbolic links. bucket optional, commonto all obj.conf functions checkFileExistence check linked file f or existence a nd 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. The

find-pathinfo function finds any extra path information after the file na me in

the URL and stores it for use in the C GI environment v ariable PATH_INFO.

68 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

PathCheck Stage

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

get-client-cert function gets the authenticated client certificate from t he

SSL3 session. It c an apply to all HTTP methods, or only to those that match a specified pattern. It only works when SSL is enabled o n the server.

If the c ertificate is present or obtained fro m the SSL3 session, the function r eturns

REQ_NOACTION, allowing the request to proceed, otherwise it returns REQ_ABORTED

and sets the protocol status to 403 FORBIDDEN, causing the request to fail and the client to be given the

FORBIDDEN status.

Parameters

dorequest controls whether to actually try to get the certificate, or just test for its

presence. If dorequest is absent the default value is 0.

• 1 tellsthe function to redo the SSL3 handshake to get a client certificate, if the server does not already have the client certificate. This typically causes the client to present a dia log box to the user to select a client certificate. The server ma y already have the 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 request to proceed.

Chapter 3 Predefined SAFs and the Request Handling Process 69

PathCheck Stage

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 no t present after dorequest is handled. In this case, the HTTP status is set to PROTOCOL_FORBIDDEN,andthe 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 willbe applied. If method is absent,the function is applied to all requests.

bucket optional, commonto 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"

load-config

Applicable in PathCheck-class directives. The

load-config function searches for configuration files in document directories

and adds the file’scontents to the server’s existing configuration. These configuration files (also known as dynamic configuration files) spe cify additional access c ontrol information for the requested resource. Depen ding on the rules in the dynamic configuration files, the server mig ht or might not allow the client to access t he requested resource.

Eachdirectivethat invokes is either stated explicitly through the 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.

70 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

load-config is associated with a base directory, which

basedir par a meter or derived from the root

PathCheck Stage

For example, if the base directory is D:/netscape/servers/docs/nikki/, then only requests for resources in this directory or its subdirectories (and their subdirectories and so on) trigger the search for dynamic c onfiguration files. A request for the resource

D:/netscape/servers/docs/somefile.html does

not trigger the search in this case, since the requested res ource 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.

Ifthebasedirectoryis

D:/netscape/servers/docs/nikki/,theserverstarts

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 d irectives 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 yo ur 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 theOBJECT 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.

For example, the following directory

my.nsconfig.

<Object ppath="D:/netscape/servers/docs/*"> PathCheck fn="load-config" file="my.nsconfig" descend=1 basedir="D:/netscape/servers/docs" </Object>

D:/netscape/servers/docs are subject to the access rules in the file

<OBJECT> tag specifies that requests for resources in the

Chapter 3 Predefined SAFs and the Request Handling Process 71

PathCheck Stage

NOTE If the ppath resolvestoaresourceordirectorythatishigherinthe

directory tree (or is i n a different branch of the tree) than the base directory, the

load-configfunction is not invoked. This is because

the base directory specifies the highest-level directory for which requests will invoke the

load-config function.

The load-config functionreturns REQ_PROCEED if configuration files were loaded,

REQ_ABORTED on error, or REQ_NOACTION when no f iles are loaded.

Parameters

file (optional)is the name of the dynamic configuration file

containingt he access rules to be applied to the requested resource. If not p rovided, 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.Requestsfor resourcesmatching these types are aborted.

descend (optional) if present, specifies that t he 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 o nly the base directory.

basedir (optional) specifies base directory. This is the highest-level

directory for which requests will invoke the load-config function and is also the directorywhere the server starts searching for configuration files.

If basedir is no t 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, commonto all obj.conf functions

72 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

server-name/a/b/file.html,the

PathCheck Stage

Examples

In this example, wh enever the server receives a request for any resource containing the substring

secret that resides in D:/netscape/servers/docs/nikki/ or a

subdirectory thereof, it searches for a configu ration file called

checkaccess.nsconfig.

The server starts the search in the directory and searches subdirectories too. It loads each instance of

D:/netscape/servers/docs/nikki,

checkaccess.nsconfig

that it finds, applying the access control rules contained therein to determine whether the c lient is allowed to access the r equested resource or not.

<Object ppath="*secret*"> PathCheck fn="load-config" file="checkaccess.nsconfig" basedir="D:/netscape/servers/docs/nikki" descend="1" </Object>

nt-uri-clean

Applicable in PathCheck-class directives. Windows NT/Windows2000 Only. The

any resource whose physical path contains security problems).

Parameters

bucket optional, commonto all obj.conf functions tildeok if present, allows tilde”~” characters in URIs. This is a potential

security risk on Windows N T/Windows 2000, where longfi~1.htm might reference longfilename.htm but does not go through the proper ACL checking. If present, “//” sequences are allowed.

nt-uri-clean function denies access to

\.\, \..\ or \\ (these are potential

dotdirok If present, “//” sequences are allowed.

Examples

PathCheck fn=nt-uri-clean

Chapter 3 Predefined SAFs and the Request Handling Process 73

PathCheck Stage

See Also

unix-uri-clean

ntcgicheck

Applicable in PathCheck-class directives. Windows NT/Windows2000 Only. The

ntcgicheck function specifies the file

name extension to be added to any file name that doe s 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

.cgi.

require-auth

Applicable in PathCheck-class directives. The

require-auth function allowsaccess to resources only if the user or group is

authorized. Before this function is called, an authorization f unction (such as

basic-auth) must be called in an AuthTrans directive.

If a user was authorized in an

AuthTrans directive, and the auth-user parameter

is provided, then the user’s name must match the if the

auth-group parameter is provided, the authorized user must belong to an

authorizedgroup which must match the

74 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

auth-user wildcard value. Also,

auth-user wildcard value.

PathCheck Stage

Parameters

path ( op tional) is a wildcard local file system path on which t his

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 t ype defined.

realm is a string sent to the browser indicating the secure ar ea (or realm)

for which a user name and password are requested.

auth-user (optional) specifies a wildcard list of users who are allowed access.

If this parameter is not provided, then any user authorized by the authorization function is allowed access.

auth-group (optional) specifies a wildcard list of groups that are allowed

access.

bucket optional, common to all obj.conf functions

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

set-virtual-index

Applicable in PathCheck-class directives. The

set-virtual-index function specifie s a virtual index for a directory, whic h

determines the URL forwarding . The index can refer to a LiveWire application, a servlet i n its own namespace, a Netscape Application Server applogic, and 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 fou nd. REQ_RESTART is returned if the current URI matches any one of the URIs mentioned

in the

from parameterorifthereisnofrom parameter.

REQ_ABORTED is returned if the file specified by the

Chapter 3 Predefined SAFs and the Request Handling Process 75

PathCheck Stage

Parameters

virtual-index is the URI of the content generator that acts as an index for the

URI the user enters.

from (optional) is a c omma-separated list of URIs for which this

virtual-index is applicable. If from is not specified, the virtual-index always applies.

bucket optional, commonto all obj.conf functions

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 w ith a Client tag to limit access of certain directories to non-exportable browsers.

The function returns

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

REQ_PROCEED,andthepath variable is set to

the bong filename. A lso, when a keysizerestriction is not met, the SSL session cache entry for the cur rent session is invalidated, so that a full SSL handshake will occur the next time the sam e cl ie nt connects to the server.

Requests that use

ssl-check returnssomething other than REQ_NOACTION.

Parameters

secret-keysize (optional) is the m inimum number of bits required in the

76 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

ssl-check are not cacheable in the accelerator file cache if

secret key.

PathCheck Stage

bong-file (optional) is the name of a file (not a URI ) to be served if the

restriction is not met

bucket optional, commonto all obj.conf functions

ssl-logout

Applicable in PathCheck-class directives.

ssl-logout invalidates the current SSL session in the server's SSL session cache.

This does not af f e ct the current request, but the next time the client connects, a new SSL session will be created. If SSL is en abled, this function returns after invalidating the session cache entry. If SSL is not enabled, it returns

REQ_NOACTION.

Parameters

bucket optional, commonto all obj.conf functions

REQ_PROCEED

unix-uri-clean

Applicable in PathCheck-class directives. UNIX Only. The

physical path contains

Parameters

bucket optional, commonto all obj.conf functions dotdirok If present, “//” sequences are allowed.

Examples

PathCheck fn=unix-uri-clean

See Also

nt-uri-clean

unix-uri-clean function denies access to any resource whose

/./, /../ or // (these are potential securityproblems).

Chapter 3 Predefined SAFs and the Request Handling Process 77

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 clie nt a s the value of the content-type

header.

ObjectType directives also set the type parameter, which is used by Service

directives to determine how to process the request according to w hat kind of content is bein g requested.

type, encoding,and

If there is more than one

ObjectType dire ctive in an object, all the directives are

applied in the order they appear. If a directive sets an attribute and later directives try t o set that attribute to something else, the first setting is used and the subsequent ones ignored.

The

obj.conf file almost always has an ObjectType directive that calls 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.

•

set-default-type allows you to define a default charset, content-encoding,andcontent-language for the response being sent back

ObjectType-class functions are described in detail in this section:

to the client.

•

shtml-hacktype requests that .htm and .html files are parsed for

server-parsedhtml 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 responsebased onthe

files extension and the MIME types database.

force-type

Applicable in ObjectType-class directives. The

force-type function assigns a type to requests that do not already have a

MIME type. This is us ed to specify a default object type.

78 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

ObjectType Stage

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 chanceto set

the MIME type first. If there is more than one

ObjectType directiveinanobject,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.

Parameters

type (optional) is the type assigned to a matching 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 browsersent the Accept-charset header or its User-agentis mozilla/1.1

ornewer,thenappend “; charset= where

charset is the value of the magnus-charset

parameter in rq->srvhdrs.

charset”tocontent-type,

bucket optional, common to all obj.conf functions

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 defau lt

content-language for the response being sent back to the client.

Chapter 3 Predefined SAFs and the Request Handling Process 79

charset, content-encoding,and

ObjectType Stage

If th e charset, content-encoding,andcontent-language have not been set for a response, t hen just before the headers are sent the defaults defined by

set-default-type are used. Note that by placing this functionin different objects

obj.conf, you can define different defaults for different parts of the document

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 request (the

content-language header).

charset (optional) is the character set for the magnus-charset

parameter in rq->srvhdrs.Ifthebrowsersentthe Accept-charset header o r its User-agentis mozilla/1.1

or newer,t hen append “; charset= where

charset is the value of the magnus-charset

parameter in rq->srvhdrs.

bucket optional, commonto all obj.conf functions

charset”tocontent-type,

Example

ObjectType fn="set-default-type" charset="iso_8859-1"

shtml-hacktype

Applicable in ObjectType-class directives. The

shtml-hacktype function changes the content-type of any .htm or .html file

magnus-internal/parsed-html and returns REQ_PROCEED.Thisprovides

backward compatibility with server-side includes for 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, o ptional) tells the function to change the

content-type only if the execute bit is enabled. The va lue of the parameter is not important. It need only be provided. You may use exec-hack=true.

80 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

.htm or .html

ObjectType Stage

bucket optional, common to all obj.conf functions

Examples

ObjectType fn=shtml-hacktype exec-hack=true

type-by-exp

Applicable in ObjectType-class directives. The

type-by-exp function ma tches the current path with a wildcard expression. If

the two match, the same as

type-by-extension, except you use wildcard patterns for the files or

directories spe cified in the URLs.

Parameters

exp is t he wildcard pattern of paths for which this function is

type paramete r information is applied to the file. This is the

applied.

type (optional) is the type assigned to a matching 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.Ifthebrowsersentthe Accept-charset header or its User-agent is mozilla/1.1

ornewer,thenappend “; charset= where

charset is the value of the magnus-charset

parameter in rq->srvhdrs.

bucket optional, common to all obj.conf functions

Examples

ObjectType fn=type-by-exp exp=*.test type=application/html

Chapter 3 Predefined SAFs and the Request Handling Process 81

charset”tocontent-type,

ObjectType Stage

See Also

type-by-extension, force-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. T he M IME type is added to the back to the client.

content-type header sent

The table of MIME type mappings is created by a

MIME element in the server.xml

file, which loads a MIME types file or list and creates the ma ppings. For more information about

server.xml,seeChapter8,“VirtualServerConfiguration

Files.” For more information about MIME types files, see A ppendix 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

If the extension of the requested resource is

htm or html,thetype-by-extension

file sets the type to text/html. If the extension is .txt, the function setsthe 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

82 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Service Stage

The Service class of functions sends the response data to the client. Every

Service directive has the following optional parameters to determine

whether the fun ction is executed. All the optional par ameters must match the current request for the function to be executed.

•

type

(optional) s pecifies a wildcard pattern of MIME types for which this func tion will be executed. The a

Service function to ex ecute.

• method

(optional) specifies a wildcard pattern of HTTP methods for whi ch 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.

Service Stage

magnus-internal/* MIME types are used only to select

GET, HEAD,andPOST.

Chapter 3 Predefined SAFs and the Request Handling Process 83

Service Stage

• UseOutputStreamSize (optional) d etermines the default output stream buffer size, in bytes, for data

sent to the client. If this pa rameter 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 millisec onds 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 applicationsthat run continuously and generate periodic statusupdate reports. If this parameter is n ot 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,andChunkedRequestTimeout parameters, see

“Buffered Streams,” on page 334. The

ChunkedRequestBufferSize,andChunkedRequestTimeout parameters also have

equivalent

obj.conf parameters o verride the magnus.conf directives.

magnus.conf directives; see “Chunked E ncoding,” on page 286. The

Service-class function, the first one matching the

type, method,andquery)isexecuted.

UseOutputStreamSize, flushTimer,

UseOutputStreamSize,

By default, the server sends the requested file to the client by calling the function. The directive t hat sets the default is:

Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"

84 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

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,orPOST,andthetypedoesnotstart with

list of characters that can be used in pat terns, 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 fil ename 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 d irectories 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 certificat e 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 renam es a file.

•

send-cgi sets up environment variables, launches a CGI program, and send s

the response t o 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 85

Service Stage

• send-shellcgi sets up environment variables, launches a shell CGI program, and sends t he response to the client.

•

send-wincgi sets up environment variables, launchesa 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 uploadsandsavesafile.

add-footer

Applicable in Service-c lass 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 th e footer can be dynamica lly 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 allService-class functions method optional,common to allService-class functions query optional,common to allService-class functions UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-classfunctions ChunkedRequestBufferSize optional, common to all Service-class functions

86 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Service Stage

ChunkedRequestTimeout optional, common t o all Service-class functions bucket optional, commonto 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/servers/footers/footer1.html" NSIntAbsFilePath="yes"

See Also

append-trailer, add-header

add-header

Applicable in Service-c lass directives. This function prepends a header to an HTML file t hat 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 r esource 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 87

Service Stage

UseOutputStreamSize o ptional, 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/servers/headers/header1.html" NSIntAbsFilePath="yes"

See Also

add-footer, append-trailer

append-trailer

Applicable in Service-c lass directives. The

append-trailer function sends an HTML file and appends text to the end. It

only appends text to HTML files. This is typically used for author 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 HTM L documents. The string

88 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

REQ_ABORTED if a required parameter is missing, if there is extra path

is unescaped with util_uri_unescape beforebeing sent. The text can contain HTML tags and can be up to 512 characterslong after unescaping and inserting the date.

If you use the string :LASTMOD:,whichisreplacedby 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.

Examples

# 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-c lass directives. The

imagemap function responds to requests for imagemaps. Imagemaps are

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 89

Service Stage

query optional, common to all Service-class functions UseOutputStreamSize o ptional, 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-c lass directives. The

index-common func tion generates a fancy (or common) list of files in t he

requested directory. The list is sorted alphab etically. Files beginning with a period (.) are not displayed. Each item appears as an HTML link. This function displays more informationthan

index-simple including the size, da te last modified, and

an icon for each fi l e. It may also include a header and/or readme file into the listing.

The

Init-class function cindex-init in magnus.conf specifies the form at for the

index list, including where to look for the images. If

obj.conf contains a call to index-common in the Service stage, magnus.conf

must initialize fancy (or common) indexing by invoking cindex-init during the

Init stage.

Indexing occurs when the requested resourceis a directory that does not contain an index file o r 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

90 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

find-index or home-page.

.gif files dependent on the content-type of the file:

Service Stage

"audio/*" sound.gif "video/*" movie.gif "application/octet-stream" binary.gif

directory menu.gif all others unknown.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 with .html addedto 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 contentsof the directory, indicate copyrights, authors, or other information. The file is first tried with .html addedto the end. If found, it is incorporated at the bottom o f 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-class functions method optional, common to all Service-class functions query optional, common to all Service-class functions UseOutputStreamSize o ptional, 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 91

Service Stage

Examples

Service fn=index-common type=magnus-internal/directory method=(GET|HEAD) header=hdr readme=rdme.txt

See Also

cindex-init, index-simple, find-index, home-page

index-simple

Applicable in Service-c lass directives. The

index-simple function generates a simple index of the files in the reques ted

directory. It scans a directoryand 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 b eginning 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 o ptional, 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

92 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Service Stage

See Also

cindex-init, index-common

key-toosmall

Applicable in Service-c lass directives.

NOTE This function is provided for backw ard compatibility only and was

deprecated in iPlanet™ Web Server 4.x. It is replaced by the PathCheck-class SAF

key-toosmall func tion returns a message to the client sp ecifying 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 allService-class functions method optional,common to allService-class functions query optional,common to allService-class functions

ssl-check.

UseOutputStreamSize optional, common to all Service-class functions flushTimer optional, common to all Service-classfunctions 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 93

Service Stage

list-dir

Applicable in Service-c lass directives. The

list-dir function returns a sequence of text lines to the client in response to a

requestwhose method is INDEX. The format of the returned lines is:

nametype sizemimetype

The namefield is the name of the file o r directory. It is relative tothe directorybeing 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 M IME 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 a

Service-class function that calls list-dir for requests whose method is INDEX.

Parameters

obj.conf file contains

Examples

Service fn=list-dir method="INDEX"

94 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Service Stage

make-dir

Applicable in Service-c lass directives. The

make-dir function creates a directory when the client sends a request whose

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.

Parameters

Examples

Service fn="make-dir" method="MKDIR"

obj.conf file contains

query-handler

Applicable in Service-c lass directives.

NOTE This function is provided for backward compatibility only and is

used mainly to support the ob solete ISINDEX tag. If possible, use an HTML form instead.

The

query-handler function runs a CGI program instead of referencingthe path

requested.

Chapter 3 Predefined SAFs and the Request Handling Process 95

Service Stage

Parameters

path is the full path and file name of the CGI program to

run.

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-c lass directives. The

remove-dir function removes a directory when the client sends an request

whose method is functionwillfailif thedirectory is not empty or if the server doesn’thave the privileges to remove the directory.

When remote file manipulation is enabled in the server, the a

Service-class fun ction that invokes remove-dir when the request method is

RMDIR.

Parameters

96 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

RMDIR. The directory must be empty (have no files in it). The

obj.conf file contains

Service Stage

flushTimer optional, common to all S e rvice-class functions ChunkedRequestBufferSize optional, common to all Service-class functions ChunkedRequestTimeout optional, common to all Service-class functions bucket optional, commonto all obj.conf functions

Examples

Service fn="remove-dir" method="RMDIR"

remove-file

Applicable in Service-c lass directives. The

remove-file function deletes a file when the client sends a request whose

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 a

Service-class fun ction that invokes remove-file when the request method is

DELETE.

Parameters

Chapter 3 Predefined SAFs and the Request Handling Process 97

obj.conf file contains

Service Stage

Examples

Service fn="remove-file" method="DELETE"

rename-file

Applicable in Service-c lass directives. The

rename-file function renames a file when the client sends a request with a New-URL head er 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 fun ction that invokes rename-file when the request method is

MOVE.

Parameters

Examples

Service fn="rename-file" method="MOVE"

obj.conf file contains

98 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Service Stage

send-cgi

Applicable in Service-c lass directives. The

send-cgi function sets up the CGI environment variables, runs a file as a CGI

program in a new process, and sends the results to the client. For details abou t the CGI environment variables and their NSAPI equivalents, refer

to section “CGI to NSAPI C onversion,” on page 135. For additional information about CGI, see the Netscape Enterprise Server

Administrator’sGuideand the Netscape Enterprise ServerProgrammer’s Guide. There are three ways to change the timing used to flush the CGI b uf fer:

• 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 334.

Parameters

user (UNIX only) Specifies the name of the user to execute

CGI programs as.

group (UNIX only) Specifies the name of the group to

execute CGI programs as.

chroot (UNIX only) Specifies t he 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 space in bytes. You can supply both current (soft) and maximum (hard) limits, separated by a comma. Th e soft limit must be listed first. If only on e limit is specified, both limits are set to this value.

Chapter 3 Predefined SAFs and the Request Handling Process 99

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, both limits 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 p rogram's priority relative to the server. Typically, the server is run with a nice value of 0 and theniceincrementwouldbebetween0(theCGI program runs at samepriority 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.

Examples

The following ex ample 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.”

100 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

Redhat NETSCAPE ENTERPRISE SERVER User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

NSAPI Programmer’s Guide

Netscape Enterprise Server

About This Book

Where to Find Related Information

Basics of Server Operation

Configuration Files

magnus.conf

server.xml

obj.conf

mime.types

Dynamic Reconfiguration

How the Server Handles Requests from Clients

HTTP Basics

Steps in the Request Handling Process

Writing New Server Application Functions

Directives for Handling Requests

Syntax and Use of obj.conf

Server Instructions in obj.conf

Summary of the D irectives

The <Object> Tag and the <Client> Tag

The Object Tag

Objects that Use the name Attribute

Object that Use the ppath Attribute

The Client Tag

Variables Defined in server.xml

Flow of Control in obj.conf

AuthTrans

NameTrans

How the Server Knows to Process Other Objects

PathCheck

ObjectType

Setting the Type By File Extension

Forcing the Type

Service

Service Examples

Default Service Directive

AddLog

Error

Syntax Rules for Editing obj.conf

Order of Directives

Parameters

Case Sensitivity

Separators

Quotes

Spaces

Line Continuation

Path Names

Comments

About obj.confDirective Examples

The bucket Parameter

AuthTrans Stage

NameTrans Stage

PathCheck Stage

ObjectType Stage

Service Stage