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.
The Softwareand documentation are copyright © 2001 Sun Microsystems,Inc. Portions copyright 1999,2002 N etscape
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.
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
3
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
5
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
7
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
9
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
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
11
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
13
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
15
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
in
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
19
Configuration Files
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
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
is
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"
27
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)
Loading...