| Sun ONE Application Server 7 Developer's Guide to NSAPI |
Chapter 3
SAFs in the init.conf FileWhen 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’s behavior and configuration. Sun ONE Application Server executes all the directives defined in init.conf. The order of the directives is not important.
This chapter lists the Init SAFs that can be specified in init.conf in Sun ONE Application Server 7. For an alphabetical list of all SAFs, see Appendix F, "Alphabetical List of Pre-defined SAFs". For information about the other, non-SAF directives in init.conf, see the Sun ONE Application Server Administrator’s Configuration File Reference.
The Init directives initialize the server, for example they load and initialize additional modules and plugins, and initialize log files.
The Init directives are SAFs, like obj.conf directives, and have SAF syntax rather than the simpler variable value syntax of other init.conf directives. They are located in init.conf because, like other init.conf directives, they are executed only once at server startup.
Each Init directive has an optional LateInit parameter. For the UNIX platform, if LateInit is set to yes, the function is executed by the child process after it is forked from the parent. If LateInit is set to no or is not provided, the function is executed by the parent process before the fork. When the server is started up by user root but runs as another user, any activities that must be performed as the user root (such as writing to a root-owned file) must be done before the fork. Functions that create threads, with the exception of thread-pool-init, should execute after the fork (that is, the relevant Init directive should have LateInit=yes set).
For all platforms, any function that requires access to a fully parsed configuration should have LateInit=yes set on its Init directive.
Upon failure, Init-class functions return REQ_ABORTED. The server logs the error according to the instructions in the Error directives in obj.conf, and terminates. Any other result code is considered a success.
The following Init-class functions are described in detail in this section:
- cindex-init changes the default characteristics for fancy indexing.
- define-perf-bucket creates a performance bucket.
- dns-cache-init configures DNS caching.
- flex-init initializes the flexible logging system.
- flex-rotate-init enables rotation for flexible logs.
- init-cgi changes the default settings for CGI programs.
- init-clf initializes the Common Log subsystem.
- init-j2ee initializes the Java subsystem.
- init-passthrough initializes the passthrough plugin.
- init-uhome loads user home directory information.
- load-modules loads shared libraries into the server.
- perf-init enables system performance measurement via performance buckets.
- pool-init configures pooled memory allocation.
- register-http-method lets you extend the HTTP protocol by registering new HTTP methods.
- stats-init enables reporting of performance statistics in XML format.
- thread-pool-init configures an additional thread pool.
cindex-init
Applicable in Init-class directives.
The function cindex-init sets the default settings for common indexing. Common indexing (also known as fancy indexing) is performed by the Service function index-common. Indexing occurs when the requested URL translates to a directory that does not contain an index file or home page, or no index file or home page has been specified.
In common (fancy) indexing, the directory list shows the name, last modified date, size and description for each indexed file or directory.
Parameters
The following table describes parameters for the cindex-init function. The left column lists the parameter name, and the right column describes what the parameter does.
Table 3-1 cindex-init parameters
Parameter
Description
opts
(optional) is a string of letters specifying the options to activate. Currently there is only one possible option:
s tells the server to scan each HTML file in the directory being indexed for the contents of the HTML <TITLE> tag to display in the description field. The <TITLE> tag must be within the first 255 characters of the file. This option is off by default.
The search for <TITLE> is not case-sensitive.
widths
(optional) specifies the width for each column in the indexing display. The string is a comma-separated list of numbers that specify the column widths in characters for name, last-modified date, size, and description respectively.
The default values for the widths parameter are 22,18,8,33.
The final three values (corresponding to last-modified date, size, and description respectively) can each be set to 0 to turn the display for that column off. The name column cannot be turned off. The minimum size of a column (if the value is non-zero) is specified by the length of its title -- for example, the minimum size of the Date column is 5 (the length of “Date” plus one space). If you set a non-zero value for a column which is less than the length of its title, the width defaults to the minimum required to display the title.
timezone
(optional) This indicates whether the last-modified time is shown in local time or in Greenwich Mean Time. The values are GMT or local. The default is local.
format
(optional) This parameter determines the format of the last modified date display. It uses the format specification for the UNIX function strftime.
The default is %d-%b-%Y %H:%M.
ignore
(optional) specifies a wildcard pattern for file names the server should ignore while indexing. File names starting with a period (.) are always ignored. The default is to only ignore file names starting with a period (.).
icon-uri
(optional) specifies the URI prefix the index-common function uses when generating URLs for file icons (.gif files). By default, it is /mc-icons/. If icon-uri is different from the default, the pfx2dir function in the NameTrans directive must be changed so that the server can find these icons.
Example:
Init fn=cindex-init widths=50,1,1,0
Init fn=cindex-init ignore=*private*
Init fn=cindex-init widths=22,0,0,50
See Also
index-common, find-index, home-page
define-perf-bucket
Applicable in Init-class directives.
The define-perf-bucket function creates a performance bucket, which you can use to measure the performance of SAFs in obj.conf see "The bucket Parameter" and the service-dump function). This function works only if the perf-init function is enabled.
For more information about performance buckets, see the Sun ONE Application Server Performance Tuning, Sizing, and Scaling Guide.
Parameters
The following table describes parameters for the define-perf-bucket function. The left column lists the parameter name, and the right column describes what the parameter does.
Table 3-2 define-perf-bucket parameters
Parameter
Description
name
A name for the bucket, for example cgi-bucket.
description
A description of what the bucket measures, for example CGI Stats.
Example:
See Also
dns-cache-init
Applicable in Init-class directives.
The dns-cache-init function specifies that DNS lookups should be cached when DNS lookups are enabled. If DNS lookups are cached, then when the server gets a client’s host name information, it stores that information in the DNS cache. If the server needs information about the client in the future, the information is available in the DNS cache.
You may specify the size of the DNS cache and the time it takes before a cache entry becomes invalid. The DNS cache can contain 32 to 32768 entries; the default value is 1024 entries. Values for the time it takes for a cache entry to expire (specified in seconds) can range from 1 second to 1 year; the default value is 1200 seconds (20 minutes).
Parameters
The following table describes parameters for the dns-cache-init function. The left column lists the parameter name, and the right column describes what the parameter does.
Example:
flex-init
Applicable in Init-class directives.
The flex-init function opens the named log file to be used for flexible logging and establishes a record format for it. The log format is recorded in the first line of the log file. You cannot change the log format while the log file is in use by the server.
The flex-log function writes entries into the log file during the AddLog stage of the request handling process.
The log file stays open until the server is shut down or restarted (at which time all logs are closed and reopened).
Note
If the server has AddLog stage directives that call flex-log, the flexible log file must be initialized by flex-init during server initialization.
You may specify multiple log file names in the same flex-init function call. Then use multiple AddLog directives with the flex-log function to log transactions to each log file.
The flex-init function may be called more than once. Each new log file name and format will be added to the list of log files.
If you move, remove, or change the currently active log file without shutting down or restarting the server, client accesses might not be recorded. To save or backup the currently active log file, you need to rename the file and then restart the server. The server first looks for the log file by name, and if it doesn’t find it, creates a new one (the renamed original log file is left for you to use).
For information on rotating log files, see flex-rotate-init.
The flex-init function has three parameters: one that names the log file, one that specifies the format of each record in that file, and one that specifies the logging mode.
Parameters
The following table describes parameters for the flex-init function. The left column lists the parameter name, and the right column describes what the parameter does.
Table 3-4 flex-init parameters
Parameter
Description
logFileName
The name of the parameter is the name of the log file. The value of the parameter specifies either the full path to the log file or a file name relative to the server’s logs directory. For example:
access="/usr/Sun/AppServer7/domains/domain1/server1/logs/access"
mylogfile = "access.log"
You will use the log file name later, as a parameter to the flex-log function.
format.logFileName
specifies the format of each log entry in the log file.
For information about the format, see the "More on Log Format" section below.
buffer-size
Specifies the size of the global log buffer. The default is 8192. See the third flex-init example below.
num-buffers
Specifies the maximum number of logging buffers to use. The default is 1000. See the third flex-init example below.
More on Log Format
The flex-init function recognizes anything contained between percent signs (%) as the name portion of a name-value pair stored in a parameter block in the server. (The one exception to this rule is the %SYSDATE% component which delivers the current system date.) %SYSDATE% is formatted using the time format %d/%b/%Y:%H:%M:%S plus the offset from GMT.
(See Chapter 4, "Creating Custom SAFs", for more information about parameter blocks and functions to manipulate pblocks.)
Any additional text is treated as literal text, so you can add to the line to make it more readable. See the "Typical components of flex-init formatting" table. Certain components might contain spaces, so they should be bounded by escaped quotes (\").
If no format parameter is specified for a log file, the common log format is used:
"%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%]
\"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status%
%Req->srvhdrs.content-length%"You can now log cookies by logging the Req->headers.cookie.name component.
In the following table, the components that are enclosed in escaped double quotes (\") are the ones that could potentially resolve to values that have white spaces.
The following table shows flex-init formatting components. The left column lists flex-log options, and the right column lists the equivalent flex-init components.
Examples
The first example below initializes flexible logging into the file /usr/Sun/AppServer7/domains/domain1/server1/logs/access.
This will record the following items
This is the default format, which corresponds to the Common Log Format (CLF).
It is advisable that the first six elements of any log always be in exactly this format, because a number of log analyzers expect that as output.
The second example initializes flexible logging into the file /usr/Sun/AppServer7/domains/domain1/server1/logs/extended.
Init fn=flex-init extended="/usr/Sun/AppServer7/domains/domain1/server1/logs/extend ed" format.extended="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length% %Req->headers.referer% \"%Req->headers.user-agent%\" %Req->reqpb.method% %Req->reqpb.uri% %Req->reqpb.query% %Req->reqpb.protocol%"
The third example shows how logging can be tuned to prevent request handling threads from making blocking calls when writing to log files, instead delegating these calls to the log flush thread.
Doubling the size of the buffer-size and num-buffers parameters from their defaults and lowering the value of the LogFlushInterval init.conf directive to 4 seconds (see the Sun ONE Application Server Administrator’s Configuration File Reference) frees the request handling threads to quickly write the log data.
Init fn=flex-init buffer-size=16384 num-buffers=2000 access="/usr/Sun/AppServer7/domains/domain1/server1/logs/access" format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.clf-request%\" %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"
See Also
flex-rotate-init
Applicable in Init-class directives.
The flex-rotate-init function configures log rotation for all log files on the server, including server logs and the common-log, flex-log, and record-useragent AddLog SAFs. Call this function in the Init section of init.conf before calling flex-init. The flex-rotate-init function allows you to specify a time interval for rotating log files. At the specified time interval, the server moves the log file to a file whose name indicates the time of moving. The log functions in the AddLog stage in obj.conf then start logging entries in a new log file. The server does not need to be shut down while the log files are being rotated.
Note
The server keeps all rotated log files forever, so you will need to clean them up as necessary to free up disk space.
By default, log rotation is disabled.
Parameters
The following table describes parameters for the flex-rotate-init function. The left column lists the parameter name, and the right column describes what the parameter does.
Table 3-6 flex-rotate-init parameters
Parameter
Description
rotate-start
Indicates the time to start rotation. This value is a 4 digit string indicating the time in 24 hour format, for example, 0900 indicates 9 am while 1800 indicates 9 pm.
rotate-interval
Indicates the number of minutes to elapse between each log rotation.
rotate-access
(optional) determines whether common-log, flex-log, and record-useragent logs are rotated. Values are yes (the default) and no.
rotate-error
(optional) determines whether server logs are rotated. Values are yes (the default) and no.
rotate-callback
(optional) specifies the file name of a user-supplied program to execute following log file rotation. The program is passed the post-rotation name of the rotated log file as its parameter.
Example
This example enables log rotation, starting at midnight and occurring every hour.
See Also
flex-init, common-log, flex-log, record-useragent
init-cgi
Applicable in Init-class directives.
The init-cgi function performs certain initialization tasks for CGI execution. Two options are provided: timeout of the execution of the CGI script, and establishment of environment variables.
Parameters
The following table describes parameters for the init-cgi function. The left column lists the parameter name, and the right column describes what the parameter does.
Table 3-7 init-cgi parameters
Parameter
Description
timeout
(optional) specifies how many seconds the server waits for CGI output. If the CGI script has not delivered any output in that many seconds, the server terminates the script. The default is 300 seconds.
cgistub-path
(optional) specifies the path to the CGI stub binary. If not specified, Sun ONE Application Server looks in the following locations, in the following order:
Use the first directory to house an suid Cgistub (that is, a Cgistub owned by root which has the set-user-ID-on-exec bit set). Use the second directory to house a non-suid Cgistub.
If present, the ../private directory must be owned by the server user and have permissions d??x------. This prevents other users (for example, users with shell accounts or CGI access) from using Cgistub to set their uid.
For information about installing an suid Cgistub, see the Sun ONE Application Server Developer’s Guide to Web Applications.
env-variable
(optional) specifies the name and value for an environment variable that the server places into the environment for the CGI. You can set any number of environment variables in a single init-cgi function.
Example
See Also
send-cgi, send-wincgi, send-shellcgi
init-clf
Applicable in Init-class directives.
The init-clf function opens the named log files to be used for common logging. The common-log function writes entries into the log files during the AddLog stage of the request handling process. The log files stay open until the server is shut down (at which time the log files are closed) or restarted (at which time the log files are closed and reopened).
Note
If the server has an AddLog stage directive that calls common-log, common log files must be initialized by init-clf during initialization.
Note
This function should only be called once. If it is called again, the new call will replace log file names from all previous calls.
If you move, remove, or change the log file without shutting down or restarting the server, client accesses might not be recorded. To save or backup a log file, you need to rename the file (and for UNIX, send the -HUP signal) and then restart the server. The server first looks for the log file by name, and if it doesn’t find it, creates a new one (the renamed original log file is left for you to use).
For information on rotating log files, see flex-rotate-init.
Parameters
The following table describes parameters for the init-clf function. The left column lists the parameter name, and the right column describes what the parameter does.
Table 3-8 init-clf parameters
Parameter
Description
logFileName
The name of the parameter is the name of the log file. The value of the parameter specifies either the full path to the log file or a file name relative to the server’s logs directory. For example:
access="/usr/Sun/AppServer7/domains/
domain1/server1/logs/access"
mylogfile = "log1"You will use the log file name later, as a parameter to the common-log function.
Examples
Init fn=init-clf access=/usr/Sun/AppServer7/domains/domain1/server1/logs/access
Init fn=init-clf templog=/tmp/mytemplog templog2=/tmp/mytemplog2
See Also
common-log, record-useragent, flex-rotate-init
init-j2ee
Applicable in Init-class directives.
The init-j2ee function initializes the Java subsystem.
Parameters
This function requires a LateInit=yes parameter.
Example
Init fn="load-modules" shlib="install_dir/lib/libj2eeplugin.so" funcs="init-j2ee,ntrans-j2ee,service-j2ee,error-j2ee" shlib_flags="(global|now)"
Init fn="init-j2ee" LateInit=yes
See Also
ntrans-j2ee, service-j2ee, error-j2ee
init-passthrough
Applicable in Init-class directives.
The init-passthrough function initializes the passthrough plugin. This function must be called before the passthrough plugin can be used.
Parameters
none
Example
Init fn="load-modules" shlib="c:/install_dir/lib/passthrough.dll" funcs="init-passthrough,auth-passthrough,check-passthrough, service-passthrough" NativeThread="no"
Init fn="init-passthrough"
See Also
auth-passthrough, check-passthrough, service-passthrough
init-uhome
Applicable in Init-class directives.
UNIX Only. The init-uhome function loads information about the system’s user home directories into internal hash tables. This increases memory usage slightly, but improves performance for servers that have a lot of traffic to home directories.
Parameters
The following table describes parameters for the init-uhome function. The left column lists the parameter name, and the right column describes what the parameter does.
Table 3-9 init-uhome parameters
Parameter
Description
pwfile
(optional) specifies the full file system path to a file other than /etc/passwd. If not provided, the default UNIX path (/etc/passwd) is used.
Examples
See Also
load-modules
Applicable in Init-class directives.
The load-modules function loads a shared library or Dynamic Link Library into the server code. Specified functions from the library can then be executed from any subsequent directives. Use this function to load new plugins or SAFs.
If you define your own Server Application Functions, you get the server to load them by using the load-modules function and specifying the shared library or DLL file to load.
Parameters
The following table describes parameters for the load-modules function. The left column lists the parameter name, and the right column describes what the parameter does.
Table 3-10 load-modules parameters
Parameter
Description
shlib
specifies either the full path to the shared library or dynamic link library or a file name relative to the server configuration directory.
funcs
is a comma separated list of the names of the functions in the shared library or dynamic link library to be made available for use by other Init directives or by Service directives in obj.conf. The list should not contain any spaces. The dash (-) character may be used in place of the underscore (_) character in function names.
NativeThread
(optional, Windows only) specifies which threading model to use.
no causes the routines in the library to use user-level threading.
yes enables kernel-level threading. The default is yes.
pool
the name of a custom thread pool, as specified in thread-pool-init.
Examples
Init fn=load-modules shlib="C:/mysrvfns/corpfns.dll" funcs="moveit"
Init fn=load-modules shlib="/mysrvfns/corpfns.so" funcs="myinit,myservice"
Init fn=myinit
perf-init
Applicable in Init-class directives.
The perf-init function enables system performance measurement via performance buckets.
For more information about performance buckets, see the Sun ONE Application Server Performance Tuning, Sizing, and Scaling Guide.
Parameters
The following table describes parameters for the perf-init function. The left column lists the parameter name, and the right column describes what the parameter does.
Table 3-11 perf-init parameters
Parameter
Description
disable
flag to disable the use of system performance measurement via performance buckets. Should have a value of true or false. Default value is true.
Example
See Also
pool-init
Applicable in Init-class directives.
The pool-init function changes the default values of pooled memory settings. The size of the free block list may be changed or pooled memory may be entirely disabled.
Memory allocation pools allow the server to run significantly faster. If you are programming with the NSAPI, note that MALLOC, REALLOC, CALLOC, STRDUP, and FREE work slightly differently if pooled memory is disabled. If pooling is enabled, the server automatically cleans up all memory allocated by these routines when each request completes. In most cases, this will improve performance and prevent memory leaks. If pooling is disabled, all memory is global and there is no clean-up.
If you want persistent memory allocation, add the prefix PERM_ to the name of each routine (PERM_MALLOC, PERM_REALLOC, PERM_CALLOC, PERM_STRDUP, and PERM_FREE).
Note
Any memory you allocate from Init-class functions will be allocated as persistent memory, even if you use MALLOC. The server cleans up only the memory that is allocated while processing a request, and because Init-class functions are run before processing any requests, their memory is allocated globally.
Parameters
The following table describes parameters for the pool-init function. The left column lists the parameter name, and the right column describes what the parameter does.
Table 3-12 pool-init parameters
Parameter
Description
free-size
(optional) maximum size in bytes of free block list. May not be greater than 1048576.
disable
(optional) flag to disable the use of pooled memory. Should have a value of true or false. Default value is false.
Example
register-http-method
Applicable in Init-class directives.
This function lets you extend the HTTP protocol by registering new HTTP methods. (You do not need to register the default HTTP methods.)
Upon accepting a connection, the server checks to see if the method that it received is known to it. If the server does not recognize the method, it returns a “501 Method Not Implemented” error message.
Parameters
The following table describes parameters for the register-http-method function. The left column lists the parameter name, and the right column describes what the parameter does.
Table 3-13 register-http-method parameters
Parameter
Description
methods
is a comma separated list of the names of the methods you are registering.
Example
The following example shows the use of register-http-method and a Service function for one of the methods.
Init fn="register-http-method" methods="MY_METHOD1,MY_METHOD2"
Service fn="MyHandler" method="MY_METHOD1"
stats-init
Applicable in Init-class directives.
This function enables reporting of performance statistics in XML format.
Parameters
The following table describes parameters for the stats-init function. The left column lists the parameter name, and the right column describes what the parameter does.
Table 3-14 stats-init parameters
Parameter
Description
update-interval
period in seconds between statistics updates within the server. Set higher for better performance, lower for more frequent updates. The minimum value is 1; the default is 5.
virtual-servers
maximum number of virtual servers for which statistics are tracked. This number should be set higher than the number of virtual servers configured. Smaller numbers result in lower memory usage. The minimum value is 1; the default is 1000.
profiling
enables performance profiling using buckets if set to yes. This can also be enabled through the perf-init Init SAF. The default is no, which results in slightly better server performance.
Example
See also
thread-pool-init
Applicable in Init-class directives.
This function creates a new pool of user threads. A pool must be declared before it’s used. To tell a plugin to use the new pool, specify the pool parameter when loading the plugin with the Init-class function load-modules.
One reason to create a custom thread pool would be if a plugin is not thread-aware, in which case you can set the maximum number of threads in the pool to 1.
The older Windows-only parameter NativeThread=yes always engages one default native pool, called NativePool.
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 jvm.stickyAttach effect or for other purposes, such as resource control and management or to emulate single-threaded behavior for plug-ins.
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.
In addition, native thread pool parameters can be added to the init.conf file for convenience. For more information, see the Sun ONE Application Server Administrator’s Configuration File Reference.
Parameters
The following table describes parameters for the thread-pool-init function. The left column lists the parameter name, and the right column describes what the parameter does.
Table 3-15 thread-pool-init parameters
Parameter
Description
name
name of the thread pool.
maxthreads
maximum number of threads in the pool.
minthreads
minimum number of threads in the pool.
queueSize
size of the queue for the pool. If all the threads in the pool are busy, further request-handling threads that want to get a thread from the pool will wait in the pool queue. The number of request-handling threads that can wait in the queue is limited by the queue size. If the queue is full, the next request-handling thread that comes to the queue is turned away, with the result that the request is turned down, but the request-handling thread remains free to handle another request instead of becoming locked up in the queue.
stackSize
stack size of each thread in the native (kernel) thread pool.
Example
Init fn=thread-pool-init name="my-custom-pool" maxthreads=5 minthreads=1 queuesize=200
Init fn=load-modules shlib="C:/mydir/myplugin.dll" funcs="tracker" pool="my-custom-pool"
See also
