Netscape ENTERPRISE SERVER 6.0, Manual

Page 1: ...NSAPI Programmer s Guide Netscape Enterprise Server Version6 0 November 2001...

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: ...teps in the Request Handling Process 22 Directives for Handling Requests 23 Writing New Server Application Functions 23 Chapter 2 Syntax and Use of obj conf 25 Server Instructions in obj conf 25 Summa...

Page 4: ...Examples 43 Chapter 3 Predefined SAFs and the Request Handling Process 45 The bucket Parameter 47 AuthTrans Stage 48 basic auth 49 basic ncsa 51 get sslid 52 qos handler 52 NameTrans Stage 53 assign n...

Page 5: ...8 key toosmall 89 list dir 90 make dir 91 query handler 91 remove dir 92 remove file 93 rename file 94 send cgi 95 send file 97 send range 99 send shellcgi 99 send wincgi 100 service dump 101 shtml_se...

Page 6: ...Service SAFs 124 Memory Management 125 File I O 125 Network I O 126 Threads 126 Enterprise ServerUtilities 127 Virtual Server 127 Required Behavior of SAFs for Each Directive 128 Init SAFs 129 AuthTr...

Page 7: ...tbuf_getc 152 netbuf_grab 153 netbuf_open 153 param_create 154 param_free 154 pblock_copy 155 pblock_create 155 pblock_dup 156 pblock_find 156 pblock_findval 157 pblock_free 157 pblock_nninsert 158 pb...

Page 8: ...valid 177 STRDUP 177 system_errmsg 178 system_fclose 178 system_flock 179 system_fopenRO 179 system_fopenRW 180 system_fopenWA 180 system_fread 181 system_fwrite 181 system_fwrite_atomic 182 system_gm...

Page 9: ...vil 201 util_uri_parse 201 util_uri_unescape 202 util_vsnprintf 202 util_vsprintf 203 vs_alloc_slot 204 vs_get_data 204 vs_get_default_httpd_object 205 vs_get_doc_root 205 vs_get_httpd_objset 206 vs_g...

Page 10: ...Examples 230 Installing the Example 230 Source Code 230 Chapter 7 Syntax and Use of magnus conf 237 Init SAFs 238 Enterprise Servercindex init 239 define perf bucket 241 dns cache init 242 flex init...

Page 11: ...UNIX Only 266 PostThreadsEarly 266 RcvBufSize 266 RqThrottle 266 RqThrottleMin 267 SndBufSize 267 StackSize 267 StrictHttpHeaders 267 TerminateTimeout 268 ThreadIncrement 268 UseNativePoll UNIX only 2...

Page 12: ...StreamSize 277 ChunkedRequestBufferSize 278 ChunkedRequestTimeout 278 Miscellaneous 279 ChildRestartCallback 279 HTTPVersion 279 MaxRqHeaders 279 Umask UNIX only 280 Chapter 8 Virtual Server Configura...

Page 13: ...rmining the MIME Type 308 How the Type Affects the Response 308 What Does the Client Do with the MIME Type 309 Syntax of the MIME Types File 310 Sample MIME Types File 310 Appendix C Wildcard Patterns...

Page 14: ...ing Functions 325 dr_cache_destroy 326 dr_cache_init 327 dr_cache_refresh 327 dr_net_write 328 fc_net_write 330 Appendix G Alphabetical List of NSAPI Functions and Macros 333 Appendix H Alphabetical L...

Page 15: ...initialization tasks and to process client requests Chapter 2 Syntax and Use of obj conf This chapter goes into detail on the configuration file obj conf The chapter discusses the syntax and use of d...

Page 16: ...xtensions to file types Appendix C Wildcard Patterns This appendix lists the wildcard patterns you can use when specifying values in obj conf various predefined SAFs and in some NSAPI functions Append...

Page 17: ...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 18: ...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 19: ...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 20: ...erver 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 spec...

Page 21: ...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 22: ...rans 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...

Page 23: ...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 24: ...Writing New Server Application Functions 24 Netscape Enterprise Server NSAPI Programmer s Guide November 2001...

Page 25: ...The sections in this chapter are Server Instructions in obj conf The Object Tag Variables Defined in server xml Flow of Control in obj conf Syntax Rules for Editing obj conf About obj conf Directive E...

Page 26: ...pter 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 Here...

Page 27: ...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 28: ...oes 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 resourc...

Page 29: ...athname that results from the NameTrans stage matches the ppath attribute of another object When the server has been alerted to use an object other than the default object it processes the directives...

Page 30: ...his physical pathname matches the ppath attribute of another object in obj conf the server switches to processing the directives in that object before processing the remaining ones in the default obje...

Page 31: ...n define variables in the server xml file and reference them in an obj conf file For example the following server xml code defines and uses a variable called docroot DOCTYPE SERVER SYSTEM server dtd A...

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

Page 33: ...er the one that calls document root it would never be executed with the result that the resultant directory pathname would be D netscape server4 docs cgi not mycgi This illustrates why the directive t...

Page 34: ...translates the requested URL to the pathname D Netscape Server4 docs internalplan1 html In this case the partial path internal matches the path D Netscape Server4 docs internalplan1 html So now the s...

Page 35: ...he 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 different attribute such...

Page 36: ...MIME type then 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...

Page 37: ...ives 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 in the default o...

Page 38: ...when the server receives a request for http server_name servlet doCalculation class This example assumes that servlets have been activated and the directory D netscape server4 docs servlet has been r...

Page 39: ...e type value that was set by the ObjectType directive So the server goes ahead and executes this Service directive which calls the NSServletService function This function invokes the requested file as...

Page 40: ...nal The invoked 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 di...

Page 41: ...rective 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 wrong way round eve...

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

Page 43: ...ice AddLog Error Object Object If any line of any example begins with a different word in the manual the line is wrapping in a way that it does not in the actual file In some cases this is due to line...

Page 44: ...About obj conf Directive Examples 44 Netscape Enterprise Server NSAPI Programmer s Guide November 2001...

Page 45: ...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 46: ...ic auth basic ncsa get sslid qos handler NameTrans Stage assign name document root home page pfx2dir redirect strip params unix home PathCheck Stage check acl deny existence find index find links find...

Page 47: ...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 48: ...on 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 that...

Page 49: ...c server authorization scheme This function is usually used in conjunction with the PathCheck class function require auth Parameters auth type specifies the type of authorization to be used This shoul...

Page 50: ...password 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 only parameters in the...

Page 51: ...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 52: ...hTrans 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 Q...

Page 53: ...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 54: ...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 affecte...

Page 55: ...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 56: ...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 sp...

Page 57: ...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 58: ...ind pathinfo 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 p...

Page 59: ...name whatever is translated to a request for http tmpserver whatever NameTrans fn pfx2dir from icons happy dir users nikki images NameTrans fn pfx2dir find pathinfo forward from cgi bin dir export hom...

Page 60: ...trip params unix home Applicable in NameTrans class directives UNIX Only The unix home function translates user names typically of the form username into the user s home directory on the server s UNIX...

Page 61: ...e executed in order The following PathCheck class functions are described in detail in this section check acl checks an access control list for authorization deny existence indicates that a resource w...

Page 62: ...keysize ssl logout invalidates the current SSL session in the server s SSL session cache unix uri clean denies access to requests with unsafe path names by indicating not found check acl Applicable i...

Page 63: ...ndex file If no index file is found the server generates a directory listing Note that if the file obj conf has a NameTrans directive that calls home page and the requested directory is the root direc...

Page 64: ...parated list of index file names to look for Use spaces only if they are part of a file name Do not include spaces before or after the commas This list is case sensitive if the file system is case sen...

Page 65: ...that match a specified pattern It only works when SSL is enabled on the server If the certificate is present or obtained from the SSL3 session the function returns REQ_NOACTION allowing the request to...

Page 66: ...encoded X 509 certificate is placed in the parameter auth cert in the Request vars pblock and the function returns REQ_PROCEED allowing the request to proceed require controls whether failure to get...

Page 67: ...est for the resource D netscape server4 docs somefile html does not trigger the search in this case since the requested resource is in a parent directory of the base directory the top most directory i...

Page 68: ...e tree than the base directory the load config function is not invoked This is because the base directory specifies the highest level directory for which requests will invoke the load config function...

Page 69: ...Windows NT Only The nt uri clean function denies access to any resource whose physical path contains or these are potential security problems Parameters basedir optional specifies base directory This...

Page 70: ...that has the extension cgi Parameters Examples See Also init cgi send cgi send wincgi send shellcgi tildeok if present allows tilde characters in URIs This is a potential security risk on the Windows...

Page 71: ...ic ncsa path optional is a wildcard local file system path on which this function should operate If no path is provided the function applies to all paths auth type is the type of HTTP authorization us...

Page 72: ...mentioned in the from parameter or if there is no from parameter Parameters Examples ssl check Applicable in PathCheck class directives If a restriction is selected that is not consistent with the cu...

Page 73: ...e accelerator file cache if ssl check returns something other than REQ_NOACTION Parameters ssl logout Applicable in PathCheck class directives ssl logout invalidates the current SSL session in the ser...

Page 74: ...one ObjectType directive in an object all the directives are applied in the order they appear If a directive sets an attribute and later directives try to set that attribute to something else the fir...

Page 75: ...ObjectType directives so that all other ObjectType directives have a chance to set the MIME type first If there is more than one ObjectType directive in an object all the directives are applied in th...

Page 76: ...jects in obj conf you can define different defaults for different parts of the document tree Parameters Example ObjectType fn force type type text plain ObjectType fn force type lang en_US enc optiona...

Page 77: ...es the current path with a wildcard expression If the two match the type parameter information is applied to the file This is the same as type by extension except you use wildcard patterns for the fil...

Page 78: ...s the mappings For more information about server xml see Chapter 8 Virtual Server Configuration Files For more information about MIME types files see Appendix B MIME Types For example the following tw...

Page 79: ...s to determine whether the function is executed All the optional parameters must match the current request for the function to be executed type optional specifies a wildcard pattern of MIME types for...

Page 80: ...ytes 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 Servic...

Page 81: ...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 82: ...ated 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 re...

Page 83: ...l method GET fn add footer file D netscape server4 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 84: ...on to all Service class functions flushTimer optional common to all Service class functions ChunkedRequestBufferSize optional common to all Service class functions ChunkedRequestTimeout optional commo...

Page 85: ...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 86: ...ains a call to index common in the Service stage magnus conf must initialize fancy or common indexing by invoking Enterprise Servercindex init during the Init stage Indexing occurs when the requested...

Page 87: ...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 88: ...directory that does not contain either an index file or a home page or no index file or home page has been specified by the functions find index or home page Parameters Examples Service fn index comm...

Page 89: ...on is provided 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 meth...

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

Page 91: ...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 92: ...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 UseOutputStream...

Page 93: ...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 94: ...e 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 95: ...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 96: ...ne 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 va...

Page 97: ...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 98: ...mer optional common to all Service class functions ChunkedRequestBufferSize optional common to all Service class functions ChunkedRequestTimeout optional common to all Service class functions bucket o...

Page 99: ...formation about shell CGI programs consult the Netscape Enterprise Server Administrator s Guide Parameters type optional common to all Service class functions method optional common to all Service cla...

Page 100: ...vice 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 cgi fn...

Page 101: ...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 102: ...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 environment of...

Page 103: ...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 104: ...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 t...

Page 105: ...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 106: ...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 nonlocal...

Page 107: ...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 108: ...client in place of a specific HTTP response status qos error returns an error page stating which quality of service limits caused the error and what the value of the QOS statistic was send error Appli...

Page 109: ...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 110: ...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 HT...

Page 111: ...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 112: ...e server uses the result code from each function to determine how to proceed with processing the request See the section Result Codes on page 115 for details of the result codes SAF Parameters This se...

Page 113: ...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 114: ...gent 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 throughou...

Page 115: ...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 116: ...ction 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 117: ...ch directive expects its SAFs 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...

Page 118: ...ched for shared objects during runtime to resolve symbols Table 4 1 Libraries Platform Library Windows NT ns httpd40 dll in addition to the standard Windows libraries HPUX libns httpd40 sl All other U...

Page 119: ...IX blibpath dir dir 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 Windo...

Page 120: ...linking Enterprise Server had specific additional software provided by IBM AIX development to Netscape to enable plugins No special runtime linking directives were required to build plugins Because of...

Page 121: ...ded plugin For example if you defined the function init_my_new_SAF to perform an operation on the maxAnimLoop parameter you would a directive such as the following to magnus conf Init fn init_my_anima...

Page 122: ...alue that matches another object and then in the new object you could invoke the new Service function For example suppose your plugin defines two new SAFs do_small_anim and do_big_anim which both take...

Page 123: ...Note that the shift reload trick does not always force the client to fetch images from source if the images are already in the cache You may also wish to disable the server cache using the cache init...

Page 124: ...g entries in a pblock data structure include pblock_findval returns the value for a given name in a pblock pblock_nvinsert adds a new name value entry to a pblock pblock_remove removes a pblock entry...

Page 125: ...request and then disposing the entire pool after each request There are wrappers for standard memory routines for using permanent memory To disable pooled memory for debugging see the built in SAF poo...

Page 126: ...o the network socket Threads Thread functions include functions for creating your own threads which are compatible with the server s threads There are also routines for critical sections and condition...

Page 127: ..._uri_escape converts the special characters in a string into URI escaped format util_uri_unescape converts the URI escaped characters in a string back into special characters Virtual Server The virtua...

Page 128: ...st for a specific virtual server Required Behavior of SAFs for Each Directive When writing a new SAF you should define it to do certain things depending on which stage of the request handling process...

Page 129: ...nd return REQ_ABORTED If successful return REQ_PROCEED AuthTrans SAFs Purpose Verify any authorization information Only basic authorization is currently defined in the HTTP 1 0 specification Check for...

Page 130: ...hts 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 wit...

Page 131: ...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 132: ...block_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 pbl...

Page 133: ...eating Custom SAFs 133 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 134: ...CGI to NSAPI Conversion 134 Netscape Enterprise Server NSAPI Programmer s Guide November 2001...

Page 135: ...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 136: ...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 information...

Page 137: ...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 138: ...rns 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_termina...

Page 139: ...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 140: ...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 function...

Page 141: ...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 142: ...so 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 operation...

Page 143: ...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 144: ...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 filebuf_...

Page 145: ...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 146: ..._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 filebuf...

Page 147: ...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 148: ...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 specifi...

Page 149: ...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 150: ...y 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 specified...

Page 151: ...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 152: ...fer 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 dea...

Page 153: ...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 154: ...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 ch...

Page 155: ...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 156: ..._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 p...

Page 157: ...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 158: ...r 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 paramete...

Page 159: ...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 160: ...n 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 161: ...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 162: ...OC 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 allocat...

Page 163: ...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 164: ...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 which...

Page 165: ...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 166: ...cture 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_st...

Page 167: ...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 168: ...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_st...

Page 169: ...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 170: ...uffix 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_statu...

Page 171: ...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 172: ...ormation 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 rea...

Page 173: ...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 174: ...ddress 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 175: ...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 176: ...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 validatio...

Page 177: ...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 178: ...msg 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 va...

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

Page 181: ...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 182: ...ystem_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 specif...

Page 183: ...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 184: ...seek 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 185: ...ulock SYS_FILE 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 s...

Page 186: ...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 thre...

Page 187: ...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 188: ...ata 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 sys...

Page 189: ...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 190: ..._can_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 t...

Page 191: ...l 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 0 if th...

Page 192: ...ax 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 o...

Page 193: ...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 194: ...ains 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 responsibl...

Page 195: ...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 196: ...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 date...

Page 197: ...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 198: ...e 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 is...

Page 199: ...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 200: ...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 th...

Page 201: ...include and also for Windows NT 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 0 if...

Page 202: ...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 I...

Page 203: ...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 204: ...ults 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 valu...

Page 205: ...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 206: ...pd_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 Note...

Page 207: ...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 208: ...ny 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 no...

Page 209: ...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 210: ...NSAPI Functions in Alphabetical Order 210 Netscape Enterprise Server NSAPI Programmer s Guide November 2001...

Page 211: ...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 212: ...lization 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 whi...

Page 213: ...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 214: ...xample 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 jo...

Page 215: ...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 216: ...he 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 environ...

Page 217: ...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 218: ...ck 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 ppath...

Page 219: ...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 220: ...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 stat...

Page 221: ...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 222: ...bidden 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 in...

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

Page 225: ...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 226: ...gh 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 co...

Page 227: ...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 228: ...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 tm...

Page 229: ...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 230: ...ed 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 Installing...

Page 231: ...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 232: ...ndwidth 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 233: ...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 234: ...s_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 235: ...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 236: ...m 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 conne...

Page 237: ...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 238: ...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 239: ...home directory information load modules loads shared libraries into the server nt console init enables the Windows NT console which is the command line shell that displays standard output and error s...

Page 240: ...e display for that column off The name column cannot be turned off 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 Dat...

Page 241: ...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 242: ...try 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 functio...

Page 243: ...sn t find it creates a new 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 name...

Page 244: ...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 request Req srvhdrs...

Page 245: ...otocol version Req reqpb protocol Accept header Req headers accept Date header Req headers date If Modified Since header Req headers if modified since Authorization header Req headers authorization An...

Page 246: ...size of the buffer size and num buffers parameters from their defaults and lowering the value of the LogFlushInterval magnus conf directive to 4 seconds see Chapter 7 Syntax and Use of magnus conf fre...

Page 247: ...ew log file The server does not need to be shut down while the log files are being rotated By default log rotation is disabled Parameters Init fn flex init buffer size 16384 num buffers 2000 access us...

Page 248: ...d establishment of environment variables Parameters rotate error optional determines whether error logs are rotated Values are yes the default and no rotate callback optional specifies the file name o...

Page 249: ...nce 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 the sec...

Page 250: ...t flex rotate init NOTE If the server has an AddLog stage directive that calls common log common log files must be initialized by init clf during initialization NOTE This function should only be calle...

Page 251: ...ic Link Library into the server code Specified functions from the library can then be executed from any subsequent directives Use this function to load new plugins or SAFs If you define your own Serve...

Page 252: ...spaces The dash character may be used in place of the underscore _ character in function names NativeThread optional specifies which threading model to use no causes the routines in the library to use...

Page 253: ...pools allow the server to run significantly faster If you are programming with the NSAPI note that MALLOC REALLOC CALLOC STRDUP and FREE work slightly differently if pooled memory is disabled If pooli...

Page 254: ...lemented error message Parameters NOTE Any memory you allocate from Init class functions will be allocated as persistent memory even if you use MALLOC The server cleans up only the memory that is allo...

Page 255: ...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 servers maximu...

Page 256: ...ins On Windows NT the default native pool is always being used and Enterprise Server uses fibers user scheduled threads for initial request processing Using custom additional pools on Windows NT intro...

Page 257: ...ot ServerConfigurationFile ServerID ServerRoot TempDir TempDirSecurity User ExtraPath Appends the specified directory name to the PATH environment variable This is used for configuring Java on Windows...

Page 258: ...t specify a value Syntax NetSiteRoot path ServerConfigurationFile Specifies the location of the virtual server configuration file Syntax ServerConfigurationFile path Default ServerConfigurationFile se...

Page 259: ...uns with By using a specific user account other than LocalSystem you can restrict or enable system features for the server For example you can use a user account that can mount files from another mach...

Page 260: ...t recommended Syntax User name name is the 8 character or less login name for the user account Default If there is no User directive the server runs with the user account it was started with Examples...

Page 261: ...dministration Default The default is iso 8859 1 DefaultLanguage For an international version of the server this directive specifies the default language for the server The default language is used for...

Page 262: ...DNS on Threads Processes and Connections In Enterprise Server 6 0 acceptor threads on a listen socket accept connections and put them onto a connection queue Session threads then pick up connections...

Page 263: ...d on how many session threads already exist This subsection lists the directives in magnus conf that affect the number and timeout of threads processes and connections They are ConnQueueSize HeaderBuf...

Page 264: ...eout Specifies the number of seconds the server waits for data to arrive from the client If data does not arrive before the timeout expires then the connection is closed By setting it to less than the...

Page 265: ...5 minutes KernelThreads Enterprise Server can support both kernel level and user level threads whenever the operating system supports kernel level threads Local threads are scheduled by NSPR within t...

Page 266: ...ng issues in the Netscape Enterprise Server Performance Tuning Sizing and Scaling Guide Default 1 PostThreadsEarly If this directive is set to 1 on the server checks the whether the minimum number of...

Page 267: ...more request processing threads are created up to a maximum of RqThrottle threads Default 48 SndBufSize Specifies the size in bytes of the send buffer used by sockets Default The default value is dete...

Page 268: ...lt value is 10 UseNativePoll UNIX only Uses a platform specific poll interface when set to 1 on Uses the NSPR poll interface in the KeepAlive subsystem when set to 0 off Default 1 on Native Thread Poo...

Page 269: ...etermines the maximum number of threads in the native kernel thread pool Enterprise ServerDefault 128 NativePoolMinThreads Determines the minimum number of threads in the native kernel thread pool Def...

Page 270: ...inutes would be a good value for most interactive CGIs but if you have CGIs that are expected to take longer without misbehaving then you should set it to the maximum duration you expect a CGI program...

Page 271: ...s the maximum number of CGIStub processes the server can spawn This is the maximum concurrent CGIStub processes in execution not the maximum number of pending requests The default value should be adeq...

Page 272: ...directive specifies the directory where the server logs its errors If errors are reported to a file then the file and directory in which the log is kept must be writable by whatever user account the...

Page 273: ...econds of the log flush thread Default 30 LogVerbose This directive determines whether verbose logging occurs or not If the value is on the server logs all server messages including those that are not...

Page 274: ...tmp ns server pid ACL This section lists the directives in magnus conf relevant to access control lists ACLs They are ACLCacheLifetime ACLUserCacheSize ACLGroupCacheSize ACLCacheLifetime ACLCacheLifet...

Page 275: ...ction lists the directives in magnus conf that affect server access and security issues for Enterprise Server They are Security SSLCacheEntries SSLClientAuthDataLimit SSLClientAuthTimeout SSLSessionTi...

Page 276: ...0 the default value which is 10000 is used SSLClientAuthDataLimit Specifies the maximum amount of application data in bytes that is buffered during the client certificate handshake phase Default The...

Page 277: ...is the number of seconds until a cached SSL3 session becomes invalid The default value is 86400 24 hours If the SSL3SessionTimeout directive is specified the value of seconds is silently constrained...

Page 278: ...ChunkedRequestBufferSize 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 c...

Page 279: ...mon_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 form m n where m...

Page 280: ...rective specifies 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...

Page 281: ...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 282: ...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 li...

Page 283: ...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 284: ...ids 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 assigne...

Page 285: ...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 286: ...a 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 same...

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

Page 288: ...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 configur...

Page 289: ...erator blocking optional Determines whether the listen socket and the accepted socket are put in to blocking mode Use of blocking mode may improve benchmark scores Legal values are on off yes no 1 0 T...

Page 290: ...s to the client servercertnickname The nickname of the server certificate in the certificate database or the PKCS 11 token In the certificate the name format is tokenname nickname Including the tokenn...

Page 291: ...LS values are rsa_des_56_sha rsa_rc4_56_sha tls optional Determines whether TLS is enabled Legal values are on off yes no 1 0 The default is on tlsrollback optional Determines whether TLS rollback is...

Page 292: ...ce separated 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 AC...

Page 293: ...r 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 value to on onl...

Page 294: ...ributes of 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 opt...

Page 295: ...on page 32 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 is selected I...

Page 296: ...the following changes have been made in Enterprise Server 6 0 Virtual servers in server xml reference ACL files The magnus conf file no longer references ACL files The ACL file s database attribute do...

Page 297: ...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 dcsuffix attr...

Page 298: ...the auxiliary 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 Grou...

Page 299: ...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 300: ...f 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 is...

Page 301: ...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 302: ...ne 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 r...

Page 303: ...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 304: ...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 i...

Page 305: ...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 306: ...cinfo 306 Netscape Enterprise Server NSAPI Programmer s Guide November 2001...

Page 307: ...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 308: ...nt 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 t...

Page 309: ...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 310: ...IME 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 ty...

Page 311: ...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 312: ...Sample MIME Types File 312 Netscape Enterprise Server NSAPI Programmer s Guide November 2001...

Page 313: ...hese characters without the special meaning precede it with a backslash character Wildcard Patterns Table C 1 Wildcard patterns Pattern Use Match zero or more characters Match exactly one occurrence o...

Page 314: ...either 198 93 92 or 198 93 93 and ending with any 3 characters Matches any string with a period in it example Matches any string except those starting with example example com quark example com Matche...

Page 315: ...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 316: ...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 317: ...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 318: ...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 ac...

Page 319: ...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 320: ...ample 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 or...

Page 321: ...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 322: ...he 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 t...

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

Page 324: ...Buffered Streams 324 Netscape Enterprise Server NSAPI Programmer s Guide November 2001...

Page 325: ...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 326: ...in 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 ca...

Page 327: ...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 328: ...ngth 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 329: ...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 330: ...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 cache...

Page 331: ...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 332: ...332 Netscape Enterprise Server NSAPI Programmer s Guide November 2001...

Page 333: ...al List of NSAPI Functions and Macros C CALLOC 138 cinfo_find 138 condvar_init 139 condvar_notify 140 condvar_terminate 140 condvar_wait 141 crit_enter 141 crit_exit 142 crit_init 142 crit_terminate 1...

Page 334: ..._open 144 filebuf_buf2sd 145 filebuf_close 146 filebuf_getc 146 filebuf_open 147 filebuf_open_nostat 147 FREE 148 func_exec 149 func_find 149 L log_error 150 M magnus_atrestart 151 MALLOC 151 N net_ip...

Page 335: ...158 pblock_dup 158 pblock_find 158 pblock_findval 159 pblock_free 159 pblock_nninsert 160 pblock_nvinsert 160 pblock_pb2env 161 pblock_pblock2str 161 pblock_pinsert 162 pblock_remove 162 pblock_str2p...

Page 336: ...ol_uri2url_dynamic 171 R REALLOC 172 request_get_vs 173 request_header 173 request_stat_path 174 request_translate_uri 175 S session_dns 175 session_maxdns 176 shexp_casecmp 177 shexp_cmp 177 shexp_ma...

Page 337: ...system_rename 187 system_ulock 187 system_unix2local 187 systhread_attach 188 systhread_current 188 systhread_getdata 189 systhread_newkey 189 systhread_setdata 190 systhread_sleep 190 systhread_start...

Page 338: ..._snprintf 199 util_sprintf 200 util_strcasecmp 200 util_strftime 201 util_strncasecmp 202 util_uri_escape 202 util_uri_is_evil 203 util_uri_parse 203 util_uri_unescape 204 util_vsnprintf 204 util_vspr...

Page 339: ...Appendix G Alphabetical List of NSAPI Functions and Macros 339 vs_register_cb 210 vs_set_data 210 vs_translate_uri 211...

Page 340: ...340 Netscape Enterprise Server NSAPI Programmer s Guide November 2001...

Page 341: ...6 ACLGroupCacheSize 277 ACLUserCacheSize 277 AdminLanguage 263 AsyncDNS 264 C CGIExpirationTimeout 272 CGIStubIdleTimeout 273 CGIWaitPid UNIX Only 273 ChildRestartCallback 281 ChunkedRequestBufferSize...

Page 342: ...uide November 2001 D DefaultCharSet 263 DefaultLanguage 263 define perf bucket 243 DNS 264 dns cache init 244 E EarlyInit 246 ErrorLog 276 ErrorLogDateFormat 275 ExtraPath 260 F flex init 244 flex rot...

Page 343: ...t uhome 253 IOTimeout 266 K KeepAliveThreads 267 KeepAliveTimeout 267 KernelThreads 267 L LateInit 255 ListenQ 268 load modules 253 LogFlushInterval 275 LogVerbose 275 LogVsId 275 M MaxCGIStubs 273 Ma...

Page 344: ...ads 271 NativePoolQueueSize 272 NativePoolStackSize 271 NetSiteRoot 260 nt console init 254 P perf init 255 PidLog 276 pool init 255 PostThreadsEarly 268 R RcvBufSize 269 register http method 256 RqTh...

Page 345: ...AuthDataLimit 278 SSLClientAuthTimeout 279 SSLSessionTimeout 279 StackSize 269 stats init 257 StrictHttpHeaders 270 T TempDir 261 TempDirSecurity 261 TerminateTimeout 270 ThreadIncrement 270 thread po...

Page 346: ...346 Netscape Enterprise Server NSAPI Programmer s Guide November 2001...

Page 347: ...l List of Pre defined SAFs For Init SAFs see Appendix H Alphabetical List of Directives in magnus conf A add footer 85 add header 86 append trailer 87 assign name 55 B basic auth 51 basic ncsa 52 C ch...

Page 348: ...rogrammer s Guide November 2001 D deny existence 65 document root 57 F find index 66 find links 67 find pathinfo 67 flex log 108 force type 78 G get client cert 68 get sslid 54 H home page 58 I imagem...

Page 349: ...endix I Alphabetical List of Pre defined SAFs 349 K key toosmall 91 L list dir 92 load config 70 M make dir 93 N nt uri clean 73 ntcgicheck 73 P pfx2dir 58 Q qos error 111 qos handler 54 query handler...

Page 350: ...60 remove dir 96 remove file 97 rename file 97 require auth 74 S send cgi 98 send error 110 send file 100 send range 102 send shellcgi 103 send wincgi 103 service dump 104 set default type 79 set virt...

Page 351: ...Appendix I Alphabetical List of Pre defined SAFs 351 T type by exp 80 type by extension 81 U unix home 61 unix uri clean 76 upload file 106...

Page 352: ...352 Netscape Enterprise Server NSAPI Programmer s Guide November 2001...

Page 353: ...ample of custom SAF 228 flow of control 40 function descriptions 105 requirements for SAFs 131 summary 28 AdminLanguage magnus conf directive 260 alphabetical reference magnus conf variables 341 NSAPI...

Page 354: ...p 175 shexp_cmp 175 shexp_match 176 shexp_valid 177 STRDUP 177 system_errmsg 178 system_fclose 178 system_flock 179 system_fopenRO 179 system_fopenRW 180 system_fopenWA 180 system_fread 181 system_fwr...

Page 355: ...ter 47 buffered streams 322 builtin SAFs 45 C cache enabling memory allocation pool 253 CALLOC API function 136 case sensitivity in obj conf 41 certificates settings in magnus conf 275 certmaps attrib...

Page 356: ...2 convergence tree auxiliary class inetSubscriber 298 in LDAP schema 297 organization of 297 user entries are called inetOrgPerson 298 core SAFs 45 creating custom SAFs 111 crit_enter API function 139...

Page 357: ...descriptions 108 requirements for SAFs 131 summary 28 error logging settings in magnus conf 272 ErrorLog magnus conf directive 272 errorlog attribute 294 ErrorLogDateFormat magnus conf directive 273...

Page 358: ...ion 75 forcing object type 36 formats time 315 forward slashes 42 FREE API function 146 from parameter 54 57 59 61 72 func_exec API function 147 func_find API function 147 funcs parameter 121 252 func...

Page 359: ...ents for SAFs 129 init cgi function 248 init clf function 249 initializing global settings 237 plugins 120 SAFs 120 initializing for CGI 248 init uhome function 251 IP address getting clients 302 ip a...

Page 360: ...nections magnus conf directive 265 MaxProcs magnus conf directive 266 MaxRqHeaders magnus conf directive 279 memory allocation pool init function 253 memory management routines 125 method parameter 66...

Page 361: ...FilePath parameter 82 83 ntcgicheck function 70 nt console init function 252 ntrans base 54 55 58 nt uri clean function 69 O obj conf 19 adding directives for new SAFs 121 case sensitivity 41 comments...

Page 362: ...function 156 pblock_findval API function 157 pblock_free API function 157 pblock_nninsert API function 158 pblock_nvinsert API function 158 pblock_pb2env API function 159 pblock_pblock2str API functio...

Page 363: ...NSAPI functions 135 NSAPI data structures 299 register http method function 254 relink_36plugin file 120 REMOTE_ADDR environment variable 132 REMOTE_HOST environment variable 132 REMOTE_IDENT environ...

Page 364: ...alues 115 signature 112 writing new 23 SCRIPT_NAME environment variable 132 search patterns 313 secret keysize parameter 73 Secuity magnus conf directive 275 security settings in mangus conf 275 secur...

Page 365: ...to a string 175 comparing case sensitive to a string 175 176 validating 177 shexp_casecmp API function 175 shexp_cmp API function 175 shexp_match API function 176 shexp_valid API function 177 shlib pa...

Page 366: ...unction 178 system_flock API function 179 system_fopenRO API function 179 system_fopenRW API function 180 system_fopenWA API function 180 system_fread API function 181 system_fwrite API function 181 s...

Page 367: ...specifying 259 unix home function 60 unix uri clean function 73 upload file function 104 uri parameter 82 83 URL mapping to other servers 57 translated to file path 27 url parameter 59 urlhosts attrib...

Page 368: ...84 substitution where allowed 284 used in the interfaces 285 vars field in request parameter 114 VARS element 287 Virtual Server selection for request processing 295 virtual server routines 127 virtua...