Netscape ENTERPRISE SERVER 6.1, Manual

Page 1: ...NSAPI Programmer s Guide Netscape Enterprise Server Version6 1 April 2002 Draft...

Page 2: ...ghts 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 softw...

Page 3: ...Basics 22 Steps in the Request Handling Process 24 Directives for Handling Requests 25 Writing New Server Application Functions 25 Chapter 2 Syntax and Use of obj conf 27 Server Instructions in obj co...

Page 4: ...4 Order of Directives 44 Parameters 44 Case Sensitivity 44 Separators 45 Quotes 45 Spaces 45 Line Continuation 45 Path Names 45 Comments 45 About obj conf Directive Examples 46 Chapter 3 Predefined SA...

Page 5: ...by exp 81 type by extension 82 Service Stage 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 remov...

Page 6: ...ating a Shared Object 122 Additional Linker Flags 122 Compiler Flags 123 Load and Initialize the SAF 124 Instruct the Server to Call the SAFs 124 Reconfigure the Server 126 Test the SAF 126 Overview o...

Page 7: ...n 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...

Page 8: ...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_maxd...

Page 9: ...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...

Page 10: ...le 223 Source Code 224 ObjectType Example 226 Installing the Example 227 Source Code 227 Service Example 228 Installing the Example 229 Source Code 229 More Complex Service Example 231 AddLog Example...

Page 11: ...266 ClientLanguage 266 DefaultCharSet 266 DefaultLanguage 266 DNS Lookup 267 AsyncDNS 267 DNS 267 Threads Processes and Connections 268 Concurrency 269 ConnQueueSize 269 HeaderBufferSize 270 IOTimeou...

Page 12: ...tic Collection 277 ErrorLog 278 ErrorLogDateFormat 278 LogFlushInterval 279 LogVerbose 279 LogVsId 279 PidLog 279 StatsUpdateInterval 280 ACL 280 ACLCacheLifetime 280 ACLUserCacheSize 281 ACLGroupCach...

Page 13: ...server xml 297 SERVER 297 VARS 297 LS Listen Socket 298 CONNECTIONGROUP 299 SSLPARAMS 300 MIME 301 ACLFILE 303 VSCLASS 303 VS Virtual Server 304 QOSPARAMS 305 USERDB 306 Virtual Server Selection for R...

Page 14: ...dix D Time Formats 327 Appendix E HyperText Transfer Protocol 329 Compliance 329 Requests 330 Request Method URI and Protocol Version 330 Request Headers 330 Request Data 331 Responses 331 HTTP Protoc...

Page 15: ...asics 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...

Page 16: ...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...

Page 17: ...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 ca...

Page 18: ...Where to Find Related Information 18 Netscape Enterprise Server NSAPI Programmer s Guide April 2002 Draft...

Page 19: ...changing the instructions in obj conf You can use the Netscape Server Application Programming Interface API to create new Server Application Functions SAFs to use in instructions in obj conf This cha...

Page 20: ...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...

Page 21: ...e system automatically updates obj conf The file obj conf contains a series of instructions directives that tell the what to do at each stage in the request response process Each directive invokes a S...

Page 22: ...server that accepts and responds to HyperText Transfer Protocol HTTP requests Browsers like Netscape Communicator communicate using several protocols including HTTP FTP and gopher The handles HTTP spe...

Page 23: ...TP 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 typi...

Page 24: ...Trans 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...

Page 25: ...on Functions SAFs Writing New Server Application Functions The comes with a variety of pre defined SAFs that you can use to create more directives in obj conf You can also write your own SAF using the...

Page 26: ...Writing New Server Application Functions 26 Netscape Enterprise Server NSAPI Programmer s Guide April 2002 Draft...

Page 27: ...ns in this chapter are Server Instructions in obj conf The Object Tag and the Client Tag Variables Defined in server xml Flow of Control in obj conf Syntax Rules for Editing obj conf About obj conf Di...

Page 28: ...hapter 4 Creating 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 Directives He...

Page 29: ...or example PathCheck fn find index index names index html home html This example calls the find index function with an index names argument of index html home html If the requested URL is a directory...

Page 30: ...does not match Another example is Service method GET HEAD type magnus internal imagemap fn imagemap In this case if the method of the request is either GET or HEAD and the type of the requested resour...

Page 31: ...th usr netscape servers docs private The server always starts handling a request by processing the directives in the default object However the server switches to processing directives in another obje...

Page 32: ...ed cgi Object that Use the ppath Attribute When the server finishes processing the NameTrans directives in the default object the logical URL of the request will have been converted to a physical path...

Page 33: ...Client Client tags are executed only if information in the client request matches the parameter value specified by the Client tag A Client tag accepts the parameters ip dns or host Use one and only o...

Page 34: ...ue of the ip parameter negates the expression so Enterprise Server will exclude clients from the 192 95 251 subnet from the access log Variables Defined in server xml You can define variables in the s...

Page 35: ...there is more than one AuthTrans directive the server executes them all unless one of them results in an error If an error occurs the server skips all other directives except for Error directives Nam...

Page 36: ...ive appeared after the one that calls document root it would never be executed with the result that the resultant directory pathname would be D netscape servers docs cgi not mycgi This illustrates why...

Page 37: ...e requested URL to the pathname D Netscape Servers docs internalplan1 html In this case the partial path internal matches the path D Netscape Servers docs internalplan1 html So now the server would st...

Page 38: ...ttempts to set the same attribute are ignored The reason that all ObjectType directives are applied is that one directive may set one attribute for example type while another directive sets a differen...

Page 39: ...if the type attribute has not been set that is the file extension was not found in the MIME types table set the type attribute to text plain If the server receives a request for a file abc dogs it loo...

Page 40: ...bjectType directives if another object has been matched to the request as a result of the NameTrans step the server considers the Service directives in the matching object before considering the ones...

Page 41: ...r receives a request for http server_name servlet doCalculation class This example assumes that servlets have been activated and the directory D netscape servers docs servlet has been registered as a...

Page 42: ...ctive matches the type value that was set by the ObjectType directive So the server goes ahead and executes this Service directive which calls the NSServletService function This function invokes the r...

Page 43: ...d function is send file which simply sends the contents of the requested file to the client AddLog After the server generate the response and sends it to the client it executes AddLog directives to ad...

Page 44: ...an ObjectType directive sets an attribute value no other ObjectType directive can change that value For example if the default ObjectType directives were listed in the following order which is the wro...

Page 45: ...not allowed at the beginning of a line except when continuing the previous line Spaces are not allowed before or after the equal sign that separates the name and value Spaces are not allowed at the e...

Page 46: ...ObjectType Service AddLog Error Object Object If any line of any example begins with a different word in the manual the line is wrapping in a way that it does not in the actual file In some cases thi...

Page 47: ...s conf This chapter includes functions that are part of the core functionality of Netscape Enterprise Server It does not include functions that are available only if additional components such as serv...

Page 48: ...sic auth basic ncsa get sslid qos handler NameTrans Stage assign name document root home page pfx2dir redirect strip params unix home PathCheck Stage check acl deny existence find index find links fin...

Page 49: ...ose in the default bucket You can define additional performance buckets in the magnus conf file see the perf init and define perf bucket functions Service Stage add footer add header append trailer im...

Page 50: ...tion The server handles the authorization of client users in two steps AuthTrans Directive validates authorization information sent by the client in the Authorization header PathCheck Stage checks tha...

Page 51: ...er authorization scheme This function is usually used in conjunction with the PathCheck class function require auth Parameters auth type specifies the type of authorization to be used This should alwa...

Page 52: ...ord pw user database userdb and group database groupdb in the pb parameter It also has access to the auth type auth user user auth db userdb and auth password pw Windows NT Windows 2000 only parameter...

Page 53: ...allowing instantaneous access to billions of users If you use this parameter don t use the userfile parameter as well userfile optional specifies the full path name of the user database in the NCSA st...

Page 54: ...thTrans class directives The qos handler function examines the current quality of service statistics for the virtual server virtual server class and global server logs the statistics and enforces the...

Page 55: ...he following NameTrans class functions are described in detail in this section assign name tells the server to process directives in a named object document root translates a URL into a file system pa...

Page 56: ...conf and continues by processing the directives in the personnel object The assign name function always returns REQ_NOACTION Parameters from is a wildcard pattern that specifies the path to be affect...

Page 57: ...tual path will fail Therefore use nostat only when the path of the virtual path does not exist on the system for example for NSAPI plugin URLs to improve performance by avoiding unnecessary stats on t...

Page 58: ...NameTrans directives listed after this will never be called so be sure that the directive that invokes document root is the last NameTrans directive There can be only one root document directory To s...

Page 59: ...slash it is assumed to be a full path to a file This function sets the server s path variable and returns REQ_PROCEED If path is a relative path it is appended to the URI and the function returns REQ_...

Page 60: ...athinfo does by default The value you assign to this parameter is ignored If you do not wish to use this parameter leave it out The find pathinfo forward parameter is ignored if the ntrans base parame...

Page 61: ...ameTrans fn pfx2dir find pathinfo forward from cgi bin dir export home cgi bin name cgi from specifies the prefix of the requested URI to match url may be optional specifies a complete URL to return t...

Page 62: ...e also recognized Table 3 2 Shell Expression Pattern Sequences Pattern Matches Zero or more characters Exactly one character Matches the end of string abc Matches one instance of any of the characters...

Page 63: ...w prefix A request for http www example com Netscape would be translated to http www netscape com A request for http www example com netscape foobar would be translated to http www netscape com foobar...

Page 64: ...this structure elements in the passwd file that are not needed are indicated with username groupid homedir If you want the server to scan the password file only once at startup use the Init class fun...

Page 65: ...quested find links denies access to directories with certain file system links find pathinfo locates extra path info beyond the file name for the PATH_INFO CGI environment variable get client cert get...

Page 66: ...icable in PathCheck class directives The deny existence function sends a not found message when a client tries to access a specified path The server sends not found instead of forbidden so the user ca...

Page 67: ...the home page rather than the index page is returned to the client The find index function does nothing if there is a query string if the HTTP method is not GET or if the path is that of a valid file...

Page 68: ...he CGI environment variable PATH_INFO disable is a character string of links to disable h is hard links s is soft links o allows symbolic links from user home directories only if the user owns the tar...

Page 69: ...Check fn find pathinfo find pathinfo forward dorequest controls whether to actually try to get the certificate or just test for its presence If dorequest is absent the default value is 0 1 tells the f...

Page 70: ...rmines two things the top most directory for which requests will invoke this call to the load config function require controls whether failure to get a client certificate will abort the HTTP request I...

Page 71: ...ration files through the Server Manager interface the system writes additional objects with ppath parameters into the obj conf file If you manually add directives that invoke load config to the defaul...

Page 72: ...pattern of types to disable for the base directory such as magnus internal cgi Requests for resources matching these types are aborted descend optional if present specifies that the server should sear...

Page 73: ...client is allowed to access the requested resource or not nt uri clean Applicable in PathCheck class directives Windows NT Windows 2000 Only The nt uri clean function denies access to any resource who...

Page 74: ...ble in PathCheck class directives The require auth function allows access to resources only if the user or group is authorized Before this function is called an authorization function such as basic au...

Page 75: ...the from parameter or if there is no from parameter path optional is a wildcard local file system path on which this function should operate If no path is provided the function applies to all paths a...

Page 76: ...EQ_ABORTED with a status of PROTOCOL_FORBIDDEN If the bong file is specified the function returns REQ_PROCEED and the path variable is set to the bong filename Also when a keysize restriction is not m...

Page 77: ...e entry If SSL is not enabled it returns REQ_NOACTION Parameters unix uri clean Applicable in PathCheck class directives UNIX Only The unix uri clean function denies access to any resource whose physi...

Page 78: ...st always has an ObjectType directive that calls the type by extension function This function instructs the server to look in a particular file the MIME types file to deduce the content type from the...

Page 79: ...pe class directives This function allows you to define a default charset content encoding and content language for the response being sent back to the client type optional is the type assigned to a ma...

Page 80: ...ensions The function may also check the execute bit for the file on UNIX systems The use of this function is not recommended Parameters enc optional is the encoding assigned to a matching request the...

Page 81: ...exp is the wildcard pattern of paths for which this function is applied type optional is the type assigned to a matching request the content type header enc optional is the encoding assigned to a matc...

Page 82: ...MIME element in the server xml file which loads a MIME types file or list and creates the mappings For more information about server xml see Chapter 8 Virtual Server Configuration Files For more infor...

Page 83: ...s must match the current request for the function to be executed type optional specifies a wildcard pattern of MIME types for which this function will be executed The magnus internal MIME types are us...

Page 84: ...bytes ChunkedRequestTimeout optional determines the default timeout in seconds for un chunking request data If this parameter is not specified the default is 60 seconds If there is more than one Servi...

Page 85: ...ends a header specified by a filename or URL to an HTML file append trailer appends text to the end of an HTML file imagemap handles server side image maps index common generates a fancy list of the f...

Page 86: ...rated To specify static text as a footer use the append trailer function Parameters file optional The pathname to the file containing the footer Specify either file or uri By default the pathname is r...

Page 87: ...l method GET fn add footer file D netscape servers footers footer1 html NSIntAbsFilePath yes file optional The pathname to the file containing the header Specify either file or uri By default the path...

Page 88: ...mon to all Service class functions flushTimer optional common to all Service class functions ChunkedRequestBufferSize optional common to all Service class functions ChunkedRequestTimeout optional comm...

Page 89: ...common to all Service class functions method optional common to all Service class functions query optional common to all Service class functions UseOutputStreamSize optional common to all Service cla...

Page 90: ...ntains a call to index common in the Service stage magnus conf must initialize fancy or common indexing by invoking cindex init during the Init stage Indexing occurs when the requested resource is a d...

Page 91: ...and name of a file HTML or plain text to append to the directory listing This file might give more information about the contents of the directory indicate copyrights authors or other information The...

Page 92: ...ory that does not contain either an index file or a home page or no index file or home page has been specified by the functions find index or home page Parameters Examples Service fn index common type...

Page 93: ...vided for backward compatibility only and was deprecated in iPlanet Web Server 4 x It is replaced by the PathCheck class SAF ssl check type optional common to all Service class functions method option...

Page 94: ...the size of the file in bytes The mtime field is the numerical representation of the date of last modification of the file The number is the number of seconds since the epoch Jan 1 1970 00 00 UTC sin...

Page 95: ...ler function runs a CGI program instead of referencing the path requested type optional common to all Service class functions method optional common to all Service class functions query optional commo...

Page 96: ...of the CGI program to run type optional common to all Service class functions method optional common to all Service class functions query optional common to all Service class functions UseOutputStrea...

Page 97: ...ional common to all Service class functions ChunkedRequestBufferSize optional common to all Service class functions ChunkedRequestTimeout optional common to all Service class functions bucket optional...

Page 98: ...he obj conf file contains a Service class function that invokes rename file when the request method is MOVE Parameters Examples Service fn remove file method DELETE type optional common to all Service...

Page 99: ...t the buffer size using the UseOutputStreamSize parameter Force Enterprise Server to flush its buffer by forcing spaces into the buffer in the CGI script For more information about flushTimer and UseO...

Page 100: ...one limit is specified both limits are set to this value nice UNIX only Accepts an increment that determines the CGI program s priority relative to the server Typically the server is run with a nice...

Page 101: ...Note here that the pattern means does not match For a list of characters that can be used in patterns see Appendix C Wildcard Patterns Parameters Object name default NameTrans fn pfx2dir from cgi bin...

Page 102: ...Timer optional common to all Service class functions ChunkedRequestBufferSize optional common to all Service class functions ChunkedRequestTimeout optional common to all Service class functions bucket...

Page 103: ...s 2000 For information about shell CGI programs consult the Netscape Enterprise Server Administrator s Guide Parameters type optional common to all Service class functions method optional common to al...

Page 104: ...all Service class functions ChunkedRequestTimeout optional common to all Service class functions bucket optional common to all obj conf functions Service fn send shellcgi Service type magnus internal...

Page 105: ...must be perf for this function method optional common to all Service class functions query optional common to all Service class functions UseOutputStreamSize optional common to all Service class func...

Page 106: ...epth of include nesting allowed The default value is 10 addCgiInitVars UNIX only if present and equal to yes the default is no adds the environment variables defined in the init cgi SAF to the environ...

Page 107: ...http server_id port stats xml iwsstats dtd For more information about the format of the iwsstats xml file see the Netscape Enterprise Server Performance Tuning Sizing and Scaling Guide Parameters Exam...

Page 108: ...that invokes upload file when the request method is PUT Parameters Object name default NameTrans fn assign name from stats xml name stats xml Object Object name stats xml Service fn stats xml Object...

Page 109: ...t specific data in the common log format used by most HTTP servers There is a log analyzer in the extras log_anly directory for Enterprise Server The common log must have been initialized previously b...

Page 110: ...s see flex rotate init Parameters bucket optional common to all obj conf functions Log all accesses to the global log file AddLog fn common log Log accesses from outside our subnet 198 93 5 to nonloca...

Page 111: ...tating logs see flex rotate init Parameters Examples See Also flex init init clf common log flex log flex rotate init Log all accesses to the global log file AddLog fn flex log Log accesses from outsi...

Page 112: ...caused the error and what the value of the QOS statistic was send error Applicable in Error class directives The send error function sends an HTML file to the client in place of a specific HTTP respon...

Page 113: ...r more information see the performance chapter of the Netscape Enterprise Server Administrator s Guide code optional is a three digit number representing the HTTP response status code such as 401 or 4...

Page 114: ...P response status code such as 401 or 407 The recommended value is 503 This can be any HTTP response status code or reason phrase according to the HTTP specification The following is a list of common...

Page 115: ...eating and Using Custom SAFs Overview of NSAPI C Functions Required Behavior of SAFs for Each Directive CGI to NSAPI Conversion Before writing custom SAFs you should familiarize yourself with the requ...

Page 116: ...he server uses the result code from each function to determine how to proceed with processing the request See the section Result Codes on page 119 for details of the result codes SAF Parameters This s...

Page 117: ...list describes the most important fields in this data structure See Chapter 5 NSAPI Function Reference for information about NSAPI routines for manipulating the Session data structure sn client is a...

Page 118: ...Agent If Modified Since received from the client in the HTTP request See Appendix E HyperText Transfer Protocol for more information about request headers This pblock does not normally change througho...

Page 119: ...indicate the cause of the error A SAF returning REQ_ABORTED should also set the HTTP response status code If the server finds an Error directive matching the status code or reason phrase it executes t...

Page 120: ...nction Reference provides information about all of the routines available For examples of custom SAFs see nsapi examples in the server root directory and also see Chapter 6 Examples of Custom SAFs The...

Page 121: ...AFs to do particular things and your SAF must conform to the expectations of the directive for which it was written For details of what each directive expects of its SAFs see the section Required Beha...

Page 122: ...ared objects during runtime to resolve symbols Table 4 1 Libraries Platform Library Windows NT Windows 2000 ns httpd40 dll in addition to the standard Windows libraries HP UX libns httpd40 sl All othe...

Page 123: ...you can use Compaq rpath dir dir Linux Wl rpath dir dir IRIX Wl rpath dir dir Table 4 4 Compiler flags and defines Platform Flags Defines Solaris Sparc DXP_UNIX D_REENTRANT KPIC DSOLARIS Windows NT Wi...

Page 124: ...n function is included in the funcs list For example if you created a shared library animations so that defines two SAFs do_small_anim and do_big_anim and also defines the initialization function init...

Page 125: ...s the desired type value If your new Service SAF is to be invoked only when the requested resource is in a particular directory you might need to define a NameTrans directive that generates a name or...

Page 126: ...by requests to resources in http server name animations small try requesting a valid resource that starts with that URI You should disable caching in your browser so that the server is sure to be acce...

Page 127: ...pter 5 NSAPI Function Reference The main categories of NSAPI functions are Parameter Block Manipulation Routines Protocol Utilities for Service SAFs Memory Management File I O Network I O Threads Ente...

Page 128: ...on phrase protocol_start_response sends the HTTP response and all HTTP headers to the browser Memory Management Memory management routines provide fast platform independent versions of the standard me...

Page 129: ...between simultaneous writes by multiple processes or threads Network I O Network I O functions provide platform independent thread safe network I O routines These routines work with SSL when it s enab...

Page 130: ...such as string manipulation as well as new utilities useful for NSAPI daemon_atrestart UNIX only registers a user function to be called when the server is sent a restart signal HUP or at shutdown uti...

Page 131: ...on for a given virtual server vs_get_id finds the ID of a virtual server vs_get_mime_type determines the MIME type that would be returned in the Content type header for the given URI vs_lookup_config_...

Page 132: ...earlier step in the process For example a PathCheck SAF retrieves values in rq vars which were previously inserted by an AuthTrans SAF This section outlines the expected behavior of SAFs used at each...

Page 133: ...r Authorization header in rq headers which contains the authorization type and uu encoded user and password information If header was not sent return REQ_NOACTION If header exists check authenticity o...

Page 134: ...ghts Check auth type auth user and or auth group in rq vars Return REQ_PROCEED if user and group is authorized for this area ppath in rq vars If not authorized insert WWW Authenticate to rq srvhdrs wi...

Page 135: ...ective in obj conf match the current error Error SAFs do the same as Service SAFs but only in response to an HTTP status error condition AddLog SAFs Purpose Log the transaction to a log file AddLog SA...

Page 136: ...pblock_findval query rq reqpb GET only POST puts query string in body data REMOTE_ADDR pblock_findval ip sn client REMOTE_HOST session_dns sn session_dns sn pblock_findval ip sn client REMOTE_IDENT pb...

Page 137: ...eating Custom SAFs 137 HTTPS_SECRETKEYSIZE pblock_findval secret keysize sn client QUERY pblock_findval query rq reqpb GET only POST puts query string in entity body data SERVER_URL http_uri2url_dynam...

Page 138: ...CGI to NSAPI Conversion 138 Netscape Enterprise Server NSAPI Programmer s Guide April 2002 Draft...

Page 139: ...t Handling Process for a list of the rest of the pre defined SAFs Each function provides the name syntax parameters return value a description of what the function does and sometimes an example of its...

Page 140: ...0 char pointers char name name char CALLOC 100 sizeof char See also FREE REALLOC STRDUP PERM_MALLOC PERM_FREE PERM_REALLOC PERM_STRDUP cinfo_find The cinfo_find function uses the MIME types informatio...

Page 141: ...ructure when you are done using it Parameters char uri is a Universal Resource Identifier URI or local file name Multiple file name extensions should be separated by periods condvar_init The condvar_i...

Page 142: ...turns call crit_exit to surrender ownership of the critical section Syntax void condvar_notify CONDVAR cv Returns void Parameters CONDVAR cv is a condition variable See also condvar_init condvar_termi...

Page 143: ...on variable before calling condvar_wait Syntax void condvar_wait CONDVAR cv Returns void Parameters CONDVAR cv is a condition variable See also condvar_init condvar_notify condvar_terminate crit_init...

Page 144: ...section variable See also crit_init crit_enter crit_terminate crit_init Critical section function that creates and returns a new critical section variable a variable of type CRITICAL Use this functio...

Page 145: ...exit D daemon_atrestart The daemon_atrestart function lets you register a callback function named by fn to be used when the server terminates Use this function when you need a callback function to dea...

Page 146: ...also passed to this function In other words the application at minimum should not issue a read operation based on this pointer that would modify the currency for the PRFileDesc If such a read operatio...

Page 147: ...n initialized by a prior call to fc_open filebuf_buf2sd The filebuf_buf2sd function sends a file buffer to a socket descriptor and returns the number of bytes sent Use this function to send the conten...

Page 148: ...uf buf Returns void Parameters filebuf buf is the file buffer previously opened with filebuf_open Example filebuf_close buf See also filebuf_open filebuf_open_nostat filebuf_buf2sd filebuf_getc filebu...

Page 149: ...of the file which has already been opened int sz is the size in bytes to be used for the buffer Example filebuf buf filebuf_open fd FILE_BUFFERSIZE if buf system_fclose fd See also filebuf_getc filebu...

Page 150: ...n_nostat function you must call the request_stat_path function to retrieve the file information Example filebuf buf filebuf_open_nostat fd FILE_BUFFERSIZE finfo if buf system_fclose fd See also filebu...

Page 151: ...unc_exec pblock pb Session sn Request rq Returns The value returned by the executed function or the constant REQ_ABORTED if no function was executed Parameters pblock pb is the pblock containing the f...

Page 152: ...y and a specified text Syntax int log_error int degree char func Session sn Request rq char fmt Returns 0 if the log entry was created or 1 if the log entry was not created Parameters int degree speci...

Page 153: ...exec M MALLOC The MALLOC macro is a platform independent substitute for the C library routine malloc It normally allocates from the request s memory pool If pooled memory has been disabled in the conf...

Page 154: ...fy the fully qualified domain name Though this requires an extra query you should use it when checking access control net_read The net_read function reads bytes from a specified socket into a specifie...

Page 155: ...o net_write net_write The net_write function writes a specified number of bytes to a specified socket from a specified buffer It returns the number of bytes written Syntax int net_write SYS_NETFD sd c...

Page 156: ...ffer See also netbuf_close netbuf_getc netbuf_grab netbuf_open netbuf_close The netbuf_close function deallocates a network buffer and closes its associated files Use this function when you need to de...

Page 157: ...a can be retrieved from buf inbuf on success This function is used by the function netbuf_buf2sd Syntax int netbuf_grab netbuf buf int sz Returns The number of bytes actually read between 1 and sz if...

Page 158: ...o prepare a pb_param structure to be used in calls to pblock routines such as pblock_pinsert Syntax pb_param param_create char name char value Returns A pointer to a new pb_param structure Parameters...

Page 159: ...e destination pblock Any previous entries in the destination pblock are left intact Syntax void pblock_copy pblock src pblock dst Returns void Parameters pblock src is the source pblock pblock dst is...

Page 160: ...k_create and pblock_copy Syntax pblock pblock_dup pblock src Returns A pointer to a newly allocated pblock Parameters pblock src is the source pblock See also pblock_create pblock_find pblock_findval...

Page 161: ...not FREE it If you want to modify it do a STRDUP and modify the copy Syntax char pblock_findval char name pblock pb Returns A string containing the value associated with the name or NULL if no match...

Page 162: ...har name int value pblock pb Returns A pointer to the new pb_param structure Parameters char name is the name of the new entry int value is the numeric value being inserted into the pblock This parame...

Page 163: ...ironment The function creates one new environment entry for each name value pair in the pblock Use this function to send pblock entries to a program that you are going to execute Syntax char pblock_pb...

Page 164: ...en allocated by MALLOC or REALLOC not by PERM_MALLOC or PERM_REALLOC which allocate from the system heap Each name value pair in the string is separated from its neighbor pair by a space and is in the...

Page 165: ...ate pblock_find pblock_free pblock_nvinsert param_create param_free pblock_str2pblock The pblock_str2pblock function scans a string for parameter pairs adds them to a pblock and returns the number of...

Page 166: ...LLOC and CALLOC both obtain their memory from the system heap Syntax void PERM_CALLOC int num int size Returns A void pointer to a block of memory Parameters int num is the number of elements to alloc...

Page 167: ...s a platform independent substitute for the C library routine malloc It provides allocation of memory that persists after the request that is being processed has been completed If pooled memory has be...

Page 168: ...tr int size Returns A void pointer to a block of memory Parameters void ptr a void pointer to a block of memory created by PERM_MALLOC PERM_CALLOC or PERM_STRDUP int size is the number of bytes to whi...

Page 169: ...FREE STRDUP CALLOC REALLOC prepare_nsapi_thread The prepare_nsapi_thread function allows threads that are not created by the server to act like server created threads This function must be called bef...

Page 170: ...ucture char t is the buffer allocated with MALLOC CALLOC or STRDUP int pos is the position within the buffer at which the headers are to be dumped int tsz is the size of the buffer See also protocol_s...

Page 171: ...because that version has no concept of status If the protocol version is HTTP 1 0 the function sends a status line followed by the response headers Use this function to set up HTTP and prepare the cli...

Page 172: ...e If it finds none it returns Unknown reason The reason string is sent to the client in the HTTP response line Use this function to set the status of the response before calling the function protocol_...

Page 173: ...http server port prefix suffix See protocol_uri2url_dynamic If you want to omit either the URI prefix or suffix use instead of NULL as the value for either parameter Syntax char protocol_uri2url char...

Page 174: ...suffix is the suffix Session sn is the Session Request rq is the Request The Session and Request parameters are the same as the ones passed into your SAF See also protocol_start_response protocol_stat...

Page 175: ...t_get_vs function finds the VirtualServer to which a request is directed The returned VirtualServer is valid only for the current request To retrieve a virtual server ID that is valid across requests...

Page 176: ...formation structure for a specified path or if none is specified the path entry in the vars pblock in the specified Request structure If the resulting file name points to a file that the server can re...

Page 177: ...apping on a specified URI during a specified session Use this function when you want to determine which file would be sent back if a given URI is accessed Syntax char request_translate_uri char uri Se...

Page 178: ...address of the client associated with a specified session into its DNS name It returns a newly allocated string You can use session_maxdns to change the numeric IP address into something more readable...

Page 179: ...s found 1 if the comparison resulted in an invalid expression Parameters char str is the string to be compared char exp is the shell expression wildcard pattern to compare against See also shexp_cmp s...

Page 180: ...e possible values representing match no match and invalid comparison The comparison in contrast to that of the shexp_casecmp function is case sensitive The shexp_match function doesn t perform validat...

Page 181: ...expression but invalid The constant VALID_SXP if exp is a valid shell expression Parameters char exp is the shell expression wildcard pattern to be validated See also shexp_casecmp shexp_match shexp_c...

Page 182: ...rrmsg int param1 Returns A string containing the text of the latest error message that resulted from a system call Do not FREE this string Parameters int param1 is reserved and should always have the...

Page 183: ...flock SYS_FILE fd Returns The constant IO_OKAY if the lock succeeded or the constant IO_ERROR if the lock failed Parameters SYS_FILE fd is the platform independent file descriptor See also system_errm...

Page 184: ...en files that will be read from and written to by your program Syntax SYS_FILE system_fopenRW char path Returns The system independent file descriptor SYS_FILE if the open succeeded or 0 if the open f...

Page 185: ...be used you must open the file using any of the system_fopen functions except system_fopenWA Syntax int system_fread SYS_FILE fd char buf int sz Returns The number of bytes read which may be less than...

Page 186: ...system_fread system_fwrite_atomic system_flock system_ulock system_fclose system_fwrite_atomic The system_fwrite_atomic function writes a specified number of bytes from a specified buffer into a speci...

Page 187: ...uct tm system_gmtime const time_t tp const struct tm res Returns A pointer to a calendar time tm structure containing the GMT time Depending on your system the pointer may point to the data item repre...

Page 188: ...lseek The system_lseek function sets the file position of a file This affects where data from system_fread or system_fwrite is read or written Syntax int system_lseek SYS_FILE fd int offset int whence...

Page 189: ...E fd Returns The constant IO_OKAY if the operation succeeded or the constant IO_ERROR if the operation failed Parameters SYS_FILE fd is the platform independent file descriptor See also system_errmsg...

Page 190: ...me See also system_fclose system_flock system_fopenRO system_fopenRW system_fopenWA system_fwrite systhread_attach The systhread_attach function makes an existing thread into a platform independent th...

Page 191: ...y if the call succeeds Returns NULL if the call did not succeed for example if the systhread_setkey function was never called with the specified key during this session Parameters int key is the value...

Page 192: ...data int key void data Returns void Parameters int key is the priority of the thread void data is the pointer to the string of data to be associated with the value of key See also systhread_current sy...

Page 193: ...riority of the thread Priorities are system dependent int stksz is the stack size in bytes If stksz is zero the function allocates a default size void fn void is the function to call void arg is the a...

Page 194: ...exec struct stat finfo uid_t uid gid_t gid Returns 1 if the file is executable or 0 if the file is not executable Parameters stat finfo is the stat structure associated with a file uid_t uid is the UN...

Page 195: ...not call this function at the same time Use util_chdir2path when you want to make file access a little quicker because you do not need to use a full paths Syntax int util_chdir2path char path Returns...

Page 196: ...ntax char util_env_find char env char name Returns The value of the environment variable if it is found or NULL if the string was not found Parameters char env is the environment char name is the name...

Page 197: ...a name value pair char value is the new value to be stored See also util_env_str util_env_free util_env_find util_env_create util_env_str The util_env_str function creates an environment entry and re...

Page 198: ...tains a description of the error Parameters filebuf buf is the file buffer to be scanned int lineno is used to include the line number in the error message when an error occurs The caller is responsib...

Page 199: ...r agent is not a Netscape browser Parameters char ua is the user agent string from the request headers char major is the major release number to the left of the decimal point char minor is the minor r...

Page 200: ...nd deallocation of a and it should be at least 32 bytes long util_later_than The util_later_than function compares the date specified in a time structure against a date specified in a string If the da...

Page 201: ...til_snprintf The util_snprintf function formats a specified string using a specified format into a specified buffer using the printf style syntax and performs bounds checking It returns the number of...

Page 202: ...he documentation on the printf function for the run time library of your compiler Syntax int util_sprintf char s char fmt Returns The number of characters formatted into the buffer Parameters char s i...

Page 203: ...number of characters placed into s not counting the terminating NULL character Parameters char s is the string buffer to put the text into There is no bounds checking so you must make sure that your b...

Page 204: ...nt n is the number of initial characters to compare See also util_strcasecmp util_uri_escape The util_uri_escape function converts any special characters in the URI into the URI format XX where XX is...

Page 205: ...and also for Windows NT Windows 2000 at the end of the URI Use this function to see if a URI requested by the client is insecure Syntax int util_uri_is_evil char t Returns 1 if the URI is insecure or...

Page 206: ...s_evil util_uri_parse util_vsnprintf The util_vsnprintf function formats a specified string using a specified format into a specified buffer using the vprintf style syntax and performs bounds checking...

Page 207: ...ing using a specified format into a specified buffer using the vprintf style syntax without bounds checking It returns the number of characters in the formatted buffer For more information see the doc...

Page 208: ...faults to NULL for every VirtualServer Syntax int vs_alloc_slot void Returns A slot number on success or 1 on failure See also vs_get_data vs_set_data vs_get_data The vs_get_data function finds the va...

Page 209: ...ualServer vs Returns A pointer the default httpd_object or NULL on failure Do not FREE this object Parameters VirtualServer vs represents the virtual server for which to find the default object See al...

Page 210: ...ttpd_object vs_register_cb vs_get_id The vs_get_id function finds the ID of a VirtualServer The ID of a virtual server is a unique null terminated string that remains constant across configurations No...

Page 211: ...ity to FREE this string Parameters const VirtualServer vs represents the virtual server of interest const char uri is the URI whose MIME type is of interest vs_lookup_config_var The vs_lookup_config_v...

Page 212: ...any virtual servers are destroyed VSDestroyFunc callbacks are called in reverse order that is the first callback registered is the last called Either initfn or destroyfn may be NULL if the caller is n...

Page 213: ...arameters const VirtualServer vs represents the virtual server to set the pointer for int slot is the slot number to store the pointer at void data is the pointer to store See also vs_get_data vs_allo...

Page 214: ...NSAPI Functions in Alphabetical Order 214 Netscape Enterprise Server NSAPI Programmer s Guide April 2002 Draft...

Page 215: ...e process discussed in Chapter 1 Basics of Server Operation and the role of the configuration file obj conf discussed in Chapter 2 Syntax and Use of obj conf Before writing your own SAF check if an ex...

Page 216: ...ialization function in the funcs argument to load modules and also add an Init directive to call the initialization function For example the PathCheck example implements the restrict by acf function w...

Page 217: ...client initially makes a request the username and password are unknown so the AuthTrans function and PathCheck function work together to reject the request since they can t validate the username and...

Page 218: ...example is in the auth c file in the nsapi examples or plugins nsapi examples subdirectory of the server root directory include nsapi h typedef struct char name char pw user_s static user_s user_set...

Page 219: ...ce code for two example NameTrans functions explicit_pathinfo This example allows the use of explicit extra path information in a URL https_redirect This example redirects the URL if the client is a p...

Page 220: ...the vars field in the request object rq vars CGI programs can access this information through the PATH_INFO environment variable One side effect of explicit_pathinfo is that the SCRIPT_NAME CGI enviro...

Page 221: ...k_findval separator pb Server variables char ppath pblock_findval ppath rq vars Temp var char t Verify correct usage if sep log_error LOG_MISCONFIG explicit pathinfo sn rq missing parameter need root...

Page 222: ...heck usage if from url log_error LOG_MISCONFIG https redirect sn rq missing parameter need from url return REQ_ABORTED Use wildcard match to see if this path is one we should redirect if shexp_cmp ppa...

Page 223: ...ct_by_acf gets the IP address of the host that is making the request and checks if it is on the list If the host is on the list it is allowed access otherwise access is denied For simplicity the stdio...

Page 224: ...include base util h util_sprintf include frame log h log_error include frame protocol h protocol_status The longest line we ll allow in an access control file define MAX_ACF_LINE 256 Used to free sta...

Page 225: ...ystem_errmsg pblock_nvinsert error err pb return REQ_ABORTED Initialize hosts array num_hosts 0 hosts char MALLOC 1 sizeof char hosts 0 NULL while fgets buf MAX_ACF_LINE f Blast linefeed that stdio he...

Page 226: ...rbidden and return an error protocol_status sn rq PROTOCOL_FORBIDDEN NULL return REQ_ABORTED ObjectType Example The example in this section demonstrates how to implement html2shtml a custom SAF that i...

Page 227: ...in the Init section of the magnus conf file Init fn load modules shlib yourlibrary funcs html2shtml To execute the custom SAF during the request response process for some object add the following lin...

Page 228: ...len strcpy npath baselen shtml If it s not there don t do anything if stat npath finfo 1 FREE npath return REQ_NOACTION Got it do the switch FREE path value path value npath The server caches the stat...

Page 229: ...e following line to that object in the obj conf file Service type text html fn simple service The type text html argument indicates that this function is invoked during the Service stage only if the c...

Page 230: ...ough we would expect the ObjectType stage to set the content type set it here just to be completely sure that it gets set to text html param_free pblock_remove content type rq srvhdrs pblock_nvinsert...

Page 231: ...of lines each of which specifies a filename followed by a content type for example one gif image gif To load the shared object containing your function add the following line at the beginning of the m...

Page 232: ...o call brief init to open the log file add the following line to the Init section in magnus conf This line must come after the one that loads the library containing brief init Init fn brief init file...

Page 233: ...ly a file name pb return REQ_ABORTED logfd system_fopenWA fn if logfd SYS_ERROR_FD pblock_nvinsert error brief init please supply a file name pb return REQ_ABORTED Close log file when server is restar...

Page 234: ...ded as an example in case you want to define your own SAFs for quality of service handling For more information see the Netscape Enterprise Server Performance Tuning Sizing and Scaling Guide Installin...

Page 235: ...1024 PRBool ours PR_FALSE PRInt32 vs_bw 0 vs_bwlim 0 vs_bw_ef 0 vs_conn 0 vs_connlim 0 vs_conn_ef 0 vsc_bw 0 vsc_bwlim 0 vsc_bw_ef 0 vsc_conn 0 vsc_connlim 0 vsc_conn_ef 0 srv_bw 0 srv_bwlim 0 srv_bw_...

Page 236: ...andwidth limit of d Current VS bandwidth d P vs_bwlim vs_bw if vs_connlim vs_conn vs_connlim VS connection limit was exceeded display it ours PR_TRUE sprintf error P Virtual server connection limit of...

Page 237: ...ontent type text html rq srvhdrs protocol_start_response sn rq net_write sn csd error strlen error return REQ_PROCEED else this 503 didn t come from a QOS SAF failure let someone else handle it return...

Page 238: ...vs_connections_enforced vs_conn_ef apb decode vsclass_bandwidth vsc_bw apb decode vsclass_connections vsc_conn apb decode vsclass_bandwidth_limit vsc_bwlim apb decode vsclass_bandwidth_enforced vsc_bw...

Page 239: ...and enforce it ok PR_FALSE if vsc_bwlim vsc_bw vsc_bwlim bandwidth limit was exceeded log it ereport LOG_FAILURE Virtual server class bandwidth limit of d exceeded Current VSCLASS bandwidth d vsc_bwli...

Page 240: ...lim srv_bw if srv_bw_ef and enforce it ok PR_FALSE if srv_connlim srv_conn srv_connlim connection limit was exceeded log it ereport LOG_FAILURE Global connection limit of d exceeded Current global con...

Page 241: ...pt for the Init SAFs the directives in magnus conf specify a variable and a value for example The order of the directives is not important This chapter lists the global settings that can be specified...

Page 242: ...t parameter For the UNIX platform if LateInit is set to yes the function is executed by the child process after it is forked from the parent If LateInit is set to no or is not provided the function is...

Page 243: ...erver nt console init enables the Windows NT Windows 2000 console which is the command line shell that displays standard output and error streams perf init enables system performance measurement via p...

Page 244: ...The minimum size of a column if the value is non zero is specified by the length of its title for example the minimum size of the Date column is 5 the length of Date plus one space If you set a non z...

Page 245: ...dump function This function works only if the perf init function is enabled For more information about performance buckets see the Netscape Enterprise Server Performance Tuning Sizing and Scaling Guid...

Page 246: ...ntry to expire specified in seconds can range from 1 second to 1 year the default value is 1200 seconds 20 minutes Parameters Example flex init Applicable in Init class directives The flex init functi...

Page 247: ...one the renamed original log file is left for you to use For information on rotating log files see flex rotate init The flex init function has three parameters one that names the log file one that spe...

Page 248: ...contain spaces so they should be bounded by escaped quotes If no format parameter is specified for a log file the common log format is used Ses client ip Req vars auth user SYSDATE Req reqpb clf requ...

Page 249: ...rmatting Flex log option Component Client Host name unless iponly is specified in flex log or DNS name is not available or IP address Ses client ip Client DNS name Ses client dns System date SYSDATE F...

Page 250: ...authorized user Req vars auth user Value of a cookie Req headers cookie name Value of any variable in Req vars Req vars varname Virtual Server ID vsid Init fn flex init access usr netscape servers ht...

Page 251: ...irectives The flex rotate init function configures log rotation for all log files on the server including error logs and the common log flex log and record useragent AddLog SAFs Call this function in...

Page 252: ...ean them up as necessary to free up disk space rotate start Indicates the time to start rotation This value is a 4 digit string indicating the time in 24 hour format for example 0900 indicates 9 am wh...

Page 253: ...instance s config directory private Cgistub then bin https bin Cgistub Use the first directory to house an suid Cgistub that is a Cgistub owned by root which has the set user ID on exec bit set Use th...

Page 254: ...d for UNIX send the HUP signal and then restart the server The server first looks for the log file by name and if it doesn t find it creates a new one the renamed original log file is left for you to...

Page 255: ...unix home find links load modules Applicable in Init class directives The load modules function loads a shared library or Dynamic Link Library into the server code Specified functions from the library...

Page 256: ...uncs is a comma separated list of the names of the functions in the shared library or dynamic link library to be made available for use by other Init directives or by Service directives in obj conf Th...

Page 257: ...r Performance Tuning Sizing and Scaling Guide Parameters Example See Also define perf bucket pool init Applicable in Init class directives stdout Directs output to the Windows NT Windows 2000 console...

Page 258: ...an up If you want persistent memory allocation add the prefix PERM_ to the name of each routine PERM_MALLOC PERM_REALLOC PERM_CALLOC PERM_STRDUP and PERM_FREE Parameters Example register http method A...

Page 259: ...onnection the server checks to see if the method that it received is known to it If the server does not recognize the method it returns a 501 Method Not Implemented error message Parameters methods is...

Page 260: ...ETHOD1 update interval period in seconds between statistics updates within the server Set higher for better performance lower for more frequent updates The minimum value is 1 the default is 5 virtual...

Page 261: ...or plug ins On Windows NT Windows 2000 the default native pool is always being used and Enterprise Server uses fibers user scheduled threads for initial request processing Using custom additional pool...

Page 262: ...le ServerID ServerRoot ServerString TempDir TempDirSecurity User ExtraPath Appends the specified directory name to the PATH environment variable This is used for configuring Java on Windows NT Windows...

Page 263: ...specify a value Syntax NetSiteRoot path ServerConfigurationFile Specifies the location of the virtual server configuration file Syntax ServerConfigurationFile path Default ServerConfigurationFile serv...

Page 264: ...NIX this directory must be owned by and writable by the user the server runs as See also the directives User and TempDirSecurity Syntax TempDir path Default tmp UNIX TEMP environment variable for Wind...

Page 265: ...er account you specify should have read permission to the server s root and subdirectories The user account should have write access to the logs directory and execute permissions to any CGI programs T...

Page 266: ...h as File Not Found Values are en English fr French de German or ja Japanese Default The default is en DefaultCharSet For an international version of the server this directive specifies the default ch...

Page 267: ...pecifies whether the server performs DNS lookups on clients that access the server When a client connects to your server the server knows the client s IP address but not its host name for example it k...

Page 268: ...uest completes The previous backlog is tracked so that if it is seen to be increasing over time and if the increase is greater than the ThreadIncrement value and the number of session threads minus th...

Page 269: ...etion packets from the NSPR I O completion port By default NSPR uses the main native thread to perform these tasks On a multiprocessor host however you may need to create additional native threads to...

Page 270: ...ption devices and 300 seconds for those that do KeepAliveThreads This directive determines the number of threads in the keep alive subsystem It is recommended that this number be a small multiple of t...

Page 271: ...ads By setting KernelThreads to 1 on you ensure that the server uses only kernel level threads not user level threads By setting KernelThreads to 0 off you ensure that the server uses only user level...

Page 272: ...s are available at a listen socket after accepting a connection but before sending the response to the request Use this directive when the server will be handling requests that take a long time to han...

Page 273: ...s Default The default value is determined by the operating system Typical defaults are 4096 4K 8192 8K StackSize Determines the maximum stack size for each request handling thread Default The most fav...

Page 274: ...on lists the directives for controlling the size of the native kernel thread pool You can also control the native thread pool by setting the system variables NSCP_POOL_STACKSIZE NSCP_POOL_THREADMAX an...

Page 275: ...l Default 1 NativePoolQueueSize Determines the number of threads that can wait in the queue for the thread pool If all threads in the pool are busy then the next request handling thread that needs to...

Page 276: ...GI processes Note that on Windows NT Windows 2000 platforms init cgi time out does not work so you must use CGIExpirationTimeout Default 0 CGIStubIdleTimeout This directive causes the server to kill a...

Page 277: ...that are started by default The first CGIStub process is not started until a CGI program has been accessed Note that if you have an init cgi directive in the magnus conf file the minimum number of CGI...

Page 278: ...use the syslog facility Syntax ErrorLog logfile The logfile can be either a full path or file name On UNIX systems it can be the keyword SYSLOG it must be in all capital letters Default There is no d...

Page 279: ...s share the same log file Default off PidLog PidLog specifies a file in which to record the process ID pid of the base server process Some of the server support programs assume that this log is in the...

Page 280: ...continue to be processed even when statistics gathering is disabled Syntax StatsUpdateInterval number_of_seconds Default 10 seconds Example StatsUpdateInterval 20 ACL This section lists the directives...

Page 281: ...AP is not likely to change often use a large number Default 120 ACLUserCacheSize ACLUserCacheSize determines the number of users in the User Cache Default 200 ACLGroupCacheSize ACLGroupCacheSize deter...

Page 282: ...rmed when the CRL is downloaded Therefore an already downloaded CRL can become older than its Next Update time in the interval between updates and still be considered valid This feature does not apply...

Page 283: ...ind out how often a particular CRL is updated The value of max_age is the time in minutes you want Enterprise Server to wait past the time specified in the Next Update field before determining that th...

Page 284: ...evocation on off Default No default This directive is added to magnus conf only after automatic CRL downloads are enabled and you have configured at least one CRL for automatic downloading see the CRL...

Page 285: ...limit Syntax SSLCacheEntries number If the number is 0 the default value which is 10000 is used SSLClientAuthDataLimit Specifies the maximum amount of application data in bytes that is buffered during...

Page 286: ...SL3 session becomes invalid The default value is 86400 24 hours If the SSL3SessionTimeout directive is specified the value of seconds is silently constrained to be between 5 and 86400 seconds Chunked...

Page 287: ...stBufferSize size The size value is the number of bytes Default The default value is 8192 ChunkedRequestTimeout The ChunkedRequestTimeout directive determines the default timeout for un chunking reque...

Page 288: ...d using the daemon_atrestart function when the server is restarting or shutting down Values are on off yes no true or false Default no HTTPVersion The current HTTP version used by the server in the fo...

Page 289: ...fies the umask value used by the NSAPI functions System_fopenWA and System_fopenRW to open files in different modes Valid values for this directive are standard UNIX umask values For more information...

Page 290: ...Miscellaneous 290 Netscape Enterprise Server NSAPI Programmer s Guide April 2002 Draft...

Page 291: ...er xml File Elements in server dtd and server xml Virtual Server Selection for Request Processing User Database Selection The Netscape LDAP Schema The server dtd File The server dtd file defines the v...

Page 292: ...A are XML data types For more information about XML see the XML specification at http www w3 org TR REC xml The server xml File The server xml file configures the addresses and ports that the server l...

Page 293: ...ile nes60 httpacl generated https server example com acl VSCLASS id defaultclass objectfile obj conf rootobject default VARS docroot nes60 docs VS id server example com connections group1 mime mime1 a...

Page 294: ...lids acl1 VARS docroot nes60 docs class2 example webapps_file web apps xml webapps_enable on USERDB id default database default VS This variable allows different document root directories to be assign...

Page 295: ...ing variables are used by the Administration Server Server Manager Class Manager and Virtual Server Manager Unlike the id variable they are not predefined in the server and they can be overridden docr...

Page 296: ...ava id VSCLASS SERVER Variables lower in the tree override variables from above For example it is possible to set a variable for a class of virtual servers and override it with a definition of the sam...

Page 297: ...295 Variables Used in the Interface on page 295 Subelements none Attributes none qosactive Enables quality of service features which let you set limits on server entities or view server statistics fo...

Page 298: ...P address of the listen socket Can be in dotted pair or IPv6 notation Can also be any for INADDR_ANY Configuring a listen socket to listen on any is required if more than one CONNECTIONGROUP is config...

Page 299: ...he legal values are on or off The default is on acceptorthreads optional Number of acceptor threads for the listen socket The recommended value is the number of processors in the machine The default i...

Page 300: ...id attribute of the default virtual server for this particular connection group servername Tells the server what to put in the host name section of any URLs it sends to the client This affects URLs th...

Page 301: ...erver tries SSL3 encryption first If that fails the server tries SSL2 encryption ssl3tlsciphers optional A space separated list of the SSL3 ciphers used with the prefix to enable or to disable for exa...

Page 302: ...de April 2002 Draft id Internal name for the MIME types listing Used in a VS element to define the MIME types used by the virtual server The MIME types name cannot begin with a number file The name of...

Page 303: ...ed list of ACL files Each ACL file must have a unique name For information about the format of an ACL file see the Netscape Enterprise Server Administrator s Guide The name of the default ACL file is...

Page 304: ...erver Manager acceptlanguage optional If on the server parses the Accept Language header and sends an appropriate language version based on which language the client can accept You should set this val...

Page 305: ...ACLFILE elements separated by spaces Specifies the ACL file s used by the virtual server errorlog optional Specifies a log file for virtual server specific error messages acceptlanguage optional If o...

Page 306: ...in obj conf on page 35 A connection group is first selected as follows If the listen socket is configured to listen on a particular IP address it can contain only one connection group and that group i...

Page 307: ...wing changes have been made in Enterprise Server Virtual servers in server xml reference ACL files The magnus conf file no longer references ACL files The ACL file s database attribute does not map to...

Page 308: ...ent and the database is not schema compliant the accesses happen relative to the base DN in the dbswitch conf entry as in previous Enterprise Server versions The Netscape LDAP Schema You can use the d...

Page 309: ...ary class inetSubscriber which is used for account management purposes If an inetUserStatus attribute is present in an entry and has a value of inactive or deleted the entry is ignored Groups are loca...

Page 310: ...The Netscape LDAP Schema 310 Netscape Enterprise Server NSAPI Programmer s Guide April 2002 Draft...

Page 311: ...ta structure in naspi h check if an accessor function exists for it For information about the privatization of some data structures in iPlanet Web Server 4 x see Privatization of Some Data Structures...

Page 312: ...of data structures defined in nsapi_pvt h will not be source compatible with versions 4 x and 6 x that is it will be necessary to include nsapi_pvt h in order to build such plugins from source There...

Page 313: ...ing and deleting entries See the functions whose names start with pblock_ in Chapter 5 NSAPI Function Reference You should not need to write code that access pblock data fields directly pb_entry The p...

Page 314: ...ine This member must be accessed through the session_dns function call request Under HTTP protocol there is only one request per session The Request structure contains the variables that apply to the...

Page 315: ...r platform s implementation but the basic outline of the structure is as follows typedef struct Server working variables pblock vars The method URI and protocol revision of this request block reqpb Pr...

Page 316: ..._t st_ino inode number short st_mode mode bits short st_nlink number of links to file short st_uid owner s user id short st_gid owner s group id dev_t st_rdev for special files off_t st_size file size...

Page 317: ...har type Identifies what kind of data is in the file char encoding encoding identifies any compression or other content independent transformation that s been applied to the file such as uuencode char...

Page 318: ...cinfo 318 Netscape Enterprise Server NSAPI Programmer s Guide April 2002 Draft...

Page 319: ...maps the extensions html and htm to the type text html type text html exts htm html When the Netscape Enterprise Server receives a request for a resource from a client it uses the MIME type mappings t...

Page 320: ...rent SAF such as force type to determine the type then the MIME types table is not used for that particular request For more details of the ObjectType step see Chapter 2 Syntax and Use of obj conf How...

Page 321: ...ce What Does the Client Do with the MIME Type The Service function generates the data and sends it to the client that made the request When the server sends the data to the client it also sends header...

Page 322: ...MIME types file identifies the file format and must read Netscape Communications Corporation MIME Information Other non comment lines have the following format type type subtype exts file extensions...

Page 323: ...x aiff exts aif aiff aifc type audio x wav exts wav type image gif exts gif type image ief exts ief type image jpeg exts jpeg jpg jpe type image tiff exts tiff tif type image x rgb exts rgb type image...

Page 324: ...Sample MIME Types File 324 Netscape Enterprise Server NSAPI Programmer s Guide April 2002 Draft...

Page 325: ...cters If you want to use one of these characters without the special meaning precede it with a backslash character Wildcard Patterns Table C 1 Wildcard patterns Pattern Use Match zero or more characte...

Page 326: ...ters Matches any string with a period in it example Matches any string except those starting with example example com quark example com Matches any host from domain example com except for a single hos...

Page 327: ...e strftime C library routine but not identical Table D 1 Symbol Meaning a Abbreviated weekday name 3 chars d Day of month as decimal number 01 31 S Second as decimal number 00 59 M Minute as decimal n...

Page 328: ...s l Hour in 12 hour format 1 12 without leading zeros m Month as decimal number 01 12 n line feed p A M P M indicator for 12 hour clock R Time H M r Time I M S p t tab U Week of year as decimal number...

Page 329: ...onse which it sends to the browser The server then closes the connection This appendix provides a short introduction to a few HTTP basics For more information on HTTP see the IETF home page at http ww...

Page 330: ...e commonly used methods include the following GET Requests the specified resource such as a document or image HEAD Requests only the header information for the document POST Requests that the server a...

Page 331: ...and Reason Phrase The server sends back a status code which is a three digit numeric code The five categories of status codes are 100 199 a provisional response 200 299 a successful transaction 300 3...

Page 332: ...example HTTP 1 1 requires a host to be specified either in the Host header or as part of the URI on the request line 401 Unauthorized The user requested a document but didn t provide a valid username...

Page 333: ...width or connection limits were attained The server will then serve requests with that code See the quality of service section Table E 3 Common response headers Response header Description Server The...

Page 334: ...the connection to indicate the end of the response Deferred header writing Response headers are written out as late as possible to give the servlets a chance to generate their own headers for example...

Page 335: ...UseOutputStreamSize ChunkedRequestBufferSize and ChunkedRequestTimeout parameters also have equivalent magnus conf directives see Chunked Encoding on page 286 The obj conf parameters override the magn...

Page 336: ...Buffered Streams 336 Netscape Enterprise Server NSAPI Programmer s Guide April 2002 Draft...

Page 337: ...s less frequently A footer which also changes for every request Without this feature a plugin would have to generate the whole page for every request unless an IFRAME is used where the header or foote...

Page 338: ...thin the web server system machine the plugin can generate the header and footer and call the fc_net_write function along with the file name This appendix lists the most important functions a results...

Page 339: ...mparator function PRUint32 maxEntriesp is the maximum number of entries possible in the cache for a given hdl PRIntervalTime maxAgep is the maximum amount of time that an entry is valid If 0 the cache...

Page 340: ...ength of the key in bytes PRIntervalTime timeout is the expiration time of this entry If a value of 0 is passed the maxAge value passed to dr_cache_init is used Entry entry is the not NULL entry to be...

Page 341: ...is passed and the entry is present in the cache dr_net_write sends out the response even if the entry has expired However if the entry is not found dr_net_write returns DR_ERROR If ref passed to dr_ca...

Page 342: ...s DR_EXPIR if the cache has expired If the calling function has not provided a refresh function and this flag is not used DR_ERROR is returned DR_IGNORE ignores cache expiration and sends out the cach...

Page 343: ...ytes which can be 0 PRUint32 flags is ORed directives for this function see Flags PRIntervalTime timeout is the timeout before this function aborts Request rq is a pointer to the request Session sn is...

Page 344: ...344 Netscape Enterprise Server NSAPI Programmer s Guide April 2002 Draft...

Page 345: ...CLUserCacheSize page 281 AdminLanguage page 266 AsyncDNS page 267 C CGIExpirationTimeout page 276 CGIStubIdleTimeout page 276 CGIWaitPid UNIX Only page 276 ChildRestartCallback page 288 ChunkedRequest...

Page 346: ...efaultCharSet page 266 DefaultLanguage page 266 define perf bucket page 245 DNS page 267 dns cache init page 246 E ErrorLog page 278 ErrorLogDateFormat page 278 ExtraPath page 262 F flex init page 246...

Page 347: ...ge 270 K KeepAliveThreads page 270 KeepAliveTimeout page 270 KernelThreads page 271 L ListenQ page 271 load modules page 255 LogFlushInterval page 279 LogVerbose page 279 LogVsId page 279 M MaxCGIStub...

Page 348: ...NativePoolStackSize page 275 NetSiteRoot page 263 nt console init page 256 P perf init page 257 PidLog page 279 pool init page 257 PostThreadsEarly page 272 R RcvBufSize page 272 register http method...

Page 349: ...LClientAuthTimeout page 285 SSLSessionTimeout page 285 StackSize page 273 stats init page 260 StrictHttpHeaders page 273 T TempDir page 264 TempDirSecurity page 264 TerminateTimeout page 273 ThreadInc...

Page 350: ...350 Netscape Enterprise Server NSAPI Programmer s Guide April 2002 Draft...

Page 351: ...d SAFs For Init SAFs see Appendix G Alphabetical List of Directives in magnus conf A add footer page 86 add header page 87 append trailer page 88 assign name page 56 B basic auth page 51 basic ncsa pa...

Page 352: ...D deny existence page 66 document root page 57 F find index page 67 find links page 67 find pathinfo page 68 flex log page 110 force type page 78 G get client cert page 69 get sslid page 54 H home pa...

Page 353: ...of Pre defined SAFs 353 K key toosmall page 93 L list dir page 94 load config page 70 M make dir page 95 N nt uri clean page 73 ntcgicheck page 74 P pfx2dir page 59 Q qos error page 113 qos handler p...

Page 354: ...rename file page 98 require auth page 74 S send cgi page 99 send error page 112 send file page 101 send range page 103 send shellcgi page 103 send wincgi page 104 service dump page 105 set default ty...

Page 355: ...Appendix H Alphabetical List of Pre defined SAFs 355 T type by exp page 81 type by extension page 82 U unix home page 64 unix uri clean page 77 upload file page 108...

Page 356: ...356 Netscape Enterprise Server NSAPI Programmer s Guide April 2002 Draft...

Page 357: ...ample of custom SAF 232 flow of control 43 function descriptions 109 requirements for SAFs 135 summary 30 AdminLanguage magnus conf directive 266 alphabetical reference magnus conf variables 345 NSAPI...

Page 358: ...mp 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_fw...

Page 359: ...rs 22 bucket parameter 49 buffered streams 334 buffer size parameter 247 buffers per file parameter 247 builtin SAFs 47 C cache enabling memory allocation pool 257 CALLOC API function 140 case sensiti...

Page 360: ...conf 268 ConnQueueSize magnus conf directive 269 CONTENT_LENGTH environment variable 136 CONTENT_TYPE environment variable 136 convergence tree auxiliary class inetSubscriber 309 in LDAP schema 308 o...

Page 361: ...dynamic reconfiguration 22 E enc parameter 79 80 81 319 encoding chunked 286 enforcebandwidth attribute 305 enforceconnections attribute 305 Enterprise Server see server environment variables and ini...

Page 362: ...ction 67 find links function 67 find pathinfo function 68 find pathinfo forward parameter 56 60 flexible logging 246 flex init function 246 flex log function 110 flex rotate init function 251 flock pa...

Page 363: ...nt 306 for VS Virtual Server element 304 for VSCLASS element 303 id variable 295 imagemap function 89 include directory for SAFs 121 index common function 90 indexing fancy 243 index names parameter 6...

Page 364: ...ket element 298 M magnus conf 20 241 alphabetical list of directives 345 directives in 241 miscellaneous directives 288 make dir function 95 MALLOC API function 153 matching special characters 325 mat...

Page 365: ...e parameter 101 nostat parameter 57 NSAPI alphabetical function reference 139 CGI environment variables 135 data structures reference 311 functions overview 127 using 25 NSAPI functions 139 nsapi h 12...

Page 366: ...rol 37 function descriptions 65 requirements for SAFs 134 summary 29 patterns 325 pb SAF parameter 116 pb_entry NSAPI data structure 313 pb_param NSAPI data structure 314 pblock NSAPI data structure 3...

Page 367: ...S element 305 qosrecomputeinterval attribute 297 quality of service example code 234 QUERY environment variable 137 query parameter 83 QUERY_STRING environment variable 136 query handler function 95 q...

Page 368: ...bject attribute 304 rotating logs 251 rq SAF parameter 117 rq headers 118 rq reqpb 118 rq srvhdrs 118 rq vars 118 RqThrottle magnus conf directive 272 RqThrottleMin magnus conf directive 273 rules for...

Page 369: ...directive 42 directives for new SAFs plugins 126 example of custom SAF 228 examples 40 flow of control 40 function descriptions 83 requirements for SAFs 134 summary 30 service dump function 105 sessi...

Page 370: ...n settings in magnus conf 277 stats init function 260 StatsUpdateInterval directive 280 STRDUP API function 181 streams buffered 334 StrictHttpHeaders magnus conf directive 273 string creating a copy...

Page 371: ...on 261 threads settings in magnus conf 268 tildeok parameter 73 time formats 327 timefmt parameter 89 TLS determining if enabled 301 tls attribute 301 TLS rollback determining if enabled 301 tlsrollba...

Page 372: ...01 util_snprintf API function 201 util_sprintf API function 202 util_strcasecmp API function 202 util_strftime 327 API function 203 util_strncasecmp API function 204 util_uri_escape API function 204 u...

Page 373: ...b API function 212 vs_set_data API function 212 vs_translate_uri API function 213 VSCLASS element 303 definition in server dtd file 292 vsnprintf see util_vsnprintf vsprintf see util_vsprintf W webapp...