<html>
<head>
<title>README for mod_aolserver</title>
</head>
<body>
<h2>README for mod_aolserver</h2>
an Apache module by <a href='mailto:rst@ai.mit.edu'>Robert
S. Thau</a> and <a href='mailto:mayoff@arsdigita.com'>Rob Mayoff</a>
<hr>
This is mod_aolserver release 1.1, an Apache module that emulates enough
of the AOLserver API to run the ArsDigita Community System.
You can try out an ACS installation running on this module at <a
href='http://apache.arsdigita-dev.com/'>http://apache.arsdigita-dev.com/</a>.
That system has bulletin boards for discussing mod_aolserver.
<ul>
<li><a href='#prereqs'>Prerequisites</a>
<li><a href='#install'>Compiling and Installing</a>
<li><a href='#apacheconf'>Configuring Apache</a>
<li><a href='#modconf'>Configuring mod_aolserver</a>
<li><a href='#bugs'>Limitations, Bugs and To-Do</a>
</ul>
<h3><a name='prereqs'>Prerequisites</a></h3>
In order to use this software, you will need these other packages:
<ul>
<li><strong>Apache 1.3.12</strong> or later in the 1.3 series. This module has not
been developed for or tested with any Apache 2.0 release.
<li>Tcl 8.1 or later. <strong>Tcl 8.3</strong> is recommended because that is what
AOLserver 3.0 uses and ACS authors may take advantage of Tcl 8.3
features.
<li><strong>MM Library</strong>. This is a portable shared memory
library.
<li>Either <strong>Oracle 8i</strong> or <strong>PostgreSQL</strong>.
</ul>
You must install these packages before compiling mod_aolserver.
<h4>Apache</h4>
<a href='http://www.apache.org'>Apache is available here.</a>
<p>We developed mod_aolserver as a dynamic shared object, so <strong>you must
compile/install Apache with mod_so</strong> built in. You can determine
whether your Apache has this module by running this command:
<blockquote><pre>httpd -l | grep mod_so</pre></blockquote>
If the output is a line that says <code>mod_so.c</code>, then your
Apache has the required module.
<p>We test with Apache 1.3.12 so you should try to use that or a later
version.
<h4>Tcl</h4>
<a href='http://dev.scriptics.com/'>Tcl is available here.</a>
<p>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 <code>--enable-shared</code>.
<p>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.
<h4>MM</h4>
<a href='http://www.engelschall.com/sw/mm/'>The MM library is available
here.</a>
<p>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.
<p>We tested with MM version 1.1.1.
<p>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.
<h4>Oracle 8i</h4>
<a href='http://technet.oracle.com/'>Oracle 8i is available here.</a>
<p>The <a href='http://www.arsdigita.com/download/'>ArsDigita Community
System</a> 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.
<p>As of release 1.1, mod_aolserver uses ArsDigita's AOLserver Oracle
driver release 2.3.
<h4>PostgreSQL</h4>
<a href='http://www.postgresql.org/'>PostgreSQL is available here.</a>
<p>An intrepid group of programmers are porting the ACS to PostgreSQL;
they call the project "OpenACS". You can download that version from
<a href='http://openacs.org/'>their development site</a>.
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.
<h3><a name='install'>Compiling and Installing</a></h3>
mod_aolserver uses GNU autoconf to configure the build process. You can
type <code>./configure --help</code> to see your options. The important
ones are these:
<ul>
<p>
<li><code>--with-database=<i>dbname</i></code>
<p> (Required.)
You must include this flag when running configure.
<i>dbname</i> must be either <code>ora8</code> or
<code>postgres</code>. (mod_aolserver currently compiles in exactly
one database driver and does not support dynamically-loaded
drivers.)
<p>
<li><code>--with-ora8=<i>dir</i></code>
<p> (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.
<p>
<li><code>--with-postgres=<i>dir</i></code>
<p> (Optional.)
If the PostgreSQL headers and libraries aren't in locations that the
compiler will find automatically, or in <code>/usr/local</code>,
you can use this flag to specify
the PostgreSQL installation directory. The headers should be in
<code><i>dir</i>/include</code> and the libraries in
<code><i>dir</i>/lib</code>, of course.
<p>
<li><code>--with-apxs=<i>dir</i></code>
<p> (Optional.)
Use this flag to specify the full path to the copy of
<code>apxs</code> you want to use to build and install this module,
for example <code>/u/mayoff/test/bin/apxs</code>.
By default, configure will use the first copy of <code>apxs</code>
in your PATH.
<p>
<li><code>--with-tcl=<i>dir</i></code>
<p> (Optional.)
You may include this flag if you've installed Tcl in a non-standard
location. Set <i>dir</i> to the directory containing
<code>tclConfig.sh</code>. Normally that would be something like
<code>/usr/lib</code> or <code>/usr/local/lib</code>.
<p>
<li><code>--with-mm=<i>dir</i></code>
<p> (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
<code><i>dir</i>/include</code> and the MM library should be in
<code><i>dir</i>/lib</code>.
</ul>
<p>In my test environment, I have private copies of Tcl, Apache, and MM,
so my typical configure command looks something like this:
<blockquote><pre>./configure \
--with-database=ora8 \
--with-tcl=/u/mayoff/test/lib \
--with-apxs=/u/mayoff/test/bin/apxs \
--with-mm=/u/mayoff/test
</pre></blockquote>
After running configure, you should just be able to run
<code>make</code>. It will compile the module and install it in your
existing Apache installation using apxs.
<h3><a name='apacheconf'>Configuring Apache</a></h3>
mod_aolserver provides two request handlers:
<ul>
<li><code>aolserver</code> - This handler is for <code>.tcl</code>
files.
<p>
<li><code>adp</code> - This handler is for <code>.adp</code> files.
</ul>
You must enable ExecCGI for these handlers to work. <em>Neither of
these handlers is really necessary if you're running ACS</em>, because
ACS uses <code>ns_register_proc</code> to handle all requests for
<code>.tcl</code> and <code>.adp</code> files anyway.
<p><strong>mod_aolserver needs an AOLserver configuration file</strong>, in either
<code>.tcl</code> or <code>.ini</code> format. You must specify the
location of the file using the <code>AolServerConf config_file</code>
directive in your <code>httpd.conf</code>:
<blockquote><pre>AolServerConf config_file /u/mayoff/test/nsd.tcl
<i>or</i>
AolServerConf config_file /u/mayoff/test/nsd.ini</pre></blockquote>
Either of these files can contain an <code>AuxConfigDir</code>
parameter, which mod_aolserver will process just like AOLserver would.
You'll need that parameter if you want to run ACS.
<p><strong>Here's an
<code>httpd.conf</code> excerpt to get you started.</strong> Assume that I have
installed Apache in <code>/u/mayoff/test</code> and the ACS in
<code>/u/mayoff/test/acs</code>.
<blockquote><pre># 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></pre></blockquote>
This should cause mod_aolserver stuff to run only in the virtual server
containing the AolServerConf directive (or the main server only if you
put it outside a virtual server section). You're probably better off
running this in the main server of a test Apache installation right
now, rather than running it in a virtual server of your production
installation.
<h3><a name='modconf'>Configuring mod_aolserver</a></h3>
<p>Configuring mod_aolserver is pretty straightforward. The module
will load whatever configuration file you specified with the
<code>AolServerConf config_file</code> 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.
<p>A sample configuration file can be found in the mod_aolserver
distribution as <code>tcl_modules/nsd.ini.sample</code>. You should be
able to use that config file, with some site-specific modifications, to
run ACS on Apache.
<p>Be sure to <strong>disable the watchdog in your ACS
configuration</strong> (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.
<p>Also, <strong>if you're using the Oracle database driver, you may
encounter problems if you leave the datasource empty</strong>. 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.
<p>The <strong>workaround for using Oracle</strong> 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,
<code>netasst</code>, 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 <a href='http://apache.arsdigita-dev.com/bboard/'>the
ACS on Apache web site</a> or <a
href='http://photo.net/bboard/q-and-a.tcl?topic=web/db'>Web Tools
Review</a>.
<h3><a name='bugs'>Limitations, Bugs and To-Do List</a></h3>
Send bug reports and other feedback to
<a href='mailto:mod_aolserver@arsdigita.com'>mod_aolserver@arsdigita.com</a>.
<p>
Here are the known limitations, bugs, and to-do tasks.
<ul>
<p><li><strong>Database connections are not pooled</strong> 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.
<p><li>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.
<p><li>ns_register_* and ns_schedule_* only work during server
initialization. ns_cancel, ns_pause, ns_resume, and
ns_unschedule_proc are not implemented.
<p>ACS only registers and schedules procedures as server
initialization time, so this should not cause problems.
<p>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.
<p><li>Preauth filters run after the Apache authorization phase.
<p><li><strong>ns_share does not share data among
processes.</strong> ns_share is deprecated, and ACS is moving away
from its use. Use nsv_* instead, which does share data among
processes.
<p><li>ns_critsec, ns_cond, and ns_sema are not implemented.
<p><li>ns_thread is not implemented.
<p><strong>The bulkmail module will probably not work,</strong> because
it uses ns_thread.
<p>Note that if you call <code>ns_scheduled_proc -thread</code>,
mod_aolserver <strong>will</strong> fork a separate process to run
the proc, instead of running the proc in the scheduler process.
<p><li>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.
<p><li>No debug support in ADPs. Only the fancy ADP parser is
supported.
<p><li>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.
<p><li><code>ns_url2file</code> drops PATH_INFO. This doesn't appear to affect
ACS.
<p><li><code>[ns_server active]</code> always returns "". Other commands are not
supported.
<p><li><code>ns_atclose</code> doesn't work for scheduled procs.
<p><li><code>ns_configsections</code> is not supported. The sets
returned by <cod>ns_configsection</code> don't nest. For example,
<code>[ns_set get [ns_configsection ns/foo] bar]</code> will not be
the set returned by <code>[ns_configsection ns/foo/bar]</code>.
<p><li><code>[ns_set split]</code> is not supported. <code>[ns_set
-persist]</code> is only supported during initialization.
<p><li><code>ns_geturl</code> just invokes ns_httpget. ACS only
uses this in one place. We should fix ACS to just use ns_httpget.
<p><li>ns_log and ns_modlog send everything to the Apache error log.
There is no control over specific facilities or log levels.
<p><li>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.
<p><li>ns_checkurl and ns_requestauthorize are no-ops.
<p><li>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.
<p><li>
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.
<p>
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).
<p><li>Database drivers. It would be nice if we could use exactly the
same drivers as AOLserver and dynamically load them.
<p><li><code>(25)Inappropriate ioctl for device:</code> - I keep seeing
this message in my error log (on Linux). Harmless but annoying.
<p><li>
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.
<p><li>
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.
<p><li>
ns_write header reparsing (hey rst, why? - mayoff)
<p><li>
run registered procs in an ordinary response handler, not (like
filters) in fixups
<p><li>
Look at diffs between aolserver 3.0b61 and 3.0 final; anything new we want
to drag in?
<p><li>ns_returnfile needs if-modified-since support.
<p><li>
Figure out "invalid method" errors when a POST to an ADP script
encounters a tcl syntax error...
<p><li>properly seed the random number generator
</ul>
<hr>
<br><code><font size=-1>$Header: /usr/local/cvsroot/mod_nsd/README.old.html,v 1.1 2001/06/06 06:26:22 petrup Exp $</font></code>
<a href='mailto:mod_aolserver@arsdigita.com'><address>mod_aolserver@arsdigita.com</address></a>
</body>
</html>