At startup, the Sun Java System Web 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. Sun Java System Web Proxy Server executes all the directives defined in magnus.conf. The order of the directives is not important.
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 Sun Java System Web Proxy Server 4. The setting categories are:
For an alphabetical list of directives, see Appendix C, Server Configuration Elements.
This section lists the directives in magnus.conf that specify information about the server, which are:
Specifies the server name.
Specifies the server ID.
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
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>
This section lists the directives in magnus.conf that affect DNS (Domain Name System) lookup. The directives are:
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.
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
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 Sun Java System Web Proxy Server 4, a basic process is always running in addition to the number of active processes specified by this setting.
Default
1
This section lists the directives in magnus.conf that affect error logging and the collection of server statistics, which are:
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 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.
PidLog /home/xx12345/builds/install1/proxy-server1/logs/pid
This section describes the security directive in magnus.conf, which affects server access and security issues for Sun Java System Web Proxy Server 4.
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
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 |
---|---|---|---|
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. |
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. |
|
200 |
Determines the number of users in the User Cache. |
||
4 |
Determines how many group IDs can be cached for a single UID/cache entry. |
||
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. |
CanonicalizeURI |
0 (off), 1 (on) |
1 (on) |
Enable/disable URI canonicalization. |
Any number of seconds |
300 (5 minutes) recommended |
Specifies the maximum time in seconds that CGI processes are allowed to run before being killed. |
|
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. |
|
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. |
|
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. |
|
A path |
(none) |
(UNIX only) Enables the UNIX system administrator to restrict the server so that it has access only to files in the “Chroot” directory. |
|
Any number of bytes |
8192 |
Determines the default buffer size for restate request data. |
|
Any number of seconds |
60 (1 minute). |
Determines the default timeout for restate request data. |
|
Any number of connections (including 0) |
4096 |
Specifies the number of outstanding connections that the web proxy server can have. |
|
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. |
|
on, off |
on |
Specifies whether the server performs DNS lookups on clients that access the server. |
|
See the manual page for the C library function strftime |
%d/%b/%Y:%H:%M:%S |
The date format for the error log. |
|
A path |
(none) |
Appends the specified directory name to the PATH environment variable. This is used for configuring the JavaTM 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. |
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. |
|
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 millisecondsafter 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. |
|
Any number of milliseconds |
200 |
Specifies the idle time between polls within each thread in the keep-alive subsystem. |
|
Any number of milliseconds |
1000 |
Specifies the timeout to the poll() call within each thread in the keep-alive subsystem. |
|
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. |
|
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. |
|
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. |
|
Ranges are platform-specific |
4096 (AIX), 200 (NT), 128 (all others) |
Defines the number of incoming connections for a server socket. |
|
Any number of seconds |
30 |
Determines the log flush interval, in seconds, of the log flush thread. |
|
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. |
|
0 - 32768 |
|
Specifies the maximum number of keep-alive and persistent connections that the server can have open simultaneously. |
|
1 |
(UNIX only) Specifies the maximum number of processes that the server can have running simultaneously. |
||
1 - 512 |
64 |
Specifies the maximum number of header lines in a request. |
|
Any number less than MaxCGIStubs |
2 |
Controls the number of processes that are started by default. |
|
Any number of threads |
|
Determines the maximum number of threads in the native (kernel) thread pool. |
|
Any number of threads |
1 |
Determines the minimum number of threads in the native (kernel) thread pool. |
|
Any nonnegative number |
0 |
Determines the number of threads that can wait in the queue for the thread pool. |
|
Any nonnegative number |
0 |
Determines the stack size of each thread in the native (kernel) thread pool. |
|
A valid path to a file |
(none) |
Specifies a file in which to record the process ID (pid) of the base server process. |
|
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. |
|
Range is platform-specific |
0 (uses platform-specific default) |
Controls the size of the receive buffer at the server’s sockets. |
|
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. |
|
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. |
|
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. |
|
Range is platform-specific |
0 (uses platform-specific default) |
Controls the size of the send buffer at the server’s sockets. |
|
5 - 86400 |
86400 (24 hours) |
The number of seconds until a cached SSL3 session becomes invalid. |
|
A non-negative integer |
10000 (used if 0 is specified) |
Specifies the number of SSL sessions that can be cached with no upper limit. |
|
Number of bytes |
1048576 (1MB) |
Specifies the maximum amount of application data that is buffered during the client certificate handshake phase. |
|
Any number of seconds |
60 |
Specifies the number of seconds after which the client certificate handshake phase times out. |
|
5 - 100 |
100 |
Specifies the number of seconds until a cached SSL2 session becomes invalid. |
|
Number of bytes |
The most favorable machine- specific stack size |
Determines the maximum stack size for each request handling thread. |
|
on, off |
off |
If on, rejects connections that include inappropriately duplicated headers. |
|
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. |
|
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. |
|
Any number of seconds |
30 |
Specifies the time in seconds that the server waits for all existing connections to terminate before it shuts down. |
|
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. |
|
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. |
|
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). |
|
Any number of bytes |
8192 (8 KB) |
Determines the default output stream buffer size for the net_read and netbuf_grab NSAPI functions. |
|
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. |
|
Any number of seconds |
60 |
WinCGI processes that require more time this value are terminated when this timeout expires. |