Fisheye: Tag 1.2 refers to a dead (removed) revision in file `mod_nsd/README.html'. Fisheye: No comparison available. Pass `N' to diff? Index: mod_nsd/README.old.html =================================================================== RCS file: /usr/local/cvsroot/mod_nsd/README.old.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ mod_nsd/README.old.html 6 Jun 2001 06:26:22 -0000 1.1 @@ -0,0 +1,451 @@ +<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> + Fisheye: Tag 1.2 refers to a dead (removed) revision in file `mod_nsd/TODO'. Fisheye: No comparison available. Pass `N' to diff?