README for mod_aolserver

• Prerequisites
• Compiling and Installing
• Configuring Apache
• Configuring mod_aolserver
• Limitations, Bugs and To-Do

Prerequisites

• Apache 1.3.12 or later in the 1.3 series. This module has not been developed for or tested with any Apache 2.0 release.
• Tcl 8.1 or later. Tcl 8.3 is recommended because that is what AOLserver 3.0 uses and ACS authors may take advantage of Tcl 8.3 features.
• MM Library. This is a portable shared memory library.
• Either Oracle 8i or PostgreSQL.

Apache

We developed mod_aolserver as a dynamic shared object, so you must compile/install Apache with mod_so built in. You can determine whether your Apache has this module by running this command:

httpd -l | grep mod_so

We test with Apache 1.3.12 so you should try to use that or a later version.

Tcl

AOLserver uses Tcl 8.3, so that's what I use to build mod_aolserver. It will probably work with Tcl 8.1 or later, but ACS might (now or in the future) use 8.2 or 8.3 features. Whichever version you use, make sure you build this with --enable-shared.

Warning: Red Hat Linux, through version 6.2 at least, only includes Tcl 8.0, so if you're on a Red Hat system, you must install a later version. You do not need to uninstall the Tcl RPM, though; you can install Tcl 8.3 somewhere else for mod_aolserver's use.

MM

AOLserver provides various APIs for threads to share data and synchronize their operations. Although Apache is not threaded, we emulate some of those APIs. The mechanism we use to share data between processes is Ralf Engelschall's MM.

We tested with MM version 1.1.1.

Note: if you are using Linux, MM will by default use System V style SHM shared memory. This work fine. Do not try to force it to use MAP_ANON shared memory. I had strange problems when I did that.

Oracle 8i

The ArsDigita Community System is built on top of Oracle 8i. mod_aolserver includes a version of ArsDigita's Oracle driver. If you want to run the ACS on mod_aolserver, you'll need Oracle 8i installed before compiling mod_aolserver.

As of release 1.1, mod_aolserver uses ArsDigita's AOLserver Oracle driver release 2.3.

PostgreSQL

An intrepid group of programmers are porting the ACS to PostgreSQL; they call the project "OpenACS". You can download that version from their development site. mod_aolserver includes a version of the PostgreSQL database driver. If you want to run OpenACS on mod_aolserver, you'll need PostgreSQL installed before compiling mod_aolserver.

Compiling and Installing

• --with-database=dbname

  (Required.) You must include this flag when running configure. dbname must be either ora8 or postgres. (mod_aolserver currently compiles in exactly one database driver and does not support dynamically-loaded drivers.)

• --with-ora8=dir

  (Optional.) Normally you set $ORACLE_HOME to your Oracle installation directory. If for some reason you want to specify it on the configure command line instead, use this flag.

• --with-postgres=dir

  (Optional.) If the PostgreSQL headers and libraries aren't in locations that the compiler will find automatically, or in /usr/local, you can use this flag to specify the PostgreSQL installation directory. The headers should be in dir/include and the libraries in dir/lib, of course.

• --with-apxs=dir

  (Optional.) Use this flag to specify the full path to the copy of apxs you want to use to build and install this module, for example /u/mayoff/test/bin/apxs. By default, configure will use the first copy of apxs in your PATH.

• --with-tcl=dir

  (Optional.) You may include this flag if you've installed Tcl in a non-standard location. Set dir to the directory containing tclConfig.sh. Normally that would be something like /usr/lib or /usr/local/lib.

• --with-mm=dir

  (Optional.) If you did not install MM in /usr, then you should use this flag to specify where you installed it. The MM headers should be in dir/include and the MM library should be in dir/lib.

In my test environment, I have private copies of Tcl, Apache, and MM, so my typical configure command looks something like this:

./configure \
  --with-database=ora8 \
  --with-tcl=/u/mayoff/test/lib \
  --with-apxs=/u/mayoff/test/bin/apxs \
  --with-mm=/u/mayoff/test

Configuring Apache

• aolserver - This handler is for .tcl files.

• adp - This handler is for .adp files.

mod_aolserver needs an AOLserver configuration file, in either .tcl or .ini format. You must specify the location of the file using the AolServerConf config_file directive in your httpd.conf:

AolServerConf config_file /u/mayoff/test/nsd.tcl
  or
AolServerConf config_file /u/mayoff/test/nsd.ini

Here's an httpd.conf excerpt to get you started. Assume that I have installed Apache in /u/mayoff/test and the ACS in /u/mayoff/test/acs.

# This is added automatically by apxs when you `make' or `make install':
LoadModule aolserver_module libexec/mod_aolserver.so

AolServerConf config_file /u/mayoff/test/nsd.ini

# The following setting is returned by [ns_info log]
AolServerConf log_file_location /u/mayoff/test/logs/error_log

# Note: Make sure that PageRoot in your nsd.ini is set
# to the same thing as this DocumentRoot.
DocumentRoot "/u/mayoff/test/acs/www"

<Directory "/u/mayoff/test/acs/www">
    Options Indexes FollowSymLinks MultiViews ExecCGI
    DirectoryIndex index.tcl index.adp index.shtml index.html index.htm
    AddHandler adp adp
    AddHandler aolserver tcl
</Directory>

Configuring mod_aolserver

Configuring mod_aolserver is pretty straightforward. The module will load whatever configuration file you specified with the AolServerConf config_file directive in your Apache configuration. The config file can be in either .ini or .tcl format. Many AOLserver configuration directives have no effect under mod_aolserver, but they will not be detrimental either.

A sample configuration file can be found in the mod_aolserver distribution as tcl_modules/nsd.ini.sample. You should be able to use that config file, with some site-specific modifications, to run ACS on Apache.

Be sure to disable the watchdog in your ACS configuration (by setting WatchDogFrequency to 0) or you'll get a lot of mail. The Apache error log is formatted differently than the AOLserver error log, so the watchdog parser doesn't work.

Also, if you're using the Oracle database driver, you may encounter problems if you leave the datasource empty. On my test system running Red Hat Linux 6.2 and Oracle 8.1.6, I found that Apache would either hang or dump core during startup. It turns out to be a problem with the "Bequeath Protocol", which is the way that the driver talks to Oracle if you leave the DataSource blank.

The workaround for using Oracle is to set the DataSource in your database pools to a TCP or IPC connection. This means you need to know a little bit about configuring Net*8 if you haven't done so before. The configuration assistant, netasst, is pretty good in Oracle 8.1.6, so you shouldn't have too much difficulty. If you run into trouble, you can try asking for help at the ACS on Apache web site or Web Tools Review.

Limitations, Bugs and To-Do List

Here are the known limitations, bugs, and to-do tasks.

• Database connections are not pooled between Apache children. This means you could end up opening a lot more database connections under mod_aolserver than under AOLserver. If you're using the Oracle driver, you'll probably want to configure Oracle to use shared connections instead of dedicated connections, or restrict your Apache MaxClients setting to something very small (like 8) to keep the number of database connections low.

• Database drivers are not dynamically loaded. This means that you can only use one of the two drivers we include - the ora8 driver and the postgres driver - and you must choose one and only one to use at compile time.

• ns_register_* and ns_schedule_* only work during server initialization. ns_cancel, ns_pause, ns_resume, and ns_unschedule_proc are not implemented.

  ACS only registers and schedules procedures as server initialization time, so this should not cause problems.

  Procedures that are scheduled to run once, after 120 seconds or less, are considered initialization procedures and are run in the Apache parent after all other mod_aolserver initialization but before the children are forked. Such procedures are used because in AOLserver you don't have access to database handles during initialization but you do have access to them from scheduled procedures.

• Preauth filters run after the Apache authorization phase.

• ns_share does not share data among processes. ns_share is deprecated, and ACS is moving away from its use. Use nsv_* instead, which does share data among processes.

• ns_critsec, ns_cond, and ns_sema are not implemented.

• ns_thread is not implemented.

  The bulkmail module will probably not work, because it uses ns_thread.

  Note that if you call ns_scheduled_proc -thread, mod_aolserver will fork a separate process to run the proc, instead of running the proc in the scheduler process.

• ns_info pageroot returns the value from nsd.ini, but the DocumentRoot from httpd.conf is what matters. Make sure you keep them in sync.

• No debug support in ADPs. Only the fancy ADP parser is supported.

• The ns_conn subcommands authpasswd, contentlength, and protocol are not implemented. ns_conn url drops PATH_INFO. This should not affect ACS since everything goes through the abstract URL system anyway.

• ns_url2file drops PATH_INFO. This doesn't appear to affect ACS.

• [ns_server active] always returns "". Other commands are not supported.

• ns_atclose doesn't work for scheduled procs.

• ns_configsections is not supported. The sets returned by ns_configsection don't nest. For example, [ns_set get [ns_configsection ns/foo] bar] will not be the set returned by [ns_configsection ns/foo/bar].

• [ns_set split] is not supported. [ns_set -persist] is only supported during initialization.

• ns_geturl just invokes ns_httpget. ACS only uses this in one place. We should fix ACS to just use ns_httpget.

• ns_log and ns_modlog send everything to the Apache error log. There is no control over specific facilities or log levels.

• The error log watchdog doesn't work because the Apache/mod_aolserver error log format is different from AOLserver's, and the watchdog parser only understands the AOLserver format.

• ns_checkurl and ns_requestauthorize are no-ops.

• For other unimplemented commands, look at tclcmds.c. For example, some socket-related commands, cache commands, and other things like ns_fork and ns_rollfile are not implemented.

• With mod_aolserver's implementation of Ns_Set, you need an Ns_SetTrunc(.., 0) to actually reclaim storage for anything that's been put in the set in the meantime (due to use of the Apache pools). The result is that right now, a select consumes the storage required for all rows retrieved before it is finally reclaimed. It may be easier to fix this in the set code than the driver (I'd need something that wipes the values without affecting the keys; I could then just call that from Ns_GetRow), but it needs some attention.

  Solution: Redo ns_sets so that the ns_set structure itself is not in the OWN_POOL, if we have one; then we can clear the pool containing the real_table without flushing and potentially invalidating the ns_set structure itself. (Right now, we make the correct but dicey assumption that --- *without* ALLOC_USE_MALLOC --- we will reallocate the ns_set structure right on top of its original location, so that pointers to it will remain valid).

• Database drivers. It would be nice if we could use exactly the same drivers as AOLserver and dynamically load them.

• (25)Inappropriate ioctl for device: - I keep seeing this message in my error log (on Linux). Harmless but annoying.

• Does the scheduler die? It sometimes trips spuriously when its parent is being debugged, but I haven't got it to die when running "au naturel". Still, the location when it does coredump is suspicious --- a sprintf into interp->result.

• ns_server active --- requires extended status; and won't give full URLs even then (you only get the first few dozen bytes of the request, so long request lines will be truncated). Currently stubbed out.

• ns_write header reparsing (hey rst, why? - mayoff)

• run registered procs in an ordinary response handler, not (like filters) in fixups

• Look at diffs between aolserver 3.0b61 and 3.0 final; anything new we want to drag in?

• ns_returnfile needs if-modified-since support.

• Figure out "invalid method" errors when a POST to an ADP script encounters a tcl syntax error...

• properly seed the random number generator