Configuring server preferences


his chapter describes how to configure server preferences 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 and its green light (to the left of the server's name) in the Server Administration page. You can start and stop the server by clicking the icon. You can also start, restart, and stop the server from the Server Manager.

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

To start or stop the server from the Server Manager:

  1. Choose Server Preferences|On/Off.

  2. Click the On or Off button.

  3. If your server is on and you click Server On, the server will restart. If you've turned on or restarted your server, access it as a client by clicking "Access server_name as a client."
Note
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 you stop your server, the server 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. You probably do not need to change this value. If you do need to change the value, add a line in magnus.conf as follows:

 TerminateTimeout seconds

where seconds represents the number of seconds you want to wait before timing out.

The advantages to configuring this value is that if for some reason you want to wait longer for connections to complete, you can. However, because most servers often have connections open from nonresponsive clients, if you increase the time the server waits, you will almost always have to wait the full time before your server shuts down.

Restarting the server

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 file.
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 start an SSL-enabled server with either of these files because the server requires that you enter a password before starting. Though you can start an SSL-enabled server automatically if you keep the password in plain text in a file, this practice is not recommended.

Caution!
Leaving your SSL-enabled server's password in plain text in the server's start script on your system is a large security risk. 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 plain text on your system.
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.

If the security risk is 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_identifier.

  2. In the 10th line counting from the top of the script, insert the following:

  3. echo "your_SSL-enabled_server_password"|

    For example, the edited line might look like this:

    echo "MBi12!mo"|./$PRODUCT_BIN -d $PRODUCT_SUBDIR/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:server_root/type-identifier/start -i

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

You need to remove this line before you 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:
  server_root/type-identifier/start
Replace server_root 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 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

 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.

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

If you used the etc/inittab file to restart the server you need to 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

Viewing server settings

You can view your server's technical and content settings from the Server Manager. You can also see if your server is running. 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_name /config. For more information about the magnus.conf and obj.conf files, see The NSAPI Programmer's Guide on Netscape's DevEdge online documentation web site at
http://developer.netscape.com/library/documentation/.

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 (https-server_id.acl, magnus.conf, obj.conf, webpub.conf, agent.conf, mime.types, .acl files, rdm.conf, csid.conf, process.conf, robot.conf, and filter.conf).

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

  1. From the Server Manager, choose Server Preferences|Restore Configuration.

  2. Set the number of backups. The number you type here is the number of backups displayed on the form. Enter the number and click Change to change the number.

  3. 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. To restore all files to their state at a particular time, click the Restore to time button, which lists the specific time to which you want to restore.

Tuning server performance

You can configure the server's technical options, including the number of maximum simultaneous requests, listen-queue size, and DNS usage.

 

Configuring maximum simultaneous requests

You can set the number of maximum simultaneous requests, which is the number of active requests allowed for the server at one time. However, for general purpose Internet or intranet use, you probably will not need to change the default value (128 requests).

To get the number of simultaneous requests, the server counts the number of active requests, adding 1 to the number when a new request arrives, subtracting 1 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. 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.

 If you need to change the number of maximum simultaneous requests, set the number before starting the server. To reset the number:

  1. Choose Server Preferences|Performance Tuning.

  2. Type the number of requests.

  3. Click OK.

  4. Click Save and Apply.

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 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
Turning off DNS lookups on your server has the following consequences: 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. 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).

 

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 size. 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 size defaults to the system's maximum.
Setting the listen-queue size too high can degrade 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, the server will only fall further behind.

Configuring the HTTP persistent connection timeout

With HTTP 1.1, a connection can be set to be persistent (similar to keep alive in HTTP 1.0). However, even if a connection is persistent, it still needs to have a timeout setting, or it may consume system resources.

Note
Normally, you should not change the persistent connection timeout. The default setting is sufficient in most cases.
If you need to change the setting:
  1. From the Server Manager, choose Server Preferences|Performance Tuning.

  2. Enter a number in seconds in the HTTP Persistent Connection Timeout field.

  3. Click OK.

  4. Save and apply your changes.

Configuring MIME types

MIME (Multi-purpose Internet Mail Extension) types control what types of multimedia files your mail system supports. You can also use MIME types to specify what file extensions belong to certain server file types, for example to designate what files are CGI programs. For more information on using file extensions with programs, see "Installing CGI programs" on page 145.

 To add a new MIME type:

  1. Choose Server Preferences|Mime Types.

  2. Select the category and enter the content type and file suffix.

  3. Click New Type.
To edit a MIME type:
  1. Click Edit next to the type you want to edit.

  2. Change the category, content type, and file suffix as needed.

  3. Click Change MIME Type to update.
To remove a MIME type, click Remove next to the type you want to remove.
 
Note
Do not put spaces between the file suffixes when you are adding or editing a MIME type. If you put a space between them, you may receive an error or your server may not restart. If this happens, edit your mime.types file to delete the space. The mime.types file is in your server root in the https-identifier/config directory. After you have edited the file, from the Server Manager, use the Apply button to apply your manual changes.

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. If you move the server, you need to change the location the server references--it needs to know where the binary files are. After changing the location, you need to shut down the server and copy the server files and subdirectories to a new location.

To change the server's location:

  1. Choose Server Preferences|Network Settings.

  2. Type the pathname 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

The 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 on as root to start the server). If you don't 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.
 

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 the root user, you don't want it to run as root all the time. You want the server 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 Server Preferences|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 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 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 on the Network Preferences form. If not, use the machine's name combined with your domain name to construct the full hostname.

 

Changing the server port number

On the Network Preferences form. 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:

 http://www.netscape.com:8090

If you aren't sure that the port number you plan to use is available, look at the /etc/services file on the server machine. Port numbers for the most commonly used network-accessible services are maintained in the file /etc/services.
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 the root user when you install or start the server, you need 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.netscape.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, on the Network Preferences form use the Bind To Address field to tell the server which IP address is associated with this hostname.

Changing the server's MTA host

To change the MTA (Message Transfer Agent) host, use the MTA Host field on the Network Preferences form to change the name of the SMTP mail server. You must enter a valid MTA host if you want to use the agent email function.

Changing the server's NNTP host

To change the NNTP (Network News Transfer Protocol) host, use the NNTP Host field to change the name of the news server. You must enter a valid NNTP host if you want to use agents with the capability to post to news.

 

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

What are the errors?

You can customize the response to several different kinds of errors:

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. From the Server Manager, choose Server Preferences|Error Responses.

  2. From the Resource Picker, choose the server resource you want to configure.

  3. Select the error response you want to customize.

  4. Type the absolute pathname to the file or CGI script that you want to return for that error code. Check the CGI box if the file is a CGI program that you want to run.

  5. Repeat this process for each of the error responses you want to customize.
  6. Click OK.

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

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 Server Manager. The subset of configuration options are stored in dynamic configuration files. Two types of dynamic configuration files are supported by the Netscape Enterprise Server: .htaccess and .nsconfig. You can enable .nsconfig files in the Server Manager; 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 Netscape Servers.
If you already use .nsconfig files, you might want to continue using them. However, Netscape also provides a utility for converting your .nsconfig files to .htaccess files.

 

Using .htaccess files

The files that support .htaccess are in the server root, in 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:

Init fn="load-modules" funcs="htaccess-init,htaccess-find" \

shlib="server_root/plugins/htaccess/htaccess.so"

Init fn="htaccess-init"
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:

 PathCheck fn="htaccess-find"
to the default server object, which is delimited by:
 <Object name="default">

...

</Object>
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 need to specify the filename in the PathCheck directive using the following format:

 PathCheck fn="htaccess-find" filename="filename"
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 Server Manager 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" on page 68, and Chapter 6, "Controlling access to your server."

 

Converting existing .nsconfig files to .htaccess files

The Netscape Enterprise 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):

server_root/install/perl server_root/plugins/htaccess/htconvert server_root/
https-server_name/config/obj.conf
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:

 

The only AuthType supported is Basic.

 

Example of an .htaccess file

The following example shows an .htaccess file:
 <Limit GET POST>

order deny,allow

deny from all

allow from all

</Limit>

<Limit PUT DELETE>

order deny,allow

deny from all

</Limit>

AuthName mxyzptlk.kawaii.com

AuthUserFile /server_root/mxyz-docs/service.pwd

AuthGroupFile /server_root/mxyz-docs/service.grp

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" on page 91.

 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 /usr/netscape/suitespot/docs/gfx/icons/logo.gif, instead of searching for /usr/netscape/suitespot/docs/.nsconfig the server would search all of the subdirectories:

 /usr/netscape/suitespot/docs/.nsconfig
/usr/netscape/suitespot/docs/gfx/.nsconfig
/usr/netscape/suitespot/docs/gfx/icons/.nsconfig

 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:

  1. Choose Server Preferences|Dynamic Configuration Files.

  2. Choose a resource from the Resource Picker.

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

  4. Type the filename.

  5. Choose whether to search only the base directory.

  6. Type the disabled types.

  7. Click OK.

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

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

 Each directive can take a variable number of parameters. 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>

Changing the root directory

You can use the server's chroot function to make the server use the document root directory as 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. The server process must be started as root (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 can't 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 Server Preferences|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 Unix 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:

  1. Choose Server Preferences|Symbolic Links.

  2. Choose the server resource.

  3. Choose whether to allow soft filesystem links.

  4. Choose whether to allow hard filesystem links.

  5. Type the pathname where the server should start looking for filesystem links.

  6. If you enter a full pathname, the server treats the path you give as a prefix. When it recognizes that prefix in a request, the server checks any directories following the prefix for filesystem links.

    If you type 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 that directory, it checks all following directories for filesystem links.

  7. Click OK.


Copyright 1997 Netscape Communications Corporation. All rights reserved.