Configuring system settings

his chapter describes how to configure system settings for your Netscape Enterprise Server by using the Server Manager configuration forms.

Starting and stopping the server

Once installed, the server runs constantly, listening for and accepting requests. If your server is running, you'll see the On icon's green light (left of the server's name) in the Server Selector, as shown in the graphic at left. You can start and stop the server by clicking the icon. You can also start, restart, and stop the server from the Server Manager.

Restart performs a soft start, which means that the server reloads its configuration files, and service isn't interrupted. Sometimes you'll need to do a hard stop and start, such as if you change the port number, enable security, and so on. (If you aren't sure whether you need to do a hard start or soft restart, do a hard stop and hard start.)

Stop shuts down the server completely, interrupting service until it is restarted. If you have the server started with inittab, you'll need to remove the line in inittab before shutting down the server; otherwise, the server automatically restarts.

To start, restart, or stop the server from the Server Manager,

  1. Choose System Settings|On/Off.
  2. Click the On or Off button. If your server is on and you click On, the server will restart. If you've turned on or restarted your server, access it as a client by clicking the "Access <server> as a client" link.

If your machine crashes or is taken offline, the server stops and any requests it was servicing are lost. You can restart the server using one of the following methods:

If you are using a version of Unix not derived from System V (such as SunOS 4.1.3), you won't be able to use the inittab option.
Because the installation forms cannot edit the /etc/rc.local or /etc/inittab files, you need to edit those files with a text editor. If you don't know how to edit these files, consult your system administrator or system documentation.

Normally, you can't run an SSL-enabled server with either of these methods because the server requires that you enter a password before starting. There is a way, however, to have an SSL-enabled server start automatically if you keep the password in cleartext in a file. This practice is not recommended.

Caution!
Leaving your SSL-enabled server's password in cleartext in the server's start script 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, which means that your server's security could be compromised. Consider whether you can tolerate the security risks before keeping your SSL-enabled server's password in plaintext on your system.
The server's start script, key pair file, and the key password should be owned by root (or the user account who installed the server), with only the owner having read and write access to them. For more information about security, see Chapter 7, "Encryption and SSL."
If you are willing to take the risk that your server's security could be compromised, follow these steps in order to have your SSL-enabled server start automatically:
  1. Using a text editor, open the start file, which is located in [ServerRoot]/https-[server_identifier]. The start file contains three lines (the second line is blank):

    #!/bin/sh

    cd [ServerRoot]; ./ns-httpd -d [ServerRoot]/https-[server_identifier]/config $@
  2. In the third line (counting the blank second line), insert the following after the semicolon: echo "[your_SSL-enabled_server_password]"|

    For example, the edited third line might look like this:

    cd /usr/ns-home/bin/https; echo "MBi12!mo"|./ns-httpd -d [ServerRoot]/https-[server_id]/config $@
    

Restarting with inittab

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

The -i option prevents the server from putting itself in a background process.
http:2:respawn:[ServerRoot]/[type-identifier]/start -i

Replace [ServerRoot] with the directory where you installed the server, and replace [type-identifier] with the server's directory.

You'll need to remove this line before you try to stop the server.

Restarting with the system RC scripts

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

[ServerRoot]/[type-identifier]/start
Replace [ServerRoot] with the directory where you installed the server.

Restarting the server manually

To restart the server from the command line, log in as root if the server runs on ports less 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:

[ServerRoot]/[type-identifier]/start

Replace [ServerRoot] with the directory where you installed the server.

You can use optional parameters at the end of the line:

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

-i runs the server in inittab mode, so that if the server process is ever killed or crashed, inittab will restart the server for you. It also prevents the server from putting itself in a background process.

Note
If the server is already running, this 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.

Soft-restart

If the server is currently running and you want to restart it so that it uses an updated configuration, type:

[ServerRoot]/[type-identifier]/restart

This script finds the parent process id (in the logs/pid file), and sends the hang-up (-HUP) signal with this process id.

Stopping the server manually

If you used inittab for restarting the server, you'll need to remove the line from /etc/inittab 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:

[ServerRoot]/[type-identifier]/stop

Viewing server settings

You can view your server's technical and content settings from the Server Manager. The technical settings come from magnus.conf, and the content settings come from obj.conf. These files are located in the directory admserv/https-server_name in your server root directory. For more information about the magnus.conf and obj.conf files, see the Programmer's Guide. You can also see if your server is running.

The following list explains the server's technical settings:

The server's content settings 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.

Restoring backup configuration files

You can view or restore a backup copy of your configuration files (magnus.conf and obj.conf).

To view or restore a backup copy of your configuration files,

  1. From the Server Manager, choose System Settings|Restore Configuration.
  2. If you want to view a backup version, click the View button next to the version you want. Click Restore if you want to restore that version.

Tuning server performance

You can configure the server's technical options, including the number of processes the server spawns, the minimum and maximum number of threads the server uses, and listen-queue size and DNS usage.

Server processes

You can set the number of processes that are created when your server starts. These processes' threads take turns answering requests. In general, you should set the number of processes equal to the number of processors your system has. Unlike the 1.x version of the server, you do not need to specify a high number of processes to handle a high-demand system's requests. If you specify too many processes for the Netscape Enterprise Server, your server's performance will not be optimized; rather, it will be decreased.

To change the number of server processes,

  1. Choose System Settings|Performance Tuning.
  2. Type the number of processes to be created when your server starts.
  3. Click OK.
  4. Click Save and Apply.

Setting the number of server threads

To change the minimum and maximum number of server threads,

  1. Choose System Settings|Performance Tuning.
  2. Type the number of minimum threads in the Minimum Threads field.
  3. Type the number of maximum threads in the Maximum Threads field.
  4. Click OK.
  5. Click Save and Apply.

Configuring listen-queue size

The listen-queue size is a socket-level parameter that specifies the number of incoming connections the system will accept for that socket. The default setting is 128 incoming connections.

Note
Normally, you should not change the listen-queue size. The default setting is sufficient in most cases.

If you manage a heavily used web site, you should make sure your system's listen-queue size is large enough to accommodate the listen-queue size setting from the Server Manager form. If you do change the listen-queue size, make sure that your system supports the new listen-queue size you've set. The listen-queue size set from the Server Manager form changes the listen-queue size requested by the server. If the server requests a listen-queue size larger than the system's maximum listen-queue size, the listen-queue size will default to the system's maximum.

Caution!
Setting the listen-queue size too high can be detrimental to server performance. The listen-queue size was designed to prevent the server from becoming overloaded with connections it cannot handle. If your server is overloaded and you increase the listen queue size further, the server will only fall farther behind.

Enabling Domain Name System lookups

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 will look 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 be expensive in terms of 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 host name for the IP address for every client making a request. This can impact performance.

Note
Be aware of the consequences of turning off DNS on your server; host name restrictions won't work, and hostnames won't appear in your log files. Instead, you'll see IP addresses.

You can also specify whether to cache the DNS entries. When the server gets a client's host name information, it can store the data, if you've enabled the DNS cache. Then if the server needs information about the client in the future, the information is cached and available for the server without querying for the information again. You can specify the size of the DNS cache and the time it takes before a cache entry becomes invalid. The DNS cache can contain 32 to 32768 entries; the default value is 1024 entries. Values for the time it takes for a cache entry to expire can range from 1 second to 1 year (specified in seconds); the default value is 1200 seconds (20 minutes).

Configuring network settings

You can change your server's network settings using the Server Manager.

Changing the server's location

For various reasons, you might need to move the server from one directory to another. To do this, you change the location the server references--it needs to know where the binary files are. Then you shut down the server and copy the server files and subdirectories to a new location.

To change the server's location,

  1. Choose System Settings|Network Settings.
  2. Type the path name of the server's new location.
  3. Click OK.
  4. Click Save and Apply for your changes to take effect.

Changing the server's user account

Server User specifies a Unix user account that the server uses. All the server's processes run as this user.

You don't need to specify a Server User if you chose a port number greater than 1024 and aren't running as the root user (in this case, you don't need to be logged as root to start the server). If you don't specify a user account, the server runs with the user account you start it with, so make sure that when you start the server, you use the correct user account.

If you don't know how to create a new user on your system, ask your system administrator or consult your system documentation.
Even if you need to start the server as root, you don't want it to run as root all the time. You want it to have restricted access to your system resources and run as a nonprivileged user. The user name you enter as the Server User should already exist as a normal Unix 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,

  1. Choose System Settings|Network Preferences.
  2. Type the new server user account.
  3. Click OK.
  4. Click Save and Apply for your changes to take effect.

Changing the server name

The server name is the full host name 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 netscape.com, you could install a server with the name www.netscape.com.

If your system administrator has set up a DNS alias for your server, use that alias here. If not, use the machine's name combined with your domain name to construct the full host name.

Changing the server port number

Server Port Number specifies the TCP port 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 8080:

http://www.netscape.com:8080

If you aren't sure the port number you plan to use is available, look at the /etc/services file on the server machine. Port numbers for all network-accessible services are maintained in the file /etc/services on Unix machines.

The standard unsecure web server port number is 80; the standard secure web server port number is 443. Technically, the port number can be any port from 1 to 65535. If you aren't running as root or superuser when you install or start the server, you'll have to use a port number higher than 1024.

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.a.com/ and http://www.b.com/ from one machine.

Because of limitations in HTTP, this is difficult to configure. However, there is a trick to do this that involves making your machine answer to more than one IP address.

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 to tell the server which IP address it belongs to.

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 a directory behaves when it gets an error. Instead of sending back the default file, you might want to send a custom error response instead. For example, if a client tried repeatedly to connect to a part of your server protected by access control and failed, an error file could be returned with information on how to get an account.

What are the errors?

There are several different kinds of errors that you can customize the server's response to:

Setting up the response

Before you can set up the response, you need to write the HTML file to send or create the CGI program to run. After you do this, set the response by doing the following:

  1. In the Server Manager, choose System Settings|Error Responses.
  2. Choose the server resource you want to configure using the Resource Picker.
  3. Select the error response you want to customize.
  4. Type the absolute pathname to the file or CGI script you want to return for that error code. Check if the file is a CGI program that you want to run. Do this for each of the errors you want to customize.
  5. Click OK.
  6. Click Save and apply to confirm your changes.
To remove a customization, return to the form and delete the filename from the text box next to the error code.

Working with dynamic configuration files

Web server content is seldom managed entirely by one person. Many times, different parts of a web server are written by different people. For example, each employee can maintain a home page.

When these users need to configure something, it's unrealistic for you as the administrator to allow all of them access to the Server Manager. In these cases, it is useful to allow them a subset of configuration options so that they can control only what they need to. The subset of configuration options are stored in a dynamic configuration file called .nsconfig.

Normally, your server gets its configuration from two or three files that are kept in the server root and modified using the Server Manager.

With this feature, you can give users the ability to control more about their home pages in their public information directories. You can allow them 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 the following section.

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 provide a base directory to the server. The server will start its search for configuration files from the filesystem directory. Alternatively, you can provide no base directory, in which case the server will attempt to infer the base directory from the URL. That is, if the requested URL is going to be serviced with a file from the document root, it will start searching from the document root. The same applies to URL mappings, user public information directories, and CGI mappings.

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

Normally, you'll centralize all of your configuration information for the subdirectories of the base directory into the configuration file in the base directory. The server is more efficient because it doesn't waste time searching for configuration files in each of the subdirectories.

For convenience, you will sometimes want to tell the server to search the subdirectories (for example, if you selected the base directory inferred from URL translation, and selected .nsconfig for your configuration filename). When a user requests the filesystem path /usr/ns-home/docs/icons/logo.gif, instead of searching for /usr/ns-home/docs/.nsconfig you want the server to search all of the subdirectories:

/usr/ns-home/docs/.nsconfig
/usr/ns-home/docs/gfx/.nsconfig
/usr/ns-home/docs/gfx/icons/.nsconfig

Finally 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, use * (cgi|parsed-html).

To configure per-directory access,

  1. Choose System Settings|Dynamic Configuration Files.
  2. Select a resource from the Resource Picker.
  3. Choose whether to base the directory from the URL or from a specified directory.
  4. Type the file name
  5. Choose whether to search only the base directory.
  6. Type the disabled types.
  7. Click OK.

Writing a dynamic configuration file

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

<Files PATTERN1>
... directives ...
</Files>
<Files PATTERN2>
... directives ...
</Files>

PATTERN1 and PATTERN2 are wildcard patterns that tell the server which filesystem pathnames to apply the directives they surround to. Any pattern given is first prefixed with the directory containing the configuration file to ensure that it is only applied to subdirectories. There can be as many Files sets in the .nsconfig file as you need.

The file can contain blank lines. Lines beginning with # are treated as comments.

Each directive can take a variable number of parameters. The directives that can appear inside Files regions include:

Changing the root directory

You can use the server's chroot function to make the server think that the document root directory is the root directory (/).

Note
If you are inexperienced in Unix system administration, you might want to learn more about Unix before using this feature.

You should keep the server root outside the server chroot directory. You should have the server use the document root as the chroot directory and turn off the document root feature. Log and configuration files should be stored outside your chroot directory. You will not be able to soft restart a server using a chroot directory; the server process must be started as superuser. Any configuration items related to documents will have to be made relative to the new root directory.

You will not be able to use CGI programs or the exec tag to parse HTML if you use the chroot feature. You will also not be able to allow users to have public information directories unless the proper system-shared libraries, binaries, and dummy-parsed files are kept in the chroot directory.

To change the root directory,

  1. From the Server Manager, choose System Settings|UNIX Chroot.
  2. Enter the chroot directory.
  3. Click OK.
  4. Click Confirm in order for the change to take effect.

Restricting symbolic links

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 system documentation.

Because filesystem links are an easy way to create pointers to documents outside of the primary document directory and anyone can create these links, you might be concerned about what people might create pointers to (for example, confidential documents or system password files).

To restrict symbolic links,

  1. Choose System Settings|Symbolic Links.
  2. Choose the server resource.
  3. Choose whether to allow soft filesystem links.
  4. Choose whether to allow hard filesystem links.
  5. Enter the pathname the server should start looking for filesystem links. If you enter a full pathname, the server treats the path you give as a prefix. When it recognizes that prefix in a request, any directories following the prefix will be checked for filesystem links.

    If you enter a partial pathname, the server looks for the partial pathname you give as a substring of the incoming request. If you enter nolinks, the server looks for a directory called nolinks in the incoming request; if it finds it, it checks all following directories for filesystem links.

  6. Click OK.