AOLserver Installation Guide
$Header: /cvsroot/aolserver/aolserver.com/docs/admin/install.html,v 1.1 2002/03/07 19:15:34 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 make is 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.global and
 include/Makefile.module have 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!