[Inso Home Page] [Home] [Collection] [Book] [Expand] [Collapse] [Search Forms] [Previous Section with Hits] [Next Section with Hits] [Clear Search] [Preferences] [Print] [Help]

 inside  Expand Search


  Appendix A: Glossary   [Table of Contents]

DynaWeb Publishers Guide

[-] Appendix B: The DynaWeb Internet Server

Appendix B: The DynaWeb Internet Server

Introduction to The DynaWeb Internet Server

The DynaWeb Internet Server is a HTTP 1.0 compliant Web server that is available on all platforms. It support a limited subset of the Netscape Server API (NSAPI) and is fully compatible with the DynaWeb Server Module or server modules that adhere to the NSAPI subset.

Controlling the Server

UNIX Platforms

The DynaWeb Internet Server is controlled by a set of commands located in the {platform}/bin directory of the server installation. {platform} stands for the current platform DynaWeb is running on.

There are three commands that are used to control the state of the server. The commands are: start, stop, and restart.

To be certain that you are running the scripts located in {platform}/bin, change directories to the {platform}/bin directory and use the syntax "./{command}" when running any of the server commands.

Start

The start command creates two or more processes, the server-controller process and a process specific to each port where the server will be listening for requests. The process ids (pids) for the processes created are recorded in a log called the pid.log.

Stop

The stop command sends a kill request to the server-controller, causing the server-controller and any port-specific processes to end. The pid log must be present in order for the stop command to take effect.

If for some reason the pid log is missing or erased, you must manually find the processes labeled dwhttpd and send a kill -3 <pid> command to them. This will stop the server and remove the processes.

Restart

The restart command causes the server-controller to restart all of the protocol modules it is currently running. This causes any changes to the nsapi.cfg file or any plugin-related configuration files to be recognized. For changes to the dwhttpd.cfg file to be recognized, the server controller must be stopped, either with the stop command or with a kill -3 command, and then started again.

Windows 95

When the server is installed on Windows 95, a Program Group is created named DynaWeb. There are two icons in this group: an UnInstall option and a program called the DynaWeb Internet Server Controller.

The Server Controller brings up a small dialog box with three buttons, Start, Stop, and Restart. The Controller pings the port specified by the dwhttpd.cfg file and, depending on the current state of the server, dims some of the buttons on the Controller. When the server is running, the title bar of the window also displays the word "(running)".

Start

The Start button starts the server running on the port specified by the dwhttpd.cfg. Once the server is running, the button dims and cannot be selected again until the server has stopped.

Stop

The Stop button kills the server. If the server is not running, this button is dimmed.

Restart

When the Restart button is selected, the Controller kills the server and immediately starts it again. If the server is not running, this button is dimmed.

Windows NT

The DynaWeb Internet Server runs as a service under Windows NT. This allows the server to start automatically on boot, without requiring a particular user to be logged in. As a service, the server is started and stopped through the Services Control Panel applet.

In order to serve books that exist on networked drives, any servers running as services that are configured to run the DynaWeb plug-in must be set to 'log on as' a user that has access to the networked drives. This is because the services can start without anybody logged into the system. To configure a service to 'log on as' a particular user:

  1. In the Services Control Panel, select the service that you want to change, e.g. the DynaWeb Internet Server, the Netscape FastTrack server, or the Netscape Enterprise server.
  2. Click the Startup button.
  3. Select the "This Account" radio button, and enter an account name (user name) that has access to the network drives that contain the books. Also, be sure to enter and confirm the password for that user.
  4. Click the OK button, then stop and start the service to complete the changes.

    Note that collections in your collects.dwc file may require fully qualified path names for networked drives rather than mapped drive letters in order for the DynaWeb plug-in to access them over your network.

    The install program creates a Program Group called 'DynaWeb' by default. In this group is a single file: an Uninstall option.

    Setting Authentication on the DynaWeb Internet Server

    Note: This information is required to successfully complete "Example 15: Adding Element-Level Security" in the Programmers Guide to Customizing DynaWeb.

    To enable basic HTTP authentication for the DynaWeb Internet Server, you must edit the nsapi.cfg file, found in the data/config directory in your server installation. Find the line:

    set autoconfig_authentication 0

    and change it to read:

    set autoconfig_authentication 1

    This will enable authentication for the server. To complete authentication you must also establish a password file for the server to check for valid names and passwords. By default, the server looks for a file named sample.pwf in the data/config directory of your installation. However, you can specify both the filename and the default location by editing a line of the nsapi.cfg file. Search the nsapi.cfg file for sample.pwf. The section displayed should look like this:

    if {$autoconfig_authentication} {
       AuthTrans fn="basic-ncsa" \
       userfile=$ServerRoot/data/config/sample.pwf \
       auth-type="basic"
    }

    In the line that starts "userfile=" change the filename or path to the one you want the DynaWeb Internet Server to search in order to validate an authentication request. The default name and location of the password file isdata/config/sample.pwf.

    The syntax of the password file is straightforward: name:password, with each entry on its own line.

    Sample sample.pwf:

    Guest:Anonymous
    Guest2:Famous
    Tester:Training
    teacher:apple
    

    If you are using a server besides the DynaWeb Internet Server, consult your server's documentation for instructions on setting up authentication.

    Server Processes

    When the DynaWeb Internet Server is running, there are always at least two processes running: one for the server-controller and one for the specific port the server is bound to (called a protocol module).

    The Server Controller

    The server-controller process maintains information about each of the running protocol modules.

    Protocol Modules

    The protocol modules handle the request according to the directives they support. Currently, the only type of directive the DynaWeb Internet Server supports is the type "NSAPIProtocolModule."

    Server Logs

    The pid.log File

    The pid.log file is only created on UNIX platforms and is located in the {platform}/bin directory. The pid.log keeps a record of the process id's for the DynaWeb Internet Servers running on that machine. Normally, there are at least two entries in the pid.log file, which is created when the server is started and erased when the server is shut down. The two entries are the server-controller and the port-specific process for the port where the server is listening. This port-specific process is referenced in the pid.log by the name "httpd-{xxxx} {pid}" where {xxxx} is the port number of the server and {pid} is the process id of the process.

    The main.log File

    The main.log file acts as the log file for the server-controller process. Any error output generated by the server-controller is stored in the main.log. By default, the main.log file is kept in the logs directory beneath the main server directory.

    The Access Log

    The access log logs all of the requests for information received by the server in a common log file format recognized by most log parsers. The access log is located in the logs directory beneath the main server directory.

    The Error Log

    The error log keeps a record of all of the error messages and informational messages generated by the server.

    Configuration Directives

    Overview of the dwhttpd.cfg File

    The dwhttpd.cfg file is used to configure various components of the DynaWeb Internet Server. The file is a text file and can be read with any text editor. The file also supports TCL constructs such as variable and command substitution and conditional branching to simplify various aspects of the server's configuration.

    The dwhttpd.cfg file is located in the data/config directory beneath the server's installation directory.

    The following sections will describe some of the directives you can modify to change your server's behavior.

    PidLog

    Note: This is only used on UNIX platforms.

    Syntax

    PidLog <pid-log-filename>

    Description

    The PidLog directive specifies the name of the log file which will contain the process ids of the various server processes as well as the path to that file.

    Example

    PidLog /pro/server/sunos5s/bin/pid.log

    MainLog

    Syntax

    MainLog <main-log-filename>

    Description

    The MainLog directive specifies the name and location of the main server log file. The main log file serves as the log file for the server controller process.

    Example

    MainLog /pro/server/logs/main.log

    Services

    Syntax

    Services {
         name1  type1
         name2  type2
         ...
         nameN  typeN 
    }

    Description

    The Services directive allows the administrator to configure which services the server will start at startup. The "name" parameter is a human-recognizable service name, and the "type" determines the type of service "name" is. Currently the only "type" allowed is "NSAPIProtocolModule" which tells the server that this service's definition is supplied by the NSAPIProtocolModule directive.

    Example

    Services {
       http-8000  NSAPIProtocolModule 
    }

    ReReadCfgOnRestart (UNIX only)

    Syntax

    ReReadCfgOnRestart [yes | no | true | false]

    Description

    The ReReadCfgOnRestart directive tells the DynaWeb Internet Server whether it should reload its configuration file (dwhttpd.cfg) on restart. The directive should be placed in the dwhttpd.cfg file. Currently, it only reads the nsapi.cfg file on restart.

    A value of "yes" or "true" tells the server to read the dwhttpd.cfg file on restart. A value of "no" or "false" tells the server to only read the nsapi.cfg file (the current behavior).

    Example

    ReReadCfgOnRestart yes

    NSAPIProtocolModule

    Syntax

    NSAPIProtocolModule <name> {
       <nsapi-protocol-module-subdirectives>
    }

    Description

    This directive allows the server administrator to configure the different modules specified in the Services directive listed above. The "name" parameter is the name of the specific module that is being configured. The "nsapi-protocol-module-subdirectives" are the list of directives that can be set for each module. The following directives are supported.

    These directives will be covered in detail in the following sections.

    Example

    NSAPIProtocolModule http-8000 {
       ServerName  www.inso.com
       ServerUser  nobody
       Port        8000
       MaxThreads  32
       NumRequests 100000
       AccessLog   /pro/server/logs/access.log
       ErrorLog    /pro/server/logs/errors.8000 
       MimeMap     /pro/server/data/config/mime.typ
       ObjectFile  /pro/server/data/config/nsapi.cfg
       ErrorPath   /pro/server/data/error 
    }

    The NSAPIProtocolModule Directives

    This section explains in more detail the different directives that can be configured for each protocol module in use by the server.

    ServerName

    Syntax

    ServerName  <name>

    Description

    The ServerName is the fully-qualified name of the machine the server is running on.

    Example

    ServerName  www.inso.com

    ServerUser

    Note: This is only used on UNIX platforms and only affects the operation of the server if the server is started by the superuser.

    Syntax

    ServerUser <username>

    Description

    This directive determines the name under which the server will be running. (i.e. "nobody", "root", etc.)

    Example

    ServerUser nobody

    Port

    Syntax

    Port <port#>

    Description

    Determines the port that the module will be listening to for requests.

    Note: The first 1024 ports are restricted. If such a port is selected, the server must be started by a superuser or superuser process.

    Example

    Port  8000

    MaxThreads

    Syntax

    MaxThreads <number>

    Description

    The value of MaxThreads determines the number of requests that the server can handle simultaneously. A setting of 0 (zero) disables the multithreading features of the server, and all requests are handled sequentially.

    Example

    MaxThreads  32

    NumRequests (Unix Only)

    Syntax

    NumRequests <number>

    Description

    Sets the numbers of requests the module will handle before recycling itself.

    A setting of 0 (zero) disables the recycling feature.

    Example

    NumRequests 10000

    AccessLog

    Syntax

    AccessLog </path/to/access.log>

    Description

    Sets the location of the log file in which to store the access log. The access log records all requests made to the module (and all other modules) and is written in a standard log format.

    Example

    AccessLog  /pro/server/logs/access.log

    Sample output:

    255.255.255.255 - - [17/Oct/1996:10:00:00 -0500] "GET / HTTP/1.0"
    2000 782

    ErrorLog

    Syntax

    ErrorLog </path/to/error.log>

    Description

    This directive points to the location of the error log, where the module records errors or informational messages generated by errant requests to the server.

    Example

    ErrorLog /pro/server/logs/errors.8000

    MimeMap

    Syntax

    MimeMap </path/to/mimetypes>

    Description

    Sets the location of the mime-types file used by the server. The mime-types file is set up in the format of "type=<some-mime-type> exts=<extension list>" and is named mime.typ.

    Example

    MimeMap /pro/server/data/config/mime.typ

    Sample mimetype:

    type=image/jpeg  exts=jpg,jpeg

    ObjectFile

    Syntax

    ObjectFile </path/to/NSAPIconfigurationfile>

    Description

    Points to the NSAPI configuration file that controls how the NSAPIProtocolModule handles requests. This file is similar to Netscape's obj.conf file. The file is named nsapi.cfg and is located in the data/config directory beneath the server's installation directory.

    Example

    ObjectFile /pro/server/data/config/nsapi.cfg

    ErrorPath

    Syntax

    ErrorPath <error-directory>

    Description

    When the module needs to return an HTTP error message in response to a request, it looks in the directory specified by ErrorPath for a file named {error-code}.htm.

    Example

    ErrorPath /pro/server/data/error

      Appendix A: Glossary   [Table of Contents]