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

The specific tasks described are

• Getting Started Quickly


• Starting and Stopping the Server


• Viewing Server Settings


• Customizing Compass Server Settings


• Restoring Backup Configuration Files


• Tuning Server Performance


• Configuring Network Settings


• Customizing Error Responses


• Scheduling Tasks

When you first start running your iPlanet 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.

Once installed, the server runs constantly, listening for and accepting requests. 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 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:

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.

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

• Automatically restart it from the inittab file.


• Automatically restart it with daemons in /etc/rc.local when the machine reboots.


• Restart it manually.

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.

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/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/serverhome/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/https-identifier/start -i

Replace ServerRoot with the directory where you installed the server, and replace https-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/https-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/https-identifier/stop

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/serverhome for the server root. The Compass Server directory is called https-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/serverhome/https-test
./stop

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 https-server_name in your server root directory. For more information about the magnus.conf and obj.conf files, see iPlanet's Developers online documentation web site at

http://developer.iplanet.com/

The following list explains the server's technical settings:

• Server Root is the directory where the server binaries are kept. You first specified this directory during installation.


• Hostname is the URL clients use to access your server.


• Port is the port on your system that the server listens to for HTTP requests.


• Error log is the name and path of the server's error log file.


• User is the user the server runs as.


• MTA host is the name of the SMTP mail server.


• DNS shows whether reverse DNS lookup is enabled or disabled.

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.

There are a number of settings that apply specifically to the operation of the Compass Server that you can set through the Server Manager. These settings are presented on the Compass Settings panel of the Preferences tab.

There are four different groups of settings on the form.

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

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

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

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.

You can view or restore a backup copy of your configuration files (https-server_id/, magnus.conf, obj.conf, webpub.conf, mime.types, .acl files, rdm.conf, csid.conf, process.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.

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

You can set the number of maximum simultaneous requests, though iPlanet 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.

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 informaiton 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 512 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 Listen Queue Size

Listen queue size is a socket-level parameter that specifies the number of incoming connections the system will accept for that socket.

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.

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.

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

Specifically, these tasks include the following:

• Changing the Server's User Account


• Changing the Server Name


• Changing the Server Port Number


• Changing the Server Binding Address


• Changing the Server's MTA Host

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

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.

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.

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 iplanet.com, you might install a server named www.iplanet.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.

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

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.

NOTE:

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.

At times you might want the server machine to answer to two URLs. For example, you might want to answer both http://www.iplanet.com/ and http://www.javasoft.com/ from one machine.

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

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.

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

• Unauthorized. This error occurs when users without access permissions try to access a document on the server that is protected by access control. You might send information on how they can get access.


• Forbidden. This error occurs when the server doesn't have file system permissions to read something, or if the server is not permitted to follow symbolic links.


• Not Found. This error occurs when the server can't find a document or when it has been instructed to deny the existence of a document.


• Server Error. This error occurs when the server is not configured properly or when a catastrophic error occurs, such as the system running out of memory or producing a core dump.

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.

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:

• Starting the Robot


• Stopping the Robot


• Running Import Agents

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

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. Restart the cron daemon.

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. Restart the cron daemon.