Oracle iPlanet Web Proxy Server 4.0.14 Configuration File Reference

Chapter 3 Syntax and Use of the magnus.conf File

At startup, Proxy Server 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. Proxy Server executes all the directives defined in magnus.conf. The order of the directives is not important.


Note –

When you edit the magnus.conf file, you must restart the server for the changes to take effect.


This chapter describes the global settings that can be specified in magnus.conf in Proxy Server 4. The setting categories are:

For an alphabetical list of directives, see Appendix C, Server Configuration Elements.

Server Information

This section lists the directives in magnus.conf that specify information about the server, which are:

Server Name Directive

Specifies the server name.

Server ID Directive

Specifies the server ID.

User Directive

Windows: 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 restriction ensures that in the unlikely event that someone compromises the server, that person will not be able to change configuration files and gain broader access to your machine. Specifying the nobody user is not recommended.

Syntax

User name

name is the login name for the UNIX user account, which can be a maximum of eight characters long.

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

NetsiteRoot

Specifies the server root. 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.

Syntax

#NetsiteRoot path

Example

#ServerRoot <install-root>/<instance-directory>

DNS Lookup

This section lists the directives in magnus.conf that affect DNS (Domain Name System) lookup. The directives are:

AsyncDNS

Specifies whether asynchronous DNS is allowed. This directive is ignored. Even if the value is set to on, the server does not perform asynchronous DNS lookups.

DNS Directive

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 receives the client’s IP address but not its host name. For example, the server identifies 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 or need to stop host name resolution. Limiting resolution can reduce the load on the DNS or NIS (Network Information System) server.

Syntax

DNS [on|off]

Default

DNS host name resolution is off as a default

Example

DNS on

Process Directive

This section describes UNIX only MaxProcs directive in magnus.conf that affect the number and timeout of threads, processes, and connections. MaxProcs 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.

One process per processor is recommended if you are running in multi process mode. In Proxy Server 4, a basic process is always running in addition to the number of active processes specified by this setting.

Default

1

Error Logging and Statistic Collection

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

ErrorLogDateFormat

Syntax

ErrorLogDateFormat format

The format can be any format valid for the C library function strftime. See Appendix B, Time Formats

Default

%d/%b/%Y:%H:%M:%S

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

Example

PidLog /home/xx12345/builds/install1/proxy-server1/logs/pid

Security

This section describes the security directive in magnus.conf, which affects server access and security issues for Proxy Server 4.

Security Directive

The Security directive globally enables or disables SSL by making certificates available to the server instance. This directive must be on for the server to use SSL. If this directive enabled, the user is prompted for the administrator password in order to access certificates, and so on.

When you create a secure listen socket through the Server Manager, security is automatically turned on globally in magnus.conf. When you create a secure listen socket manually in server.xml, security must be turned on by editing magnus.conf.

Syntax

Security [on|off]

Default

off

Example

Security off

ServerString

Allows the administrator to change the string sent with the Server HTTP header.

Syntax

ServerString string

string is the new string to send as the header. All characters, including quotes, will be sent. The string none, will cause the header to not be sent at all.

Example

ServerString My Own Server/1.0
ServerString none

Summary of Directives in the magnus.conf File

Purpose

The magnus.conf file contains global variable settings that affect server functioning. This file is read only at server startup.

Directives have the following syntax:

directive value

The following table lists the directives in the magnus.conf file.

Table 3–1 magnus.conf Directives

Directive  

Allowed Values  

Default Value  

Description  

AcceptLanguage

on, off

off

Determines whether the server parses the Accept-Language header sent by the client to indicate which languages the client accepts. 

AcceptTimeout

Any number of seconds 

30 for servers that don’t use hardware encryption devices and 300 for those that do

Specifies the number of seconds the server waits for data to arrive from the client. If data does not arrive before the timeout expires then the connection is closed. 

ACLCacheLifetime

Any number of seconds 

120

Determines the number of seconds before cache entries expire. Each time an entry in the cache is referenced, its age is calculated and checked against ACLCacheLifetime. The entry is not used if its age is greater than or equal to the ACLCacheLifetime. If this value is set to 0, the cache is turned off.

ACLCacheMax

 

1

Determines the configurable limit of the ACL cache. By restricting the size of ACL cache, this directive flushes the old entries from the cache which otherwise contributes significantly to memory usage. 

ACLUserCacheSize

 

200

Determines the number of users in the User Cache. 

ACLGroupCacheSize

 

4

Determines how many group IDs can be cached for a single UID/cache entry. 

AsyncDNS

on, off

off

Specifies whether asynchronous DNS is allowed. 

Address

IP address 

not enabled 

When Address is enabled, proxy will bind all connect sockets (sockets used to connect to the web server) to the IP address specified in the directive.  

If Address is “0.0.0.0”, then proxy does not perform any bind operation and lets the operating system handle the binding of socket when connect() is called.

BufferedLogEnabled

Boolean value 

FALSE

If set to true, an error that is generated multiple times over a period of time is written only once into the error logs, accompanied by information on the number of times the particular error was actually generated during the specified period.  

BufferedLogCountMax

1 – 65536 

128 

It specifies the maximum number of times an error can be generated after which it will be flushed out to the error log. 

BufferedLogSizeMax

1 – 65536 

8192 

It specifies the maximum number of error messages that the log buffer can contain after which the log messages will be flushed to the error log.  

BufferedLogAgeMax

1 - 3600 

300 

It specifies the maximum age, in seconds, of a log message in the log buffer after which it will be considered aged and flushed to the error log. 

BufferedLogFlushInterval

1 - 300 

30 

It specifies the time interval, in seconds, during which the log buffer is inspected by the thread responsible for flushing log messages to the error log. 

CacheOnDedicatedFS

Boolean value 

false

If the Proxy Server's cache partitions are on dedicated file systems, setting this to true will have a positive effect on performance, especially with large cache sizes. This specifically speeds up the calculation of cache partition size by obtaining the size occupied from the file system's superblock through the use of native operating system calls.

CacheRefreshSizeFiles

Boolean value 

false

When set to true, it instructs the Proxy Server to refresh the values of the partition's .size files, each time the total size of a partition is calculated. The procedure used to calculate the partition size remains unchanged from the default.


Note –

CacheRefreshSizeFiles and CacheUseSizeFiles should not be set to true simultaneously.


CacheUseSizeFiles

Boolean value 

false

When set to true, it instructs the Proxy Server to rely on the cache partition's .size files, while calculating the total size of the partition.


Note –

CacheRefreshSizeFiles and CacheUseSizeFiles should not be set to true simultaneously.


CanonicalizeURI

0 (off), 1 (on)

1 (on)

Enable/disable URI canonicalization. 

CGIExpirationTimeout

Any number of seconds 

300 (5 minutes) recommended

Specifies the maximum time in seconds that CGI processes are allowed to run before being killed. 

CGIStubIdleTimeout

Any number of seconds 

30

Causes the server to kill any CGIStub processes that have been idle for the number of seconds set by this directive. Once the number of processes is at the MinCGIStubs level, the server does not kill any more processes.

CGIWaitPid

on, off

on

(UNIX only) Makes the action for the SIGCHLD signal the system default action for the signal. Makes the SHTML engine wait explicitly for its exec cmd child processes. 

ChannelPoolMonitorInterval

Any number of seconds 

30

Specifies how frequently (in seconds) Proxy Server checks the channel pool for stale or closed connections. This value is used when ChannelPoolValidate is set to true.

ChannelPoolValidate

true, false

false

Causes Proxy Server to actively check the channel pool for stale or closed connections every ChannelPoolMonitorInterval seconds.

ChannelReuseValidate

true, false

false

Causes Proxy Server to validate channels in the channel pool before reusing them. 

ChildRestartCallback

on, off, yes, no, true, false

no

Forces the callback of NSAPI functions that were registered using the daemon_atrestart function when the server is restarting or shutting down.

Chroot

A path 

(none) 

(UNIX only) Enables the UNIX system administrator to restrict the server so that it only has access to files in the “Chroot” directory. 

ChunkedRequestBufferSize

Any number of bytes 

8192

Determines the default buffer size for restate request data. 

ChunkedRequestTimeout

Any number of seconds 

60 (1 minute).

Determines the default timeout for restate request data. 

ConnQueueSize

Any number of connections (including 0) 

4096

Specifies the number of outstanding connections that the web proxy server can have. 

DefaultLanguage

en (English),fr (French),de (German),ja (Japanese)

en

Specifies the default language for the server. The default language is used for both the client responses and administration. 

DNS

on, off

on

Specifies whether the server performs DNS lookups on clients that access the server. 

ErrorLogDateFormat

See the manual page for the C library function strftime

%d/%b/%Y:%H:%M:%S

The date format for the error log. 

ExtraPath

A path 

(none) 

Appends the specified directory name to the PATH environment variable. This is used for configuring the JavaTM application environment on Windows NT. No default value is assigned. You must specify a value.

Favicon

On,off

on

Enables the server administrator to disable or change the icon that appears in the web address book or favorites list on Internet Explorer browsers “favorite icon”. 

flushTimer

Any number of milliseconds 

3000 (3 seconds).

If the interval in milliseconds between subsequent write operations for an application is greater than this value, further buffering is disabled. 

HeaderBufferSize

Any number of bytes 

8192 (8 KB)

The size in bytes of the buffer used by each of the request processing threads for reading the request data from the client. The maximum number of request processing threads is controlled by the RqThrottle setting.

HTTPVersion

m.n; m is the major version number and n the minor version number

1.1

The current HTTP version used by the server. 

KeepAliveQueryMaxSleepTime

 

100

On lightly loaded systems that primarily service keep-alive connections, you can lower this number to enhance performance. However doing so can increase CPU usage. 

This directive specifies an upper limit to the time slept in milliseconds after polling keep-alive connections for further requests. 

KeepAliveQueryMeanTime

 

100 is appropriate for almost all installations.

CPU usage will increase with lower KeepAliveQueryMeanTime values. 

This directive specifies the desired keep-alive latency in milliseconds. 

KeepAliveIdleTime

Any number of milliseconds 

200

Specifies the idle time between polls within each thread in the keep-alive subsystem. 

KeepAlivePollTimeout

Any number of milliseconds 

1000

Specifies the timeout to the poll() call within each thread in the keep-alive subsystem.

KeepAliveThreads

Any number of threads 

1

Specifies the number of threads in the keep-alive subsystem. This number should be a small multiple of the number of processors on the system. 

KeepAliveTimeout

300 seconds maximum

30

Determines the maximum time that the server holds open an HTTP keep-alive connection or a persistent connection between the client and the server. 

KernelThreads

0 (off), 1 (on)

0 (off)

If on, ensures that the server uses only kernel-level threads, not user-level threads. If off, uses only user-level threads. 

ListenQ

Ranges are platform-specific 

4096 (AIX), 200 (NT), 128 (all others)

Defines the number of incoming connections for a server socket. 

LogFlushInterval

Any number of seconds 

30

Determines the log flush interval, in seconds, of the log flush thread. 

MaxCGIStubs

Any number of CGI stubs 

10

Controls the maximum number of CGIStub processes the server can spawn. This value is the maximum concurrent CGIStub processes in execution, not the maximum number of pending requests. 

MaxKeepAliveConnections

0 - 32768

 

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

MaxProcs

 

1

(UNIX only) Specifies the maximum number of processes that the server can have running simultaneously. 

MaxRqHeaders

1 - 512

64

Specifies the maximum number of header lines in a request. 

MinCGIStubs

Any number less than MaxCGIStubs 

2

Controls the number of processes that are started by default. 

NativePoolMaxThreads

Any number of threads 

 

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

NativePoolMinThreads

Any number of threads 

1

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

NativePoolQueueSize

Any nonnegative number 

0

Determines the number of threads that can wait in the queue for the thread pool. 

NativePoolStackSize

Any nonnegative number 

0

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

PairedConnections

Boolean Value 

FALSE 

If set to TRUE, it enables "connection pairing" where a server channel is dedicated, or paired, to a specific client connection. 

PidLog

A valid path to a file 

(none) 

Specifies a file in which to record the process ID (pid) of the base server process. 

PostThreadsEarly

1 (on), 0 (off)

0 (off) 

If on, checks whether the minimum number of threads is available at a socket after accepting a connection but before sending the response to the request. 

RcvBufSize

Range is platform-specific 

0 (uses platform-specific default)

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

RqThrottle

Any number of requests (including 0) 

 

Specifies the maximum number of simultaneous request processing threads that the server can handle simultaneously per socket. 

This setting can have performance implications. For more information, see the Proxy Server 4 Performance Tuning, Sizing, and Scaling Guide.

RqThrottleMin

Any number less than RqThrottle

 

Specifies the number of request processing threads that is created when the server is started. As the load on the server increases, more request processing threads are created up to a maximum of RqThrottle threads.

Security

on, off

off

Globally enables or disables SSL by making certificates available to the server instance. Must be on for virtual servers to use SSL.

SndBufSize

Range is platform-specific 

0 (uses platform-specific default)

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

SSL3SessionTimeout

5 - 86400

86400 (24 hours)

The number of seconds until a cached SSL3 session becomes invalid. 

SSLCacheEntries

A non-negative integer 

10000 (used if 0 is specified)

Specifies the number of SSL sessions that can be cached with no upper limit. 

SSLClientAuthDataLimit

Number of bytes 

1048576 (1MB)

Specifies the maximum amount of application data that is buffered during the client certificate handshake phase. 

SSLClientAuthTimeout

Any number of seconds 

60

Specifies the number of seconds after which the client certificate handshake phase times out. 

SSLSessionTimeout

5 - 100

100

Specifies the number of seconds until a cached SSL2 session becomes invalid. 

StackSize

Number of bytes 

The most favorable machine- specific stack size 

Determines the maximum stack size for each request handling thread. 

StrictHttpHeaders

on, off

off

If on, rejects connections that include inappropriately duplicated headers.

TempDir

A path 

/tmp (UNIX)

TEMP (environment variable for Windows NT)

Specifies the directory the server uses for its temporary files. On UNIX, this directory should be owned by, and writable by, the user the server runs as. 

TempDirSecurity

on, off

on

Determines whether the server checks if the TempDir directory is secure. On UNIX, specifying TempDirSecurity off allows the server to use /tmp as a temporary directory.

TerminateTimeout

Any number of seconds 

30

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

ThreadIncrement

Any number of threads 

10

The number of additional or new request processing threads created to handle an increase in the load on the server. 

Umask

A standard UNIX umask value 

(none) 

UNIX only: Specifies the umask value used by the NSAPI functions System_fopenWA() and System_fopenRW() to open files in different modes.

UseNativePoll

1 (on), 0 (off)

1 (on)

Uses a platform-specific poll interface when set to 1 (on). Uses the NSPR poll interface in the KeepAlive subsystem when set to 0 (off).

UseOutputStreamSize

Any number of bytes 

8192 (8 KB)

Determines the default output stream buffer size for the net_read and netbuf_grab NSAPI functions.

User

A login name, 8 characters or less 

(none) 

(Windows NT) Specifies the user account the server runs with, allowing you to restrict or enable system features for the server. 

(UNIX) 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.

WincgiTimeout

Any number of seconds 

60

WinCGI processes that require more time this value are terminated when this timeout expires.