Chapter 3 Syntax and Use of magnus.conf

When the Sun Java System Web Proxy 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. Sun Java System Web 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 lists the global settings that can be specified in magnus.conf in Sun Java System Web Proxy Server 4.

Server Information

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

Server Name

Server ID

User

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

Default

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

Examples

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

Example

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

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 (Network Information System) server.

Syntax

Default

Example

Processes

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

MaxProcs (UNIX Only)

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 Sun Java System Web Proxy Server 4, there is always a primordial process in addition to the number of active processes specified by this setting.

Default

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:

ErrorLogDateFormat

Syntax

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

Default

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

Example

Security

This section describes the directive in magnus.conf that affects server access and security issues for Sun Java System Web Proxy Server 4.

Security

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

Syntax

Default

Example


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

Summary of Directives in magnus.conf

Purpose

Contains global variable settings that affect server functioning. This file is read only at server start-up.

Directives

Table 3-1 magnus.conf directives
Directive	Allowed Values	Default Value	Description
AcceptLanguage	on, off	off	Determines whether (on) or not (off) 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.
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.
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.
AsyncDNS	on, off	off	Specifies whether asynchronous DNS is allowed.
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 MinCGIStubs, 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 on its exec cmd child processes.
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) 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”.
ChunkedRequestBufferSize	Any number of bytes	8192	Determines the default buffer size for “un-chunking” request data.
ChunkedRequestTimeout	Any number of seconds	60 (1 minute).	Determines the default timeout for “un-chunking” request data.
ConnQueueSize	Any number of connections (including 0)	4096	Specifies the number of outstanding (yet to be serviced) 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 Java on Windows NT. There is no default value; you must specify a value.
Favicon	On / Off	on	Provides the server administrator the ability to disable or change the icon which appears in the web address book or favorites list on Internet Explorer browsers (so, favicon translates as 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. Note that 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. It is recommended that this number 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 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.
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 are 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 Sun Java System Web Proxy Server 4 Performance Tuning, Sizing, and Scaling Guide.
RqThrottleMin	Any number less than RqThrottle		Specifies the number of request processing threads that are 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. There is 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 take longer than this value are terminated when this timeout expires.

Previous Contents Index Next
Sun Java System Web Proxy Server 4.0.1 Configuration File Reference