Previous Contents Index Next |
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Administrator's Configuration File Reference

> ## Chapter 3
> Syntax and Use of init.conf

> When the Sun Java System 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 Java System 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.

> Note | The init.conf interface is Unstable. An unstable interface may be experimental or transitional, and hence may change incompatibly, be removed, or be replaced by a more stable interface in the next release.

> This chapter lists the global settings that can be specified in init.conf in Sun Java System 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 Appendix C, "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” on page 131 and the Sun Java System Application Server Performance Tuning Guide.

> ##

> Init Functions

> The Init functions load and initialize server modules and plug-ins, and they initialize log files. For more information about these functions, see the Sun Java System 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
> - TempDir
> - TempDirSecurity
> - User (UNIX only)

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

> ### 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. Use of the nobody user may not provide adequate security.

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

> ### 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 off as a default.

> ##### Example

> DNS on

> ##

> Threads, Processes and Connections

> In Sun Java System 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
> - 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. This value should 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. This number should 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).

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

> ### 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 Java System Application Server Performance Tuning 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>

> The directives are:

> - NativePoolStackSize
> - NativePoolMaxThreads
> - NativePoolMinThreads
> - NativePoolQueueSize

> ### 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
> - CGIStubIdleTimeout
> - MaxCGIStubs
> - MinCGIStubs

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

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

> ##

> Error Logging

> This section lists the directives in that affect error logging. They are:

> - ErrorLogDateFormat
> - LogFlushInterval
> - PidLog

> ### ErrorLogDateFormat

> The ErrorLogDateFormat directive specifies the date format that the server log uses.

> ##### Syntax

> ErrorLogDateFormat format

> The format can be any format listed in Appendix A, “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
> - ACLUserCacheSize
> - ACLGroupCacheSize

> ### 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 Java System Application Server when you make changes to the LDAP entries. For example, if this value is set to 120 seconds, the Sun Java System 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 Java System 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

> Note | When you create a secure listen socket through the Administration interface, security is automatically turned on globally in init.conf. When you create a secure listen socket manually in server.xml, security must be turned on by editing init.conf.

> For more information about enabling SSL for individual virtual servers, see Chapter 2, “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.

> - UseOutputStreamSize
> - ChunkedRequestBufferSize
> - ChunkedRequestTimeout

> These directives have equivalent Service SAF parameters in obj.conf. The obj.conf parameters override these directives. For more information, see the Sun Java System 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 Java System 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 Java System 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.

> ##### 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 Java System Application Server NSAPI Developer's Guide.

> Previous Contents Index Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.