AOLserver Installation Guide
$Header: /cvsroot/aolserver/aolserver.com/docs/admin/install.html,v 1.2 2002/09/26 19:51:32 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 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.
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.
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
distribution. The 7.6 library is heavily modified, mostly for thread
and ns_share support. The 8.x library is modified slightly to
thread support through AOLserver's nsthread library and to
patch a few
The installation directory contains a file named "sample-config.tcl" which represents a complete configuration of AOLserver. This configuration will:
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!