Previous     Contents     Index          Next     
iPlanet Web Server, Enterprise Edition Administrator's Guide



Chapter 7   Configuring Server Preferences


This chapter describes how to configure server preferences for your iPlanet Web Server.

This chapter contains the following sections:



Starting and Stopping the Server

On Unix, some iPlanet Web Server installations may require access to more memory and/or file descriptors than your operating system allows by default. If you are unable to start the server, check the resource limits imposed by your operating system using the ulimit command. Your operating system's ulimit man page should provide more information.

Once the server is installed, it runs constantly, listening for and accepting HTTP requests.

The status of the server appears in the Server On/Off page. You can start and stop the server using one of the following methods:

  • Click the Server On or Server Off in The Server On/Off Page.

  • Use the Services window in the Control Panel (Windows NT).

  • Use start. If you want to use this script with init, you must include the start command http:2:respawn:server_root/type-identifier/start -start -i in /etc/inittab. (Unix/Linux)

  • Use stop, which shuts down the server completely, interrupting service until it is restarted. If you set the etc/inittab file to automatically restart (using "respawn"), you must remove the line pertaining to the web server in etc/inittab before shutting down the server; otherwise, the server automatically restarts. (Unix/Linux)

After you shut down the server, it may take a few seconds for the server to complete its shut-down process and for the status to change to "Off."

If your machine crashes or is taken offline, the server stops and any requests it was servicing may be lost.


Note

If you have a security module installed with your server, you will be required to enter the appropriate passwords before starting or stopping the server.



Note

On Unix, some iPlanet Web Server installations may require access to more memory and/or file descriptors than your operating system allows by default. If you are unable to start the server, check the resource limits imposed by your operating system using the ulimit command. Your operating system's ulimit man page should provide more information.



Setting the Termination Timeout

When the server is off, it stops accepting new connections. Then it waits for all outstanding connections to complete. The time the server waits before timing out is configurable in the magnus.conf file, which can be found in server_root/https-server_name/config/. By default it is set to 30 seconds. To change the value, add the following line to magnus.conf:

TerminateTimeout seconds

where seconds represents the number of seconds the server will wait before timing out.

The advantages to configuring this value is that the server will wait longer for connections to complete. However, because servers often have connections open from nonresponsive clients, increasing the termination timeout may increase the time it takes for the server to shut down.


Restarting the Server (Unix/Linux)

You can restart the server using one of the following methods:

  • Automatically restart it from the inittab file.

    Note that if you are using a version of Unix/Linux not derived from System V (such as SunOS 4.1.3), you will not be able to use the inittab file.

  • Automatically restart it with daemons in /etc/rc2.d when the machine reboots.

  • Restart it manually.

Because the installation scripts cannot edit the /etc/rc.local or /etc/inittab files, you must edit those files with a text editor. If you do not know how to edit these files, consult your system administrator or system documentation.

Normally, you cannot start an SSL-enabled server with either of these files because the server requires a password before starting. Although you can start an SSL-enabled server automatically if you keep the password in plain text in a file, this is not recommended.


Caution

Leaving the SSL-enabled server's password in plain text in the server's start script is a large security risk. Anyone who can access the file has access to the SSL-enabled server's password. Consider the security risks before keeping the SSL-enabled server's password in plain text.


The server's start script, key pair file, and the key password should be owned by root (or, if a non-root user installed the server, that user account), with only the owner having read and write access to them.


Starting SSL-enabled Servers Automatically

If security risks are not a concern for you, follow these steps to start your SSL-enabled server automatically:

  1. Using a text editor, open the start file, which is located in server_root/https-server_id.

  2. Locate the -start line in the script and insert the following:

    echo "password"|

    where password is the SSL password you have chosen.

    For example, if the SSL password is netscape, the edited line might look like this:

    -start)

       echo "netscape"|./$PRODUCT_BIN -d $PRODUCT_SUBDIR/config $@


Restarting With Inittab (Unix/Linux)

To restart the server using inittab, put the following text on one line in the
/etc/inittab file:

http:2:respawn:server_root/type-identifier/start -start -i

where server_root is the directory where you installed the server, and type-identifier is the server's directory.

The -i option prevents the server from putting itself in a background process.

You must remove this line before you stop the server.


Restarting With the System RC Scripts (Unix/Linux)

If you use /etc/rc.local, or your system's equivalent, place the following line in /etc/rc.local:

server_root/type-identifier/start

Replace server_root with the directory where you installed the server.


Restarting the Server Manually (Unix/Linux)

To restart the server from the command line, log in as root if the server runs on ports with numbers lower than 1024; otherwise, log in as root or with the server's user account. At the command-line prompt, type the following line and press Enter:

server_root/type-identifier/start

where server_root is the directory where you installed the server.

You can use the optional parameter -i at the end of the line. The -i option runs the server in inittab mode, so that if the server process is ever killed or crashed, inittab will restart the server for you. This option also prevents the server from putting itself in a background process.


Note

If the server is already running, the start command will fail. You must stop the server first, then use the start command. Also, if the server startup fails, you should kill the process before trying to restart it.



Stopping the Server Manually (Unix/Linux)

If you used the etc/inittab file to restart the server you must remove the line starting the server from /etc/inittab and type kill -1 1 before you try to stop the server. Otherwise, the server restarts automatically after it is stopped.

To stop the server manually, log in as root or use the server's user account (if that is how you started the server), and then type the following at the command line:

server_root/type-identifier/stop


Restarting the Server (Windows NT)

You can restart the server by:

  • Using the Services Control Panel to restart any server.

  • Using the Services Control Panel to configure the operating system to restart the server or the administration server each time the machine is restarted.

For Windows NT, perform the following steps:

  1. In the Control Panel double-click the Services icon.

  2. Scroll through the list of services and select the service for your server.

  3. Check Automatic to have your computer start the server each time the computer starts or reboots.

  4. Click OK.


    Note

    You can also use the Services dialog box to change the account the server uses. For more information about changing the account the server uses, see Changing the User Account (Unix/Linux).


By default, the web server prompts the administrator for the key database password before starting up. If you want to be able to restart an unattended web server, you need to save the password in a password.conf file. Only do this if your system is adequately protected so that this file and the key databases are not compromised.


Using the Automatic Restart Utility (Windows NT)

The server is automatically restarted by a server-monitoring utility if the server crashes. On systems that have debugging tools installed, a dialog box with debugging information appears if the server crashes. To help debug server plug-in API programs (for example, NSAPI programs), you can disable the auto-start feature by setting a very high timeout value. You can also turn off the debugging dialog boxes by using the Registry Editor.


Changing the Time Interval (Windows NT)
To change the time interval that elapses between startup and the time the server can automatically restart, perform the following steps:

  1. Start the Registry Editor.

  2. Select your server's key (in the left side of the Registry Editor window, located in HKEY_LOCAL_MACHINE\SOFTWARE\Netscape\Enterprise\6.0).

  3. Choose Add Value from the Edit menu. The Add Key dialog box appears.

  4. In Value Name, type MortalityTimeSecs.

  5. Select REG_DWORD from the Data Type pull-down list.

  6. Click OK. The DWORD Editor dialog box appears.

  7. Type the time interval (in seconds) that will elapse between startup and the time the server can restart automatically.

    The interval can be in binary, decimal, or hexadecimal format.

  8. Click the numerical format for the value you entered in the previous step (binary, decimal, or hexadecimal).

  9. Click OK.

    The MortalityTimeSecs value appears in hexadecimal format at the right side of the Registry Editor window.


Turning Off the Debugging Dialog Box (Windows NT)
If you've installed an application (such as a compiler) that has modified the system debugging settings and the server crashes, you might see a system-generated application error dialog box. The server will not restart until you click OK.

To turn off the debugging dialog box that appears if the server crashes, perform the following steps:

  1. Start the Registry Editor.

  2. Select the AeDebug key, located in the left side of the Registry window in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion.

  3. Double-click the Auto value in the right side of the window.

    The String Editor dialog box appears.

  4. Change the string value to 1.



Tuning Your Server for Performance

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:

  1. Go to the Preferences tab.

  2. Click the Performance Tuning link.

  3. Enter the desired value in the Maximum simultaneous requests field.

For additional information, see the online help for The Performance Tuning Page.



Editing the magnus.conf File


When the iPlanet Web Server starts up, it looks in a file called magnus.conf in the server_root/server_id/config directory to establish a set of global variable settings that affect the server's behavior and configuration. iPlanet Web Server executes all the directives defined in magnus.conf. You can edit certain settings in the magnus.conf file using the Magus Editor in the Server Manager.

For a complete description of the magnus.conf file and information about editing the file using a text editor, see the NSAPI Programmer's Guide.

To access the Magnus Editor, perform the following steps:

  1. Access the Server Manager and choose the Preferences tab.

  2. Click the Magnus Editor link.

  3. Select the settings to edit from the drop-down list and click Manage.

    The Server Manager displays the editor for the settings you specified.

  4. Make the desired changes to the settings and click OK.

For more information about each Settings page, see The Magnus Editor Pagein the online help.



Adding and Editing Listen Sockets


Before the server can process a request, it must accept the request via a listen socket, then direct the request to the correct connection group and virtual server. When you install iPlanet Web Server, one listen socket, ls1, is created automatically. This listen socket uses the IP address 0.0.0.0 and the port number you specified as your HTTP server port number during installation (the default is 80). You cannot delete the default listen socket.

You can edit your server's listen socket settings using the Server Manager's Listen Sockets Table. To access the table, perform the following steps:

  1. Access the Server Manager and click the Preferences tab.

  2. Click the Edit Listen Sockets link.

  3. Make the desired changes and click OK.



Choosing MIME Types

The Mime Types page allows you to edit your server's MIME files.

MIME (Multi-purpose Internet Mail Extension) types control what types of multimedia files your mail system supports. MIME types also specify what file extensions belong to certain server file types, for example to designate what files are CGI programs.

You don't need to create a separate MIME types file for each virtual server. Instead, you create as many MIME types files as you need and associate them with a virtual server. One MIME types file, mime.types, exists by default on the server, and cannot be deleted. This file can be the absolute path.

To access the MIME Types page, perform the following steps:

  1. Access the Server Manager and click the Preferences tab.

  2. Click the MIME Types link.

  3. Make the desired changes and click OK.

For more information, see The Mime Settings Pagein the online help and Using Virtual Servers.



Restricting Access


You can control access to the entire server or to parts of the server (that is, directories, files, file types) using the Server Manager's Restrict Access page. When the server evaluates an incoming request, it determines access based on a hierarchy of rules called access-control entries (ACEs), and then it uses the matching entries to determine if the request is allowed or denied. Each ACE specifies whether or not the server should continue to the next ACE in the hierarchy. The collection of ACEs is called an access-control list (ACL). When a request comes in to the server, the server looks in vsclass.obj.conf (where vsclass is the virtual server class name) for a reference to an ACL, which is then used to determine access. By default, the server has one ACL file that contains multiple ACLs.

You can set access control globally for all servers through the Administration Server or for a resource within a specific server instance through the Server Manager. For more information about setting access control for a resource, see "Setting Access Control,".

To restrict access to your iPlanet Web Servers, perform the following steps:

  1. Access the Server Manager and choose the Preferences tab.

  2. Click the Restrict Access link.

For more information, see Controlling Access to Your Server and The Restrict Access Pagein the online help.



Restoring Configuration Settings


The Restore Configuration page allows you to view a backup copy of your configuration files and revert to the configuration data saved on a specific date.


Note

On Windows NT, use this page only to roll back your own changes to the configuration files. Do not roll back to backup versions created during installation; they may not be complete.


For more information, see The Restore Configuration Pagein the online help.



Configuring the File Cache


The iPlanet Web Server uses a file cache to serve static information faster. In the previous version of the server, there was also an accelerator cache which routed requests to the file cache, but the accelerator cache is no longer used. The file cache contains information about files, and static file content. The file cache also caches information that is used to speed up processing of server-parsed HTML.

The file cache is turned on by default. The file cache settings are contained in a file called nsfc.conf. You can use the Server Manager to change the file cache settings.

For more information, see the online Performance Tuning and Sizing Guide on http://docs.iplanet.com/docs/manuals/enterprise.html.



Adding and Using Thread Pools


You can use thread pools to allocate a certain number of threads to a specific service.

Another use for thread pools is for running thread-unsafe plugins. By defining a pool with the maximum number of threads set to 1, only one request is allowed into the specified service function.

When you add a thread pool, the information you specify includes the minimum and maximum number of threads, the stack size, and the queue size.

For more information, see the online Performance Tuning and Sizing Guide on http://docs.iplanet.com/docs/manuals/enterprise.html.


The Native Thread Pool and Generic Thread Pools (Windows NT)

On Windows NT, you can use two types of thread pools: the native thread pool (NativePool) and additional generic thread pools.

To edit the native thread pool, access The Native Thread Pool Page (NT) in the Server Manager.

You can create as many generic thread pools as you want, for as many purposes as you want. To create generic thread pools, access The Generic Thread Pools Page (NT) in the Server Manager.


Thread Pools (Unix/Linux)

Since threads on Unix/Linux are always OS-scheduled (as opposed to user-scheduled) Unix/Linux users do not need to use the NativePool, and do not have a Server Manager page for editing its settings. However, Unix/Linux users can still create thread pools. To create thread pools, access The Thread Pools Page (Unix/Linux) in the Server Manager.


Editing Thread Pools

Once you have added a thread pool, you can change the values of the thread pool settings (minimum threads, maximum threads and so on) through the Server Manager.

You can also edit the thread pool settings in vsclass.obj.conf, where vsclass is the virtual server class name.

A thread pool appears in vsclass.obj.conf as follows:

Init fn="thread-pool-init" name=name_of_the_pool MaxThreads=n MinThreads=n QueueSize=n StackSize=n

Use the following parameters to change the pool: MinThreads, MaxThreads, QueueSize, and StackSize.

Windows NT users can always edit the settings for the native pool using the Server Manager.


Using Thread Pools

After you've set up a thread pool, use it by designating it as the thread pool for a specific service.

To configure a thread pool, go to the Server Manager Preferences tab and select Thread Pool. Once a thread pool is configured, then the Thread Pool list will show the thread pool available to be used for the specific service you've designated.

You can also designate a thread pool by using the pool parameter of the load-modules function in vsclass.obj.conf, where vsclass is the virtual server class name.

pool="name_of_pool"

In addition, you can use the pool parameter on any NSAPI function so that only that NSAPI function runs on the pool you specify.


Previous     Contents     Index          Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated May 09, 2002