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:

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.
  1. Check the include/Makefile.global file for platform-specific options.  Most platforms use gcc.
  2. Enable optional modules.  The default Makefile builds nssock, nsssl, nscgi, nscp, nslog, nsperm, and nsext.
  3. Type "gmake", ensuring the make which is executed is GNU make.  You might want to call your GNU Make "gmake" instead of "make".
  4. 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:

  1. 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.
  2. Check security settings for nscp (Control Port module) and listen on localhost:9999 if they are set.
  3. 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!