Building, Installing, and Configuring AOLserver

$Header: /cvsroot/aolserver/aolserver/doc/install.html,v 1.2 2000/10/10 22:56:42 kriston Exp $

AOLserver is distributed in source form. Pre-built binary kits for many platforms are available at http://aolserver.com/.

Getting Started

AOLserver 3 is reasonably portable and known to compile and run on the following platforms:

Linux 2.2 and better (x86 and others)
FreeBSD 3.4 and better (x86 and others)
OpenBSD 2.5 and better (x86 and others)
Solaris 2.x and better (SPARC and x86)
IRIX 6.x (mips)
HP/UX 10 and 11 (hppa)
DEC Tru64 &OSF/1 4.0 and better (alpha)
UnixWare 7.x and better (x86)
Apple OS/X "Darwin" (first consumer beta release only) (ppc)

It's likely AOLserver can compile on other systems and/or higher or lower numbered versions but this has not been extensively tested. The primary development platforms for AOLserver at AOL are IRIX 6.4 and Solaris 7. We also use HP/UX 10.20/11.0, Solaris 2.6, and VA Linux 6.2.1 (Linux 2.2).

You will need a C compiler. The best one to use is GNU GCC from http://www.gnu.org/and its mirrors. The versions we use are 2.95.2. AOLserver (and the included Tcl libraries) are written entirely in ANSI standard C.

GNU makeis also required. It is also available from the GNU web site.

Building

We've tried to make building AOLserver as simple as possible. On the supported platforms, simply typing "gmake" will build the server and its standard modules.

Check the include/Makefile.global file for platform-specific options. Most platforms use gcc.
Enable optional modules. The default Makefile builds nssock, nsssl, nscgi, nscp, nslog, nsperm, and nsext.
Type "gmake", ensuring the make which is executed is GNU make. You might want to call your GNU Make "gmake" instead of "make".
Watch for any warnings. The warning for a missing third-party library in nsssl can be safely ignored.

Some modules use third-party libraries. If the library is missing, the AOLserver build will continue without error -- it just will not build the offending module. The only module in the base server installation that requires an external library is "nsssl" (in the nssock/ directory) which requires BSAFE from http://www.rsasecurity.com/. You can download a binary version of nsssl at http://aolserver.com/if you don't have BSAFE.

Note: If you have any problems building, the two files include/Makefile.globaland include/Makefile.modulehave all the information you need to change settings throughout the AOLserver environment.

Installing

Type "gmake install" to make a production server. This will create an installation directory at /usr/local/aolserver/, populate the directories with various startup files and configuration files, copy the binaries to the /usr/local/aolsever/bin directory, and finish. To install confidence tests, type "make install-tests" and they will appear in the tests/ directory of your server's pageroot. The default location for installations can be overridden by typing "gmake install PREFIX=/your/directory/".

Note: AOLserver requires the modified versions of Tcl included with the distribution. The 7.6 library is heavily modified, mostly for thread safety and ns_share support. The 8.x library is modified slightly to enable thread support through AOLserver's nsthread library and to patch a few minor problems.

Configuring

The installation directory contains a file named "sample-config.tcl" which represents a complete configuration of AOLserver. This configuration will:

Listen for http connections on your computer's primary interface at port 8000. To use another port and/or select interfaces, you can set the "host" and "httpport" variables.
Check security settings for nscp (Control Port module) and listen on localhost:9999 if they are set.
Check for the existence of ssl keys (nsssl module) and listen with https on port 8443 if they exist.

Note: Some modules have been disabled in the sample nsd.tcl for security reasons. They are nscp and nsperm. They aren't required to run a server unless you want to use the Control Port and/or the Permissions module, respectively. Before using them, change the passwords and default permissions by following the instructions in the AOLserver documentation.

Although you must be root to start AOLserver, the server itself must change to a regular user shortly after initialization. You either need to start the server as a non-root user (in which case you will not be able to listen for connections on privileged ports such as port 80) or you must include a -u user command line flag to which the server will setuid(2) after startup. You may either specify a Unix username or numeric uid, e.g.: ./bin/nsd76 -t ./config.tcl -u user -g group

AOLserver can be started by executing the nsd76 or nsd8x binary. The choice of nsd76 or nsd8x depends on whether you need compatibility with Tcl7.6 (closer to the 7.4 of previous releases) or special features of Tcl8.x (e.g., internationalizaton). For the mode of operation, there are three choices: Foreground, Background, and Inittab.

In Foreground mode , the server starts and emits diagnostic log messages directly to the terminal window. This is useful for testing, configuration or debugging a server. To start the server in foreground mode use:
/bin/nsd -ft ./config.tcl -u user -g group
To stop a server running the foreground simply press interrupt on your keyboard (e.g., ctrl-c or the DEL key) which will send a SIGINT to the server and initiate shutdown.

In Background mode, the server forks and disassociates from the terminal. Diagnostic messages are appended to log/server.log. This is a typical daemon-style mode of operation. To start the server in background mode use: ./bin/nsd -t ./config.tcl -u user -g group. To stop a server running the background you may either use the kill(2) command to send a SIGTERM to the background process id(*) or the special -K flag of the nsd binary. This flag will determine the process id from a special marker file, send the signal and wait for shutdown, e.g.:
./bin/nsd8x -Kt ./config.tcl -u user -g group
You may also use the -k flag to kill and restart a background server.

In Inittab mode, the server runs in the foreground but opens the log file as with background mode. This mode is used when the server is started from an entry in the /etc/inittab file. The benefit of this mode is that init will restart the server if it happens to crash. Production servers at AOL normally run in this mode. To run the server from /etc/inittab, add an entry similar to the following, substituting the proper id, run levels, and full pathnames:
w1:23:respawn:/usr/local/as3/bin/nsd -it /usr/local/as3/nsd.tcl -u user -g group
To restart a server you can simply kill the current server with the -K flag as with the background mode; init will then restart the server for you. To stop a server running in inittab mode you must comment out or remove the entry from the /etc/inittab file and signal the init process to re-read inittab with the "init q" command.

Note: While running AOLserver on some Unix platforms (e.g., Linux, SGI), you'll notice multiple nsd processes. This is normal and represents the individual threads. The main process id can be determined by checking the log/nspid.server1 file or looking at the last few entries of the server log, each of which will include the process id and thread id in the form [pid.tid]. You can also telnet to the control port and type "ns_info pid".

For more detailed configuration information refer to the online documentation at http://aolserver.com/. Enjoy!