The nsdb pool files which have the same configuration
can be symlinks to a single file on unix systems.

The startup file  is jnm.tcl

The server startup script is servers/jnm/run

Output of a typical startup is in sample-startup.txt

Socket bind file is jnm-bind.txt

STARTUP NOTES

The configuration relies on DJB's daemontools for startup
and log rolling.

AOLserver is started in foreground mode with stdout and stderr 
redirected to the multilog program. With this configuration,
AOLserver can be started at the command line using the same run
script without the need to edit the command line. 

The run script (servers/jnm/run) lists a bind file (bind-jnm.txt) and a startup
configuration file (jnm.tcl).

NSSOCK AND VIRTUAL SERVERS

In the example there are three virtual servers listening on three ip/port combinations.

Each ip/port needs a separate instance of nssock. To make it easy to view a configuration 
without actually opening the startup config file, each nssock is configured in a 
separate file, named to reflect the configuration. 

It is important to note that any particular virtual server is not limited to one ip/port.

Each nssock has a default virtual server. The default virtual server is used if a request
which is handled by the nssock does not have a Host: header, or if the Host: header
does not match any of the host to virtual server mappings.

In the example, the amresolve virtual host is mapped to two nssocks: nssock0 and nssock2.
However, the default virtual server for nssock2 is jnm. The default virtual server for a
nssock could be used to serve error messages for clients which do not present a correct 
Host: header, or to log the fact that requests are arriving at an ip/port which do not 
resolve to a configured virtual host.

CONFIGURATION FILE LOADING

AOLserver is started via a command line interface. It has become standard practice to
create a startup script which sets a few environment variables. A separate file also make
it easy to copy or backup the startup configuration. 

In the example, there are several features worth noting. First is a period of sleep. For some
reason, if AOLserver is instantly restarted it occasionally fails to bind to the ip ports.
This failure is usually silent and AOLserver will appear to be running, but will not be listening
on the expected ports.

The second feature is that standard error is redirected to standard output. This ensures that
all errors get logged to multilog, and not just those which pass through ns_log. It also ensures
that all startup errors get logged.

Third, the command line specifies that startup is in foreground mode so this script can be 
used for testing and debugging without change, and also that all, ALL, output will be logged. 

Finally, a bind file is used. A bind file lists one line per ip:port combination. This is a list
of the ip/ports where the nssock modules will listen. In this example the bind file is bind-jnm.txt.

The final command line in the startup script is an exec. This replaces the bash binary with AOLserver's
binary (nsd) and allows the service program to control nsd.

MULTIPLE CONFIGUATION FILES

One important feature of this example is that the configuration file has been split
into multiple files.  When running a single virtual server there is little need for
this split, and it might make life more difficult. However, due to the structure of 
AOLserver's configuration into many similarly named sections (ns_section) for each different
virtual server, it can become very difficult to maintain a single file.    
 
The example is an attempt to make it easier to understand what the actual configuration
is for a server. This is necessary because it is typical for everything to be working fine until
a tiny change is made. Any typo or a number of other problems can lead to complete failure
of AOLserver to startup. Essentially one bad virtual server configuration can affect all the
others. Finding the error can be difficult, so a number of the features of
this example are aiming at making the configuration easier to understand and more explicit. The example
also allows correctly configured virtual servers to startup. 

From this point of view, it should be noted that each AOLserver instance, which may contain
several virtual servers must have a separate main configuration file. Parameters are usually 
explicitly listed. The only variables used are $home and $server. $home is the main configuration
file directory. $server is the name of the virtual server being processed at a given instant.

The main configuration file is read. This is actually a tcl script, so tcl command can be used
anywhere in this file. One or more virtual servers are listed in a variable called 'servers'.

For each of these virtual servers, a separate configuration file is listed. These
are set in the array ServerConfig, with the keys being the servers listed in 'servers'. The
values are an absolute path to the virtual server configuration file.

The main configuration file lists overall parameters for AOLserver. This includes nssocks, database 
drivers, and global parameters. Usually the global parameters in the 'ns/parameters' ns_section, are
used as defaults for the individual virtual servers if that virtual server's parameters are missing.

The main configuration file sources the listed virtual server configuration files. An important feature
of using source is that if there is an error in a virtual server, typo or otherwise, the error
does not kill the AOLserver startup. Instead, the virtual server is marked in error and the other
virtual servers are allowed to startup unaffected.

Each virtual server configuration is broken down into separate files. Essentially each module which
is loaded into the virtual server has a separate configuration file. First, this makes it very
easy to see what modules a virtual server has loaded, second it makes it easy to move a configuration
to another virtual server. There is also a separate file for each threadpool for this virtual server.

All of the virtual server configuration files are kept in a separate directory, usually on the same
level as the modules and pages directories, and also where the run file is stored. In the example,
jnm's configuration is kept at 'servers/jnm/config'.

Once all the configuration files are loaded, the main startup script will remove failed servers from the
configuration. This allows AOLserver to startup with as many virtual servers as possible. 

In case of any errors, the current internal AOLserver configuration is written to standard output, any
errors are written to a configured error file, but AOLserver will still startup with the virtual servers
that are working.

Output for a typical startup of this example is in sample-startup.txt

Tom Jackson