
$Header: /cvsroot/aolserver/aolserver3/doc/install.txt,v 1.2 2000/03/25 22:14:20 kriston Exp $


Building, Installation, and Configuration
-----------------------------------------

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


Requirements:
-------------

o A supported Unix platform: AOLserver 3 is reasonably portable and
known to compile and run on the following platforms:

	- Linux (x86 and others)
	- FreeBSD 3.3 (x86 and others)
	- OpenBSD 2.6 (x86 and others)
	- Solaris 2.6 and 7 (SPARC and x86)
	- IRIX 6.4/6.5 (mips)
	- HP/UX 10.20 (hppa)
	- HP/UX 11 (hppa)
	- DEC OSF/1 4.0 (alpha)
	- UnixWare 7.1 (x86)
	- Apple OS/X (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 and production platforms for
    AOLserver 3 at AOL are IRIX 6.4/6.5 and Solaris 7.  We also use
    HP/UX 10.20/11.0 and Solaris 2.6.

o A C compiler: AOLserver (and the included Tcl) are written entirely
in C.  The GNU gcc compiler appears to work on all platforms (although
it complains when compiling on DEC and cannot compile "old" 32
binaries on IRIX).  In addition, we have received reports that certain
older versions of gcc on Solaris break the dynamic module loading
facilities.  The current version of gcc in use for Solaris 7 at AOL
are 2.8.1 and 2.95.2.  The Cygnus 99r1, 99r2 releases of gcc are
broken on Solaris, so if you're using Cygnus please obtain the latest
gcc from http://www.gnu.org/ and use that version, instead.

o GNU make: The AOLserver 3 makefiles require GNU make.  GNU make
comes with Linux and compiles very quickly on all platforms.


Compiling:
----------

o Check the include/Makefile.global file.  Most platforms use gcc.

o Enable optional modules.  The default Makefile builds nssock, nscgi,
nscp, nslog, nsperm, and nsext.

o Type "make", ensuring the make which is executed is GNU make.  This
will:

	- Build the nsthread library
	- Configure and build the Tcl 7.6 library (*)
	- Configure and build the Tcl 8.x library (*)
	- Build nsd76 and nsd8x
	- Build several modules:
		- nssock - basic standard socket comm driver
		- nscgi - CGI support
		- nscp - interactive control port
		- nslog - common log format logging
		- nsperm - new permission module
		- nsext - external database driver (**)
	- Build the nspd library for linking external database drivers

o Type "make install" to make a production server.  This will:

	- Create an installation directory.  This is determined by
	$(INST) in Makefile.global and can be overriden by typing
	"make install INST=/your/pathname".

	- Populate the directories with various startup files and
	configuration files.

	- Copy binaries to the "$(INS)/bin" directory


If you have a machine with multiple processors, you may be able to
build faster with GNU Makes's multiple job feature:

	make MAKE='make -j 4' install

(*) 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.

(**) To compile the included Sybase, Solid, Postgres, and nsssl2
drivers, edit the makefile in the corresponding directory to point to
the location of the vendor database library and header files.


Running:
--------

o The sample nsd.tcl file will listen for connections on your
computer's primary interface at port 8000.  To use another port and/or
select interfaces, you can use the "host" and "httpport" variables.

     set host     "hostname.com"
     set httpport 80

o 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.

o AOLserver will not run as root.  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 privilieged ports such as port 80) or you must include
a -u user command line flag to which the server will setuid() after
startup.  You may either specify a Unix username or numeric uid, e.g.:

	nsd -t nsd.tcl -u nsadmin

In addition, you can also specify a group or gid for the server to
setgid() after startup, e.g.:

	nsd -t nsd.tcl -u nsadmin -g webgroup


o AOLserver can be started by executing the nsd76 or nsd8x binary,
indicating the mode of operation and the path to the config file.  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).  If you're new to
AOLserver, use nsd8x as the 7.6 version will be removed in a future
release.  For the mode of operation, there are three choices:

    - Foreground: 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, e.g.:

	./bin/nsd -ft ./nsd.tcl

      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.

    - Background: The server forks and disassociates from the
    terminal.  Diagnostic messages are appended to the server log
    file, normally log/server.log.  This is a typical daemon-style
    mode of operation.  To start the server in background mode use:

	./bin/nsd -t ./nsd.tcl

      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 shutodwn, e.g.:

	./bin/nsd8 -Kt ./nsd.tcl

      You may also use the -k flag to kill and restart a background
      server.

    - inittab: 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 nsadmin

      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.


(*) While running AOLserver on some platforms (e.g., Linux, SGI
non-pthread), you'll notice multiple Unix 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].

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

Enjoy!

