Netscape NETSCAPE ENTERPRISE SERVER 6.1 - NSAPI PROGRAMMER... User manual

NSAPI Programmer’s Guide
Netscape Enterprise Server
Version 6.1
April 2002 (Draft)

Netscape Communications Corporation ("Netscape") and its licensors retain all ownership rights to the software programs offered by
Netscape (referred to herein as "Software") and related documentation. Use of the Software and related documentation is governed
by the license agreement for the Software and applicable copyright law.
Your right to copy this documentation is limited by copyright law.Making unauthorized copies, adaptations or compilation works is
prohibited and constitutes a punishable violation of the law. Netscape may revise this documentation from time to time without
notice.
THIS DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL NETSCAPE BE
LIABLE FOR INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY KIND ARISING FROM ANY
ERROR IN THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION ANY LOSS OR INTERRUPTION OF BUSINESS,
PROFITS, USE, OR DATA.
The Software and documentation are copyright © 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002 Netscape
Communications Corporation. All rights reserved.
This product includes software developed by Apache Software Foundation (http://www.apache.org/). Copyright (c) 1999 The
Apache Software Foundation. All rights reserved.
This product includes software developed by the University of California, Berkeley and its contributors. Copyright (c) 1990, 1993,
1994 The Regents of the University of California. All rights reserved.
Netscape and the Netscape N logo are registered trademarks of Netscape Communications Corporation in the United States and
other countries. Other Netscape logos, product names and service names are also trademarks of Netscape and may be 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 Netscape software or documentation
to the U.S. government is with restricted rights as described in the license agreement for that Software.

3
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

4 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
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

5
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

6 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
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

7
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

8 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
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

9
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

10 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
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

11
pool-init........................................................................... 257
register-http-method................................................................ 258
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

12 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
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

13
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

14 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
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

15
About This Book
This book discusses how to use the Netscape® Server Application Programmer's
Interface (NSAPI) to build plugins that define Server Application Functions (SAFs)
to extend and modify Netscape Enterprise Server. The book also discusses the
purpose and use of the configuration files obj.conf,magnus.conf,server.xml,
and mime.types, and provides comprehensive lists of the directives and functions
that can be used in these configuration files. It also provides a reference of the
NSAPI functions you can use to define new plugins.
This book has the following chapters and appendices:
• Chapter 1, “Basics of Server Operation”
This chapter discusses how the uses configuration files to perform
initialization tasks and to process client requests.
• Chapter 2, “Syntax and Use of obj.conf”
This chapter goes into detail on the configuration file obj.conf.Thechapter
discusses the syntax and use of directives in this file, which instruct the server
how to process requests.
• Chapter 3, “Predefined SAFs and the Request Handling Process”
This chapter discusses each of the stages in the request handling process, and
provides an API reference of the Server Application Functions (SAFs) that can
be invoked at each stage.
• Chapter 4, “Creating Custom SAFs”
This chapter discusses how to create your own plugins that define new SAFs to
modify or extend the way the server handles requests.
• Chapter 5, “NSAPI Function Reference”

16 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
This chapter presents a reference of the functions in the Netscape Server
Application Programming Interface (API). You use NSAPI functions to define
SAFs.
• Chapter 6, “Examples of Custom SAFs”
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 set in the configuration file
magnus.conf to configure the during initialization.
• Chapter 8, “Virtual Server Configuration Files”
This appendix discusses the variables you can set in the configuration file
server.xml to configure virtual servers in .
• Appendix A, “Data Structure Reference”
This appendix discusses some of the commonly used NSAPI data structures.
• Appendix B, “MIME Types”
This appendix discusses the MIME types file, which maps file extensions to file
types.
• Appendix C, “Wildcard Patterns”
This appendix lists the wildcard patterns you can use when specifying values
in obj.conf, various predefined SAFs, and in some NSAPI functions.
• Appendix D, “Time Formats”
This appendix lists time formats.
• Appendix E, “HyperText Transfer Protocol”
This appendix gives an overview of HTTP.
• Appendix F, “Dynamic Results Caching Functions”
This appendix explains how to create a results caching plugin.
• Appendix G, “Alphabetical 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 magnus.conf.

Where to Find Related Information
About This Book 17
Where to Find Related Information
Additional Enterprise Server documentation includes:
• Netscape Enterprise Server Installation and Migration Guide
• Netscape Enterprise Server Performance Tuning, Sizing, and Scaling Guide
• Netscape Enterprise 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:
http://enterprise.netscape.com/docs
NOTE Throughout this manual, all descriptions specific to UNIX®
descriptions apply to the Linux® operating system as well, except
where Linux is specifically mentioned.

Where to Find Related Information
18 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)

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

Configuration Files
20 Netscape Enterprise Server NSAPI Programmer’s Guide • April 2002 (Draft)
Configuration Files
The configuration and operation of the is controlled by configuration files. The
configuration files reside in the directory server-root/server-id/config/.This
directory contains various configuration files for controlling different components,
such as jsa.conf for configuring server-side JavaScript™ and netshare.conf for
configuring NetShare. The exact number and names of configuration files depends
on which components have been enabled or loaded into the server.
However, this directory always contains four configuration files that are essential
for the server to operate. These files are:
•magnus.conf – contains global server initialization information.
•server.xml – contains initialization information for virtual servers and listen
sockets.
•obj.conf – contains instructions for handling requests from clients.
•mime.types – contains information for determining the content type of
requested resources.
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 classes and virtual servers to these listen sockets. A master file,
server.dtd, defines its format and content.
For more information about how the server uses server.dtd and server.xml,see
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.