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.

Note
The configuration information stored in the Registry in the version 1.1 Web servers is now stored in the configuration files.

You might need to manually configure the server for various reasons. If you accidentally lock your hosts out of the administrative forms or if you forget your administrative password, you'll have to manually change information in the server's configuration files.

Before you can edit any of the configuration files, you must have permission to read and write to the files. This probably means you need to log in as root.
The magnus.conf, obj.conf, and mime.types files are kept in the config directory in your server root directory; the admpw file is in the admserv directory in your server root directory.

The magnus.conf file

The technical configuration file, called magnus.conf, controls all server operations not related to handling of documents or directories. (The obj.conf file handles these.) All of the items in magnus.conf are global and apply to the entire server, as opposed to affecting only one document or set of documents.

Every command line in the file has the format:

Directive Value

Sample magnus.conf file

# Sample magnus.conf file for Netscape server 2.0
# The server's home--its root directory
ServerRoot /usr/ns-home/https-server1
# The server's name
ServerName www.netscape.com
# Which port?
Port 443
# This tells the server to get its objects from obj.conf, and use
# the "default" object as the default.
LoadObjects obj.conf
RootObject default
# The logfile for errors, and the file where it should keep
# the pid of the master server process.
ErrorLog /usr/ns-home/https-server1/logs/errors
PidLog /usr/ns-home/https-server1/logs/pid
# Which user should the server run as? This is the UNIX user
# account name.
User http
# Processes - number of processes to spawn
MaxProcs 1
MinThreads 4
MaxThreads 128
# Use DNS? (turn this off for performance reasons)
DNS on
# Security directives: is security on, where is my keyfile,
# which ciphers should I support (Ciphers directive is on the
# US version only)
Security on
Keyfile ServerKey.der
Certfile ServerCert.der
Ciphers +rc4, +des, +rc4export

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

ServerName 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

Port 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

User 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

MaxProcs 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

MinThreads 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 between 1 and

number is a whole number between 1 and

DEFAULT
MinThreads 4

EXAMPLES
MinThreads 6
MinThreads 8

MaxThreads

ErrorLog

ErrorLog 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

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 the pid 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 pathname and filename where the process ID is stored.

DEFAULT
There is no default.

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

LoadObjects

LoadObjects 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's Administration forms only work with one file and assume that it is in the server root in config/obj.conf. If you use the Administration forms (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 pathname or a relative pathname. Relative pathnames 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

RootObject 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 Administration forms assume the default to be the default named object. Don't deviate from this convention if you use (or plan to use) the Administration forms.

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.

EXAMPLES
RootObject default
RootObject server1

Chroot

Chroot lets the UNIX system administrator place the server into a "jail," where it only has access to files in a given 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 pathname to the directory used as the server's root directory.

DEFAULT
There is no default.

EXAMPLES
Chroot /d/ns-httpd
Chroot /www

DNS

DNS specifies if 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 hostname (for example, it knows the client as 198.95.251.30, rather than its hostname www.a.com). The server will resolve the client's IP address into a hostname 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 hostname resolution; doing so can reduce the load on the DNS or NIS server.

SYNTAX
DNS [on|off]

DEFAULT
Hostname resolution is on as a default.

EXAMPLE
DNS on

Security

The Security directive tells the server whether security is enabled or disabled.

SYNTAX
Security [on|off]

DEFAULT
By default, security is off.

EXAMPLE
Security off

ServerKey

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

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

The Ciphers directive specifies the ciphers enabled for your server.

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

The obj.conf file

The object configuration file, called obj.conf, uses objects to control how the server handles documents.

Objects (also referred to as resources) are settings that tell the server how to treat all documents, CGI programs, directories, imagemap files, and so on. You can define objects in two ways:

The structure of obj.conf

The obj.conf file must have four specific objects in it. You can add other objects to this file. To specify an object, you use the following format:

<Object ppath=wildcardpattern>
Directives

  <Client dns=wildcardpattern>
    Directives
   
  </Client>
</Object>
<Object name=cgi>
Directives

</Object>
You use wildcard patterns to control what is grouped in the object, or you use a name to create a template. You then specify one or more directives to control what the server does when it encounters anything that uses the template or that matches the wildcard pattern specified with ppath.

You can also set options for specific client hosts. This is a powerful feature because, unlike other servers where a host either can or cannot access a document, you make the server act differently for a client depending on the document they access. Although you don't need any <Client> sections in an object section, you can specify more than one--so the server acts differently based both on who requests something and what they request.

Directive syntax

Each directive line (regardless of where it appears) has the format:

Directive fn=function [parameter1=value1][parameterN=valueN]
Directive identifies an aspect of server operation. This string is case insensitive and must appear at the beginning of a line.

Function is a function and parameters given to the directive. Its format depends on the directive.

Comment lines begin with a # character with no leading white space.
Directive lines can contain white space at the beginning of the line and between the directive and value, but trailing white space after the value might confuse the server. Long lines (which should only occur with the Init directive) can be continued with a space before the linefeed.

A sample object

The following sample object applies to the /user/public/ directory.

When the server receives a request for a document in this directory, it doesn't send the document. Instead, it denies the existence of any files or subdirectories and displays the "not found" error message.

<Object ppath="/user/public/*">
PathCheck fn=deny-existence
Service fn=server-retrieve
</Object>
The Service directive tells the server to get the documents by default.

Sample obj.conf file

#
# Sample obj.conf file for Netscape server 2.0.
#
# This file was automatically generated by the server.
# Edit at your own risk.
# The default object. This is what the server uses if none of the other
# objects fit.
#
# This one has a CGI directory specified in /usr/local/bin/cgi,
# a directory mapping to a bigger disk in /gig-drive/sales,
# and a document root of /usr/http-docs
#
# Initializations, such as log files and loading NSAPI libraries
Init format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%" fn="flex-init" access="/usr/ns-home/httpd-80/logs/access"
Init fn=load-types mime-types=mime.types
Init fn="dns-cache-init" cache-size="512" expire="1200"

<Object name="default">
NameTrans from="/ns-icons" fn="pfx2dir" dir="/usr/ns-home/ns-icons"
NameTrans from="/cgi-bin" dfn="pfx2dir" ir="/usr/local/bin/cgi" name="cgi"
NameTrans from="/sales" fn="pfx2dir" dir="/gig-drive/sales"
NameTrans root="/usr/http-docs" fn="document-root"
PathCheck fn="unix-uri-clean"
PathCheck fn="find-pathinfo"
PathCheck index-names="index.html,home.html" fn="find-index"
ObjectType fn="type-by-extension"
ObjectType fn="force-type" type="text/plain"
Service fn="imagemap" method="(GET|HEAD)" type="magnus-internal/imagemap"
Service fn="index-common" method="(GET|HEAD)" type="magnus-internal/directory"
Service fn="send-cgi" type="magnus-internal/cgi"
Service fn="send-file" method="(GET|HEAD)" type="*~magnus-internal/*"
AddLog fn="flex-log" name="access"
</Object>

# All CGI directories have these configuration options set
<Object name="cgi">
ObjectType fn="force-type" type="magnus-internal/cgi"
Service fn="send-cgi"
</Object>

Required objects for obj.conf

There are certain objects that must be in the obj.conf file to make the Administration forms work for your server. These functions control local file access and CGI execution.

The following sections describe the objects that must be in obj.conf.

The default object

<Object name="default">
NameTrans fn="pfx2dir" from="/mc-icons" dir="/usr/home/mc-icons"
NameTrans fn="document-root" root="/usr/http-docs"
PathCheck fn="unix-uri-clean"
PathCheck fn="find-pathinfo"
ObjectType fn="type-by-extension"
ObjectType fn="force-type" type="text/plain"
Service fn="imagemap" method="(GET|HEAD)"
type="magnus-internal/imagemap"
Service fn="index-common" method="(GET|HEAD)"
type="magnus-internal/directory"
Service fn="send-file" method="(GET|HEAD)"
type="*~magnus-internal/*"
</Object>

CGI Object

This object controls the admin form handler scripts and should read exactly as follows:

  <Object name="cgi">
ObjectType fn="force-type" type="magnus-internal/cgi"
Service fn="send-cgi"
</Object>

How the server handles objects

The Netscape design breaks down the process of responding to an information request. Each step in the process is done once for all objects, then another step is done for all objects, and so on. The process steps are as follows:

  1. Authorization translation. Translate any authorization information given by the client into a user and group. If necessary, decode the message to get the actual request. Also, server authorization is available.
  2. Name translation. Before anything else is done, a URL can be translated into a filesystem-dependent name (an administration URL), a redirection URL, mirror site URL, or it might be kept intact and retrieved as-is (the normal server case).
  3. Path checks. Perform various tests on the resulting path, largely used to make sure that it's safe for the given client to retrieve the document (only for local access).
  4. Object types. Determine the MIME type information for the given document. MIME types can be registered document types such as text/html and image/gif, or they can be internal document identification types. Internal types always begin with magnus-internal/, and are used to select a server function to use to deCode the document. (Only used for local access, the server system calls these routines automatically when necessary.)
  5. Service. Select an internal server function that should be used to send the result back to the client. This function can be the normal server-service routine, or local file blast, or a CGI execution for admin forms.
  6. Log. Select a function to record information about the transaction that just finished. These steps map directly to six of the configuration directives allowed for each object. There is a seventh configuration directive (send-error) that controls how the server responds to the client when it encounters an error.

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

Init

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 functions are described in detail in the following sections:

load-types

The function load-types scans a file that tells it how to map file-name extensions to MIME types. MIME types are essential for 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 Administration forms.

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 re-opened).

Initializing this function is required if you are using the common log features.
You use this function 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.

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 function in obj.conf to add a log entry to the file (such as AddLog fn=server-log name=http-log). If you ever change the path or file name of the log file, you only do it once--in magnus.conf--instead of multiple times in obj.conf.

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 given. The parm part of the parm=value pair should be a unique name for the log file. You will use this name later on, as a parameter to the server-log function.

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

init-uhome

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

The function cindex-init configures fancy indexing. You must use fancy indexing for this function to work.

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:

pool-init

The pool-init function is a new Netscape FastTrack Serverfunction that turns on memory allocation pools, allowing the server to run significantly faster. You typically will not disable this function. It is configurable because it could affect NSAPI compatibility. If you are programming with NSAPI, 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 NSAPI code that is recompiled with Netscape FastTrack Server 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 each routine (PERM_MALLOC, PERM_REALLOC, PERM_STRDUP, and PERM_FREE). If you're programming with NSAPI, you should change to the PERM_ versions, even if you do not plan to recompile.

Note
If you're using Init functions to allocate memory, it 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 functions are run before processing any requests, the clean-up is performed anyway.

SYNTAX
Init fn=pool-init

The pool-init function is on by default. To disable it, replace Init fn=pool-init with Init fn=pool-init disable=true in the obj.conf file.

EXAMPLE
Init fn=pool-init

cache-init

The server caches files to enhance performance. The file cache is enabled by default and is controoled by the cache-init function.

SYNTAX
Init fn=cache-init cache-size mmap-max

The cache-init function has three arguments:

dns-cache-init

If you enable DNS lookups, you can also specify whether you want to cache the DNS entries. When the server gets a client's hostname information, it can store the data it receives if you've enabled the DNS cache. If the server needs information about the client in the future, the information is cached and available for 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 expire

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"

AuthTrans

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. First, it translates authorization information sent by the client, and then 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 NCSA

DESCRIPTION
basic-ncsa 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 function require-server-auth.

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

dbm specifies the full path and base filename 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 userfile as well.

userfile specifies the full pathname 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 the next one.

grpfile (optional) specifies the NCSA-style httpd group file to be used. Each line of a group file consists of group:user1 user2userN 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

NameTrans stands for Name Translation. This directive maps URLs to physical directories on your server. For example, the URL http://www.test.com/some/file is a virtual path that could map to the real directory called /docs/http/files/.

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.

Prefix to directory

DESCRIPTION
pfx2dir 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

Public information directories

DESCRIPTION
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 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 prefix=/~ subdir=public_html name=userhome

NameTrans fn=unix-home prefix=/u subdir=public_html name=userhome



Document root

DESCRIPTION
The document-root function specifies the directory that contains all of your documents. This directory is prepended to the virtual path that the client sends to form the full pathname 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

Redirection

DESCRIPTION
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

Home page

DESCRIPTION
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 filesystem.

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

PathCheck

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.

URI cleaning

DESCRIPTION
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 files for directories

DESCRIPTION
The find-index function determines if 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 authorization

DESCRIPTION
The require-auth function allows access to objects only if the user or group is authorized. You must use the AuthTrans directive before using the 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 | character.

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)

Deny path's existence

DESCRIPTION
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. Note that "not found" is sent instead of "forbidden," which means the user can't tell if 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 file system links

DESCRIPTION
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:

ObjectType

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.

File typing by extension

DESCRIPTION
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 NSAPI. See the Programmer's Guide for more information.

PARAMETERS
None.

EXAMPLES
ObjectType fn=type-by-extension

Image switching

DESCRIPTION
The image switching 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 will 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

File typing by wildcard pattern

DESCRIPTION
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

Forcing file types

DESCRIPTION
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

Server-parsed HTML

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

Server-side includes require a different MIME type 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 the Programmer's Guide for more information on server-parsed HTML.

PARAMETERS
exec-hack (optional) checks if the execute bit is enables 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

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:

AddLog

After the request is finished and the server has stopped talking to the client, the server logs the transaction. 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.

Log in the Common Format

DESCRIPTION
common-log is an AddLog 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 records the IP address instead. The value of iponly has no significance, as long as it exists; the Administration forms set 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>

Record the client software name

DESCRIPTION
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 browser) the client 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

At any time during a request, conditions can occur that stop the server from fulfilling a request and then return an error to the client. When these 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 are returned by the server. Each line has the 3-digit HTTP Code that designates the error, followed by a short description of the error.

The mime.types file

The mime.types file tells the server how to convert files with 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 browsers (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 non-comment lines have the following format:

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

Internal icons for MIME types

Sample 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 Administration 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.