NSAPI Programmer's Guide for Enterprise Server 4.0
Table of Contents | Previous | Next | Index | Bookshelf

NSAPI Programmer's Guide for Enterprise Server 4.0

Appendix B
Variables in magnus.conf

When the Enterprise Server starts up, it looks in a file called magnus.conf in the server-id/config directory to establish a set of global variable settings that affect the server's behavior and configuration.

Each directive in magnus.conf specifies a variable and a value, for example:

ServerID https-boots.mcom.com
ServerName boots.mcom.com
Address 123.45.67.89
The order of the directives is not important.

This appendix lists the global settings that can be specified in magnus.conf in Enterprise Server 3.x and 4.0.

The categories are:

For an alphabetical list of directives, see Appendix I, "Alphabetical List of Directives in magnus.conf."

Note

In Enterprise Server 4.0, much of the functionality of the file cache is controlled by a new configuration file called nsfc.conf. For information about nsfc.conf, see the tuning chapter in the Administrator's Guide for Enterprise Server 4.0.

Server Information

This sub-section lists the directives in magnus.conf that specify information about the server. They are:

Address

If a server has multiple IP addresses and you want it listen for requests only at a specific IP address, set the value of this directive.

Concurrency

This directive determines the number of CPU processors that the server uses. By default, the server uses all the CPU processors. You only need to set this directive if you want the server to use less than the available processors.

MtaHost

Specifies the name of the SMTP mail server used by the server's agents. This value must be specified before reports can be sent to a mailing address.

Port

The Port directive determines which TCP port the server listens to. There should be only one Port directive in magnus.conf.

Unix: If you choose a port number less than 1024, the server must be started as root.

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 (unsecured servers) or 443 (secured servers).

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 (Unix only)

ServerID

Specifies the server ID, such as https-boots.mcom.com.

ServerName

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

ServerRoot

Specifies the server root, such as d:/netscape/server4/https-boots.mcom.com. This directive is set during installation and is commented out. Unlike other directives, the server expects this directive to start with #. Do not change this directive. If you do, the Server Manager may not function properly.

Syntax

#ServerRoot d:/netscape/server4/https-boots.mcom.com

User

Windows NT: The User directive specifies the user account the server runs with. By using a specific user account (other than LocalSystem), you can restrict or enable system features for the server. For example, you can use a user account that can mount files from another machine.

Unix: 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 that 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 user account.

Default

If there is no User directive, the server runs with the user account it was started with.

Examples

User http
User server
User nobody

VirtualServerFile

The value of this directive is the name of a file that specifies virtual servers. Each line in this file contains an IP, docroot pair.

Object Configuration File

This subsection lists the directives in magnus.conf that provide information about the object configuration file that instructs the server how to handle requests. These directives are:

LoadObjects

The LoadObjects directive specifies one or more object configuration files to use on startup, most notably obj.conf, which contains instructions that tell the server how to handle requests from clients.

Note: Although you can have more than one object configuration file, the Server Manager interface works on only one file and assumes that it is the file obj.conf in the config directory in the server root directory. If you use the Server Manger interface, 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.
Unix: When the server starts executing, relative path names are resolved from the directory specified with the -d command lien flag. If no -d flag was given, the server looks in the current directory.

Default

There is no default. Make sure that your magnus.conf loads the obj.conf object, otherwise your server will not be able to process requests from clients.

Examples

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

RootObject

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

Language Issues

This section lists the directives in magnus.conf related to language issues. The directives are:

AcceptLanguage

This directive determines whether or not the server parses the Accept-Language header sent by the client to indicate which languages the client accepts. If the value is on, the server parses this header and sends an appropriate language version based on which language the client can accept. You should set this value to on only if the server supports multiple languages.

When this directive is set to on, the accelerator cache is disabled since it does not use AcceptLanguage in its cache keys.

Default

The default value is off.

AdminLanguage

For an international version of the server, this directive specifies the language for the Server Manager. Values en (English), fr (French), de (German) or ja (Japanese).

ClientLanguage

For an international version of the server, this directive specifies the language client messages (such as File Not Found). Values en (English), fr (French), de (German) or ja (Japanese).

DefaultLanguage

For an international version of the server, this directive specifies the default language for the server. The default language is used for both the client responses and administration. Values en (English), fr (French), de (German) or ja (Japanese).

DNS Lookup

This section lists the directives in magnus.conf that affect DNS lookup. The directives are:

AsyncDNS

Specifies whether asynchronous DNS is allowed. The value is either on or off. If DNS is enabled, enabling asynchronous DNS improves server performance.

DNS

The DNS directive specifies whether the server performs DNS lookups on clients that access the server. When a client connects to your server, the server knows the client's IP address but not its host name (for example, it 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

Threads, Processes and Connections

This subsection lists the directives in magnus.conf that affect the number and timeout of threads, processes, and connections. They are:

Also see the section "Native Thread Pools" for new directives in Enterprise Server 4.0 for controlling the pool of native kernel threads.

BlockingListenSockets

This directive determines whether or not the server's sockets listen in blocking mode. Do not use this directive with SSL.

KeepAliveTimeout

This directive determines the maximum time that the server holds open an HTTP Keep-Alive connection or a persistent connection between the client and the server. The Keep-Alive feature for earlier versions of the server allows the client/server connection to stay open while the server processes the client request. For Enterprise Server 3.0+, the default connection is a persistent connection that remains open until the server closes it or the connection has been open for longer than the time allowed by KeepAliveTimeout.

KernelThreads

Enterprise Server can support both kernel-level and user-level threads whenever the operating system supports kernel-level threads. Usually, the standard debugger and compiler are intended for use with kernel-level threads. By setting KernelThreads to on, you ensure that the server uses only kernel-level threads, not user-level threads.

ListenQ

Defines the number of incoming connections for a server socket.

MaxKeepAliveConnections

Specifies the maximum number of Keep-Alive and persistent connections that the server can have open simultaneously.

Default

200

MaxProcs

New in Enterprise Server 4.0.

Specifies the maximum number of processes that the server can have running simultaneously. If you don't include MaxProcs in your magnus.conf file, the server defaults to running a single process.

There is additional discussion of this and other server configuration and performance tuning issues in the "Configuring the Server for Performance" chapter in the Enterprise Server 4.0 Administrator's Guide, which can be found at 

http://home.netscape.com/eng/server/webserver/4.0/ag/esperfrm.htm
The "Enterprise Server 4.0 Administrator's Guide " is also shipped in the Enterprise Server 4.0 build in the manuals/ag directory.

PostThreadsEarly

If this directive is set to on, the server checks the whether the minimum number of threads are available at a socket (as specified by RqThrottleMinPerSocket) after accepting a connection but before sending the response to the request. Use this directive when the server will be handling requests that take a long time to handle, such as those that do long database connections.

RcvBufSize

Controls the size of the receive buffer at the server's sockets.

RqThrottle

Specifies the maximum number of simultaneous requests that the server can handle simultaneously per socket. Each request runs in its own thread.

There is additional discussion of this and other server configuration and performance tuning issues in the "Configuring the Server for Performance" chapter in the Enterprise Server 4.0 Administrator's Guide, which can be found at 

http://home.netscape.com/eng/server/webserver/4.0/ag/esperfrm.htm
The "Enterprise Server 4.0 Administrator's Guide " is also shipped in the Enterprise Server 4.0 build in the manuals/ag directory.

Default

512

RqThrottleMinPerSocket

Specifies the approximate minimum number of threads that wait at each socket for requests to come in.

SndBufSize

Controls the size of the send buffer at the server's sockets.

StackSize

Determines the maximum stack size for each request handling thread.

TerminateTimeout

Specifies the time that the server waits for all existing connections to terminate before it shuts down.

Native Thread Pools

New in Enterprise Server 4.0.

This section lists the directives for controlling the size of the native kernel thread pool. These directives are all new in Enterprise Server 4.0. In previous versions of the server, you could control the native thread pool by setting the system variables NSCP_POOL_STACKSIZE, NSCP_POOL_THREADMAX, and NSCP_POOL_WORKQUEUEMAX.

NOTE:
If you have set these values as environment variables and also in magnus.conf, the environment variable values will take precedence.
The directives are:

NativePoolStackSize

New in Enterprise Server 4.0.

Determines the stack size of each thread in the native (kernel) thread pool.

NativePoolMaxThreads

New in Enterprise Server 4.0.

Determines the maximum number of threads in the native (kernel) thread pool.

Default

128

NativePoolMinThreads

New in Enterprise Server 4.0.

Determines the minimum number of threads in the native (kernel) thread pool.

Default

1

NativePoolQueueSize

New in Enterprise Server 4.0.

Determines the number of threads that can wait in the queue for the thread pool. If all threads in the pool are busy, then the next request-handling thread that needs to use a thread in the native pool must wait in the queue. If the queue is full, the next request-handling thread that tries to get in the queue is rejected, with the result that it returns a busy response to the client. It is then free to handle another incoming request instead of being tied up waiting in the queue.

CGI

This section lists the directives in magnus.conf that affect requests for CGI programs. The directives are:

CGIExpirationTimeout

New in Enterprise Server 4.0.

This directive specifies the maximum time in seconds that CGI threads are allowed to run before being killed.

The value of CGIExpirationTimeout should not be set too low - 5 minutes would be a good value for most interactive CGIs; but if you have CGIs that are expected to take longer without misbehaving, then you should set it to the maximum duration you expect a CGI program to run normally.

CGIWaitPid (UNIX Only)

This directive is to prevent defunct processes on UNIX systems for each SHTML access. If the value is on, the server calls waitpid explicitly to pickup terminated shtml or CGI child processes.

Error Logging and Statistic Collection

This section lists the directives in magnus.conf that affect error logging and the collection of server statistics. They are:

DaemonStats (Unix Only)

This directive specifies whether or not the server collects some daemon statistics. The value is on or off. If the value is off, SNMP statistic collection will not work.

ErrorLog

The ErrorLog directive specifies the directory where the server logs its errors. If errors are reported to a file, then the file and directory in which the log is kept must be writable by whatever user account the server runs as.

Unix: You can also use the syslog facility.

Syntax

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

Default

There is no default error log.

Examples

Windows NT:
ErrorLog C:\Netscape\ns-home\Logs\Errors
Unix:
ErrorLog /var/ns-server/logs/errors
ErrorLog SYSLOG

LogVerbose

This directive determines whether verbose logging occurs or not. If the value is on, the server logs all server messages including those that are not logged by default (such as WAI initialization messages).

PidLog

PidLog specifies a file in which to record the process ID (pid) of the base server process. Some of the server support programs assume that this log is in the 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

ACL

This section lists the directives in magnus.conf relevant to access control lists (ACLs).

ACLFile

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 the ACL definitions in all the specified ACL definition files when it starts up. Each ACL file must have a unique name.

Usually the value of ACLFile is generated.https-servername.acl, and it resides in the httpacl directory of the server installation directory.

Syntax

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

Example

ACLFile d:/netscape/server4/httpacl/generated.https- boots.mcom.com.acl

Security

This section lists the directives in magnus.conf that affect server access and security issues for Enterprise Server. They are:

Chroot (Unix only)

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

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

Security

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

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.

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.

SSLCacheEntries

Specifies the number of SSL sessions that can be cached.

SSLClientAuth

The SSLClientAuth directive causes SSL3 client authentication on all requests.

Syntax

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

SSLSessionTimeout

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.

SSL2

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

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

SSL3Ciphers

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.

SSL3SessionTimeout

The SSL3SessionTimeout directive controls SSL3 session caching.

Syntax

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

Miscellaneous

This section lists miscellaneous other directives in magnus.conf.

Umask (UNIX only)

This directive specifies the umask value used by the NSAPI functions System_fopenWA() and System_fopenRW() to open files in different modes. Valid values for this directive are standard UNIX umask values.

For more information on these functions, see system_fopenWA() and system_fopenRW() in Chapter 5, "NSAPI Function Reference."

Table of Contents | Previous | Next | Index | Bookshelf

Last Updated: 08/12/99 14:33:09

Copyright © 1999 Netscape Communications Corporation