|
| Sun ONE Application Server 7 Administrator's Configuration File Reference |
Syntax and Use of init.confWhen the Sun ONE Application Server starts up, it looks in a file called init.conf in the instance_dir/config directory to establish a set of global variable settings that affect the server instance's behavior and configuration. Sun ONE Application Server executes all the directives defined in init.conf.
Except for the Init functions, the directives in init.conf specify a variable and a value, for example:
TempDir /tmp
The order of the directives is not important.
Note Directives noted with boolean values have the following equivalent values: on/yes/true and off/no/false.
Note When you edit the init.conf file, you must restart the server for the changes to take effect.
This module lists the global settings that can be specified in init.conf in Sun ONE Application Server 7.
The categories are:
- Init Functions
- Server Information
- DNS Lookup
- Threads, Processes and Connections
- Native Thread Pools
- CGI
- Error Logging
- ACL
- Security
- Chunked Encoding
- Miscellaneous
For an alphabetical list of directives, see "Alphabetical List of Directives in init.conf."
Note Much of the functionality of the file cache is controlled by a configuration file called nsfc.conf. For information about nsfc.conf, see "nsfc.conf" and the Sun ONE Application Server Performance Tuning, Sizing, and Scaling Guide.
Init Functions
The Init functions load and initialize server modules and plugins, and they initialize log files. For more information about these functions, see the Sun ONE Application Server Developer's Guide to NSAPI.
Server Information
This sub-section lists the directives in init.conf that specify information about the server. They are:
NetSiteRoot
Specifies the absolute pathname to the top-level directory under which the server's bin and lib directories can be found. There is no default value; the file must specify a value.
Syntax
NetSiteRoot path
TempDir
Specifies the directory on the local volume that the server uses for its temporary files. On UNIX, this directory must be owned by, and writable by, the user the server runs as. See also the directives User (UNIX only) and TempDirSecurity.
Syntax
TempDir path
Default
/tmp (UNIX)
TEMP (environment variable for Windows)
TempDirSecurity
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.
Caution
Specifying TempDirSecurity off or using /tmp as a temporary directory on UNIX is highly discouraged. Using /tmp as a temporary directory opens a number of potential security risks.
Syntax
TempDirSecurity [on|off]
Default
on
User (UNIX only)
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 UNIX 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
DNS Lookup
This section lists the directives in init.conf that affect DNS lookup. The directives are:
AsyncDNS
Specifies whether asynchronous DNS is used. The DNS directive must be set to on for this directive to take effect. The value is either on or off. If DNS is enabled, enabling asynchronous DNS improves server performance.
Default
The default is off.
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
In Sun ONE Application Server 7, acceptor threads on a listen socket accept connections and put them onto a connection queue. Session threads then pick up connections from the queue and service the requests. The session threads post more session threads if required at the end of the request. The policy for adding new threads is based on the connection queue state:
- Each time a new connection is returned, the number of connections waiting in the queue (the backlog of connections) is compared to the number of session threads already created. If it is greater than the number of threads, more threads are scheduled to be added the next time a request completes.
- The previous backlog is tracked, so that if it is seen to be increasing over time, and if the increase is greater than the ThreadIncrement value, and the number of session threads minus the backlog is less than the ThreadIncrement value, then another ThreadIncrement number of threads are scheduled to be added.
- The process of adding new session threads is strictly limited by the RqThrottle value.
- To avoid creating too many threads when the backlog increases suddenly (such as the startup of benchmark loads), the decision whether more threads are needed is made only once every 16 or 32 times a connection is made based on how many session threads already exist.
This subsection lists the directives in init.conf that affect the number and timeout of threads, processes, and connections. They are:
- ConnQueueSize
- HeaderBufferSize
- IOTimeout
- KeepAliveThreads
- KeepAliveTimeout
- KernelThreads (Windows only)
- ListenQ
- MaxKeepAliveConnections
- PostThreadsEarly
- RcvBufSize
- RqThrottle
- RqThrottleMin
- SndBufSize
- StackSize
- StrictHttpHeaders
- TerminateTimeout
- ThreadIncrement
Also see the section "Native Thread Pools" for directives for controlling the pool of native threads.
ConnQueueSize
Specifies the number of outstanding (yet to be serviced) connections that the application server can have. It is recommended that this value always be greater than the operating system limit for the maximum number of open file descriptors per process.
Default
The default value is 5000.
HeaderBufferSize
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.
Default
The default value is 8192 (8 KB).
IOTimeout
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. By setting it to less than the default 30 seconds, you can free up threads sooner. However, you may also disconnect users with slower connections.
Syntax
IOTimeout seconds
Default
30 seconds for servers that don't use hardware encryption devices and 300 seconds for those that do.
KeepAliveThreads
This directive determines 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. (for example, a 2 CPU system should have 2 or 4 keep alive threads). The maximum number of keep-alive connections allowed (MaxKeepAliveConnections) should also be taken into consideration when choosing a value for this setting.
Default
1
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. 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.
The timeout countdown starts when the connection is handed over to the keep-alive subsystem. If there is no activity on the connection when the timeout expires, the connection is closed.
Default
The default value is 30 seconds. The maximum value is 300 seconds (5 minutes).
KernelThreads (Windows only)
Sun ONE Application Server can support both kernel-level and user-level threads whenever the operating system supports kernel-level threads. Local threads are scheduled by NSPR within the process whereas kernel threads are scheduled by the host operating system. Usually, the standard debugger and compiler are intended for use with kernel-level threads. By setting KernelThreads to 1 (on), you ensure that the server uses only kernel-level threads, not user-level threads. By setting KernelThreads to 0 (off), you ensure that the server uses only user-level threads, which may improve performance.
Default
The default is 0 (off).
ListenQ
Specifies the maximum number of pending connections on a listen socket. Connections that time out on a listen socket whose backlog queue is full will fail.
Default
The default value is platform-specific: 4096 (AIX), 200 (Windows), 128 (all others).
MaxKeepAliveConnections
Specifies the maximum number of Keep-Alive and persistent connections that the server can have open simultaneously. Values range from 0 to 32768.
Default
256
PostThreadsEarly
If this directive is set to 1 (on), the server checks the whether the minimum number of threads are available at a listen socket 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.
Default
0 (off)
RcvBufSize
Specifies the size (in bytes) of the receive buffer used by sockets. Allowed values are determined by the operating system.
Default
The default value is determined by the operating system. Typical defaults are 4096 (4K), 8192 (8K).
RqThrottle
Specifies the maximum number of request processing threads that the server can handle simultaneously. Each request runs in its own thread.
There is additional discussion of this and other server configuration and performance tuning issues in the Sun ONE Application Server Performance Tuning, Sizing, and Scaling Guide.
Default
128
RqThrottleMin
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).
Default
48
SndBufSize
Specifies the size (in bytes) of the send buffer used by sockets.
Default
The default value is determined by the operating system. Typical defaults are 4096 (4K), 8192 (8K).
StackSize
Determines the maximum stack size for each request handling thread.
Default
The most favorable machine-specific stack size.
StrictHttpHeaders
Controls strict HTTP header checking. If strict HTTP header checking is on, the server rejects connections that include inappropriately duplicated headers.
Syntax
StrictHttpHeaders [on|off]
Default
off
TerminateTimeout
Specifies the time that the server waits for all existing connections to terminate before it shuts down.
Default
30 seconds
ThreadIncrement
The number of additional or new request processing threads created to handle an increase in the load on the server, for example when the number of pending connections (in the request processing queue) exceeds the number of idle request processing threads.
When a server starts up, it creates RqThrottleMin number of request processing threads. As the load increases, it creates ThreadIncrement additional request processing threads until RqThrottle request processing threads have been created.
Default
The default value is 10.
Native Thread Pools
This section lists the directives for controlling the size of the native thread pool. This thread pool consists entirely of native, OS-level threads. The native pool on UNIX is normally not engaged, as all threads are OS-level threads. Using native pools on UNIX may introduce a small performance overhead as they'll require an additional context switch; however, they can be used to localize the stickyAttach effect or for other purposes, such as resource control and management or to emulate single-threaded behavior for plug-ins.
You can specify stickyAttach as a property of the java-config element in the server.xml file as follows:
<java-config>
...
<property name="stickyAttach" value="1" >
</java-config>On Windows, the default native pool is always being used and Sun ONE Application Server uses fibers (user-scheduled threads) for initial request processing. Using custom additional pools on Windows introduces no additional overhead.
The directives are:
NativePoolStackSize
Determines the stack size of each thread in the native thread pool.
Default
0 (represents an operating-system-specific default value)
NativePoolMaxThreads
Determines the maximum number of threads in the native thread pool.
Default
128
NativePoolMinThreads
Determines the minimum number of threads in the native thread pool.
Default
1
NativePoolQueueSize
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.
Default
0 (represents an unlimited queue size)
CGI
This section lists the directives in init.conf that affect requests for CGI programs. The directives are:
CGIExpirationTimeout
This directive specifies the maximum time in seconds that CGI processes are allowed to run before being killed.
The value of CGIExpirationTimeout should not be set too low - 300 seconds (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. A value of 0 disables CGI expiration, which means that there is no time limit for CGI processes.
Note that on Windows platforms init-cgi time-out does not work, so you must use CGIExpirationTimeout.
Default
0 (unlimited)
CGIStubIdleTimeout
This directive 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.
Default
30
MaxCGIStubs
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. The default value should be adequate for most systems. Setting this too high may actually reduce throughput.
Default
10
MinCGIStubs
Controls the number of processes that are started by default. The first CGIStub process is not started until a CGI program has been accessed. Note that if you have an init-cgi directive in the init.conf file, the minimum number of CGIStub processes are spawned at startup. The value must be less than the MaxCGIStubs value.
Default
2
WincgiTimeout (Windows only)
WinCGI processes that take longer than this value are terminated when this timeout (in seconds) expires.
Default
60
Error Logging
This section lists the directives in that affect error logging. They are:
ErrorLogDateFormat
The ErrorLogDateFormat directive specifies the date format that the server log uses.
Syntax
ErrorLogDateFormat format
The format can be any format listed in "Time Formats."
Default
%d/%b/%Y:%H:%M:%S
LogFlushInterval
This directive determines the log flush interval, in seconds, of the log flush thread.
Default
30
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
The 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 init.conf relevant to access control lists (ACLs). They are:
ACLCacheLifetime
ACLCacheLifetime 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.
If you use a large number for this value, you may need to restart the Sun ONE Application Server when you make changes to the LDAP entries. For example, if this value is set to 120 seconds, the Sun ONE Application Server might be out of sync with the LDAP server for as long as two minutes. If your LDAP is not likely to change often, use a large number.
Default
120
ACLUserCacheSize
ACLUserCacheSize determines the number of users in the User Cache.
Default
200
ACLGroupCacheSize
ACLGroupCacheSize determines how many group IDs can be cached for a single UID/cache entry.
Default
4
Security
This section lists the directives in init.conf that affect server access and security issues for Sun ONE Application Server. They are:
- Security
- SSLCacheEntries
- SSLClientAuthDataLimit
- SSLClientAuthTimeout
- SSLSessionTimeout
- SSL3SessionTimeout
Security
The Security directive globally enables or disables SSL by making certificates available to the server instance. It must be on for virtual servers to use SSL. If set to on, the user is prompted for:
- The password to the trust database, which contains the server's private key(s)
- The PINs required by any installed cryptographic hardware
For more information about enabling SSL for individual virtual servers, see "Server Configuration Files."
Syntax
Security [on|off]
Default
off
Example
Security off
SSLCacheEntries
Specifies the number of SSL sessions that can be cached. There is no upper limit.
Syntax
SSLCacheEntries number
If the number is 0, the default value, which is 10000, is used.
SSLClientAuthDataLimit
Specifies the maximum amount of application data, in bytes, that is buffered during the client certificate handshake phase.
Default
The default value is 1048576 (1 MB).
SSLClientAuthTimeout
Specifies the number of seconds after which the client certificate handshake phase times out.
Default
60
SSLSessionTimeout
The SSLSessionTimeout directive controls SSL2 session caching.
Syntax
SSLSessionTimeout seconds
The seconds value is the number of seconds until a cached SSL2 session becomes invalid. If the SSLSessionTimeout directive is specified, the value of seconds is silently constrained to be between 5 and 100 seconds.
Default
The default value is 100.
SSL3SessionTimeout
The SSL3SessionTimeout directive controls SSL3 session caching.
Syntax
SSL3SessionTimeout seconds
The seconds value 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.
Chunked Encoding
This section lists directives that control chunked encoding.
These directives have equivalent Service SAF parameters in obj.conf. The obj.conf parameters override these directives. For more information, see the Sun ONE Application Server NSAPI Developer's Guide.
UseOutputStreamSize
The UseOutputStreamSize directive determines the default output stream buffer size for the net_read and netbuf_grab NSAPI functions. For details about these functions, see the Sun ONE Application Server NSAPI Developer's Guide.
Note The UseOutputStreamSize parameter can be set to zero in the obj.conf file to disable output stream buffering. For the init.conf file, setting UseOutputStreamSize to zero has no effect.
Syntax
UseOutputStreamSize size
The size value is the number of bytes.
Default
The default value is 8192 (8 KB).
ChunkedRequestBufferSize
The ChunkedRequestBufferSize directive determines the default buffer size for "un-chunking" request data.
Syntax
ChunkedRequestBufferSize size
The size value is the number of bytes.
Default
The default value is 8192.
ChunkedRequestTimeout
The ChunkedRequestTimeout directive determines the default timeout for "un-chunking" request data.
Syntax
ChunkedRequestTimeout seconds
The seconds value is the number of seconds.
Default
The default value is 60 (1 minute).
Miscellaneous
This section lists miscellaneous other directives in init.conf.
- ChildRestartCallback
- HTTPVersion
- MaxRqHeaders
- ReentrantTimeFunctions (Solaris only)
- Umask (UNIX only)
ChildRestartCallback
This directive forces the callback of NSAPI functions that were registered using the daemon_atrestart NSAPI function when the server is restarting or shutting down. Values are on, off, yes, no, true, or false. For details about daemon_atrestart, see the Sun ONE Application Server NSAPI Developer's Guide.
Default
no
HTTPVersion
The current HTTP version used by the server in the form m.n, where m is the major version number and n the minor version number.
Default
The default value is 1.1.
MaxRqHeaders
Specifies the maximum number of header lines in a request. Values range from 0 to 512.
Default
64
ReentrantTimeFunctions (Solaris only)
The ReentrantTimeFunctions directive specifies whether the server should use its own reentrant time formatting implementation instead of the implementation provided by the operating system. Using the server's reentrant implementation may provide a small performance improvement on computers with a very large number of CPUs.
The default value, off, instructs the server to use the operating system's implementation. This is the recommended value.
Default
off
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 the Sun ONE Application Server NSAPI Developer's Guide.