Netscape Compass Server Administrator's Guide

[Contents] [Previous] [Next] [Index]

Chapter 2
Configuring Server Preferences

This chapter describes how to configure server preferences for your Netscape Compass Server by using the Server Manager configuration forms.

The specific tasks described are

Getting Started Quickly

 When you first start running your Netscape Compass Server, you will probably find it handy to consult a list of the most common configuration tasks.

The Quick Start Tasks form shows the most common administrative tasks, grouped by subject matter.

To use the list of common tasks, do the following:

  1. Access the Server Manager for the Compass Server.

  2. Choose Server Preferences|Quick Start Tasks to open the Quick Start Tasks form.
    The form shows a list of the most common tasks you might want to perform on a newly installed Compass Server. The green bars highlight the major tasks, creating sections. Each section has a description of the task, along with a list of specific tasks to perform.

  3. Click each of the specific tasks in the order given to complete the task.

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 (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 (or the Windows NT Control Panel) or from the command line.

To start or stop the server from the Server Manager:

  1. Choose Server Preferences|On/Off.

  2. Click the On or Off button.
    If your server is on and you click Server On, the server will restart.
NOTE: Sometimes the status indicated on the Server Administration form does not update correctly. You can correct this by reloading the page.
If your machine crashes or is taken offline, the server stops and any requests it was servicing may be lost.

Unix Stopping shuts down the server completely, interrupting service until it is restarted. If you started the server with the inittab file (as described in Restarting with inittab), you need to remove the line pertaining to the server in inittab before shutting down the server; otherwise, the server automatically restarts.

Restarting the Server

Restarting the server is somewhat different depending on your operating system.

Restarting the Server for Unix

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

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.

WARNING: 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 ServerRoot/catalog-server_identifier.
    The start file contains three lines (the second line is blank): 
    #!/bin/sh

    cd     ServerRoot; ./ns-httpd -d ServerRoot/catalog-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/Netscape/SuiteSpot/bin/https; echo "MBi12!mo"|./ns-httpd -d ServerRoot/compass-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/compass-identifier/start -i

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

ServerRoot/compass-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 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:

ServerRoot/type-identifier/start

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

Performing a 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
The restart command 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 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:

ServerRoot/compass-identifier/stop

Restarting the Server for Windows NT

 If you are using Windows NT, you can restart the server using one of the following methods:

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.
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 a text 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 plain text on your system.
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, such as Notepad, create a new text file called password.txt in ServerRoot\catalog-identifier\config. For a default web server installation using Windows NT, password.txt would be stored in the C:\Netscape\Server\catalog-server_id\config directory.

  2. Type your private-key password in the first line, making sure not to put carriage returns or linefeeds after the password. The file must contain only the password.
    When you start your SSL-enabled server, it first tries to read the password in password.txt. If the file does not exist, you will be prompted for the password. If password.txt exists but the password is incorrect, the server will add an entry to the error log and exit.
WARNING: If you have an NTFS file system, you should protect the directory that contains password.txt 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.txt file.
On FAT file systems, you cannot protect directories or files by restricting access to them.
Using the Automatic Restart Utility
 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 (WAI or 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.

To change the time interval that elapses before the server is automatically restarted, do the following:

  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 Edit|Add Value.
    The Add Key dialog box appears.

  4. In the Value Name box, 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 before the server restarts automatically.
    The interval can be in binary, decimal, or hexadecimal format.

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

  9. Click OK.
    The MortalityTimeSecs value appears in hexadecimal format at the right side of the Registry Editor window.
Turning Off the Debugging Dialog Box
 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:

  1. Start the Registry Editor.

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

  3. Double-click the Auto value in the right side of the window.
    The String Editor dialog box appears.

  4. Change the string value to 1.

Starts and Stops at the Command Line

 You can start or stop your Compass Server from the command line of your operating system.

Unix Command Lines

For Unix systems, the Compass Server provides scripts to start or stop the server.

To start or stop the Compass Server at the command line, do the following:

  1. Go to the directory for the Compass Server under the server root directory.
    The default installation uses /usr/Netscape/SuiteSpot for the server root. The Compass Server directory is called compass-identifier.

  2. Type ./start or ./stop to start or stop the server, respectively.
For example, to stop a Compass Server called test in the default directory, you would type as follows:

cd /usr/Netscape/SuiteSpot/compass-test
./stop

Windows NT Command Lines

 For Windows NT systems, you use the net utility to start or stop the server at the command line, as follows:

  1. Go to the console window.

  2. Type net start compass-identifier or net stop compass-identifier to start or stop the server, respectively.
For example, to stop a Compass Server called test, you would type the following:

net stop compass-test

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 directory admin-serv/catalog-server_name in your server root directory. For more information about the magnus.conf and obj.conf files, see Netscape's DevEdge online documentation web site at 

http://developer.netscape.com/docs/manuals/index.html
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.

Customizing Compass Server Settings

There are a number of settings that apply specifically to the operation of the Compass Server that you can set through the Server Manager.

There are four different groups of settings on the form.

Database Options

These settings control how much information the Compass Server robot generates, and how often it updates the database while it is indexing.

Setting Meaning
Max Categories

 This is the maximum number of categories the robot can assign a given document to. After it makes this many assignments, the robot will stop processing classification rules for that document.

The default value of 3 is probably sufficient for most cases.

DB Batch Size

 This value indicates how often an import agent submits the resource descriptions it has imported to the database. Import agents hold the newly imported resource descriptions in a temporary database for batch addition to the main database. This is much more efficient than adding each item as it is imported.

You can change the default number, 1024, to force import agents to add their resource descriptions to the database more often or less often.

Directory Locations

You can specify the locations of several kinds of files used by the Compass Server, as described in the following table.

Setting Meaning
Temporary Files

 This is a directory where the server and the robot can store temporary files, including newly generated resource descriptions that have not yet been added to the main database.

Templates

 This specifies the location of user interface templates. by default, it points to ServerRoot/compass-server_id/templates.

Database

 This is the directory that contains the Compass Server's database of resource descriptions.

Transaction Logs

 This subdirectory must be under the Compass Server's directory in the server root. By default, since it covers database transactions, it is the same directory as the database itself.

Logfile Locations

You can specify pathnames for most of the log files generated by the Compass Server and its robot.

Setting Meaning
Search (rdm)

 This log file records which queries end users and the My Compass profiler make of the database. You can check the Disable Search Log box to suppress this logging.

If you do not generate this log file, you will not be able to use the Popular Searches report.

Verity

 This file logs the transactions involving the Verity search engine, not including the registration of resource descriptions.

RD Manager

 This log file records the registration of resource descriptions from the robot or an import agent into the database.

RDM Debug

 This file logs debugging information on RDM transactions. The level of detail is controlled by the setting that follows.

RDM Debug Level

 This setting controls how much detail the RDM Debug logfile contains. The default setting of 1 generates very limited messages, covering only severe errors. Higher numbers indicate more detail. 0 indicates no logging.

Administration Preferences

You have a certain amount of control over the appearance and behavior of the Server Manager itself, using the settings described in the following table.

Setting Meaning
Backup System

 These options control the way the Server Manager handles backups of changes to configuration files.

Manual Save and Apply requires the administrator to click a Save and Apply button for each change. Automatic Save and Apply will automatically apply new changes and back up the old settings, with or without a pop-up notification that it is doing so. The default is to back up automatically with a notification.

Smart Site Definitions

 There are two options you can choose that enable "smart" options during the creation and editing of site definitions. The first checks DNS aliases when you enter site names to ensure that the robot knows how to handle them properly. The second actively checks sites you enter to detect whether the specified site redirects access to another site.

Using these options can help prevent DNS problems when you first index new sites.

Robot Overview

 This option allows you to specify how often the Robot Overview form updates its statistics. The default value is every 30 seconds. You can change this interval from 10 seconds up to 5 minutes. Keep in mind that updating the form requires a small amount of overhead, so updating more frequently might cut into the productivity of the robot.

Admin Screen Layout

 You can customize the order in which items appear in the Server Manager screens. There are two options here, one optimized for deployment, for when you are setting up or extensively modifying a server, and production, which emphasizes the daily tasks you'll perform.

Restoring Backup Configuration Files

You can view or restore a backup copy of your configuration files (compass-server_id.ad, magnus.conf, obj.conf, webpub.conf, mime.types, .acl files, rdm.conf, csid.conf, process.conf, gv.conf, import.conf, site.conf, filterrules.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. 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 and DNS usage.

Configuring Maximum Simultaneous Requests

You can set the number of maximum simultaneous requests, though Netscape recommends leaving it at the default 128 requests.

However, should 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 hostname 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: hostname 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 the HTTP Persistent Connection Timeout

With HTTP 1.1, a page can be set to be persistent (similar to keep alive in HTTP 1.0). However, even if a page 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.

  3. Click OK.

  4. Save and apply your changes.

Configuring Network Settings

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

Specifically, these tasks include the following:

Changing the Server's User Account

 User accounts have different implications, depending on your operating system. The following sections explain some of the issues.

NOTE: All Compass Servers installed in the same server root must use the same user account. This account controls file access permissions. If you attempt to run different server users on the same system, only one will operate properly.

Unix Issues

 The server user field 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.

Windows NT Issues

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. The account must have the privilege to run as a service, however.

Changing the User Account

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 DNS 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 domain is netscape.com, you might install a server named 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 hostname.

Changing the Server Port Number

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

Port numbers for the most commonly used network-accessible services are maintained in a file called services. If you aren't sure that the port number you plan to use is available, look at the services file on the server machine. The following table shows the location of the services file.

Table 2.1 Path names for services file
Operating system Location of services file
Unix

 /etc/services

Windows NT

 \WINNT\System32\drivers\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 use the standard port number for a protocol, users do not have to specify the port number explicitly.

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

Because of limitations in HTTP, this is difficult to configure. However, there is a 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 is associated with this hostname.

Changing the Server's MTA Host

The Compass Server uses a mail server (sometimes called an MTA, for Message Transfer Agent, host, or SMTP server) to send email messages to users of the My Compass newsletter feature. You can specify the mail server to use as part of the initial installation and configuration, but you can also change it later.

To change the mail server used, use the MTA Host field on the Network Preferences form to specify the name of the new mail server. You must enter the name of a valid SMTP server if you want to use the My Compass newsletter function.

NOTE: The default is localhost, but the default may or may not work on your system.

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. Select the error response you want to customize.

  2. 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.
    Repeat this process for each of the error responses you want to customize.

  3. Click OK.
To remove a customization, return to the form and delete the filename from the text box next to the error code.

Scheduling Tasks

Compass Servers have a number of tasks you can automate by scheduling them to occur periodically. Having regular tasks run automatically is generally more reliable than running them manually.

Tasks you can schedule include the following:

You can automate these tasks by activating a schedule. You can also deactivate the schedule to prevent automatic starting.

Activating a Schedule

To activate a schedule, do the following:

  1. Specify the time you want to start the task.
    Choose the hour and minutes for the starting time using the lists provided.

  2. Check the days to start the task on.
    Check only the days the task should run on. All other days are unchecked.

  3. Click Activate.

  4. Click OK.

  5. (Unix systems only) Restart the cron daemon.

Deactivating a Schedule

 To deactivate the current schedule, do the following:

  1. Click Deactivate.
    You don't need to change the time and date settings.

  2. Click OK.

  3. (Unix systems only) Restart the cron daemon.

[Contents] [Previous] [Next] [Index]

Last Updated: 02/12/98 13:33:17

Copyright © 1997 Netscape Communications Corporation

Any sample code included above is provided for your use on an "AS IS" basis, under the Netscape License Agreement - Terms of Use