Server configuration files

his chapter describes the configuration files the server uses. When you use the Server Manager, the forms act as an interface to the configuration files. The changes you make in the Server Manager are saved in these configuration files. Although you can use these files to manually configure the server, you should use the Server Manager to configure your server.

The server uses four configuration files:

Syntax

Several rules are important in the specification of directives.

Case sensitivity

Because case sensitivity can be important in some systems and in some cases, it is best to assume that the directives are case sensitive.

Separators

The C language requires that identifiers be composed of letters, digits, and underscores. You can use either the minus (hyphen) character or the underscore in the configuration files, but must consistently use the same one throughout.

Quotes

Quotes (") are not required around character strings unless there is an embedded space in the character string.

Spaces

Do not put any spaces before the name of a directive. Do not put any spaces before or after the equal (=) sign that separates the name and value of a name-value pair.

Comments

To insert a comment, begin the line of text with a # sign. If you operate on the configuration files with the Server Manager, when it writes the files out again it does not write comment lines.

Line continuation

In the Server Manager, you do not concern yourself with line continuation, but in editing the configuration files by hand, you may need to deal with continued lines.

In magnus.conf, a line can be continued by ending it with a character. In obj.conf, a line can be continued by beginning the succeeding line with a space.

Directives in magnus.conf

This section defines the directives and describes their characteristics, including the directive name and description, format for the value string, default value if the directive is omitted, and how many instances of the directive should be in the file. The directives are

ServerName directive

The ServerName directive tells the server what to put in the host name section of any URLs it sends to the client. This affects URLs the server automatically generates; it doesn't affect the URLs for directories and files stored in the server. This name is what all clients use to access the server; they need to combine this name with the port number if the port number is anything other than 80.

This name should be the alias name if your server uses an alias. You can't have more than one ServerName directive in magnus.conf.

Syntax

ServerName host
host is a fully qualified domain name such as myhost.netscape.com.

Default

If ServerName isn't in magnus.conf, the server attempts to derive a host name through system calls. If they don't return a qualified domain name (for example, it gets myhost instead of myhost.netscape.com), the server won't start, and you'll get a message telling you to manually set this value.

Examples

ServerName server.netscape.com
ServerName www.server.anycompany.com
ServerName www.agency.gov

Port directive

The Port directive determines which TCP port the server listens to. If you choose a port number less than 1024, the server must be started as root. There should be only one Port directive in magnus.conf.

Note
The port you choose can affect how users configure their navigators. Users must specify the port number when accessing the server if the port number is anything other than 80 or 443.

Syntax

Port number
number is a whole number between 0 and 65535.

Default

If no port is specified, the server assumes 80.

Examples

Port 80
Port 8080
Port 8000

User directive

The User directive specifies the Unix user account for the server. If the server is started by the superuser or root user, the server binds to the Port you specify and then switches its user ID to the user account specified with the User directive. This directive is ignored if the server isn't started as root.

The user account you specify should have read permission to the server's root and subdirectories. The user account should have write access to the logs directory and execute permissions to any CGI programs. The user account should not have write access to the configuration files. This ensures that in the unlikely event someone compromises the server, they won't be able to change configuration files and gain broader access to your machine.

Although you can use the nobody user, it isn't recommended.

Syntax

User name
name is the 8-character (or less) login name for the Unix user account.

Default

If there is no User directive, the server runs with the user account it was started with. If the server was started as root or superuser, you'll see a warning message after startup.

Examples

User http
User server
User nobody

MaxProcs directive

The MaxProcs directive sets the maximum number of processes the server can have active.

Choose a number that is appropriate for the type of access you expect for the server. If this number is too small, clients will experience delays. If the number is too large, you might run out of memory and get an error such as "could not fork new process."

Syntax

MaxProcs number
number is a whole number between 1 and the size of your system's process table.

Default

MaxProcs 50

Examples

MaxProcs 20
MaxProcs 40
MaxProcs 80

MinThreads directive

The MinThreads directive sets the minimum number of threads the server can have active.

Choose a number that is appropriate for the type of access you expect for the server. If this number is too small, clients will experience delays. If the number is too large, you might run out of memory

Syntax

MinThreads number 
number is a whole number.

Examples

MinThreads 6
MinThreads 8

MaxThreads directive

The MaxThreads directive sets the maximum number of threads the server can have active.

Choose a number that is appropriate for the type of access you expect for the server. If this number is too small, clients will experience delays. If the number is too large, you might run out of memory

Syntax

MaxThreads number 
number is a whole number.

Examples

MaxThreads 6
MaxThreads 8

ErrorLog directive

The ErrorLog directive specifies the directory where the server logs its errors. You can also use the syslog facility. If errors are reported to a file (instead of syslog), then the file and directory in which the log is kept must be writable by whatever user account the server runs as.

Syntax

ErrorLog logfile
logfile can be either a full path and file name or the keyword SYSLOG (it must be in all capital letters).

Default

There is no default error log.

Examples

ErrorLog /var/ns-server/logs/errors 
ErrorLog SYSLOG

PidLog directive

PidLog specifies a file in which to record the process ID (pid) of the base server process. Some of the server support programs assume that this log is in the server root, in logs/pid.

To shut down your server, kill the base server process listed in the pid log file by using a -TERM signal. To tell your server to reread its configuration files and reopen its log files, use kill with the -HUP signal.

If the PidLog file isn't writable by the user account that the server uses, the server does not log its process ID anywhere. The server won't start if it can't log the process ID.

Syntax

PidLog file 
file is the full path name and file name where the process ID is stored.

Default

There is no default.

Examples

PidLog /var/ns-server/logs/pid
PidLog /tmp/ns-server.pid

LoadObjects directive

The LoadObjects directive specifies one or more object configuration files to use on startup; these files tell the server where to find documents.

Note
Although you can have more than one object configuration file, the Server Manager works on only one file and assumes that it is in the server root in config/obj.conf. If you use the Server Manger (or plan to), don't put the obj.conf file in any other directory and don't rename it.

Syntax

LoadObjects filename 
filename is either the full path name or a relative path name. When the server starts executing, relative path names are resolved from the directory specified with the -d command line flag. If no -d flag was given, the server looks in the current directory.

Default

There is no default.

Examples

LoadObjects obj.conf
LoadObjects /var/ns-server/admin/config/local-objs.conf

RootObject directive

The RootObject directive tells the server which object loaded from an object file is the server default. The default object is expected to have all of the name translation directives for the server; any server behavior that is configured in the default object affects the entire server.

If you specify an object that doesn't exist, the server doesn't report an error until a client tries to retrieve a document. The Server Manager assumes the default to be the object named default. Don't deviate from this convention if you use (or plan to use) the Server Manager.

Syntax

RootObject name 
name is the name of an object defined in one of the object files loaded with a LoadObjects directive.

Default

There is no default; that is, if you specify RootObject, you must specify a name with it.

Examples

RootObject default
RootObject server1

Chroot directive

The Chroot directive lets the Unix system administrator place the server under a constraint such that it has access only to files in a given directory, termed the "Chroot directory". This is useful if the server's security is ever compromised. For example, if an intruder somehow obtains shell access on the server machine, the intruder could only affect a very limited set of files on the server machine.

The server must be started as the superuser to use the Chroot directive. CGI programs must be linked statically, and any binaries (perl or /bin/sh) must be copied to the Chroot directory.

The user public information directory feature isn't available unless a copy of /etc/passwd is kept in the Chroot directory and all of the users home directories are exactly mirrored within the Chroot directory.

A server using Chroot can't be restarted with the -HUP signal.

Logs and server configuration files should be kept outside the Chroot directory.

IMPORTANT

All paths in magnus.conf must be absolute; paths in obj.conf must be relative to the Chroot directory.

Syntax

Chroot directory
directory is the full path name to the directory used as the server's root directory.

Default

There is no default. You must specify a directory.

Examples

Chroot /d/ns-httpd
Chroot /www

DNS directive

The DNS directive specifies whether the server performs DNS lookups on clients accessing the server. When a client connects to your server, the server knows the client's IP address but not its host name (for example, it knows the client as 198.95.251.30, rather than its host name www.a.com). The server will resolve the client's IP address into a host name for operations like access control, CGI, error reporting, and access logging.

If your server responds to many requests per day, you might want (or need) to stop host name resolution; doing so can reduce the load on the DNS or NIS server.

Syntax

DNS [on|off]

Default

DNS host name resolution is on as a default.

Example

DNS on

Security directive

The Security directive tells the server whether encryption (Secure Sockets Layer version 2 or version 3 or both) is enabled or disabled.

If Security is set to on, and both SSL2 and SSL3 are enabled, then the server tries SSL3 encryption first. If that fails, the server tries SSL2 encryption.

Syntax

Security [on|off]

Default

By default, security is off.

Example

Security off

SSL2 directive

The SSL2 directive tells the server whether Secure Sockets Layer, version 2 encryption is enabled or disabled. The Security directive dominates the SSL2 directive; if SSL2 encryption is enabled but the Security directive is set to off, then it is as though SSL2 were disabled.

Syntax

SSL2 [on|off]

Default

By default, security is off.

Example

SSL2 off

SSL3 directive

The SSL3 directive tells the server whether Secure Sockets Layer, version 3 security is enabled or disabled. The Security directive dominates the SSL3 directive; if SSL3 security is enabled but the Security directive is set to off, then it is as though SSL3 were disabled.

Syntax

SSL3 [on|off]

Default

By default, security is off.

Example

SSL3 off

ServerKey directive

The ServerKey directive tells the server where the key file is located.

Syntax

ServerKey keyfile
keyfile is the server's key file, specified as a relative path from the server root or as an absolute path.

ServerCert directive

The ServerCert directive specifies where the certificate file is located.

Syntax

ServerCert certfile
certfile is the server's certificate file, specified as a relative path from the server root or as an absolute path.

Ciphers directive

The Ciphers directive specifies the ciphers enabled for your server. For a discussion of the pros and cons of these ciphers, see the Server Administrator's Guide.

Syntax

Ciphers +rc4 +rc4export -rc2 -rc2export +idea +des +desede3
A + means the cipher is active, and a - means the cipher is inactive.

Valid ciphers are rc4, rc4export, rc2, rc2export, idea, des, desede3. Any cipher with export as port of its name is not stronger than 40 bits.

SSL3Ciphers directive

The SSL3Ciphers directive specifies the SSL3 ciphers enabled for your server.

Syntax

SSL3Ciphers +rc4 +rc4export -rc2 -rc2export +idea +des +desede3
A + means the cipher is active, and a - means the cipher is inactive.

Valid ciphers are rsa_rc4_128_md5, rsa3des_sha, rsa_des_sha, rsa_rc4_40_md5, rsa_rc2_40_md5, and rsa_null_md5. Any cipher with 40 as part of its name is 40 bits.

ACLFile directive

The ACLFile directive specifies an ACL (Access Control List) definition file--a text file that normally resides in the httpacl directory. Multiple ACLFile directives can appear in the magnus.conf file. The server reads all of the ACL definitions in all the specified ACL definition files when it starts up. Each ACL file must have a unique name.

Syntax

ACLFile name
name is the name of an ACL definition file.

SSLSessionTimeout directive

The SSLSessionTimeout directive controls SSL2 session caching.

Syntax

SSLSessionTimeout seconds
seconds is the number of seconds until a cached SSL2 session becomes invalid. The default value is 100. If the SSLSessionTimeout directive is specified, the value of seconds is silently constrained to be between 5 and 100 seconds.

SSL3SessionTimeout directive

The SSL3SessionTimeout directive controls SSL3 session caching.

Syntax

SSL3SessionTimeout seconds
seconds is the number of seconds until a cached SSL2 session becomes invalid. The default value is 86400 (24 hours). If the SSLSessionTimeout directive is specified, the value of seconds is silently constrained to be between 5 and 86400 seconds.

SSLClientAuth directive

The SSLClientAuth directive causes SSL3 client authentication on all requests.

Syntax

SSLClientAuth on|off
on directs that SSL3 client authentication be performed on every request, independent of ACL-based access control.

Directives in obj.conf

This section defines the directives and describes their characteristics, including the directive name and description, format for the function string, default value if the directive is omitted, and how many instances of the directive can be in the file. The directives are

Summaries of the obj.conf directives

The following tables summarize the eight directives and their component functions.

Init Directive Summary

Function

Parameters

Description

cindex-init

widths=n,n,n,n opts=i[s], ignore=pattern, icon-uri=vpath

Global character for fancy indexing; for width, n is chars for each column; opts - i is icons links, s is HTML title included; ignore - skips files matching pat, icon-uri are alternate icons

flex-init

logname=file format.logname= log format

Initializes the flexible log system, identifies a log name and a log file, and defines the format for logging to that file

init-cgi

[timeout=seconds], passthrough

Initializes for CGI activities: time-limits the CGI script, sets an environment variable for the enviroment of the CGI.

init-clf

logname=file

Initializes the Common Log Subsystem and identifies one or more log file names for use in AddLog-class functions

init-uhome

pwfile=file

Loads user home directory info for faster access

load-modules

shlib=sh-obj-file, funcs="func1, func2,..."

Loads shared objects and functions

load-types

mime-types=file, local-types=file

Loads MIME types from files

pool-init

disable=true

Enables/disables server private memory pool allocation



AuthTrans Directive Summary

Function

Parameters

Description

basic-auth

auth-type=type userdb=dbname, userfn=myfunc, [groupdb=groupdbname, groupfn=groupfunc]

Calls a custom function for authorization. Superseded by basic-ncsa.

basic-ncsa

dbm=file, auth-type="basic", userfile=ufile, grpfile=gfile

Translates auth info into user/group, decodes message for request, provides an interface to the user database



NameTrans Directive Summary

Function

Parameters

Description

assign-name

from=shexp, name=objname

Maps named directory prefix to an object. All processing sent to named object.

document-root

root=dir

Sets the document root

home-page

path=file

Specifies the home page for this server

mozilla-redirect

from=pattern, url=URL

Redirect a request from any client that represents itself as Mozilla 0.96 or later.

pfx2dir

from=directory, dir=directory, [name=obj_name]

Maps virtual paths to physical paths

redirect

from=vpath, url=URL | url-prefix=URL

Redirects a virtual path to another URL

unix-home

prefix=homedirs, subdir=dirname, name=objname, pwfile=file

Makes local user dirs available to public



PathCheck Directive Summary

Function

Parameters

Description

cert2user

userdb=authdbpath, [makefrombasic=}{"0"|"1"}], [require={"0"|"1"}], [method=shexpr]

Maps the authenticated client certificate from the SSL3 session to a user name, using the certificate-to-user mappings specified in authdbpath.

deny-existence

path=pattern, bong-msg=file

Sends a "not found" message when a client tries to access a path.

find-index

index-names=file,...

Searches for default files to load when requesting a dir, else output a dir listing

find-links

disable={sho}, dir=path

Searches for symbolic or hard links and deny access

find-pathinfo

Uses extra path info if it can't find a file in the specified path

get-client-cert

[dorequest={"0"|"1"}], [method=shexpr]

Get the authorized client certificate from the SSL3 session.

load-config

file=filename, disable-types=pattern, basedir=dir, [descend=1]

Enables dynamic configuration of directories using filename files resident in the local directories

require-auth

auth-type=basic, realm=name, [auth-group=grp], [auth-users=name,...]

Allows access to objects only if user or group is authorized

unix-uri-clean

Denies access to URL with ., .., ../ or other bad paths

check-acl

acl=aclname, [path=shexp], [bong-file=deny-file]

Attaches an Access Control List to the object in which the directive appears.



ObjectType Directive Summary

Function

Parameters

Description

force-type

[lang=language], [enc=encoding], type=MIME type/subtype>

Force content-type to type. Optionally force language and encoding

shtml-hacktype

exec-hack=true|false

Provide backwards compatibility with server-side includes

type-by-exp

exp=pattern, [lang=language], [enc=encoding], type=MIME type/subtype

Determine content-type based on wildcard expression. Optionally set language and encoding

image-switch

Let server send different image type (such as a JPEG in place of a GIF)

type-by-extension

Determine content-type based on file extension and mime type mapping



Service Directive Summary

Function

Parameters

Description

{any}

[type=MIME type/subtype], [method=(GET|HEAD|POST)], [query=query_string]

Check that each optional wildcard parameter matches before calling Service function

append-trailer

trailer=file, timefmt=time_format

Append file to end of every HTML document

imagemap

Includes imagemap files

index-common

header=file, readme=file

Scan dir, product bulleted entries, reference icons, show additional files

index-simple

Scan dir, produce bulleted entries

parse-html

opts=no-exec

Parse an HTML file for server directives

query-handler

path=file

Run a CGI program instead of the path requested. For ISINDEX.

send-cgi

Run a CGI program and send results

send-error

path=file

Sends an HTML file to client regardless of path requested

send-file

Sends the contents of a plain text file.

send-range

Sends a portion of a document.

upload-file

Handles a browser uploading a new file with the PUT command.

remove-file

Removes (deletes) a file the file specifies through a DELETE command

list-dir

Returns a directory listing in response to a browser's INDEX command

make-dir

Creates a directory the browser requested through the MKDIR command

remove-dir

Removes an empty directory the browser requested through the RMDIR command

rename-file

Renames a file in response to a MOVE command and a New-URL header from the browser

key-toosmall

Returns a message to the browser to report that the secret key size for SSL communications is too small



AddLog Directive Summary

Function

Parameters

Description

record-useragent

name=logfile

Record IP address of each client

record-keysize

name=logfile

Record the keysize for secure transactions

flex-log

name=logfile

Record transaction in the flexible log format

common-log

[name=logfile], [iponly=1]

Record transaction in the common log format. If name is omitted, uses "global". The iponly records IP address, instead of host name.



Error Directive Summary

Function

Parameters

Description

send-error

code=int, reason=string, path=file

Send an HTML file to client if an error occurs

Init directive

Init is a special directive that initializes certain server subsystems such as access logging and user public directories. The functions referenced with the Init directive load data for specific subsystems once on server startup and keep that data internally until the server is shut down. You can specify zero or more Init directives.

Syntax

Init fn=function-name [parm1=value1]...[parmN=valueN]
function-name identifies the server initialization function to call. These functions shouldn't be called more than once.

parm=value pairs are values for function-specific parameters. The number of parameters depends on the function you use. The order of parameters doesn't matter.

The following Init-class functions are described in detail in the following sections:

load-types function

The load-types function scans a file that tells it how to map file-name extensions to MIME types. MIME types are essential to enable network navigation software like Netscape Navigator to tell the difference between file types. For example, they are used to tell an HTML file from a GIF file.

Calling this function is crucial if you use the Server Manager.

Parameters

mime-types specifies either the full path to the global MIME types file or a file name relative to the server configuration directory. The server comes with a default file called mime.types.

local-types is an optional parameter to a file with the same format as the global MIME types file, but it is used to maintain types that are applicable only to your server.

Examples

Init fn=load-types mime-types=mime.types
Init fn=load-types mime-types=/tp/mime.types 
        local-types=local.types

init-clf

The init-clf function initializes the Common Log subsystem. It opens the log files whose names are given as parameters. The log files stay open until the server is shut down or until the base server process is sent the -HUP signal (at which time the logs are closed and reopened).

Initializing this function is required if you are using the common log features.

You use init-clf to specify which log files the server uses to record transactions. Then, you use the AddLog directive in the obj.conf file to specify the log file where the server stores the transaction record (log entry).
For example, you use init-clf to specify a name that refers to a log file (such as http-log=/var/ns-server/loghttp); then you use the name with the AddLog-class function to add a log entry to the file (such as AddLog fn=common-log name=http-log). If you ever change the path or file name of the log file, you only do it once--in the init-clf function.

Note
You also can use AddLog to store transactions in more than one log file.
If you move, remove, or change the log file without shutting down or restarting the server, client accesses might not be recorded. To save or backup a log file, you need to rename the file and then send the -HUP signal to restart the server. The server uses the inode number, but when you do a soft restart, the server first looks for the file name, and if it doesn't find the log file, it creates a new one (the renamed original log file is left for you to use).

Parameters

At least one log file should be specified. The name part of the name-value pair should be a unique name for the log file. You will use this name later on, as a parameter to the common-log function.

Examples

Init fn=init-clf global=/var/ns-server/logs/access 
Init fn=init-clf global=/tmp/server-access

flex-init function

The flex-init function initializes the flexible logging system. It opens the log file whose name is passed as a parameter, and establishes a record format that is passed as another parameter. The log file stays open until the server is shut down or until the base server process is sent the -HUP signal (at which time all logs are closed and reopened).

As in init-clf, you use flex-init to specify a log-file name (such as loghttp=/var/ns-server/loghttp); then you use that name with the AddLog-class flex-log function in obj.conf to add a log entry to the file (such as AddLog fn=flex-log name=loghttp).

Note
You can use AddLog to store transactions in more than one log file.
If you move, remove, or change the log file without shutting down or restarting the server, client accesses might not be recorded. To save or backup a log file, you need to rename the file and then send the -HUP signal to restart the server. The server uses the inode number, but when you do a soft restart, the server first looks for the file name, and if it doesn't find the log file, it creates a new one (the renamed original log file is left for you to use).

Parameters

The flex-init function recognizes two possible parameters: one that names the log file and one that specifies the components of a record in that file.

The flex-init function recognizes anything contained between percent signs (%) as the name portion of a name-value pair stored in a parameter block in your program. (The one exception to this rule is the %SYSDATE% component which delivers the current system date.)

Any additional text is treated as literal text, so you can add to the line to make it more readable. Typical components of the formatting parameter are listed in Table B.9. Certain components might contain spaces, so they should be bounded by escaped quotes (/").

Options for flex-logging

Flex-log option

Component

Escaped

Client host name

%Ses->client.ip%

Authenticate user name

%Req->vars.auth-user%

System date

%SYSDATE%

Full request

/"%Req->reqpb.clf-request%/"

yes

Status

%Req->srvhdrs.clf-status%

Content length

%Req->srvhdrs.content-length%

Referer

/"%Req->headers.referer%/"

yes

User_agent

/"%Req->headers.user-agent%/"

yes

Method

%Req->reqpb.method%

URI

%Req->reqpb.uri%

Query string of the URI

%Req->reqpb.query%

Protocol

/"%Req->reqpb.protocol%/"

yes

Accept header

%Req->headers.accept%

Date header

/"%Req->headers.date%/"

yes

"If Modified Since" header

%Req->headers.if-modified-since%

Authorization

%Req->headers.authorization%

Examples

The first example below initializes flexible logging into the file /usr/ns-home/https-NOTES/logs/access.

Init fn=flex-init access="/usr/ns-home/https-NOTES/logs/access" format.access= 
"%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] /"%Req->reqpb.clf-request%/"  
%Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%" 
This will log the following items

    1. ip or hostname, followed by the three characters " - "
    2. the user name, followed by the two characters " ["
    3. the system date, followed by the two characters "] "
    4. the full request, followed by a single space
    5. the full status, followed by a single space
    6. the content length
This is the default format, which corresponds to the Common Log Format (CLF).

It is advisable that the first six elements of any log always be in exactly this format, because a number of log analyzers expect that as output.

The second example initializes flexible logging into the file /usr/ns-home/https-NOTES/logs/access.

Init fn=flex-init extended="/usr/ns-home/https-NOTES/logs/extended" format.extended= 
"%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] /"%Req->reqpb.clf-request%/"  
%Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%" "%Req->headers.referer%" 
"%Req->headers.user-agent%" "%Req->reqpb.method%" "%Req->reqpb.uri%" "%Req->reqpb.query%" 
"%Req->reqpb.protocol%"

init-uhome function

The init-uhome function loads information about the system's user home directories into internal hash tables. This increases the shared memory size slightly, but saves CPU cycles for servers that have a lot of traffic to home directories.

Parameters

pwfile (optional) specifies the full file system path to a file other than /etc/passwd. If not listed, the default (NIS or /etc/passwd) is used.

Examples

Init fn=init-uhome
Init fn=init-uhome pwfile=/etc/passwd-http

cindex-init function

The function cindex-init configures fancy indexing. You would only use it to do fancy indexing.

Default

Init fn=cindex-init widths=22,1,1,33

Parameters

opts (optional) specifies options to activate for indexing. You specify a string of letters, one for each option to activate:

widths specifies the width for each column in the indexing printout. A zero width disables the column. The string should be a comma-separated list of numbers that specify the column widths according to name, last-modified date, size, and description.

ignore specifies a wildcard pattern for file names the server can ignore while indexing. File names starting with a dot are automatically ignored.

icon-uri specifies the prefix the server uses for icons. By default, this is /mc-icons/. The server looks in this directory for the .GIF files to use in fancy indexing.

Examples

Init fn=cindex-init widths=50,1,1,0
Init fn=cindex-init widths=50,1,1,30 opts=s
Init fn=cindex-init widths=22,0,0,50 opts=is

pool-init function

The pool-init function is a server function added in release 2.0 that activates memory allocation pools, allowing the server to run significantly faster. You typically will not disable this function. It is configurable because it could affect the compatibility of server application functions (SAFs) created with earlier releases.

If you are programming with the server plug-in API, note that MALLOC, REALLOC, STRDUP, and FREE work slightly differently. If pooling is enabled, the server automatically cleans up all memory allocated by these routines when the request completes. In most cases, this clean-up will not cause code to break.

The pool-init function affects any API code that is recompiled with server release 2.0 header files. If your code is not recompiled, it will not break. If you plan to recompile and want persistent memory allocation, add the prefix PERM_ to the name of each routine in your code (PERM_MALLOC, PERM_REALLOC, PERM_STRDUP, and PERM_FREE). If you're programming with the API, you should change to the PERM_ versions, even if you do not plan to recompile.

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 was allocated while processing a request, and because Init-class functions are run before processing any requests, the clean-up is performed anyway.

Syntax

Init fn=pool-init [disable=true]
The pool-init function is on by default. To disable it, include the disable=true name-value pair.

Example

Init fn=pool-init

cache-init function

The cache-init function controls file caching. The server caches files to enhance performance. File caching is enabled by default.

Syntax

Init fn=cache-init cache-size=value1 mmap-max=value2
The cache-init function has three arguments:

Note
To optimize server speed, you should ideally have enough RAM for the server and cache because swapping can be slow. Do not allocate a cache that is greater in size than the amount of memory on the system.

Example

Init fn=cache-init cache-size=512 mmap-max=10000

dns-cache-init function

The dns-cache-init function specifies (when DNS lookups are enabled through a Server Manager setting) that you want to cache the DNS entries. If you cache DNS entries, then when the server gets a client's host name information, it can store the data it receives. Then, if the server needs information about the client in the future, the information available to the server without querying for the information again.

You can specify the size of the DNS cache and the time it takes before a cache entry becomes invalid. The DNS cache can contain 32 to 32768 entries; the default value is 1024 entries. Values for the time it takes for a cache entry to expire can range from 1 second to 1 year (specified in seconds); the default value is 1200 seconds (20 minutes).

Syntax

Init fn=dns-cache-init [cache-size=entries] [expire=seconds]

Parameters

The dns-cache-init function takes two arguments, cache-size and expire.

cache-size specifies how many entries are contained in the cache. Acceptable values for cache-size are 32 to 32768; the default value is 1024.

expire specifies how long it takes for a cache entry to expire. Acceptable values (specified in seconds) for expire are 1 second to 1 year; the default is 1200 seconds (20 minutes).

Example

Init fn="dns-cache-init" cache-size="2140" expire="600"

init-cgi function

The init-cgi function provides certain initializations for the CGI execution. Two options are provided: timeout of the execution of the CGI script, and establishment of environment variables.

Syntax

Init fn=init-cgi [timeout=seconds] [env-var=value]...

Parameters

The init-cgi function takes two kinds of arguments.

seconds specifies how many seconds the server will wait for CGI output. If the CGI script has not delivered any output in that many seconds, the server terminates the script.

env-var=value specifies the name and value for an environment variable that the server will place into the environment for the CGI. You can set any number of environment variables in a single directive.

Example

Init fn= LD_LIBRARY_PATH=/usr/lib;/usr/local/lib

AuthTrans Directive

AuthTrans stands for Authorization Translation. Server resources can be protected so that accessing them requires the client to provide certain information about the person using the client program. This authorization information is encoded to prevent clients from authorizing themselves as a different user.

The server analyzes the authorization of client users into two steps.

  1. it translates authorization information sent by the client.
  2. it requires that such authorization information be present.
This is done in the hope that multiple translation schemes can be easily incorporated, as well as providing the flexibility to have resources that record authorization information but do not require it.

If there is more than one AuthTrans directive in an object, all functions are applied.

basic-auth function

The basic-auth function is obsolete, superseded by the basic-ncsa function.

This function is usually used in conjunction with the PathCheck-class function require-auth.

basic-ncsa function

The basic-ncsa function translates authorization information provided through the basic server authorization scheme. This scheme is similar to the HTTP authorization scheme, but doesn't interfere with it, so using server authorization doesn't prevent the ability to authenticate to the remote server.

This function is usually used in conjunction with the PathCheck-class function require-auth.

Parameters

auth-type specifies the type of authorization to be used. This should always be "basic".

dbm specifies the full path and base file name of the user database in the server's native format. The native format is a system DBM file, which is a hashed file format allowing instantaneous access to billions of users. If you use this parameter, don't use the userfile parameter as well.

userfile specifies the full path name of the user database in the NCSA-style HTTPD user file format. This format consists of lines using the format name:password, where password is encrypted. If you use this parameter, don't use dbm.

grpfile (optional) specifies the NCSA-style HTTPD group file to be used. Each line of a group file consists of group:user1 user2 ... userN where each user is separated by spaces.

Examples

AuthTrans fn=basic-ncsa auth-type=basic  
  dbm=/var/ns-server/userdb/rs
AuthTrans fn=basic-ncsa auth-type=basic 
  userfile=/var/ns-server/.htpasswd  
  grpfile=/var/ns-server/.grpfile

NameTrans directive

NameTrans stands for Name Translation. This directive maps URLs to physical directories on your server. For example, the URL

is a virtual path that could map to the real directory called

NameTrans directives should appear in the root object (the "default" object), although you can put them elsewhere. If there is more than one NameTrans directive in an object, the server applies functions until one succeeds.

pfx2dir function

The pfx2dir function looks for a directory prefix in the path and replaces the prefix with a real directory name. Don't use trailing slashes in either the prefix or the directory.

Parameters

from is the prefix to map.

dir is the directory that the prefix is mapped to.

name (optional) gives a named object (template) from which to derive configuration for this mirror site.

Examples

NameTrans fn=pfx2dir from=/cgi-bin dir=/httpd/cgi-bin name=cgi
NameTrans fn=pfx2dir from=/icons dir=/httpd/mc-icons

unix-home function

The unix-home function lets your internal users provide information to external users. You specify a URL prefix that corresponds to the user directories. Any request that begins with the prefix is translated to the user's home directory.

You specify the list of users with either the /etc/passwd file or a file with a similar structure. Each line in the file should have this structure (elements in the passwd file that aren't needed are indicated with *):

   username:*:*:groupid:*:homedir:*
If you want to have the server scan the password file only once at startup, use the Init-class function init-uhome.

Parameters

from is the URL prefix to translate.

subdir is the subdirectory of the user's directory that contains their documents.

pwfile is the full path and file name of the password file you want to use, if it's different from /etc/passwd or the NIS database.

name (optional) specifies a named object that configures this directory.

Examples

NameTrans fn=unix-home subdir=public_html name=userhome
NameTrans fn=unix-home pwfile=/mydir/passwd subdir=public_html 

document-root function

The document-root function specifies the directory that contains all of your documents. This directory is prepended to the virtual path that the client sent, to create the full path name of the file or directory. For example, the client sends /home/file.html, which is translated to docroot/home/file.html.

Parameters

root specifies the document directory.

Examples

NameTrans fn=document-root root=/netscape/docs

redirect function

The redirect function lets you change URLs and send the updated URL to the client. When a client accesses your server with an old path, they are told to use the new URL you provide.

Parameters

from specifies the old path.

url specifies a complete URL to return to the client. If you use this parameter, don't use url-prefix (and vice-versa).

url-prefix is the new URL to pass to the client. The from prefix is simply replaced by this URL prefix.

Examples

NameTrans fn=redirect from=/ url-prefix=http://tmpserver
nameTrans fn=redirect from=/toopopular  
   url=http://bigger/better/stronger/morepopular/new.html

mozilla-redirect function

The mozilla-redirect function (somewhat like the redirect function) lets you change URLs and send the updated URL to the client. It does this for any user who is using the Netscape Navigator, version 0.96 or later.

Parameters

from specifies the URI wildcard pattern that the directive applies to.

url specifies a complete URL to return to the client. If you use this parameter, don't use url-prefix (and vice-versa).

Example

NameTrans fn=mozilla-redirect from=/ url-prefix=http://newserver

home-page function

The home-page function specifies the home page for your server. Whenever a user doesn't specify a path, they'll get an index file for the document root directory. If you use this function, you specify the .HTML file they see instead. This file must be on the server's local file system.

Parameters

path is the path and name of the home page .HTML file.

Examples

NameTrans fn=home-page path=homepage.html
NameTrans fn=home-page path=/httpd/docs/home.html

assign-name function

The assign-name function associates the name of a configuration object with a path specified by a shell expression. It always returns REQ_NOACTION.

Parameters

shexp specifies a pattern, presented as a shell expression. that specifies a path to be affected.

name is the name of the configuration object to associate with the path.

Example

NameTrans fn=assign-name name=personnel from=/httpd/docs/pers*

PathCheck directive

PathCheck directives check the full file system path that is returned after all of the NameTrans directives finish running. The paths are checked for things such as CGI path info and for dangerous elements such as /./and /../ and //, and then any access restriction is applied.

If there is more than one PathCheck directive in an object, all of the directives are applied in the order they appear.

unix-uri-clean function

The unix-uri-clean function denies access to any requested URL that contains /./, /../ or // (these URLs are potential security problems). If you use scripts with these elements in paths, use the find-pathinfo function (described in the next section) before unix-uri-clean.

Parameters

None.

Examples

PathCheck fn=unix-uri-clean

find-index function

The find-index function investigates whether the requested path is a directory. If it is, the function searches for an index file in the directory, and then changes the path to point to the index file. If no index file is found, the server generates a directory listing.

Parameters

index-names is a comma-separated list of index file names to look for. Use spaces only if they are part of a file name.

Examples

PathCheck fn=find-index index-names=index.html,home.html

require-auth function

The require-auth function allows access to objects only if the user or group is authorized. You must use the AuthTrans directive before using this PathCheck directive with this function.

Parameters

auth-type is the type of HTTP authorization to use. This currently can be only set to basic.

realm is a string (enclosed in double-quotation marks) sent to the client application so users can see what object they need authorization for.

auth-user (optional) specifies a list of users who get access. The list should be enclosed in parentheses with each user name separated by the pipe | symbol.

auth-group (optional) specifies a list of groups that get access. Groups are listed in the password-type file.

Examples

PathCheck fn=require-auth auth-type=basic realm="Marketing Plans"
          auth-group=mktg auth-users=(jdoe|johnd|janed)

load-config function

The load-config function searches for configuration information in document directories.

Parameters

file (optional) is the name of the file to look for in the document directory.

disable-types (optional) specifies a shell expression identifying types to disable for this directory. For example, magnus-internal/cgi.

descend (optional) if present, specifies that the server should search in subdirectories of the base directory for configuration files. For example, descend=1 specifies that the server should search subdirectories. No descend parameter at all would specify that the server shouldn't.

basedir (optional) specifies a directory in which to look for configuration files. If not specified, the server will start from the directory that was specified in name translation (for example, when accessing /a/b/home.html, the filesystem path might be /docroot/a/b/home.html and the name translation directory would be /docroot).

Returns REQ_PROCEED if config files were loaded, REQ_ABORTED on error, or REQ_NOACTION when no files are loaded.

deny-existence function

The deny-existence function sends a "not found" message when a client tries to access a specified path. If this function appears in a <client> region, then it performs access control. The server sends "not found" instead of "forbidden," which means the user can't tell whether the path exists or not.

Parameters

path (optional) is a wildcard pattern of the path to hide. If no paths are specified, then all paths are hidden.

bong-msg specifies a file to send instead of the "not found" message. The file should be an HTML file specified as an absolute path.

Examples

PathCheck fn=deny-existence path=*/~
<client> 
PathCheck fn=deny-existence bong-msg=/svr/msg/go-away.html 
</client>

find-links function

The find-links function searches the current path for symbolic or hard links to other directories or file systems. If any are found, the server returns an error. Usually you use this function in directories you don't trust (such as user home directories). This prevents someone from pointing to information that you don't want made public.

Parameters

disable is a character string of links to disable:

dir is the directory to begin checking. If you specify an absolute path, any request to that path and its subdirectories is checked for symbolic links. If you specify a partial path, any request containing that partial path is checked for symbolic links. For example, if you use /user/ and a request comes in for some/user/directory, then that directory is checked for symbolic links.

Examples

PathCheck fn=find-links disable=sh dir=/foreign-dir
PathCheck fn=find-links disable=so dir=public_html

find-pathinfo function

The find-pathinfo function uses extra path information if it can't find a file in a specified path. Extra path information is included after the path and file in the URL.

Parameters

None.

Examples

PathCheck fn=find-pathinfo

check-acl function

The check-acl function attaches an Access Control List to the object in which the directive appears. Regardless of the order of PathCheck directives in the object, check-acl functions are executed first, and will cause user authentication to be performed, if required by the specified ACL, and will also update the access control state.

Parameters

acl is the name of an Access Control List.

shexp (optional) is a shell expression that specifies the path to which to apply the ACL.

bong-file (optional) is the path name for a file that will be sent if this ACL is responsible for denying access.

Examples

PathCheck fn=check-acl acl="HRonly" 

get-client-cert function

The get-client-cert function gets the authenticated client certificate from the SSL3 session. It can apply to all methods, or only to those that match a specified pattern.

If the certificate is present or obtained from the SSL3 session, the function returns REQ_NOACTION, allowing the request to proceed, otherwise it returns REQ_ABORTED and sets the protocol status to 403 FORBIDDEN, causing the request to fail and the client to be given the FORBIDDEN status.

Parameters

dorequest controls whether to actually try to get the certificate, or just test for its presence. If dorequest is absent the default value is 0.

If a certificate is obtained from the client and verified successfully by the server, the ASCII base64 encoding of the DER-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.

method=shexp specifies a pattern, presented as a shell expression. If a pattern is thus specified, the function will only operate on those requests in which the HTTP method matches the pattern. If method is absent, the function is applied to all requests.

Examples

# Get the client cert from the session, request one if there is not 
# already one associated with the session. Fail the request if the 
# client does not present a valid one. 
PathCheck fn="get-client-cert" dorequest="1" 

cert2user function

The cert2user function maps the authenticated client certificate from the SSL3 session to a user name, using the certificate-to-user mappings in the user database specified by userdb.

Parameters

userdb names the user database from which to obtain the certificate.

makefrombasic tells the directive to establish a certificate-to-user mapping. If makefrombasic is present and is not 0, the directive uses basic password authentication to authenticate the user and to then create a new certificate-to-user mapping in the specified user database if no such mapping has already been created there.

The server allows the certificate-to-user mapping to be created automatically by:

    1. Obtaining and verifying a certificate from the user
    2. Obtaining a user name and password using WWW basic authentication.
    3. Creating a mapping from that certificate to that user (provided both check out ok).
require governs the return value. If the certificate cannot be mapped successfully to a user name, and the value of require is 0, the function returns REQ_NOACTION allowing the processing of the request to continue. But if the value of require is not 0, the function returns REQ_ABORTED and sets the protocol status to 403 FORBIDDEN, causing the request to fail and the client to be given the FORBIDDEN status. The default value of require is 1.

method=shexp specifies a pattern, presented as a shell expression. If a pattern is thus specified, the function will only operate on those requests in which the HTTP method matches the pattern. If method is absent, the function is applied to all requests.

Examples

# Map the client cert to a user using this userdb.  If a mapping is not 
# present, fail the request. 
PathCheck fn="cert2user" userdb="/usr/ns-home/authdb/default" 
require="1"

ObjectType directive

ObjectType directives determine the MIME type of the file sent to the client. This type is usually sent back to the client to let the client decide what to do. MIME attributes currently sent are type, encoding, and language.

If there is more than one ObjectType directive in an object, all of the directives are applied in the order they appear. If a directive sets an attribute and a later directive tries to set that attribute to something else, the first setting is used and the subsequent ones ignored.

type-by-extension function

The type-by-extension function uses file extensions to determine information about files. (Extensions are strings after the last period in a file name.) This matches an incoming request to extensions in the mime.types file. The MIME type is added to the "content-type" header sent back to the client. The type can be set to internal server types that have special results when combined with function you write using the server plug-in API.

Parameters

None.

Examples

ObjectType fn=type-by-extension

image-switch function

The image-switch function allows the server to send a corresponding file of a different type (if the file exists in the same directory) to the client. For example, if someone is using Netscape Navigator to request a graphic.gif file from a Netscape server, and there is a graphic.jpg file in the same server directory, the server can send graphic.jpg to the client. The user will see the requested image, but in JPEG format, which has better color depth and higher compression than GIF images.

Parameters

None.

Examples

ObjectType fn=image-switch

type-by-exp function

The type-by-exp function matches 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 files or directories specified in the URLs.

Parameters

exp is the wildcard pattern of files or directories that the information is applied to.

type (optional) is the type to assign to any matching files.

enc (optional) is the encoding given to matching files (the "content-encoding" header).

lang (optional) is the language assigned to matching paths.

Examples

ObjectType fn=type-by-exp exp=*.test type=application/html

force-type function

The force-type function assigns a type to objects that do not already have a MIME type. This is used to specify a default object type.

Parameters

type is the type to assign to matching files.

enc (optional) is the encoding given to matching files.

lang (optional) is the language assigned to matching paths.

Examples

ObjectType fn=force-type type=text/plain
ObjectType fn=force-type lang=en_US

shtml-hacktype function

The shtml-hacktype function provides backward compatibility with server-side includes.

Server-side includes require a MIME type other than HTML. This means that your parsed documents must have different file extensions than nonparsed documents. If this is a problem, this function can be used as a solution. Another is to have the server parse all HTML, but this can have detrimental performance effects. You can also check for the execute bit on the file. If it's there, the file is parsed; otherwise, it isn't. None of these solutions is recommended. See "Customizing server-parsed HTML" on page 49 for more information on server-parsed HTML.

Parameters

exec-hack (optional) checks if the execute bit is enabled for the file. If you don't specify this parameter, all files are marked as parsed.

Examples

ObjectType fn=shtml-hacktype exec-hack=true

Service directive

Once the other directives have done all the necessary checks and translations, the Service class of functions sends the data (first receiving it from a remote server when necessary) and completes the request.

Service directives support the following optional parameters to help determine whether the directive is used or not:

If there is more than one Service-class function in an object, the first is one is used and all subsequent ones are ignored.

send-file function

The send-file function sends the contents of a plain text file to the client. If this function finds any extra path information, it doesn't send the text file to the client.

Parameters

None.

Examples

Service type=*~magnus-internal/* method=(GET|HEAD) fn=send-file

send-error function

The send-error function sends an HTML file to the client regardless of the path the client requested. This is used mainly for error messages.

Parameters

path specifies the full file system path of the HTML file.

Examples

Service fn=send-error path=/popular/service/we-moved.html
Service fn=send-error path=/http/errors/no-post.html

send-range function

When the client requests a portion of a document, by specifying HTTP byte ranges, the send-range function returns that portion.

Parameters

None.

Examples

Service fn=send-range

append-trailer function

The append-trailer function appends text to the end of every HTML document from the object. This is mainly used for author information and copyright text. The date the file was last modified can automatically be included.

If there is extra path information, the request is flagged as not found and the document isn't send to the client.

Parameters

trailer is the text you want to append to all HTML documents. The text can contain HTML tags and can be approximately 700 characters long. The string :LASTMOD: is replaced by the date the file was last modified; you must also specify a time format with timefmt.

timefmt is a time string in the strftime function format. See your operating system's manual for this format.

Examples

Service fn=Service type=text/html fn=append-trailer
        trailer="<hr><img scr=/logo,gif> Copyright 1995"
Service fn=Service type=text/html fn=append-trailer timefmt="%D"
        trailer="<hr>File last updated on: :LASTMOD:"

send-cgi function

The send-cgi function runs a file as a CGI program and sends the results to the client.

Parameters

None.

Examples

Service fn=send-cgi
Service type=magnus_internal/cgi fn=send-cgi

query-handler function

The query-handler function runs a CGI program instead of referencing the path requested. This is used mainly to support the obsolete ISINDEX tag. If possible, use a FORM instead.

Parameters

path is the full path and file name of the CGI program to run.

Examples

Service query=* fn=query-handler path=/http/cgi/do-grep
Service query=* fn=query-handler path=/http/cgi/proc-info

imagemap function

The imagemap function includes imagemap files.

Parameters

None.

Examples

Service type=magnus_internal/imagemap method=(GET|HEAD) fn=imagemap

index-simple function

The index-simple function scans a directory and produces an HTML file containing a bulleted list of the files in the directory. Each file appears as a link.

If this function encounters a subdirectory, the link redirects the user to the subdirectory. In directories with subdirectories, use fancy indexing as described in the following section.

Parameters

None.

Examples

Service type=magnus-internal/directory fn=index-simple

index-common function

The index-common function scans a directory and produces an HTML file containing a bulleted list of the files in the directory. Each file appears as a link. This function produces a format common to the CERN and NCSA HTTP servers. It includes more information than simple indexing, and references icon files.

Parameters

header names a file to prepend to the indexing that introduces the contents of the directory. If you specify a file name for this parameter, the server looks for the file name as an .HTML file, and then incorporates the file in the directory list as HTML; otherwise, the file is included as plain text.

readme names a file (HTML or plain text) to append to the indexing. This gives more information about the contents of the directory.

Examples

Service type=magnus_internal/directory method=(GET|HEAD) fn=index-
common header=hdr.html readme=end-text.txt

parse-html function

The parse-html function parses an HTML document, scanning for embedded server directives. These server directives provide certain information only the server has, or they include the contents of other files. Parsing lots of HTML documents can reduce server performance.

Parameters

opts are parsing options. The no-exec option is the only currently available option--it disables the exec directive.

Examples

Service type=magnus_internal/parsed-html method=(GET|HEAD) 
        fn=parse-html

upload-file function

The upload-file function enables the server to upload a new file with the PUT command.

Parameters

None.

Examples

Service fn=upload-file

remove-file function

The remove-file function enables the server to delete a file when the client sends a DELETE command.

Parameters

None.

Examples

Service fn=remove-file

list-dir function

The list-dir function enables the server to return a sequence of text lines to the client in response to an INDEX command. The format of the returned lines is:

name type size mimetype

The name field is the name of the file or directory. It is relative to the directory being indexed. It is URL-encoded, that is, any character might be represented by %xx, where xx is the hexadecimal representation of the character's ASCII number.

The type field is a MIME type such as text/html. Directories will be of type directory. A file for which the server doesn't have a type will be of type unknown.

The size field is the size of the file, in bytes.

The mtime field is the numerical representation of the date of last modification of the file. The number is the number of seconds since the epoch (Jan 1, 1970 00:00 UTC) since the last modification of the file.

Parameters

None.

Examples

Service fn=list-dir

make-dir function

The make-dir function enables the server to create a directory when the client sends a MKDIR command. The function can fail if the server can't write to that directory.

Parameters

None.

Examples

Service fn=make-dir

remove-dir function

The remove-dir function enables the server to remove a directory when the client sends a RMDIR command. The directory must be empty (have no files in it). The function can fail if the server can't write to that directory

Parameters

None.

Examples

Service fn=remove-dir

rename-file function

The rename-file function enables the server to rename a file when the client sends a MOVE command and a New-URL header. The function renames the URL to New-URL within a directory.

Parameters

None.

Examples

Service fn=rename-file

key-toosmall function

The key-toosmall function returns a message to the client specifying that the secret key size for SSL communications is too small. This function is designed to be used together with a Client directive to limit access of certain directories to non-exportable browsers.

Parameters

None.

Examples

<Object ppath=/mydocs/secret/*> 
<Client secret-keysize=40> 
Service fn=key-toosmall 
</Client> 
</Object>

AddLog directive

The AddLog directives log the transaction after the request is finished and the server has stopped talking to the client. The server records information about every access clients make, and it records information about the client making the request.

If there is more than one AddLog directive in an object, all are used.

common-log function

The common-log function is an AddLog-class function that records request-specific data in the common log format (used by most HTTP servers). There is a log analyzer in the /extras directory. There are also a number of free statistics generators for the common format.

The log format is specified by the init-server function call.

Parameters

name (optional) gives the name of a log file, which must have been given as a parameter to the init-clf Init function. If no name is given, global is assumed.

iponly (optional) instructs the server to skip looking up the host name of the remote client and to record the IP address instead. The value of iponly has no significance, as long as it exists; the Server Manager sets iponly="1".

Examples

# Log all accesses to the central log file 
AddLog fn=common-log 
# Log non-local accesses to another log file 
<Client ip=*~198.93.9[2345].*> 
AddLog fn=common-log name=nonlocal 
</Client>

flex-log function

The flex-log function is an AddLog-class function that records request-specific data in the flexible log format. There is a log analyzer in the /extras directory. There are also a number of free statistics generators for the common format.

The log format is specified by the flex-init function call.

Parameters

name (optional) gives the name of a log file, which must have been given as a parameter to the init-clf Init function. If no name is given, global is assumed.

iponly (optional) instructs the server to skip looking up the host name of the remote client and to record the IP address instead. The value of iponly has no significance, as long as it exists; the Server Manager sets iponly="1".

Examples

# Log all accesses to the central log file 
AddLog fn=flex-log 
# Log non-local accesses to another log file 
<Client ip=*~198.93.9[2345].*> 
AddLog fn=flex-log name=nonlocal 
</Client>

record-useragent function

The record-useragent function records the IP address of each client, followed by their User-Agent HTTP header. This tells the server what version of Netscape Navigator (or which other client) was used for this transaction.

Parameters

name (optional) gives the name of the log file where the log is recorded--it must have been specified with the init-clf function. If no name is listed, the log is recorded in global.

Examples

AddLog fn=record-useragent name=browsers-used

Error directive

At any time during a request, conditions can occur that cause the server to stop fulfilling a request and then return an error to the client. When such conditions happen, the server can send a short HTML page to the client telling them in very general terms about the error.

In order to make error handling more friendly, the server lets you intercept certain errors and send a file of your choosing instead of the server's default error message.

The following is a list of errors that the server returns. Each line shows the three-digit HTTP code that designates the error, followed by a short phrase describing the error.

The only logical function to use in an Error directive is the send-error function.

send-error function

The send-error function sends an HTML file to the client.

Parameters

path specifies the full file system path of the HTML file you want sent to the client.

Use reason or Code; but not both.

Examples

Error fn=send-error Code=401 path=/var/ns-server/errors/401.html

The mime.types file

The mime.types file tells the server how to convert files that have certain extensions (such as .GIF) into a Multipurpose Internet Mail Extensions type (such as image/gif). MIME files are compact files and transfer quickly. Also, MIME is needed by clients (like Netscape Navigator); without MIME they couldn't tell the difference between an HTML page and a graphic file.

The mime.types file contains the global file extensions for all servers. The first line in the file identifies the file format and must read:

#--Netscape Communications Corporation MIME Information
Other noncomment lines have the following format:

type=type/subtype exts=[file extensions] icon=icon

Parameters

Internal icons for MIME types

Here is an example of a mime.types file:

#--Netscape Communications Corporation MIME Information 
# Do not delete the above line. It is used to identify the file type. 
type=application/octet-stream  exts=bin,exe 
type=application/oda           exts=oda 
type=application/pdf           exts=pdf 
type=application/postscript    exts=ai,eps,ps 
type=application/rtf           exts=rtf 
type=application/x-mif         exts=mif 
type=application/x-csh         exts=csh 
type=application/x-dvi         exts=dvi 
type=application/x-hdf         exts=hdf 
type=application/x-latex       exts=latex 
type=application/x-netcdf      exts=nc,cdf 
type=application/x-sh          exts=sh 
type=application/x-tcl         exts=tcl 
type=application/x-tex         exts=tex 
type=application/x-texinfo     exts=texinfo,texi 
type=application/x-troff       exts=t,tr,roff 
type=application/x-troff-man   exts=man 
type=application/x-troff-me    exts=me 
type=application/x-troff-ms    exts=ms 
type=application/x-wais-source exts=src 
type=application/zip           exts=zip 
type=application/x-gtar        exts=gtar 
type=application/x-shar        exts=shar 
type=application/x-tar         exts=tar 
type=application/mac-binhex40  exts=hqx 
 
type=audio/basic               exts=au,snd 
type=audio/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-cmu-raster        exts=ras 
type=image/x-portable-anymap   exts=pnm 
type=image/x-portable-bitmap   exts=pbm 
type=image/x-portable-graymap  exts=pgm 
type=image/x-portable-pixmap   exts=ppm 
type=image/x-rgb               exts=rgb 
type=image/x-xbitmap           exts=xbm 
type=image/x-xpixmap           exts=xpm 
type=image/x-xwindowdump       exts=xwd 
 
type=text/html                 exts=htm,html 
type=text/plain                exts=txt 
type=text/richtext             exts=rtx 
type=text/tab-separated-values exts=tsv 
type=text/x-setext             exts=etx 
 
type=video/mpeg                exts=mpeg,mpg,mpe 
type=video/quicktime           exts=qt,mov 
type=video/x-msvideo           exts=avi 
type=video/x-sgi-movie         exts=movie 
 
enc=x-gzip exts=gz 
enc=x-compress exts=z 
enc=x-uuencode exts=uu,uue 
 
type=magnus-internal/imagemap  exts=map 
type=magnus-internal/parsed-html exts=shtml 
type=magnus-internal/cgi exts=cgi,exe,bat

The admpw file

The admpw file contains the Administration password. If you forget your password, there is no way to find out what it was. You must encrypt a new one and replace the old version with it. The file has the format user:password.

You can create multiple Administration users by creating an NCSA-type of user database, and then rename that file to replace admpw.

If you forget your Administration password, you can edit the admpw file and delete the password section (everything after the colon). When you go to the Server Manager, you won't need to enter a new password, but you should immediately go to the Server Manager and set a new one.

Warning
Because you can do this, it is important to keep secure the server's Unix ID account and to ensure that only that server account and the root account have full (write) access to the server root directory. This way, only someone running as root or with the server's user account can enter the [ServerRoot]/admserv directory and edit the admpw file.