Complete Contents
About This Guide
Chapter 1 Introduction to iPlanet Web Server
Chapter 2 Administrating iPlanet Web Servers
Chapter 3 Setting Administration Preferences
Chapter 4 Managing Users and Groups
Chapter 5 Working with Server Security
Chapter 6 Managing Server Clusters
Chapter 7 Configuring Server Preferences
Chapter 8 Understanding Log Files
Chapter 9 Using SNMP to Monitor Servers
Chapter 10 Configuring the Server for Performance
Chapter 11 Extending Your Server with Programs
Chapter 12 Working with Configuration Styles
Chapter 13 Managing Server Content
Chapter 14 Controlling Access to Your Server
Chapter 15 Configuring Web Publishing
Chapter 16 Using Search
Appendix A HyperText Transfer Protocol
Appendix B ACL File Syntax
Appendix C Internationalized iPlanet Web Server
Appendix D Server Extensions for Microsoft FrontPage
Appendix E iPlanet Web Server User Interface
Glossary
Index
Sans-Serif" Size=-1>
Previous Next Contents Index Bookshelf


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

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.

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. By default it is set to 3 seconds. To change the value, add the following line to magnus.conf:

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:

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.

If your server is an SSL server, see "Restarting an SSL Server".

Note that the server's start script and key pair file 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.

Restarting With Inittab (Unix/Linux)
To restart the server using inittab, put the following text on one line in the
/etc/inittab file:

Replace server_root with the directory where you installed the server, and replace type-identifier with 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:

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:

Replace server_root with the directory where you installed the server.

You can use the optional parameters -p and -i at the end of the line:

The -p option starts the server on a specific port number. This overrides the setting in magnus.conf.

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:

Restarting the Server (Windows NT)
You can restart the server by:

For Windows NT 3.51, perform the following steps:

  1. In the Main group, double-click the Control Panel icon.

  2. Double-click the Services icon.

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

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

  5. Click OK.
For Windows NT 4.0, perform the following steps:

  1. From the Start menu, choose Settings, and then Control Panel.

  2. Double-click the Services icon.

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

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

  5. 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 Server's User Account (Windows NT).

Normally, you can't start an SSL-enabled server automatically because you have to enter its password. There is a way to have an SSL-enabled server start without having to enter a password if you keep the password in plain text in a text file. This practice is not recommended.

Warning. Leaving your SSL-enabled server's password in the password.conf file on your system is a large security risk. In essence, you are trading security for convenience. Anyone who can access the file has access to your SSL-enabled server's password. Consider whether you can afford the security risks before keeping your SSL- enabled server's password in this file on your system.

If the security risk is not a concern for you, see Restarting an SSL Server, to start your SSL- enabled server automatically.

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\).

  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.

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

  9. Click OK.
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.

  4. Change the string value to 1.

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

Normally, you cannot start an UNIX SSL-enabled server with the /etc/rc.local or the etc/inittab 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.

Unix Note. The server's password.conf file 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.

Warning. Leaving the SSL-enabled server's password in the password.conf file 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 the password.conf file.

Windows NT Warning. If you have an NTFS file system, you should protect the directory that contains the password.conf file by restricting its access, even if you do not use the file. The directory should have read/write permissions for the administration server user and the web server user. Protecting the directory prevents others from creating a false password.conf file. Note that on FAT file systems, you cannot protect directories or files by restricting access to them.

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

  1. To configure the password, create a new password.conf file in the config subdirectory of the server instance. If you are using the internal PKCS#11 software encryption module that comes with the server, type in the following information:

    Communicator Certificate DB : yourpassword

  2. If you are using a different PKCS#11 module, for example for hardware encryption or hardware accelerators, you will need to specify the name of the PKCS#11 module, followed with the password. For example:

    nFast: yourpassword


Viewing Server Settings
You can see if your server is running and view your server's technical and content settings. The technical settings come from magnus.conf, and the content settings come from obj.conf. These files are located in the server root, in the directory https-server_id \config. For more information about the magnus.conf and obj.conf files, see the NSAPI Programmer's Guide for iPlanet Web Server.

To view your server settings, see The View Server Settings Page in the Server Manager.

The content settings displayed in the View Server Settings page depend on how you've configured your server. Common server content settings include the server's document directory, its index filenames, name and location of its access log, and default MIME type.


Adding and Using Thread Pools
Use thread pools to allocate a certain number of threads to a specific service. For example, you can set up a thread pool specifically for Server-Side JavaScript applications. As part of adding the Server-Side JavaScript thread pool, you specify the maximum number of threads you want to allocate to Server-Side JavaScript applications, and they cannot take up more than their allocated number of threads.

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.

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.

The native thread pool is defined by default for backwards compatability with Netscape Enterprise Server 3.6. To edit the native thread pool, see 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, see 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, see The Thread Pools Page (Unix/Linux) in the Server Manager.

Editing Thread Pools
Once you have added a thread pool, you cannot change the values of the thread pool settings (minimum threads, maximum threads and so on) through the Server Manager. Instead you must edit the thread pool settings in obj.conf.

A thread pool appears in obj.conf as follows:

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. For example, if you set up a thread pool you want to use for Server-Side JavaScript (SSJS) applications (this allows limiting the number of threads used for SSJS applications and isolation), you can designate it as the Sever-Side JavaScript thread pool using the Server Manager's Activate Server-Side JavaScript page.

To configure a thread pool, go to the Administration Server Preferences tab and select Thread Pool. Once a thread pool is configured, then the Javascript Thread Pool list will show the thread pool available to be used for configuring SSJS to run in that pool.

You can also designate a thread pool by using the pool parameter of the load-modules function in obj.conf.

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


Configuring Network Settings
You can change the following network settings on your server: server user, server name, server port, bind to address, and MTA host.

Changing the Server's Location (Unix/Linux)
For various reasons, you might move the server from one directory to another. If you move the server, you must change the location the server references—it needs to know where the binary files are. After changing the location, you must shut down the server and copy the server files and subdirectories to a new location.

To change the server's location edit the Server Location field in The Network Settings Page in the Administration Server.

Changing the Server's User Account (Unix/Linux)
The server user specifies a Unix/Linux user account that the server uses. All the server's processes run as this user.

You do not need to specify a server user if you chose a port number greater than 1024 and are not running as the root user (in this case, you do not need to be logged on as root to start the server). If you do not specify a user account here, the server runs with the user account you start it with. Make sure that when you start the server, you use the correct user account.

Note. If you do not know how to create a new user on your system, contact your system administrator or consult your system documentation.

Even if you start the server as root, you should not run the server as root all the time. You want the server to have restricted access to your system resources and run as a non-privileged user. The user name you enter as the server user should already exist as a normal Unix/Linux user account. After the server starts, it runs as this user.

If you want to avoid creating a new user account, you can choose the user nobody or an account used by another HTTP server running on the same host. On some systems, however, the user nobody can own files but not run programs.

To change the server's user account, edit the Server User field in The Network Settings Page in the Administration Server.

Changing the Server's User Account (Windows NT)
By using a specific user account (other than LocalSystem), you can restrict or enable system features for the server. For example, you can use a user account that can mount files from another machine.

To change the web server user account after installation, perform the following steps:

  1. Create a user with the Windows NT Users Manager. The user must have "Log in as a service" rights.

  2. Stop the server.

  3. From the Windows Control Panel, choose Services.

  4. Select the iWS service.

  5. In the Service pop-up, in the Log on As section, click the This Account radio button.

  6. Type the user account you want the web server to use.

  7. Type the password for that account; type it again for confirmation.

  8. Click OK.

  9. Restart the server using the Services program or the Server Administration page.
Changing the Server Name
The server name is the full hostname of your server machine. When clients access your server, they use this name. The format for the server name is machinename.yourdomain.domain. For example, if your full domain name is iplanet.com, you could install a server with the name www.iplanet.com.

If your system administrator has set up a DNS alias for your server, use that alias on The Network Settings Page in the Administration Server. If you do not have a DNS alias for your server, use the machine's name combined with your domain name to construct the full hostname.

To change the server name, edit the Server Name field in The Network Settings Page in the Administration Server.

Changing the Server Port Number
The Server Port Number specifies the TCP port that the server listens to. The port number you choose can affect your users—if you use a nonstandard port, then anyone accessing your server must specify a server name and port number in the URL. For example, if you use port 8090, the user would specify something like this URL:

Port numbers for the most commonly used network-accessible services are maintained in the file /etc/services (on Unix/Linux) or \WINNT\System32\drivers\etc\services (on Windows NT).

Although the port number can be any port from 1 to 65535, the standard insecure web server port number is 80, and the standard secure web server port number is 443.

For Unix/Linux, if you are not running as the root user when you install or start the server, you must use a port number higher than 1024.

To change the server port number, edit the Server Port field in The Network Settings Page in the Administration Server.

Changing the Server Binding Address
At times you'll want the server machine to answer to two URLs. For example, you might want to answer both http://www.iplanet.com/ and
http://www.mozilla.com/ from one machine.

If you have already set up your system to listen to multiple IP addresses and want to use this feature, use the Bind To Address field in the Network Settings window to tell the server which IP address is associated with this hostname.

To change the server binding address, edit the Bind To Address field in The Network Settings Page in the Administration Server.

Changing the Server's MTA Host
You can change the server's MTA (Message Transfer Agent) host. You must enter a valid MTA host if you want to use the agent email function.

To change the MTA Host, edit the MTA host field in The Network Settings Page in the Administration Server.


Customizing Error Responses
You can specify a custom error response that sends a detailed message to clients when they encounter errors from your server. You can specify a file to send or a CGI program to run.

You might want to change the way the server behaves when it gets an error for a specific directory. Instead of sending back the default file, you might want to send a custom error response instead. For example, if a client tries repeatedly to connect to a part of your server protected by access control, you might return an error file with information on how to get an account.

Before you can enable a custom error response, you must create the HTML file to send or the CGI program to run in response to an error. After you do this, enable the response in The Network Settings Page in the Administration Server.


Working with Dynamic Configuration Files
Server content is seldom managed entirely by one person. You may need to allow end users to access a subset of configuration options so that they can configure what they need to, without giving them access to the iPlanet Web Server. The subset of configuration options are stored in dynamic configuration files. Two types of dynamic configuration files are supported by iPlanet Web Server: .htaccess and .nsconfig. You can enable .nsconfig files in iPlanet Web Server; you have to manually enable .htaccess files.

Note. There is no support for LDAP or the 3.0 Netscape user databases in the dynamic configuration files. You should not use dynamic configuration files if you use LDAP. You must use NCSA-style user databases to use .htaccess files. You must use either NCSA-style user databases or Enterprise 2.x DBM- format user databases with .nsconfig files. For more information on user databases, see Managing Servers with Netscape Console.

If you already use .nsconfig files, you might want to continue using them. However, iPlanet Web Server also includes a utility for converting your .nsconfig files to .htaccess files.

Using .htaccess Files
The files that support .htaccess are in the directory
server_root/plugins/htaccess. These files include a plug-in that enables you to use .htaccess files and a script for converting .nsconfig files to .htaccess files.

Activating .htaccess checking
To use .htaccess files, you must first modify the server's obj.conf file to load, initialize, and activate the plug-in. At the top of the obj.conf file, after the other Init directives, add the following lines:

For Unix/Linux:

For Windows NT:

These lines load and initialize the module when the server is started. server_root is the path to your server root.

To activate .htaccess file processing for all directories managed by the server, add the PathCheck directive:

to the default server object, which is delimited by:

Generally, the directive to activate .htaccess processing should be the last PathCheck directive in the object.

To activate .htaccess file processing for particular server directories, place the PathCheck directive in the corresponding object definition in obj.conf.

If you want to name your .htaccess files something other than .htaccess, you must specify the filename in the PathCheck directive using the following format:

Replace filename with the filename you are using.

After editing the configuration file, stop and start your server. Apply your configuration file changes in the iPlanet Web Server by clicking the Apply button. Subsequent accesses to the server will be subject to .htaccess access control in the specified directories.

To restrict write access to .htaccess files, create a configuration style for them, and apply access control to that configuration style. For more information, see Working With Configuration Styles and Controlling Access to Your Server.

Converting Existing .nsconfig Files to .htaccess Files

The iPlanet Web Server includes a script for converting your existing .nsconfig files to .htaccess files. To convert your files, at the command prompt, enter the path to Perl on your system, the path to the script, and the path to your obj.conf file. For example you might type the following (it should all be on one line when you type it):

The script converts all .nsconfig files to .htaccess files, but does not delete the .nsconfig files.

Supported .htaccess Directives

The following .htaccess directives are supported in this release:

There is an option, called groups-with-users, that facilitates handling large numbers of users in groups. That is, if you have many users in a group, you can follow these steps:

  1. Revise the format of the user file format to list all the groups a user belongs to:

  2. Revise the AuthGroupFile directive to point to the same file as the AuthUserFile.
Or, alternatively, you can perform these steps:

  1. Remove the AuthGroupFile directive entirely.

  2. And add this option to the 'Init fn=htaccess-init' line in the obj.conf file:
Example of an .htaccess File

The following example shows an .htaccess file:

Using .nsconfig Files
With .nsconfig files, you can allow end users to apply access control or customize error messages without allowing them to use CGI or parsed HTML. The format and capability of these dynamic configuration files is described in Writing .nsconfig Files.

When a request is made for a resource in which dynamic configuration is enabled, the server must search for the configuration files within one or more directories of that resource. This search can be an expensive operation in terms of performance, so the server lets you configure how much flexibility you need, weighing it against the efficiency cost.

You can provide a base directory to the server, in which case the server starts its search for configuration files from the filesystem directory. Alternatively, you can provide no base directory, in which case the server attempts to infer the base directory from the URL. That is, if the requested URL is to a file in the document root, the server starts searching from the document root.

You also specify the name of the configuration file to search for within the base directory.

If you centralize all of your configuration information for the subdirectories of the base directory in the base directory's configuration file, the server is more efficient because it doesn't have to search for configuration files in the subdirectories.

However, you may sometimes want the server to search the subdirectories. If you do, the server searches for .nsconfig files starting from the top level directory and searching downward until reaching the directory in which the referenced resource resides. The server processes .nsconfig files in the order it encounters them. If a top level file restricts a user's access, the server does not give the user access, even though a lower level file might allow access.

The server processes all restrictions based on IP address and DNS entry (RestrictAccess directive) as it finds them in a file. If the server finds a file that denies a user access because of IP address or DNS entry, it stops processing files. The server collects restrictions based on user name (RequireAuth directive) and processes them at the end, unless the request has already been denied because of IP address or DNS entry.

For example, if you selected the base directory inferred from URL translation, selected .nsconfig for your filename, and chose to search subdirectories, the following search would occur.

When a user requests the filesystem path C:\Netscape\server4\docs\icons\gfx\logo.gif, instead of searching for C:\Netscape\server4\docs\.nsconfig the server would search all of the subdirectories:

You can also enter a wildcard pattern of file types you want to disable in directories where dynamic configuration is enabled. To disable CGI programs and parsed HTML, for example, use * (cgi|parsed-html).

To configure .nsconfig files, perform the following steps:

  1. From the Server Manager, choose Server Preferences.

  2. Click the Dynamic Configuration Files link.

  3. Choose a resource from the Resource Picker.

  4. Choose whether to base the directory from the URL or from a specified directory.

  5. Type the filename.

  6. Choose whether to search only the base directory.

  7. Type the disabled types.

  8. Click OK.

  9. Click Save and Apply.
Writing .nsconfig Files

The .nsconfig files consist of sets of directives that control the server. These directives are surrounded by Files directives that tell the server which files in the configuration file's directory the directives apply to. For example:

PATTERN1 and PATTERN2 are wildcard patterns that tell the server which filesystem paths to apply the directives to. For example, * would apply the directive to all filesystem pathnames. Any pattern given is first prefixed with the directory containing the configuration file to ensure that the directives are applied only to subdirectories. There can be as many sets of Files directives in the .nsconfig file as you need.

The file can contain blank lines. Lines beginning with # are treated as comments. Note that lines are limited to a maximum of 1024 characters.

For Windows NT, all paths must use the forward slash (/) instead of the backwards slash (\), otherwise you receive a server "path not found" error.

Each directive can take a variable number of parameters, all of which must be lowercase. The Files directives include:

Example of an .nsconfig File

The following example shows an .nsconfig file:

<Files *
ErrorFile reason="Unauthorized" code="401" path="/errors/unauthorized.html"
ErrorFile reason="Forbidden" code="403" path="/errors/forbidden.html"
ErrorFile reason="Not Found" code="404" path="/errors/notfound.html"
ErrorFile reason="Server Error" code="500" path="/errors/server-error.html"
RestrictAccess method="(GET|HEAD|POST)" type="allow" ip="*"
RestrictAccess method="(GET|HEAD|POST)" type="deny" ip="198.95.251.30" return-code="404"
</Files
<Files *.gif
AddType exp=*.gif type=application/octet-stream
</Files
<Files *.txt
RequireAuth dbm="server_root/authdb/default" realm=Text userpat="user*"
</Files


Restricting Symbolic Links (Unix/Linux)
You can limit the use of the filesystem links in your server. Filesystem links are references to files stored in other directories or filesystems. The reference makes the remote file as accessible as if it were in the current directory. There are two types of filesystem links:

For more information about hard and symbolic links, see your Unix/Linux system documentation.

Filesystem links are an easy way to create pointers to documents outside of the primary document directory and anyone can create these links. For this reason you might be concerned that people might create pointers to sensitive files (for example, confidential documents or system password files).

To restrict symbolic links, use The Limit Symbolic Links Page (Unix/Linux) in the Server Manager.


Using the Watchdog (uxwdog) Process (Unix/Linux)
The uxwdog process is the name of the web server watchdog process, introduced in Enterprise Server 3.01. Prior to Enterprise Server 3.01, the server would fork a copy of itself at startup, and the parent server process would serve as the watchdog for the child. In Enterprise 2.x, a server restart operation would cause the parent server process (ns-httpd) to terminate the child ns-httpd process, and then recreate it. This result had the advantage that the parent process could maintain the key file password for a secure server, so that restarting the server would not require the server administrator to reenter the password.

However, with the addition of a number of subsystems to the server in Enterprise Server 3.0, it was felt that the server should be completely stopped and started for a restart operation, as the most expedient way to be sure that all subsystems were properly initialized. This had several immediate drawbacks. First, it became necessary to reenter the key file password for a secure server during a restart. This was particularly a problem for a secure server with automatic log rotation enabled, since log rotation relies on a server restart operation. Finally, every server configuration change required the server to be completely stopped and started.

The basic idea of uxwdog is to have a lightweight process that keeps around just enough state information to be able to start a new server process during a restart operation, without human intervention. This state consists mainly of any passwords or PINs required to start a secure server, and open file descriptors for sockets on which the server will listen. The socket file descriptors had to be kept around because some of them might be for privileged TCP ports, port 80 for example, which would require a process running as root to bind them. When this is the case, the Administration Server generally runs as root, and starts uxwdog as root, or else an administrator who is running as root executes the server start script. Once uxwdog binds the server listen port(s), it changes its uid to the server uid, often "nobody," and then starts the server process as that uid.

One consequence of this behavior is that the NSAPI Init directives always run under the server uid, unlike in Enterprise 3.0 and earlier, where it was possible to have them run as root. This has created some problems in upgrade situations, when a plugin Init function was creating a file during the Init. The file would be owned by root in the older server version, and when installing the plugin in Enterprise 3.01 and later, it would be necessary to change the ownership or protection on the migrated file.

In order to determine on which ports the server listens, uxwdog must read magnus.conf and obj.conf. It does this each time the server is restarted, and verifies that the port numbers have not been changed. If they have, a restart operation is not possible, uxwdog will exit, and the server will have to be manually started. This is also true if security is turned on, the server uid is changed, or the PidLog filename is changed.

The restart and stop scripts send SIGHUP and SIGTERM, respectively, to uxwdog. In both cases, uxwdog sends SIGTERM to the ns-httpd process to shut down the server. For a restart operation, uxwdog then creates a new server process, passing it the file descriptors of the listen ports, and any passwords or PINs it has saved.

The default behavior of the server watchdog process automatically restarts the server if the server process should terminate unexpectedly. You can revert to the previous default behavior, which was for the watchdog process to exit if the server terminates unexpectedly. To revert to the original default behavior, set the environment variable, UXWDOG_NO_AUTOSTART, at the beginning of the server start script as follows:

(following the "#!/bin/sh" line):

You also now have the option to have the watchdog restart the server if the server process calls exit() with a non-zero argument value. This feature is disabled by default, but can be enabled by setting the UXWDOG_RESTART_ON_EXIT environment variable in the server start script as follows:

Between Enterprise Server 3.01 and Enterprise Server 3.5.1, the Administration Server CGIs for Enterprise Server were changed to actually restart, rather than start and stop the server, when configuration changes are applied. As part of this change, these CGIs will create a file, wdnotify, in the server's logs directory, which will contain a TCP port number on which the CGI listens for status from the watchdog. During a start or restart operation, uxwdog checks for the existence of this file, and if it finds it, connects to that port, and reads the name of a file to which stderr is to be redirected during the operation. uxwdog opens that file, redirects stderr to it, and performs the operation. If the operation is successful, uxwdog writes a single byte value of zero back to the CGI. Otherwise it writes a non-zero status byte, typically a value of one. Finally uxwdog closes the connection to the CGI, and redirects stderr to /dev/console.

There may be some cases where wdnotify does not get deleted when it should, which may cause uxwdog to exit instead of starting or restarting the server. This can be corrected by manually removing the wdnotify file from the logs directory.

 

© Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.