| Previous Contents Index Next |
| iPlanet Web Server: FastTrack Edition Administrator's Guide |
Chapter 6 Configuring Server Preferences
This chapter describes how to configure server preferences for your iPlanet Web Server.This chapter contains the following sections:
Starting and Stopping the Server
Working with Dynamic Configuration Files
Starting and Stopping the Server
Once the server is installed, it runs constantly, listening for and accepting HTTP requests. The status of the server appears in the Server On/Off page. You can start and stop the server using one of the following methods:
Click the Server On or Server Off in The Server On/Off Page.
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."Use the Services window in the Control Panel (Windows NT).
Use start. If you want to use this script with init, you must include the start command http:2:respawn:server_root/type-identifier/start -start -i in /etc/inittab. (Unix/Linux)
Use stop, which shuts down the server completely, interrupting service until it is restarted. If you set the etc/inittab file to automatically restart (using "respawn"), you must remove the line pertaining to the web server in etc/inittab before shutting down the server; otherwise, the server automatically restarts. (Unix/Linux)
If your machine crashes or is taken offline, the server stops and any requests it was servicing may be lost.
Setting the Termination Timeout
When the server is off, it stops accepting new connections. Then it waits for all outstanding connections to complete. The time the server waits before timing out is configurable in the magnus.conf file. By default it is set to 3 seconds. To change the value, add the following line to magnus.conf:
where seconds represents the number of seconds the server will wait before timing out.
- TerminateTimeout seconds
The advantages to configuring this value is that the server will wait longer for connections to complete. However, because servers often have connections open from nonresponsive clients, increasing the termination timeout may increase the time it takes for the server to shut down.
Restarting the Server (Unix/Linux)
You can restart the server using one of the following methods:
Automatically restart it from the inittab file.
Because the installation scripts cannot edit the /etc/rc.local or /etc/inittab files, you must edit those files with a text editor. If you do not know how to edit these files, consult your system administrator or system documentation.
Automatically restart it with daemons in /etc/rc2.d when the machine reboots.
- Note that if you are using a version of Unix/Linux not derived from System V (such as SunOS 4.1.3), you will not be able to use the inittab file.
Normally, you cannot start an SSL-enabled server with either of these files because the server requires a password before starting. Although you can start an SSL-enabled server automatically if you keep the password in plain text in a file, this is not recommended.
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 security risks are not a concern for you, follow these steps to start your SSL-enabled server automatically:
Using a text editor, open the start file, which is located in server_root/http-server-id.
In the 10th line counting from the top of the script, insert the following:
- 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 (Unix/Linux)
To restart the server using inittab, put the following text on one line in the
/etc/inittab file:
Replace server_root with the directory where you installed the server, and replace type-identifier with the server's directory.
- http:2:respawn:server_root/type-identifier/start -start -i
The -i option prevents the server from putting itself in a background process.
You must remove this line before you stop the server.
Restarting With the System RC Scripts (Unix/Linux)
If you use /etc/rc.local, or your system's equivalent, place the following line in /etc/rc.local:
Replace server_root with the directory where you installed the server.
- server_root/type-identifier/start
Restarting the Server Manually (Unix/Linux)
To restart the server from the command line, log in as root if the server runs on ports with numbers lower than 1024; otherwise, log in as root or with the server's user account. At the command-line prompt, type the following line and press Enter:
Replace server_root with the directory where you installed the server.
- server_root/type-identifier/start
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.
Stopping the Server Manually (Unix/Linux)
If you used the etc/inittab file to restart the server you must remove the line starting the server from /etc/inittab and type kill -1 1 before you try to stop the server. Otherwise, the server restarts automatically after it is stopped.To stop the server manually, log in as root or use the server's user account (if that is how you started the server), and then type the following at the command line:
- server_root/type-identifier/stop
Restarting the Server (Windows NT)
You can restart the server by:
Using the Services Control Panel to restart any server.
For Windows NT 3.51, perform the following steps:Using the Services Control Panel to configure the operating system to restart the server or the administration server each time the machine is restarted.
In the Main group, double-click the Control Panel icon.
For Windows NT 4.0, perform the following steps:Double-click the Services icon.
Scroll through the list of services and select the service for your server.
Check Automatic to have your computer start the server each time the computer starts or reboots.
From the Start menu, choose Settings, and then Control Panel.
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.Double-click the Services icon.
Scroll through the list of services and select the service for your server.
Check Automatic to have your computer start the server each time the computer starts or reboots.
Note You can also use the Services dialog box to change the account the server uses. For more information about changing the account the server uses, see Changing the Server's User Account (Windows NT).
If the security risk is not a concern for you, follow these steps to start your SSL- enabled server automatically:
Using a text editor, such as Notepad, create a new text file called password.txt in server_root\https-server_id\config. For a default web server installation, password.txt would be stored in the C:\Netscape\server4\https-server_id\config directory.
On FAT file systems, you cannot protect directories or files by restricting access to them.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.
Using the Automatic Restart Utility (Windows NT)
The server is automatically restarted by a server-monitoring utility if the server crashes. On systems that have debugging tools installed, a dialog box with debugging information appears if the server crashes. To help debug server plug-in API programs (for example, NSAPI programs), you can disable the auto-start feature by setting a very high timeout value. You can also turn off the debugging dialog boxes by using the Registry Editor.
Changing the Time Interval (Windows NT)
To change the time interval that elapses between startup and the time the server can automatically restart, perform the following steps:
Start the Registry Editor.
Select your server's key (in the left side of the Registry Editor window, located in HKEY_LOCAL_MACHINE\SOFTWARE\Netscape\).
Choose Add Value from the Edit menu. The Add Key dialog box appears.
In Value Name, type MortalityTimeSecs.
Select REG_DWORD from the Data Type pull-down list.
Click OK. The DWORD Editor dialog box appears.
Type the time interval (in seconds) that will elapse between startup and the time the server can restart automatically.
Click the numerical format for the value you entered in the previous step (binary, decimal, or hexadecimal).
- The interval can be in binary, decimal, or hexadecimal format.
- The MortalityTimeSecs value appears in hexadecimal format at the right side of the Registry Editor window.
Turning Off the Debugging Dialog Box (Windows NT)
If you've installed an application (such as a compiler) that has modified the system debugging settings and the server crashes, you might see a system-generated application error dialog box. The server will not restart until you click OK.To turn off the debugging dialog box that appears if the server crashes, perform the following steps:
Start the Registry Editor.
Select the AeDebug key, located in the left side of the Registry window in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion.
Double-click the Auto value in the right side of the window.
Change the string value to 1.
- The String Editor dialog box appears.
Viewing Server Settings
You can see if your server is running and view your server's technical and content settings. The technical settings come from magnus.conf, and the content settings come from obj.conf. These files are located in the server root, in the directory https-server_id \config. For more information about the magnus.conf and obj.conf files, see the NSAPI Programmer's Guide for iPlanet Web Server.To view your server settings, see The View Server Settings Page in the Server Manager.
The content settings displayed in the View Server Settings page depend on how you've configured your server. Common server content settings include the server's document directory, its index filenames, name and location of its access log, and default MIME type.
Adding and Using Thread Pools
Use thread pools to allocate a certain number of threads to a specific service. For example, you can set up a thread pool specifically for Server-Side JavaScript applications. As part of adding the Server-Side JavaScript thread pool, you specify the maximum number of threads you want to allocate to Server-Side JavaScript applications, and they cannot take up more than their allocated number of threads.Another use for thread pools is for running thread-unsafe plugins. By defining a pool with the maximum number of threads set to 1, only one request is allowed into the specified service function.
When you add a thread pool, the information you specify includes the minimum and maximum number of threads, the stack size, and the queue size.
The Native Thread Pool and Generic Thread Pools (Windows NT)
On Windows NT, you can use two types of thread pools: the native thread pool (NativePool) and additional generic thread pools.The native thread pool is defined by default for backwards compatibility with Netscape Enterprise Server 3.6. To edit the native thread pool, see The Native Thread Pool Page (NT) in the Server Manager.
You can create as many generic thread pools as you want, for as many purposes as you want. To create generic thread pools, see The Generic Thread Pools Page (NT) in the Server Manager.
Thread Pools (Unix/Linux)
Since threads on Unix/Linux are always OS-scheduled (as opposed to user-scheduled) Unix/Linux users do not need to use the NativePool, and do not have a Server Manager page for editing its settings. However, Unix/Linux users can still create thread pools. To create thread pools, see The Thread Pools Page (Unix/Linux) in the Server Manager.
Editing Thread Pools
Once you have added a thread pool, you cannot change the values of the thread pool settings (minimum threads, maximum threads and so on) through the Server Manager. Instead you must edit the thread pool settings in obj.conf.A thread pool appears in obj.conf as follows:
Use the following parameters to change the pool: MinThreads, MaxThreads, QueueSize, and StackSize.
- Init fn="thread-pool-init" name=name_of_the_pool MaxThreads=n MinThreads=n QueueSize=n StackSize=n
Windows NT users can always edit the settings for the native pool using the Server Manager.
Using Thread Pools
After you've set up a thread pool, use it by designating it as the thread pool for a specific service.To configure a thread pool, go to the Administration Server Preferences tab and select Thread Pool.
You can also designate a thread pool by using the pool parameter of the load-modules function in obj.conf.
In addition, you can use the pool parameter on any NSAPI function so that only that NSAPI function runs on the pool you specify.
- pool="name_of_pool"
Configuring Network Settings
You can change the following network settings on your server: server user, server name, server port, bind to address, and MTA host.
Changing the Server's Location (Unix/Linux)
For various reasons, you might move the server from one directory to another. If you move the server, you must change the location the server references—it needs to know where the binary files are. After changing the location, you must shut down the server and copy the server files and subdirectories to a new location.To change the server's location edit the Server Location field in The Network Settings Page in the Administration Server.
Changing the Server's User Account (Unix/Linux)
The server user specifies a Unix/Linux user account that the server uses. All the server's processes run as this user.You do not need to specify a server user if you chose a port number greater than 1024 and are not running as the root user (in this case, you do not need to be logged on as root to start the server). If you do not specify a user account here, the server runs with the user account you start it with. Make sure that when you start the server, you use the correct user account.
Note If you do not know how to create a new user on your system, contact your system administrator or consult your system documentation.
Even if you start the server as root, you should not run the server as root all the time. You want the server to have restricted access to your system resources and run as a non-privileged user. The user name you enter as the server user should already exist as a normal Unix/Linux user account. After the server starts, it runs as this user.
If you want to avoid creating a new user account, you can choose the user nobody or an account used by another HTTP server running on the same host. On some systems, however, the user nobody can own files but not run programs.
To change the server's user account, edit the Server User field in The Network Settings Page in the Administration Server.
Changing the Server's User Account (Windows NT)
By using a specific user account (other than LocalSystem), you can restrict or enable system features for the server. For example, you can use a user account that can mount files from another machine.To change the web server user account after installation, perform the following steps:
Create a user with the Windows NT Users Manager. The user must have "Log in as a service" rights.
From the Windows Control Panel, choose Services.
Select the iPlanet Web Server service.
In the Service pop-up, in the Log on As section, click the This Account radio button.
Type the user account you want the web server to use.
Type the password for that account; type it again for confirmation.
Restart the server using the Services program or the Server Administration page.
Changing the Server Name
The server name is the full hostname of your server machine. When clients access your server, they use this name. The format for the server name is machinename.yourdomain.domain. For example, if your full domain name is iplanet.com, you could install a server with the name www.iplanet.com.If your system administrator has set up a DNS alias for your server, use that alias on The Network Settings Page in the Administration Server. If you do not have a DNS alias for your server, use the machine's name combined with your domain name to construct the full hostname.
To change the server name, edit the Server Name field in The Network Settings Page in the Administration Server.
Changing the Server Port Number
The Server Port Number specifies the TCP port that the server listens to. The port number you choose can affect your users—if you use a nonstandard port, then anyone accessing your server must specify a server name and port number in the URL. For example, if you use port 8090, the user would specify something like this URL:
Port numbers for the most commonly used network-accessible services are maintained in the file /etc/services (on Unix/Linux) or \WINNT\System32\drivers\etc\services (on Windows NT).
- http://www.iplanet.com:8090
Although the port number can be any port from 1 to 65535, the standard insecure web server port number is 80, and the standard secure web server port number is 443.
For Unix/Linux, if you are not running as the root user when you install or start the server, you must use a port number higher than 1024.
To change the server port number, edit the Server Port field in The Network Settings Page in the Administration Server.
Changing the Server Binding Address
At times you'll want the server machine to answer to two URLs. For example, you might want to answer both http://www.iplanet.com/ and
http://www.mozilla.com/ from one machine.If you have already set up your system to listen to multiple IP addresses and want to use this feature, use the Bind To Address field in the Network Settings window to tell the server which IP address is associated with this hostname.
To change the server binding address, edit the Bind To Address field in The Network Settings Page in the Administration Server.
Changing the Server's MTA Host
You can change the server's MTA (Message Transfer Agent) host. You must enter a valid MTA host if you want to use the agent email function.To change the MTA Host, edit the MTA host field in The Network Settings Page in the Administration Server.
Customizing Error Responses
You can specify a custom error response that sends a detailed message to clients when they encounter errors from your server. You can specify a file to send or a CGI program to run.You might want to change the way the server behaves when it gets an error for a specific directory. Instead of sending back the default file, you might want to send a custom error response instead. For example, if a client tries repeatedly to connect to a part of your server protected by access control, you might return an error file with information on how to get an account.
Before you can enable a custom error response, you must create the HTML file to send or the CGI program to run in response to an error. After you do this, enable the response in The Network Settings Page in the Administration Server.
Working with Dynamic Configuration Files
Server content is seldom managed entirely by one person. You may need to allow end users to access a subset of configuration options so that they can configure what they need to, without giving them access to the iPlanet Web Server. The subset of configuration options are stored in dynamic configuration files. Two types of dynamic configuration files are supported by iPlanet Web Server: .htaccess and .nsconfig. You can enable .nsconfig files in iPlanet Web Server; you have to manually enable .htaccess files.
Note There is no support for LDAP or the 3.0 Netscape user databases in the dynamic configuration files. You should not use dynamic configuration files if you use LDAP. You must use NCSA-style user databases to use .htaccess files. You must use either NCSA-style user databases or Enterprise 2.x DBM- format user databases with .nsconfig files. For more information on user databases, see Managing Servers with Netscape Console.
If you already use .nsconfig files, you might want to continue using them. However, iPlanet Web Server also includes a utility for converting your .nsconfig files to .htaccess files.
Using .htaccess Files
The files that support .htaccess are in the directory
server_root/plugins/htaccess. These files include a plug-in that enables you to use .htaccess files and a script for converting .nsconfig files to .htaccess files.
Activating .htaccess checking
To use .htaccess files, you must first modify the server's obj.conf file to load, initialize, and activate the plug-in. At the top of the obj.conf file, after the other Init directives, add the following lines:
For Unix/Linux:
For Windows NT:
These lines load and initialize the module when the server is started. server_root is the path to your server root.To activate .htaccess file processing for all directories managed by the server, add the PathCheck directive:
to the default server object, which is delimited by:
Generally, the directive to activate .htaccess processing should be the last PathCheck directive in the object.
- <Object name="default"
...
</Object
To activate .htaccess file processing for particular server directories, place the PathCheck directive in the corresponding object definition in obj.conf.
If you want to name your .htaccess files something other than .htaccess, you must specify the filename in the PathCheck directive using the following format:
Replace filename with the filename you are using.
- PathCheck fn="htaccess-find" filename="filename"
After editing the configuration file, stop and start your server. Apply your configuration file changes in the iPlanet Web Server by clicking the Apply button. Subsequent accesses to the server will be subject to .htaccess access control in the specified directories.
To restrict write access to .htaccess files, create a configuration style for them, and apply access control to that configuration style. For more information, see Working With Configuration Styles and Controlling Access to Your Server
Converting Existing .nsconfig Files to .htaccess Files
The iPlanet Web Server includes a script for converting your existing .nsconfig files to .htaccess files. To convert your files, at the command prompt, enter the path to Perl on your system, the path to the script, and the path to your obj.conf file. For example you might type the following (it should all be on one line when you type it):
The script converts all .nsconfig files to .htaccess files, but does not delete the .nsconfig files.
- server_root\install\perl server_root/plugins/htaccess/htconvert server_root/https-server_name/config/obj.conf
Supported .htaccess Directives
The following .htaccess directives are supported in this release:
AuthName
There is an option, called groups-with-users, that facilitates handling large numbers of users in groups. That is, if you have many users in a group, you can follow these steps:AuthType (The only AuthType supported is Basic.)
AuthGroupFile
AuthUserFile (This has different formats depending on your usage. See below.)
Revise the format of the user file format to list all the groups a user belongs to:
Or, alternatively, you can perform these steps:
Revise the AuthGroupFile directive to point to the same file as the AuthUserFile.
- username:password:group1,group2,group3,...groupn
Remove the AuthGroupFile directive entirely.
And add this option to the 'Init fn=htaccess-init' line in the obj.conf file:
- groups-with-users="yes"
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.When a request is made for a resource in which dynamic configuration is enabled, the server must search for the configuration files within one or more directories of that resource. This search can be an expensive operation in terms of performance, so the server lets you configure how much flexibility you need, weighing it against the efficiency cost.
You can provide a base directory to the server, in which case the server starts its search for configuration files from the filesystem directory. Alternatively, you can provide no base directory, in which case the server attempts to infer the base directory from the URL. That is, if the requested URL is to a file in the document root, the server starts searching from the document root.
You also specify the name of the configuration file to search for within the base directory.
If you centralize all of your configuration information for the subdirectories of the base directory in the base directory's configuration file, the server is more efficient because it doesn't have to search for configuration files in the subdirectories.
However, you may sometimes want the server to search the subdirectories. If you do, the server searches for .nsconfig files starting from the top level directory and searching downward until reaching the directory in which the referenced resource resides. The server processes .nsconfig files in the order it encounters them. If a top level file restricts a user's access, the server does not give the user access, even though a lower level file might allow access.
The server processes all restrictions based on IP address and DNS entry (RestrictAccess directive) as it finds them in a file. If the server finds a file that denies a user access because of IP address or DNS entry, it stops processing files. The server collects restrictions based on user name (RequireAuth directive) and processes them at the end, unless the request has already been denied because of IP address or DNS entry.
For example, if you selected the base directory inferred from URL translation, selected .nsconfig for your filename, and chose to search subdirectories, the following search would occur.
When a user requests the filesystem path C:\Netscape\server4\docs\icons\gfx\logo.gif, instead of searching for C:\Netscape\server4\docs\.nsconfig the server would search all of the subdirectories:
You can also enter a wildcard pattern of file types you want to disable in directories where dynamic configuration is enabled. To disable CGI programs and parsed HTML, for example, use * (cgi|parsed-html).
- C:\Netscape\server4\docs\.nsconfig
C:\Netscape\server4\docs\gfx\.nsconfig
C:\Netscape\server4\docs\gfx\icons\.nsconfig
To configure .nsconfig files, perform the following steps:
From the Server Manager, choose Server Preferences.
Click the Dynamic Configuration Files link.
Choose a resource from the Resource Picker.
Choose whether to base the directory from the URL or from a specified directory.
Writing .nsconfig Files
The .nsconfig files consist of sets of directives that control the server. These directives are surrounded by Files directives that tell the server which files in the configuration file's directory the directives apply to. For example:
PATTERN1 and PATTERN2 are wildcard patterns that tell the server which filesystem paths to apply the directives to. For example, * would apply the directive to all filesystem pathnames. Any pattern given is first prefixed with the directory containing the configuration file to ensure that the directives are applied only to subdirectories. There can be as many sets of Files directives in the .nsconfig file as you need.
- <Files PATTERN1
... directives ...
</Files
<Files PATTERN2
... directives ...
</Files
The file can contain blank lines. Lines beginning with # are treated as comments. Note that lines are limited to a maximum of 1024 characters.
For Windows NT, all paths must use the forward slash (/) instead of the backwards slash (\), otherwise you receive a server "path not found" error.
Each directive can take a variable number of parameters, all of which must be lowercase. The Files directives include:
AddType exp=SHEXP type=mime-type enc=http-encoding AddType assigns the give type or encoding to the paths represented by the wildcard pattern SHEXP . One or both of type and encoding can appear, but only one expression can be used. You cannot apply two MIME types or encodings to the same pattern of the files.
ErrorFile reason=error-string code=error-code path=html-file
ErrorFile causes the HTML file described by the URL suffix path to be sent in place of the server's default error message. The file is substituted when an error described by one or both of reason and code occurs. path is a valid URL to the local server but without the http://server prefix. The error codes are the standard HTTP error codes:RequireAuth dbm=dbmfile userfile=database_name realm=string userpat=PATTERN
RequireAuth lets you ask the user for a username and a password when accessing the directory. dbm is a user database. Note that dbm can only be used on a 2.x Enterprise user database. userfile is an NCSA-style user database filename. The file consists of lines in the format user:encrypted_password. realm is a unique string to tell your users which password they should use. userpat determines which users from the given dbm or userfile are allowed access. userpat is a wildcard pattern or list of user names. For example, you can use the syntax userpat="user1" or userpat="(user1|user2)" for specifying a user or a list of users.RestrictAccess method=HTTP-method type=allow|deny ip=addrpattern dns=hostpattern return-code=403|404
RestrictAccess applies access control to the directory and restricts certain users. method is an optional parameter specifying a wildcard pattern of HTTP methods to protect (no method specified means all of them). type determines whether the IP address wildcard pattern or hostname wildcard pattern is allowed or denied access. If the only RestrictAccess directives in a Files set are of type allow, then all hosts not specified by the patterns are denied. ip must be typed in lowercase for the directive to work. More than one RestrictAccess can appear in the file. The order in which these lines appear is important; later RestrictAccess lines override earlier ones.
Example of an .nsconfig File
The following example shows an .nsconfig file:
<Files * ErrorFile reason="Unauthorized" code="401" path="/errors/unauthorized.html" ErrorFile reason="Forbidden" code="403" path="/errors/forbidden.html" ErrorFile reason="Not Found" code="404" path="/errors/notfound.html" ErrorFile reason="Server Error" code="500" path="/errors/server-error.html" RestrictAccess method="(GET|HEAD|POST)" type="allow" ip="*" RestrictAccess method="(GET|HEAD|POST)" type="deny" ip="198.95.251.30" return-code="404" </Files <Files *.gif AddType exp=*.gif type=application/octet-stream </Files <Files *.txt RequireAuth dbm="server_root/authdb/default" realm=Text userpat="user*" </Files
Restricting Symbolic Links (Unix/Linux)
You can limit the use of the filesystem links in your server. Filesystem links are references to files stored in other directories or filesystems. The reference makes the remote file as accessible as if it were in the current directory. There are two types of filesystem links:
Hard links—A hard link is really two filenames that point to the same set of data blocks; the original file and the link are identical. For this reason, hard links cannot be on different filesystems.
For more information about hard and symbolic links, see your Unix/Linux system documentation.Symbolic (soft) links—A symbolic link consists of two files, an original file that contains the data, and another that points to the original file. Symbolic links are more flexible than hard links. Symbolic links can be used across different filesystems and can be linked to directories.
Filesystem links are an easy way to create pointers to documents outside of the primary document directory and anyone can create these links. For this reason you might be concerned that people might create pointers to sensitive files (for example, confidential documents or system password files).
To restrict symbolic links, use The Access Control List Management Page in the Server Manager.
Using the Watchdog (uxwdog) Process (Unix/Linux)
The uxwdog process is the name of the web server watchdog process, introduced in Enterprise Server 3.01. Prior to Enterprise Server 3.01, the server would fork a copy of itself at startup, and the parent server process would serve as the watchdog for the child. In Enterprise 2.x, a server restart operation would cause the parent server process (ns-httpd) to terminate the child ns-httpd process, and then recreate it. This result had the advantage that the parent process could maintain the key file password for a secure server, so that restarting the server would not require the server administrator to reenter the password.However, with the addition of a number of subsystems to the server in Enterprise Server 3.0, it was felt that the server should be completely stopped and started for a restart operation, as the most expedient way to be sure that all subsystems were properly initialized. This had several immediate drawbacks. First, it became necessary to reenter the key file password for a secure server during a restart. This was particularly a problem for a secure server with automatic log rotation enabled, since log rotation relies on a server restart operation. Finally, every server configuration change required the server to be completely stopped and started.
The basic idea of uxwdog is to have a lightweight process that keeps around just enough state information to be able to start a new server process during a restart operation, without human intervention. This state consists mainly of any passwords or PINs required to start a secure server, and open file descriptors for sockets on which the server will listen. The socket file descriptors had to be kept around because some of them might be for privileged TCP ports, port 80 for example, which would require a process running as root to bind them. When this is the case, the Administration Server generally runs as root, and starts uxwdog as root, or else an administrator who is running as root executes the server start script. Once uxwdog binds the server listen port(s), it changes its uid to the server uid, often "nobody," and then starts the server process as that uid.
One consequence of this behavior is that the NSAPI Init directives always run under the server uid, unlike in Enterprise 3.0 and earlier, where it was possible to have them run as root. This has created some problems in upgrade situations, when a plugin Init function was creating a file during the Init. The file would be owned by root in the older server version, and when installing the plugin in Enterprise 3.01 and later, it would be necessary to change the ownership or protection on the migrated file.
In order to determine on which ports the server listens, uxwdog must read magnus.conf and obj.conf. It does this each time the server is restarted, and verifies that the port numbers have not been changed. If they have, a restart operation is not possible, uxwdog will exit, and the server will have to be manually started. This is also true if security is turned on, the server uid is changed, or the PidLog filename is changed.
The restart and stop scripts send SIGHUP and SIGTERM, respectively, to uxwdog. In both cases, uxwdog sends SIGTERM to the ns-httpd process to shut down the server. For a restart operation, uxwdog then creates a new server process, passing it the file descriptors of the listen ports, and any passwords or PINs it has saved.
The default behavior of the server watchdog process automatically restarts the server if the server process should terminate unexpectedly. You can revert to the previous default behavior, which was for the watchdog process to exit if the server terminates unexpectedly. To revert to the original default behavior, set the environment variable, UXWDOG_NO_AUTOSTART, at the beginning of the server start script as follows:
(following the "#!/bin/sh" line):
You also now have the option to have the watchdog restart the server if the server process calls exit() with a non-zero argument value. This feature is disabled by default, but can be enabled by setting the UXWDOG_RESTART_ON_EXIT environment variable in the server start script as follows:
- UXWDOG_NO_AUTOSTART=1; export UXWDOG_NO_AUTOSTART
Between Enterprise Server 3.01 and Enterprise Server 3.5.1, the Administration Server CGIs for Enterprise Server were changed to actually restart, rather than start and stop the server, when configuration changes are applied. As part of this change, these CGIs will create a file, wdnotify, in the server's logs directory, which will contain a TCP port number on which the CGI listens for status from the watchdog. During a start or restart operation, uxwdog checks for the existence of this file, and if it finds it, connects to that port, and reads the name of a file to which stderr is to be redirected during the operation. uxwdog opens that file, redirects stderr to it, and performs the operation. If the operation is successful, uxwdog writes a single byte value of zero back to the CGI. Otherwise it writes a non-zero status byte, typically a value of one. Finally uxwdog closes the connection to the CGI, and redirects stderr to /dev/console.
- UXWDOG_RESTART_ON_EXIT=1; export UXWDOG_RESTART_ON_EXIT
There may be some cases where wdnotify does not get deleted when it should, which may cause uxwdog to exit instead of starting or restarting the server. This can be corrected by manually removing the wdnotify file from the logs directory.
Previous Contents Index Next
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.
Last Updated July 13, 2000