Red Hat NETSCAPE ENTERPRISE SERVER 6.1 - NSAPI PROGRAMMER GUIDE Manuel d'utilisateur Page 1

Programmer’s GuideNetscape Enterprise ServerVersion 6.1April 2002 (Draft)

Enterprise Server 6.1 APIs10 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)The main configuration files are magnus.conf, server.xm

server.xml100 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)errorlog (optional) Specifies a log file forvirtual-server-specific err

servers.lstChapter 2 Configuration Files 101servers.lstPurposeLists the Netscape servers managed by the Administration Server. Do not modifythis file.

servlets.properties102 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)The servlet properties, described in Table 2-24, apply only to

servlets.propertiesChapter 2 Configuration Files 103• The Servlet 2.2 API specification at:http://java.sun.com/products/servlet/index.htmlTable 2-24 s

web.xml104 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)web.xmlPurposeDefines a web application, including its servlets, URL mappi

web-apps.xmlChapter 2 Configuration Files 105See Also• Netscape Enterprise Server Programmer’s Guide to Servlets• The Servlet 2.2 API specification at

web-apps.xml106 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)Table 2-26 web-apps.xmlElement/Attribute Allowed Subelements orValues

web-apps.xmlChapter 2 Configuration Files 107filter,filter-mappingImplements the Filter APIfrom the Servlet 2.3specification. Used within aweb-app ele

web-apps.xml108 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)init-param param-name,param-value,descriptionSpecifies an initializat

web-apps.xmlChapter 2 Configuration Files 109enc none, auto,oraspecific encoding suchas utf8 or Shift_JISauto • encoding:usesthespecified encoding.• n

Enterprise Server 6.1 APIsChapter 1 Overview 11Server-Parsed HTML TagsEnterprise Server 6.1 provides a C API for defining your own server-side tags.Th

web-apps.xml110 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)map-to user, group group Specifies whether to maprole-name values fro

web-apps.xmlChapter 2 Configuration Files 111vs auth-native,class-loader,form-login-session,jsp-servlet,parameter-encoding,response-buffer,response-co

web-apps.xml112 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)

113Chapter 3Server-Parsed HTML TagsHTML files can contain tags that are executed on the server. In addition tosupporting the standard server-side tags

UsingServer-SideHTMLCommands114 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)Notethatyou mustset NativeThread="no" for 6

Using Server-Side HTML CommandsChapter 3 Server-Parsed HTML Tags 115• flastmod• execconfigThe config command initializes the format for other commands

UsingServer-SideHTMLCommands116 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)In Enterprise Server 6.1, you can use the include com

Using Server-Side HTML CommandsChapter 3 Server-Parsed HTML Tags 117execThe exec command runs a shellcommand or CGI program.•Thecmd attribute (UNIX on

Embedding Servlets118 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)Embedding ServletsEnterprise Server 6.1 supports the <SERVLE

Defining Customized Server-Parsed HTML TagsChapter 3 Server-Parsed HTML Tags 119<servlet><servlet-name> pparams </servlet-name><s

Enterprise Server 6.1 APIs12 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)CGICommon Gateway Interface (CGI) programs run on the s

Defining Customized Server-Parsed HTML Tags120 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)The MechanicsThe steps for defining a

Defining Customized Server-Parsed HTML TagsChapter 3 Server-Parsed HTML Tags 121The tag execution function must return an int that indicates whether t

Defining Customized Server-Parsed HTML Tags122 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)The signatures for these functions are

Defining Customized Server-Parsed HTML TagsChapter 3 Server-Parsed HTML Tags 123mytag_des(TagUserData v1){}/* FUNCTION : mytag_load** DESCRIPTION: Sht

Defining Customized Server-Parsed HTML Tags124 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)length = util_sprintf(buf, "<h

Defining Customized Server-Parsed HTML TagsChapter 3 Server-Parsed HTML Tags 125Any of these arguments can return NULL except for the tag and execFn.L

Defining Customized Server-Parsed HTML Tags126 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)

127Appendix AConfiguration File ChangesThis chapter summarizes major configuration file changes between iPlanet WebServer 4.x and Netscape Enterprise

magnus.conf128 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)ACLFile (none) See the ACLFILE element inserver.xmlAddress (none) See

magnus.confAppendix A Configuration File Changes 129(none) IOTimeout (new)(none) Init functions from obj.conf Allfunctions arepresent except forcache-

Enterprise Server 6.1 APIsChapter 1 Overview 13Do not remove this objectfrom obj.conf.Ifyoudo,theserverwillneverrecognizeCGI directories, regardless o

magnus.conf130 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)PidLog PidLog (unchanged)Port (none) See the LS element inserver.xmlPo

obj.confAppendix A Configuration File Changes 131obj.confThe obj.conf file has lost its Init directives to the magnus.conf file and acquirednew direct

contexts.properties132 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)contexts.propertiesThe contexts.properties file is still suppo

rules.propertiesAppendix A Configuration File Changes 133rules.propertiesThe function of the rules.properties file is now handled by theservlet-mappin

servlets.properties134 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)Afewservlets.properties functions are in the web.xml file. For

servlets.propertiesAppendix A Configuration File Changes 135config.bufferSize size attribute ofresponse-buffer elementstartup (none) Specified in aloa

servlets.properties136 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)

Index 137IndexAabbrev, value ofsizefmt attribute 115about this book 7AccelFileCache directive 127acceptlanguage attribute 99, 100AcceptLanguage direct

138 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)Bbackups.conf 32basedir parameter 81basedn attribute 100basic-auth function 75bas

Index 139config.docRoot property 103, 134config.realPathFromRequest property 103, 134config.reloadInterval property 104, 134config.respondCookieVersio

Enterprise Server 6.1 APIs14 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)6. Set the owner of Cgistub to root:chown root Cgistub7

140 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)Days directive 41dbm parameter 75dbswitch.conf 41dcsuffix property 42DefaultCharS

Index 141Ffamily attribute 95file attribute 98file attribute of include command 116file extensionsfor CGI 13file parameter 80, 85FileCacheEnable param

142 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)of SLAVE element 36of thread-pool element 64of USERDB element 100of virtual-serve

Index 143Kkeepalive-bucket element attribute 66KeepAliveThreads directive 56, 129KeepAliveTimeout directive 56, 129KernelThreads directive 56, 129key-

144 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)Nname attribute 64name directive 40name parameterof assign-name function 76of com

Index 145pid attribute 65PidLog directive 58, 130pluginscreating 24for more info 25installing 25pool parameter 51pool-init function 52port attribute 9

146 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)for more info 25installing 25secondsMaxAge attribute 67secondsRunning attribute 6

Index 147function for registering custom server-side tags125shtml_init 11, 113shtml_public.h 120shtml_send 11, 113shtml_send function 89, 131shtml-hac

148 Netscape Enterprise Server Programmer’sGuide • April 2002 (Draft)thread-pool-bucket element 65thread-pool-init function 52ticksDispatch attribute

Enterprise Server 6.1 APIsChapter 1 Overview 15Cgistub enforces the following security restrictions:• The user the CGI program executes as must have a

Enterprise Server 6.1 APIs16 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)3. Create the cgi-bin directory.mkdir cgi-binchown user

Enterprise Server 6.1 APIsChapter 1 Overview 175. List /dev/tcp, and notethe major and minor numbers oftheresulting output.In this example, the major

Enterprise Server 6.1 APIs18 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)10. Create and populate bin and usr/bin in the chroot d

Enterprise Server 6.1 APIsChapter 1 Overview 19Adding CGI Programs to the ServerTo add CGI programs to the Enterprise Server, simply do one of the fol

Netscape Communications Corporation ("Netscape") and its licensorsretain all ownershiprights to thesoftware programs offered byNetscape (ref

Enterprise Server 6.1 APIs20 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)HTTPS_SECRETKEYSIZE The keysize of thesecret part of th

Enterprise Server 6.1 APIsChapter 1 Overview 21For More InformationA myriad of information about writing CGI programs is available. A good startingpoi

Enterprise Server 6.1 APIs22 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)A JavaServer Page (JSP) is a page, much like an HTML pa

Enterprise Server 6.1 APIsChapter 1 Overview 23For UNIX, the shlib valueisasfollows:shlib="server_root/bin/https/lib/libNSServletPlugin.so"T

Enterprise Server 6.1 APIs24 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)NSAPINetscape Server Application Programming Interface

Enterprise Server 6.1 APIsChapter 1 Overview 25Installing NSAPI Plugins (SAFs)ToloadnewNSAPIpluginscontainingcustomizedSAFsintotheserver,addanInit dir

Enterprise Server 6.1 APIs26 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)To create access control lists, use the Restrict Access

Enterprise Server 6.1 APIsChapter 1 Overview 27For information about changes to the access control API in Enterprise Server 6.1,see the comments in th

API Summary28 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)API SummaryThe following table lists the APIs available in Enterprise

Changes from Previous VersionsChapter 1 Overview 29API Changes Since Enterprise Server 3.x• New API for defining customized server-parsed tags as NSAP

3ContentsAboutThisBook ...7WheretoFindRelatedInformation ...

Changes from Previous Versions30 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)

31Chapter 2Configuration FilesConfiguration files control how Netscape Enterprise Server operates. This chaptersummarizes the Purpose, Location, and C

backups.conf32 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)•password.conf• rules.properties•server.xml•servers.lst• servlets.pro

certmap.confChapter 2 Configuration Files 33dmserv/config/contexts.propertiesrules.properties:https-admserv/conf_bk/rules.properties:2:952103068:https

certmap.conf34 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)Locationserver_root/bin/https/install/miscserver_root/userdbSyntaxcer

cjava.propertiesChapter 2 Configuration Files 35cjava.propertiesPurposeDefines servlet and JVM error messages.Locationserver_root/bin/https/resSyntaxe

cluster.xml36 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)SyntaxMost of the file has the following basic XML syntax, with nested

contexts.propertiesChapter 2 Configuration Files 37contexts.propertiesPurposeProvided for backward compatibility with iPlanet Web Server 4.x.Usingweb-

contexts.properties38 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)sessionmgr.initArgs Commaseparatedname=valuepairsDepends onses

contexts.propertiesChapter 2 Configuration Files 39authdb A databasenamedefault The name of the authenticationdatabase. This database mustalso be defi

4 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)ForMoreInformation ...26

cron.conf40 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)cron.confPurposeAllows you to program the server to perform maintenance

dbswitch.confChapter 2 Configuration Files 41dbswitch.confPurposeSpecifies the LDAP directory that Enterprise Server uses.Locationserver_root/userdbSy

jvm12.conf42 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)jvm12.confPurposeAllows you to change Java Virtual Machine™ settings.Lo

jvm12.confChapter 2 Configuration Files 43server_root/https-server_id/conf_bkSyntax[JVMConfig]setting=value...See AlsoNetscape Enterprise Server Progr

jvm12.conf44 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)jvm.printErrors 0 (off), 1 (logsto log file), 2(logs tostderr)0 Enables

magnus.confChapter 2 Configuration Files 45magnus.confPurposeContains global variable settings that affect server functioning. This file is readonly a

magnus.conf46 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)Locationserver_root/https-admserv/configserver_root/https-admserv/conf

magnus.confChapter 2 Configuration Files 47See AlsoNetscape Enterprise Server NSAPI Programmer’s GuideAppendix A, “Configuration File Changes”Init Fun

magnus.conf48 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)format FormatfortheUNIXfunctionstrftime()%d-%b-%Y%H:%M(optional, iPlan

magnus.confChapter 2 Configuration Files 49expire 1 to31536000seconds(1 year)1200 seconds(20 minutes)(optional) specifies how long(in seconds) ittakes

5Chapter 3 Server-ParsedHTMLTags ...113UsingServer-SideHTMLCommands...

magnus.conf50 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)rotate-error yes, no yes (optional) determines whethererror logs are r

magnus.confChapter 2 Configuration Files 51init-uhome Loads user home directoryinformation.pwfile (optional) specifies the full filesystem path to a f

magnus.conf52 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)stdout console Directs output to the WindowsNT/Windows 2000 console.pe

magnus.confChapter 2 Configuration Files 53magnus.conf Directivesname Name of the thread pool.maxthreads Maximum number ofthreadsinthe pool.minthreads

magnus.conf54 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)CGIExpirationTimeout Any numberof seconds300(5 minutes)recommendedSpec

magnus.confChapter 2 Configuration Files 55ConnQueueSize Any numberof connections5000 Specifies the number ofoutstanding(yet to be serviced) connectio

magnus.conf56 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)HTTPVersion m.n; m is themajor versionnumber and nthe minorversionnumb

magnus.confChapter 2 Configuration Files 57MaxCGIStubs Any numberof CGI stubs10 Controls the maximum number ofCGIStub processes the server canspawn. T

magnus.conf58 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)PidLog Avalidpathtoa file(none) Specifiesa filein whichto recordthepro

magnus.confChapter 2 Configuration Files 59ServerString Astring Netscape-Enterprise/6.1 AOLModifies the HTTP header Server.Can be used when the type,

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

magnus.conf60 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)TempDir Apath /tmp (UNIX)TEMP(environmentvariable forWindowsNT/Windows

mime.typesChapter 2 Configuration Files 61mime.typesPurposeMaps standard MIME types to file extensions. Each virtual server can have its ownmime.types

nesstats.xml62 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)nesstats.xmlPurposeReports server performance statistics. Configured

nesstats.xmlChapter 2 Configuration Files 63SyntaxThe file has the following basic XML syntax, with nested elements:<ELEMENT attribute="value&

nesstats.xml64 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)maxProcs The maximum number of processes.maxThreads The maximum numbe

nesstats.xmlChapter 2 Configuration Files 65pid The operating system process identifier thatuniquely identifies this process.mode unknown, active Disp

nesstats.xml66 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)countThreads The number of request processing threads.maxThreads The

nesstats.xmlChapter 2 Configuration Files 67countHits The total number of times connections inkeepalive mode have subsequently made avalid request.cou

nesstats.xml68 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)countInfoMisses Thenumberoftimesa fileinformationlookuphas failed.cou

nesstats.xmlChapter 2 Configuration Files 69countBytesReceived The number of bytes received, or 0 if thisinformation is not available.countBytesTransm

7About This BookThis book is a starting point for developers who need information about using thevarious APIs and programming technologies that are su

ns-cron.conf70 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)ns-cron.confPurposeActivates or deactivates the cron.conf file.Locati

nsfc.confChapter 2 Configuration Files 71Syntaxparameter=valueSee AlsoNetscape Enterprise Server Performance Tuning, Sizing, and Scaling GuideTable 2-

obj.conf72 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)obj.confPurposeDetermines client responses to requests. Each virtualserve

obj.confChapter 2 Configuration Files 73server_root/https-server_id/configserver_root/https-server_id/conf_bkSyntaxdirective fn=function param1="

obj.conf74 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)The bucket ParameterThe following performance buckets are predefined in E

obj.confChapter 2 Configuration Files 75AuthTrans FunctionsTable 2-15 obj.conf AuthTrans functionsFunction/Parameter AllowedValuesDefaultValueDescript

obj.conf76 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)NameTrans Functionsqos-handler Examines the current quality of service st

obj.confChapter 2 Configuration Files 77path Thepathandnameofthehomepagefile.Ifpathstarts with a slash (/),it is assumed to be a full pathtoa file.pfx

obj.conf78 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)PathCheck Functionssubdir The subdirectory within the user’s home directo

obj.confChapter 2 Configuration Files 79deny-existence Indicatesthataresourcewasnotfound.path (optional) a wildcard pattern of the file-systempath to

Where to Find Related Information8 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)Where to Find Related InformationAdditional Enter

obj.conf80 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)get-client-cert Gets the authenticated client certificate from theSSL3 se

obj.confChapter 2 Configuration Files 81descend (optional) if present, specifies that the servershould search in subdirectories of this directoryfor d

obj.conf82 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)ObjectType Functionsfrom A commaseparated list(optional) a listof URIs fo

obj.confChapter 2 Configuration Files 83set-default-type Allows you to define a default charset,content-encoding,andcontent-languagefor the response b

obj.conf84 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)Service Functionstype-by-extension Sets the content-type header for the r

obj.confChapter 2 Configuration Files 85ChunkedRequestTimeout Numberofseconds60 (optional) determinesthe default timeout,inseconds, for “un-chunking”

obj.conf86 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)timefmt (optional) a time format string for:LASTMOD:.Iftimefmt is not pro

obj.confChapter 2 Configuration Files 87send-cgi Sets up environment variables, launches aCGI program, and sends the response to theclient.user (UNIXo

obj.conf88 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)nice (UNIX only) Accepts an increment thatdetermines the CGI program&apos

obj.confChapter 2 Configuration Files 89shtml_send Parses an HTML document, scanning forembedded commands. These commandsmay provide information from

9Chapter 1OverviewNetscape Enterprise Server 6.1 supports a variety of application programminginterfaces (APIs) and programming technologies that enab

obj.conf90 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)AddLog FunctionsTable 2-20 obj.conf AddLog functionsFunction/Parameter Al

password.confChapter 2 Configuration Files 91Error Functionspassword.confPurposeBy default, the web server prompts the administrator for the key datab

rules.properties92 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)Ifyou areusing the internal PKCS#11softwareencryption modulethatc

server.xmlChapter 2 Configuration Files 93See Also• Netscape Enterprise Server Programmer’s Guide to Servlets•Theweb.xml file• Appendix A, “Configurat

server.xml94 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)See AlsoNetscape Enterprise Server NSAPI Programmer’s Guide, Chapter 8T

server.xmlChapter 2 Configuration Files 95ip An IP address indotted-pair or IPv6notation.Canalso be0.0.0.0 forINADDR_ANY.IP address of the listen sock

server.xml96 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)tcpnodelay on, off on (optional) Allows you to modify thedefault TCP da

server.xmlChapter 2 Configuration Files 97servercertnickname The nickname of the server certificatein the certificate database or thePKCS#11 token. In

server.xml98 Netscape Enterprise Server Programmer’s Guide • April 2002 (Draft)file ThenameofaMIMEtypesfile.Forinformation about the format of thisfil

server.xmlChapter 2 Configuration Files 99acceptlanguage on, off off (optional) If on, the server parses theAccept-Language header and sendsan appropr