"Netscape Enterprise Server Administrator's Guide": Configuring the Server for Performance

Performance Report
The server statistics in buckets can be accessed using The perfdump Utility. The performance buckets information is located in the last section of the report that perfdump returns. To enable reports on performance buckets, complete the following steps:

Define an extension for the performance bucket report. Add the following line to the mime.types file:

type=perf exts=perf

Associate the type you declared in mime.types with the service-dump function in the obj.conf file:

Service fn=service-dump type=perf

Use the URL http://server_name:port_number/.perf to view the performance report.

Note. You must include a period (.) before the extension you defined in the mime.types file (in this case, .perf).

The report contains the following information:

Average column shows per request statistics.

Request processing time is the total time the required by the server to process all the requests it has received so far. Even on the busiest of the servers this number will be very small compared to the server uptime.

Number of Requests is the total number of requests for the function.

Number of Invocations is the total number that the function was invoked. This differs from the number of requests in that a function could be called multiple times while processing one request. The percentage column for this row is calculated in reference to the total number of invocations for all the buckets.

Latency (in seconds) The time Enterprise Server takes to prepare for calling "send-cgi."

Function Processing Time (in seconds) The percentage of Function Processing Time and Total Response Time is calculated with reference to the total Request processing time. (The time spent in "send-cgi" (that is, the time required to fork/exec the CGI program plus the execution time of the program itself.)

Total Response Time(in seconds) The sum of Function Processing Time and Latency.

Percent column displays of Number of Requests is calculated with reference to the Total number of requests.

Miscellaneous magnus.conf Directives

You can use the following magnus.conf directives to configure your server to function more effectively:

RqThrottle (See About RqThrottle)

PostThredsEarly (See PostThreadsEarly)

MaxProcs (See Multi-process Mode)

MinAcceptThreadPerSocket and MaxAcceptThreadPerSocket (SeeAccept Thread Information)

MinCGIStubs, MaxCGIStubs, and CGIStubIdleTimeout (See CGIStub Processes (Unix))

SndBufSize and RcvBufSize (See Buffer Size)

NativePoolStackSize/NativePoolQueueSize/NativePoolMaxThreads/NativePoolMinThreads (See Native Thread Pool Size)

Multi-process Mode
The Enterprise Server can be configured to handle requests using multiple processes and multiple threads in each process. This flexibility provides optimal performance for sites using threads and also provides backward compatibility to sites running legacy applications that are not ready to run in a threaded environment. Because applications on Windows NT generally already take advantage of multi-process considerations, this feature mostly applies to Unix platforms.

The advantage of multiple processes is that legacy applications which are not thread-aware or thread safe can now be run more effectively in Enterprise Server 4.0. However, because all the Netscape extensions are built to support a single-process, threaded environment, they cannot run in the multi-process mode. WAI, LiveWire, Java, Server-side JavaScript, LiveConnect and the Web Publishing and Search plugins fail on startup if the server is in multi-process mode. There are two approaches to multi-thread design:

Enterprise Server with a single process

Enterprise Server with multiple processes

In the single-process design, the server receives requests from web clients to a single process. Inside the single server process, many threads are running which are waiting for new requests to arrive. When a request arrives, it is handled by the thread receiving the request. Because the server is multi-threaded, all extensions written to the server (NSAPI) must be thread-safe. This means that if the NSAPI extension uses a global resource (like a shared reference to a file or global variable) then the use of that resource must be synchronized so that only one thread accesses it at a time. All plugins provided by Netscape are thread-safe and thread-aware, providing good scalability and concurrency. However, your legacy applications may be single-threaded. When the server runs the application, it can only execute one at a time. This leads to severe performance problems when put under load. Unfortunately, in the single-process design, there is no real workaround.

In the multi-process design, the server spawns multiple server processes at startup. Each process contains one or more threads (depending on the configuration) which receive incoming requests. Since each process is completely independent, each one has its own copies of global variables, shared libraries, caches, and other resources. Using multiple processes requires more resources from your system. Also, if you try to install an application which requires shared state, it has to synchronize that state across multiple processes. NSAPI provides no helper functions for implementing cross-process synchronization.

If you are not running any NSAPI in your server, you should use the default settings: one process and many threads. If you are running an application which is not scalable in a threaded environment, you should use a few processes and many threads, for example, 4 or 8 processes and 256 or 512 threads per process.

Prior to HPUX 10.30, HPUX thread support consisted of DCE threads. The implementation of DCE threads were "user level" threads, which means that they are schedule only in user space. Since the kernel does not know anything about the user threads, these threads are cooperatively scheduled within the context of a single process. This means that on multi-processor systems, all the DCE threads will only be scheduled on one processor at a time. This prevents MP scaling. With HPUX 10.30, HPUX introduced its first kernel based threading model (pthreads). Since the kernel has knowledge of these threads, and since the kernel is responsible for scheduling these threads, programs written to the pthreads API can be scheduled on all processors in a multi-processor system. Enterprise Server 4.0 now uses HP's kernel-level threads.

MaxProcs (Unix)

Use this directive to set your Unix server in multi-process mode, which allows for higher scalability on multi-processor machines. If, for example, you are running on a four-processor CPU, setting MaxProcs to 4 improves performance: one process per processor.

If you are running Enterprise Server 4.0 in multi-process mode, you cannot run LiveWire, Web Publisher, and WAI.

This directive results in one primordial process and four active processes:

MaxProcs 4

Note. This value is not tunable from the server.

Accept Thread Information
MinAcceptThreadsPerSocket / MaxAcceptThreadsPerSocket

Use this directive to specify how many threads you want in accept mode on a listen socket at any time. It's a good practice to set this to equal the number of processes. You can set this to twice (2x) the number of processes, but setting it to a number that is too great (such as ten (10x) or fifty (50x)) allows too many threads to be created and slows the server down.

CGIStub Processes (Unix)
You can adjust the CGIStub parameters on Unix systems. In Enterprise Server 4.0, the CGI engine creates CGIStub processes as needed to handle CGI processes. On systems that serve a large load and rely heavily on CGI-generated content, it is possible for the CGIStub processes spawned to consume all system resources. If this is happening on your server, the CGIStub processes can be tuned to restrict how many new CGIStub processes can be spawned, their timeout value, and the minimum number of CGIStub processes that will be running at any given moment.

Note. If you have an init-cgi function in the obj.conf file and you are running in multi-process mode, you must add LateInit = yes to the init-cgi line.

MinCGIStubs/MaxCGIStubs/CGIStubIdleTimeout

The three directives (and their defaults) that can be placed in the magnus.conf file to control Cgistub are :

MinCGIStubs 2
MaxCGIStubs 10
CGIStubIdleTimeout 45

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. The default value is 2. Note that if you have a init-cgi directive in the obj.conf file, the minimum number of CGIStub processes are spawned at startup.

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 shown should be adequate for most systems. Setting this too high may actually reduce throughput. The default value is 10.

CGIStubIdleTimeout 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 it does not kill any more processes.

Buffer Size
SndBufSize/RcvBufSize

You can specify the size of the send buffer (SndBufSize) and the receiving buffer (RcvBufSize) at the server's sockets. For more information regarding these buffers, see your Unix documentation.

Native Thread Pool Size
NativePoolStackSize/NativePoolQueueSize/NativePoolMaxThreads/NativePoolMinThreads

In preiveous versions of Enterprise Server, you could control the native thread pool by setting the system environment variables NSCP_POOL_STACKSIZE, NSCP_POOL_THREADMAX, and NSCP_POOL_WORKQUEUEMAX. In Enterprise Server 4.0, you can use the directives in magnus.conf to control the size of the native kernel thread pool.

NativePoolStackSize determines the stack size of each thread in the native (kernel) thread pool.

NativePoolQueueSize determines the number of threads that can wait in the queue for the thread pool. If all threads int he 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 thres to get in the queue is rejected, with the result that it reutnrs a busy response to the client. It is then free to handle another incoming request instead of being tied up waiting in the queue.

NativePoolMaxThreads determines the maximum number of threas in the native (kernel) thread pool.

NativePoolMinThreads determines the minimum number of threads in the native (kernel) thread pool.

About RqThrottle

The RqThrottle parameter in the magnus.conf file specifies the maximum number of simultaneous transactions the web server can handle. The default value is 512. Changes to this value can be used to throttle the server, minimizing latencies for the transactions that are performed. The RqThrottle value acts across multiple virtual servers, but does not attempt to load-balance.

To compute the number of simultaneous requests, the server counts the number of active requests, adding one to the number when a new request arrives, subtracting one when it finishes the request. When a new request arrives, the server checks to see if it is already processing the maximum number of requests. If it has reached the limit, it defers processing new requests until the number of active requests drops below the maximum amount.

In theory, you could set the maximum simultaneous requests to 1 and still have a functional server. Setting this value to 1 would mean that the server could only handle one request at a time, but since HTTP requests generally have a very short duration (response time can be as low as 5 milliseconds), processing one request at a time would still allow you to process up to 200 requests per second.

However, in actuality, Internet clients frequently connect to the server and then do not complete their requests. In these cases, the server waits 30 seconds or more for the data before timing out. (You can define this timeout period in obj.conf. It has a default of 5 minutes.) Also, some sites do heavyweight transactions that take minutes to complete. Both of these factors add to the maximum simultaneous requests that are required. If your site is processing many requests that take many seconds, you may need to increase the number of maximum simultaneous requests.

In the 3.0 server the defaults were 48/128. With 4.0, the limits are increased to 48/512. This is because 128 can be a gating factor for performance even on sites with as few as 750,000 hits per day. If your site is experiencing slowness and the ActiveThreads count remains close to the limit, consider increasing the maximum threads limit. To find out the active thread count, use The perfdump Utility.

A suitable RqThrottle value ranges from 200-2000 depending on the load. If you want your server to use all the available resources on the system (that is, you don't run other server software on the same machine), then you can increase RqThrottle to a larger value than necessary without negative consequences.

Note. If you are using older NSAPI plugins that are not reentrant, they will not work with the multithreading model described in this document. To continue using them, you should revise them so that they are reentrant. If this is not possible, you can configure your server to work with them by setting RqThrottle to 1 and then using a high value for MaxProcs, such as 48 or greater, but this will adversely impact your server's performance.

Tuning

There are two ways to tune the thread limit: through editing the magnus.conf file and through the Server Manager.

If you edit the magnus.conf file, RqThrottleMinPerSocket is the minimum value and RqThrottle is the maximum value.

The minimum limit is a goal for how many threads the server attempts to keep in the WaitingThreads state. This number is just a goal. The number of actual threads in this state may go slightly above or below this value. The default value is 48. The maximum threads represents a hard limit for the maximum number of active threads that can run simultaneously, which can become a bottleneck for performance. The default value is 512.

If you use the Server Manager, follow these steps:

Go to the Preferences tab.

Click the Performance Tuning link.

Enter the desired value in the Maximum simultaneous requests field.

For additional information, see The Performance Tuning Page.

The perfdump Utility

The perfdump utility is a service function built into Enterprise Server. It collects various pieces of performance data from the web server internal statistics and displays them in ASCII text.

To install perfdump, you need to make the following modifications in obj.conf in the netscape/server4/https-server_name/config directory:

Add the following object to your obj.conf file (after the default object):

Service fn="service-dump"

</Object>

Edit the "ppath=" line if your document root is different than the example above. Make sure to put ".perf" after the path to the document root, as shown above.

Restart your server software, and access perfdump by accessing this URL:

http://yourhost/.perf

You can request the perfdump statistics and inform the browser to automatically refresh the statistics every n seconds by using this URL, which sets the refresh to every 5 seconds:

http://yourhost/.perf?refresh=5

Sample Output
ns-httpd pid: 133

ListenSocket #0:

------------------

Address https:\\INADDR_ANY:80

KeepAliveTimeout 30 seconds

CacheSize(bytes) 0/10485760

Hit Ratio 0/1 ( 0.00)

pollInterval 5

maxFileSize 537600

Native Thread Pool Data:

------------------------

Idle/Peak/Limit 1/1/100

Work queue length/Limit 0/2147483647

Peak work queue length 1

Work queue rejections 0

Server DNS cache disabled

Using perfdump Statistics to Tune Your Server

This section describes the information available through the perfdump utility and discusses how to tune some parameters to improve your server's performance. The default tuning parameters are appropriate for all sites except those with very high volume. The only parameter that large sites may regularly need to change is the RqThrottle parameter, which is tunable from Server Manager.

The perfdump utility monitors these statistics:

ListenSocket Information

KeepAlive Information

Cache Information

Cache Information

Native Threads Pool

Asynchronous DNS Lookup (Unix)

ListenSocket Information
The ListenSocket is the listen-queue size which is a socket-level parameter that specifies the number of incoming connections the system will accept for that socket. The default setting is 128 (for Unix) or 100 (for Windows NT) incoming connections.

Make sure your system's listen-queue size is large enough to accommodate the ListenSocket size set in Enterprise Server. The ListenSocket size set from Enterprise Server changes the listen-queue size requested by your system. If Enterprise Server requests a ListenSocket size larger than your system's maximum listen-queue size, the size defaults to the system's maximum.

Warning. Setting ListenSocket too high can degrade server performance. ListenSocket was designed to prevent the server from becoming overloaded with connections it cannot handle. If your server is overloaded and you increase ListenSocket, the server will only fall further behind.

The first set of perfdump statistics is the ListenSocket information. For each hardware virtual server you have enabled in your server, there is one ListenSocket structure. For most sites, only one is listed.

ListenSocket #0:

------------------

Address https:\\INADDR_ANY:80

Note. The "thread" fields specify the current thread use counts and limits for this listen socket. Keep in mind that the idea of a "thread" does not necessarily reflect the use of a thread known to the operating system. "Thread" in these fields really means an HTTP session. If you check the operating system to see how many threads are running in the process, it is not going to be the same as the numbers reported in these fields.

Tuning

There are two ways to create virtual servers: Using the virtual.conf file and using the obj.conf file. If you use the virtual.conf method, the 512 default maximum threads are available to all virtual servers on an as-needed basis. If you use the obj.conf method, the 512 threads are allocated equally to each of the defined virtual servers. For example, if you had two servers, each would have 256 threads available. This is less efficient. To maximize performance in this area, use the virtual.conf method. You can also configure the listen-queue size in The Performance Tuning Page of the Server Manager.

Address
This field contains the base address that this listen socket is listening to. For most sites that are not using hardware virtual servers, the URL is:

http://INADDR_ANY:80"

The constant value "INADDR_ANY" is known internally to the server that specifies that this listen socket is listening on all IP addresses for this machine.

Tuning

This setting is not tunable except as described above.

ActiveThreads
The total number of "threads" (HTTP sessions) that are in any state for this listen socket. This is equal to WaitingThreads + BusyThreads.

This setting is not tunable.

WaitingThreads
The number of "threads" (HTTP sessions) waiting for a new TCP connection for this listen socket.

Tuning

This is not directly tunable, but it is loosely equivalent to the RqThrottleMinPerSocket. See Thread limits <min/max>.

BusyThreads
The number of "threads" (HTTP sessions) actively processing requests which arrived on this listen socket.

This setting is not tunable.

Thread limits <min/max>
The minimum thread limit is a goal for how many threads the server attempts to keep in the WaitingThreads state. This number is just a goal. The number of actual threads in this state may go slightly above or below this value.

The maximum threads represents a hard limit for the maximum number of active threads that can run simultaneously, which can become a bottleneck for performance. Enterprise Server 3.6, has default limits of 48/512. For more information, see About RqThrottle.

Tuning

See About RqThrottle.

KeepAlive Information
KeepAliveInfo:
------------------
KeepAliveCount 0/200
KeepAliveHits 0
KeepAliveFlushes 0
KeepAliveTimeout 30 seconds

This section reports statistics about the server's HTTP-level KeepAlive system.

Note. The name "KeepAlive" should not be confused with TCP "KeepAlives." Also, note that the name "KeepAlive" was changed to "Persistent Connections" in HTTP/1.1, but for clarity this document continues to refer to them as "KeepAlive" connections.

Both HTTP/1.0 and HTTP/1.1 support the ability to send multiple requests across a single HTTP session. A web server can receive hundreds of new HTTP requests per second. If every request was allowed to keep the connection open indefinitely, the server could become overloaded with connections. On Unix systems, this could lead to a file table overflow very easily.

To deal with this problem, the server maintains a "Maximum number of `waiting' keepalive connections" counter. A `waiting' keepalive connection is a connection that has fully completed processing of the previous request over the connection and is now waiting for a new request to arrive on the same connection. If the server has more than the maximum waiting connections open when a new connection starts to wait for a keepalive request, the server closes the oldest connection. This algorithm keeps an upper bound on the number of open, waiting keepalive connections that the server can maintain.

Enterprise Server does not always honor a KeepAlive request from a client. The following conditions cause the server to close a connection even if the client has requested a KeepAlive connection:

KeepAliveTimeout is set to 0.

MaxKeepAlive count is exceeded.

Dynamic content, such as CGI, does not have an HTTP content_length header set or the header is not lowercase.

Request is not HTTP GET or HEAD.

HTTP 1.1 pipelined request.

The request was determined to be bad-- if have bad client sends only headers, no content.

When SSL is enabled, KeepAliveTimeout defaults to 0, which effectively disables persistent connections. If you want to use persistent connections with SSL, set KeepAliveTimeout to a non-zero value.

You can also change KeepAliveTimeout in The Performance Tuning Page in the Server Manager.

AcceptTimeout
The number of seconds the server will wait for data from the client after accepting the connection before sending the request to the unaccelerated path.

Tuning

If AcceptTimout is set to a small number, rather than reading the initial read from clients with slow responses, the read may timeout and have to be read on the second attempt. This may impact performance.

KeepAliveCount <KeepAliveCount/KeepAliveMaxCount>
The number of sessions currently waiting for a keepalive connection and the maximum number of sessions that the server allows to wait at one time.

Tuning

Edit the MaxKeepAliveConnections parameter in the magnus.conf file.

KeepAliveHits
The number of times a request was successfully received from a connection that had been kept alive.

This setting is not tunable.

KeepAliveFlushes
The number of times the server had to close a connection because the KeepAliveCount exceeded the KeepAliveMaxCount.

This setting is not tunable.

Cache Information
CacheInfo:
------------------
enabled yes
CacheEntries 0/4096
CacheSize(bytes) 0/10485760

Hit Ratio 0/1 ( 0.00)
pollInterval 5
maxFileSize 537600

This section describes the server's cache information. The contents of a file are cached to a specific static file on disk, with the keys being the file's URI. If multiple virtual servers are set up, the key also includes the virtual server's host ID and the port number.

enabled
If the cache is disabled, the rest of this section is not displayed.

Tuning

To disable the server cache, add the following line to the obj.conf file:

Init fn=cache-init disable=true

CacheEntries <CurrentCacheEntries / MaxCacheEntries>
The number of current cache entries and the maximum number of cache entries. A single cache entry represents a single URI.

Tuning

To set the maximum number of cached files in the cache, add the following line to the obj.conf file:

Init fn=cache-init MaxNumberOfCachedFiles=xxxxx

CacheSize <CurrentCacheSize / MaxCacheSize>
The current size of the cache in bytes and the maximum size of the cache in bytes. The default size is 10MB, and the cache cannot insert new entries once that size is reached.

Tuning

To set the maximum size of the cache (in kilobytes), add the following line to the obj.conf file:

Init fn=cache-init MaxTotalCachedFileSize=xxxxx

Hit Ratio <CacheHits / CacheLookups (Ratio)>
The hit ratio value tells you how efficient your site is. The hit ratio should be above 90%. If the number is 0, you need to optimize your site. See the troubleshooting section for more information on how to improve your site.

This setting is not tunable.

pollInterval
When a file is in the cache, the server constantly goes back to the disk to make sure that it hasn't changed since it was last cached. The pollInterval represents a maximum amount of time that can pass before the server checks the disk again. The default value is 5 seconds. If you'd like to check the file with every access, you can set this value to 0.

Tuning

To set the polling interval (in seconds), add the following line to the obj.conf file:

Init fn=cache-init PollInterval==xxxxx

maxFileSize
The maxFileSize is the maximum size of a file that we will cache. The default size is 537600 bytes. This means that a file which is 600K will not be cached. It is recommended that you avoid caching large files unless you have lots of RAM available.

Tuning

To set the maximum cachable file size (in bytes), add the following line to the obj.conf file:

Init fn=cache-init MaxCachedFileSize=xxxxx

DNS Cache Information
Server DNS cache disabled

The DNS cache caches IP addresses and DNS names.

enabled
If the cache is disabled, the rest of this section is not displayed.

Tuning

By default, the DNS cache is off. Add the following line to obj.conf to enable the cache:

Init fn=dns-cache-init

CacheEntries <CurrentCacheEntries / MaxCacheEntries>
The number of current cache entries and the maximum number of cache entries. A single cache entry represents a single IP address or DNS name lookup.

Tuning

To set the maximum size of the DNS cache, add the following line to the obj.conf file:

Init fn=dns-cache-init cache-size=xxxxx

HitRatio <CacheHits / CacheLookups (Ratio)>
The hit ratio is displays the number of cache hits and the number of cache lookups. A good hit ratio for the DNS cache is ~60-70%.

This setting is not tunable.

Native Threads Pool
Native Thread Pool Data:
------------------------
Idle/Peak/Limit 1/1/100
Work queue length/Limit 0/2147483647
Peak work queue length 1
Work queue rejections 0

The native thread pool is used internally by the server to execute NSAPI functions that require a native thread for execution.

Enterprise Server uses NSPR, which is an underlying portability layer that provides access to the host OS services. This layer provides abstractions for threads that are not always the same asthose for the OS-provided threads. These non-native threads have lower scheduling overhead so their use improves performance. However, these threads are sensitive to blocking calls to the OS, such as I/O calls. To make it easier to write NSAPI extensions that can make use of blocking calls, the server keeps a pool of threads that safely support blocking calls (usually this means it is a native OS thread). During request processing, any NSAPI function that is not marked as being safe for execution on a non-native thread is scheduled for execution on one of the threads in the native thread pool.

If you have written your own NSAPI plug-ins such as NameTrans, Service, or PathCheck functions, these execute by default on a thread from the native thread pool. If your plug-in makes use of the NSAPI functions for I/O exclusively or does not use the NSAPI I/O functions at all, then it can execute on a non-native thread. For this to happen, the function must be loaded with a "NativeThread=no" option indicating that it does not require a native thread. To do this, add this to the "load-modules" Init line in the obj.conf file:

Init funcs="pcheck_uri_clean_fixed_init" shlib="C:/Netscape/p186244/ P186244.dll" fn="load-modules" NativeThread="no"

The NativeThread flag affects all functions in the funcs list, so if you have more than one function in a library but only some of them use native threads, use separate Init lines.

Idle/Peak/Limit
Idle indicates the number of threads that are currently idle. Peak indicates the peak number in the pool. Limit indicates the maximum number of native threads allowed in the thread pool, and is determined by the setting of the NSCP_POOL_THREADMAX environment variable.

Tuning

Modify the NSCP_POOL_THREADMAX environment variable.

Work queue length/Limit
These numbers refer to a queue of server requests that are waiting for the use of a native thread from the pool. The Work Queue Length is the current number of requests waiting for a native thread. Limit is the maximum number of requests that can be queued at one time to wait for a native thread., and is determined by the setting of the NSCP_POOL_WORKQUEUEMAX environment variable.

Tuning

Modify the NSCP_POOL_WORKQUEUEMAX environment variable.

Peak work queue length
This is the highest number of requests that were ever queued up simultaneously for the use of a native thread since the server was started. This value can be viewed as the maximum concurrency for requests requiring a native thread.

This setting is not tunable.

Work queue rejections
This is the cumulative number of requests that have needed the use of a native thread, but that have been rejected due to the work queue being full. By default, these requests are rejected with a "503 - Service Unavailable" response.

This setting is not tunable.

PostThreadsEarly
This advanced tuning parameter changes the thread allocation algorithm by causing the server to check for threads available for accept before executing a request. The default is set to Off. Recommended only in those situations when the load on the server is primarily comprised of lengthy transactions such as LiveWire and the Netscape Application Server or custom applications that access databases and other complex back-end systems. Turning this on allows the server to grow its thread pool more rapidly.

Tuning

Turn this parameter on by adding this directive to magnus.conf:

PostThreadsEarly 1

Thread Pool Environmental Variables
NSCP_POOL_WORKQUEUEMAX

This value defaults to 0x7FFFFFFF (a very large number). Setting this below the RqThrottle value causes the server to execute a busy function instead of the intended NSAPI function whenever the number of requests waiting for service by pool threads exceeds this value. The default returns a "503 Service Unavailable" response and logs a message if LogVerbose is enabled. Setting this above RqThrottle causes the server to reject connections before a busy function can execute.

This value represents the maximum number of concurrent requests for service which require a native thread. If your system is unable to fulfill requests due to load, letting more requests queue up increases the latency for requests and could result in all available request threads waiting for a native thread. In general, set this value to be high enough to avoid rejecting requests under "normal" conditions, which would be the anticipated maximum number of concurrent users who would execute requests requiring a native thread.

The difference between this value and RqThrottle is the number of requests reserved for non-native thread requests (such as static html, gif, and jpeg files). Keeping a reserve (and rejecting requests) ensures that your server continues to fill requests for static files, which prevents it from becoming unresponsive during periods of very heavy dynamic content load. If your server consistently rejects connections, this value is set too low or your server hardware is overloaded.

NSCP_POOL_THREADMAX

This value represents the maximum number of threads in the pool. Set this value as low as possible to sustain the optimal volume of requests. A higher value allows more requests to execute concurrently, but has more overhead due to context switching, so "bigger is not always better." If you are not saturating your CPU but you are seeing requests queue up, then increase this number. Typically, you will not need to increase this number.

Busy Functions
The default busy function returns a "503 Service Unavailable" response and logs a message if LogVerbose is enabled. You may wish to modify this behavior for your application. You can specify your own busy functions for any NSAPI function in the obj.conf file by including a service function in the configuration file in this format:

busy="<my-busy-function>"

For example, you could use this sample service function:

Service fn="send-cgi" busy="service-toobusy"

This allows different responses if the server become too busy in the course of processing a request that includes a number of types (such as Service, AddLog, and PathCheck). Note that your busy function will apply to all functions that require a native thread to execute when the default thread type is non-native.

To use your own busy function instead of the default busy function for the entire server, you can write an NSAPI init function that includes a func_insert call as shown below:

extern "C" NSAPI_PUBLIC int my_custom_busy_function(pblock *pb, Session *sn, Request *rq);

my_init(pblock *pb, Session *, Request *)

func_insert("service-toobusy", my_custom_busy_function);

Busy functions are never executed on a pool thread, so you must be careful to avoid using function calls that could cause the thread to block.

Asynchronous DNS Lookup (Unix)
You can configure the server to use Domain Name System (DNS) lookups during normal operation. By default, DNS is not enabled; if you enable DNS, the server looks up the host name for a system's IP address. Although DNS lookups can be useful for server administrators when looking at logs, they can impact performance. When the server receives a request from a client, the client's IP address is included in the request. If DNS is enabled, the server must look up the hostname for the IP address for every client making a request.

DNS causes multiple threads to be serialized when you use DNS services. If you do not want serialization, enable asynchronous DNS. You can enable it only if you have also enabled DNS. Enabling asynchronous DNS can improve your system's performance if you are using DNS.

Note. If you turn off DNS lookups on your server, host name restrictions will not work, and hostnames will not appear in your log files. Instead, you'll see IP addresses.

You can also specify whether to cache the DNS entries. If you enable the DNS cache, the server can store hostname information after receiving it. If the server needs information about the client in the future, the information is cached and available without further querying. You can specify the size of the DNS cache and an expiration time for DNS cache entries. 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 can range from 1 second to 1 year (specified in seconds); the default value is 1200 seconds (20 minutes).

enabled
If asynchronous DNS is disabled, the rest of this section will not be displayed.

Tuning

Add "AsyncDNS on" to magnus.conf.

NameLookups
The number of name lookups (DNS name to IP address) that have been done since the server was started.

This setting is not tunable.

AddrLookups
The number of address loops (IP address to DNS name) that have been done since the server was started.

This setting is not tunable.

LookupsInProgress
The current number of lookups in progress.

This setting is not tunable.

File Cache in Enterprise Server 4.0

Enterprise Server 4.0 uses anew file cache module, NSFC, which caches static HTML, image, and sound files. In previous versions of Enterprise Server, the file cache was integrated with the accelerator cache for static pages. Therefore, an HTTP request was serviced by the accelerator, or passed to the NSAPI engine for full processing, and requests that could not be accelerated did not have the benefit of file caching. This prevented many sites with NSAPI plugins, customized logs, or used server-parsed HTML from taking advantage of the accelerator.

The NSFC module implements an independent file cache used in the NSAPI engine to cache static files that could not be accelerated. It is also used by the accelerator cache, replacing its previously integrated file cache. NSFC has also been used to cache information that is used to speed up processing of server-parsed HTML.

File Cache Configuration
The file cache is configured in the nsfc.conf configuration file located in the server_root/https-server-id/config directory. You can tune the file cache configuration parameters for improved performance.

FileCacheEnable
Whether the file cache is enabled or not.

By default, this is set to true.

FileCacheEnable=true

MaxAge
The maximum age (in seconds) of a valid cache entry. This setting controls how long cached information will continue to be used once a file has been cached. An entry older than MaxAge is replaced by a new entry for the same file if the same file is referenced through the cache. This setting works in conjuctions with FlushInterval.

By default, this is set to 30.

MaxAge=30

MaxFiles
The maximum number of files that may be in the cache at once.

By default, this is set to 256.

MaxFiles=256

FlushInterval
The interval (in seconds) at which a reaper thread looks for cache entries that are older th an MaxAge and deletes them.

By default, this is set to 60.

FlushInterval=60

SmallFileSizeLimit
The size (in bytes) of the largest file considered to be "small". The contents of "small" files are cached by allocating heap space and reading the file into it.

By default, this is set to 2048.

SmallFileSizeLimit=2048

SmallFileSpace
The size of heap space (in bytes) used for the cache, including heap space used to cache small files.

By default, this is set to 128000 (128 KB).

SmallFileSpace=128000

MediumFileSizeLimit (Unix)
The size (in bytes) of the largest file that is not a "small" file that is considered to be "medium" size. The contents of medium files are cached by mapping the file into virtual memory (currently only on Unix platforms). The contents of "large" files (larger than "medium") are not cached, although information about large files is cached.

By default, this is set to 128000 (128 KB).

MediumFileSizeLimit=128000

MediumFileSpace
The size (in bytes) of the virtual memory used to map all medium sized files.

By default, this is set to 4000000(4MB).

MediumFileSpace=4000000

TransmitFile
When TransmitFile is set to "true," open file descriptors are cached for files in the file cache, rather than the file contents, and PR_TransmitFile is used to send the file contents to a client. When set to "true," the distinction normally made by the file cache between small, medium, and large files no longer applies, since only the open file descriptor is being cached. By default, TransmitFile is "false" on Unix and "true" on Windows NT.

This directive is intended to be used on Unix platforms that have native OS support for PR_TransmitFile, which currently includes HPUX and AIX. It is not recommended for other Unix platforms.

TransmitFile="true"

File Cache Dynamic Control and Monitoring
An object can be added to obj.conf to enable the NSFC file cache to be dynamically monitored and controlled while the server is running. Typically this would be done by first adding a NameTrans directive to the "default" object:

NameTrans fn="assign-name" from="/nsfc" name="nsfc"

Then add a new object definition:

<Object ppath="{SR}/docs/nsfc">
Service fn="service-nsfc-dump"
</Object>

This enables the file cache control and monitoring function to be accessed via the URI, "/nsfc." By changing the "from" parameter in the NameTrans directive, a different URI can be used.

Accessing this URI displays the following information:

Number of file entries in the cache.

Amount of heap space being used by the cache.

Amount of virtual memory space used to map file contents.

Total number of cache hits.

Number of hits on cached file information.

Number of hits on cached file contents.

Parameter setttings.

List of the current cache entries.

The file listing includes the file name, a set of flags, the current number of references to the cache entry, the size of the file, and an internal file ID value. The flags are as follows:

C - File contents are cached.

D - Cache entry is marked for delete.

E - PR_GetFileInfo() returned an error for this file.

I - File information (size, modify date, etc.) is cached.

M - File contents are mapped into virtual memory.

P - File has associated private data (should appear on shtml files).

W - Cache entry is locked for write access.

A query string can be included when the "/nsfc" URI is accessed. The following values are recognized:

?refresh=n - Causes the client to reload the page every n seconds.

?restart - Causes the cache to be shut down and then started.

?start - Starts the cache.

?stop - Shuts down the cache.

For sites with scheduled updates to content, consider shutting down the cache while the content is being updated, and starting it again after the update is complete. Although performance will slow down, the server operates normally when the cache is off.

Cache-init
The cache-init function controls file caching. The server caches files to improve performance. To optimize server speed, you should have enough RAM for the server and cache because swapping can be slow. Do not allocate a cache that is greater in size than the amount of memory on the system.

Note. In Enterprise Server 4.0, much of the functionality of the file cache is controlled by a new configuration file called nsfc.conf.

Parameters:


cache-size	(optional) Specifies the size of the cache in bytes. Valid values for the number of elements in the cache are 32 to 32768; the default is 512. The cache-size value should be greater than the size of all the documents on your server. You should include any static files such as HTML, text, images, sounds, or any other unchanging data in the count. URLs that are dynamic (such as CGI or NSAPI routines) return different data, depending on who calls them, and should not be counted.
mmap-max	(optional) Specifies the maximum amount of memory set aside for memory-mapped (mmap) files the server will keep open at any point. Acceptable values range from 512K to (512*1024)KB; the default is 10000KB (10MB). To get maximum speed, the cache keeps many mmap files open. To estimate the optimal value for mmap-max on your system, approximately compute the total number of bytes of "static" data on your system. For example, if you have 200 files that are 10K in size, then 2MB should be sufficient for mmax-map.
disable	(optional) Specifies whether the file cache is disabled or not. If set to anything but "false" the cache is disabled. By default, the cache is enabled.
PollInterval	(optional) How often the files in the file cache are checked for changes. The default is 5 seconds. In Enterprise Server 4.0, this parameter is ignored -- use the MaxAge parameter in the nsfc.conf file instead.
MaxNumberOfCachedFiles	(optional) Maximum number of entries in the accelerator cache. The default is 4096, minimum is 32, maximum is 32K.
MaxNumberOfOpenCachedFiles	(optional) Maximum number of accel_file_cache entries with file_cache entries. Default is 512, minimum is 32, maximum is 32K.
MaxCachedFileSize	(optional) Maximum size of a file that can be cached. Files larger than this size are not cached. The default is 525K. In Enterprise Server 4.0, this parameter is ignored. Use the MediumFileSizeLimit parameter in `nsfc.conf` instead.
MaxTotalCachedFileSize	(optional) Total size of all files in the cache. Default is 10K, minimum is 1K, maximum is 16M. In Enterprise Server 4.0, this parameter is ignored on Unix. Use the MediumFileSpace parameter in nsfc.conf instead. In Enterprise Server 4.0, this parameter is ignored because it no longers applies to the platform.
MaxNumberOfOpenCachedFiles	(optional) Maximum number of cached files that can be open simultaneously.
CacheHashSize	(optional) size of hash table for the file cache accelerator. Default is 8192, minimum is 32, max is 32K.
NoOverflow	(optional) IRIX only.
IsGlobal	(optional) IRIX only.