Magma Soft (magma), Aolserver

Aolserver is a power- and featureful webserver.

Magma Soft has developed a configuration managment for Aolserver, which allows almost-no-effort configuration of multiple virtual domains, by just editing one configuration file: domains.cfg.

The same configuration file is used by the startup script run of the server, to pre-bind to the respective ports and addresses.

Standard SSL, CGI, LDAP and database configuration for nsopenssl nsldap and nspostgres is provided too.

WebDAV support has been added, as well as a new aproach to permission handling for Basic-Authentication via nsperm.

Each virtual server can be configured completely externally, and/or the SSL, CGI, and database configuration can selectively be sourced in from external files.

Minimal configuration example:

  server magma.com.ni "Magma Soft" {
     fqdn   www.magma.com.ni
     http   yes
  }

Go to the MagmaSoft Wiki for News about aolconf.

Files

We are trying to follow the FHS - Filesystem Hierarchy Standard - If not otherwise specified the files go into /usr/lib/aolserver4, or a similar directory, where your aolserver libraries live (see a discussión on directories later).

domains.cfg:

configure the virtual domains in this file. The provided example includes anotations documenting all available options. This file has to be installed in /etc/aolserver4 unless you change run and main.tcl acordingly.

run:

Supervise runscript.

aolserver4-init:

System V like runscript. This has to be installed in /etc/init.d or the respective place for your operating system, and linked to from the /etc/rc*.d directories. Note: you should only run the Supervise runscript or this script to start Aolserver, but not both at the same time.

main.tcl: this is the main configuration script, which is sourced in by the server. It loads first domains.cfg than the other configuration files on demand and finally configures main parameters of the server.

server.tcl:

Handles the individual server configuration. It sources on demand the SSL, CGI, and Database specific scripts an configures the LDAP-Pools for the server. This file can be overridden by the config directive in domains.cfg.

You can include aditional configuration for CGI Script by putting a file named server.cgi in the configuration directory, or by specifying one with the config_cgi directive in domains.cfg.
See magma.com.ni.cgi for an example.

ssl.tcl:

Provides a standard SSL configuration. You have to put the key, cert and ca files in the following location to make it work by default:

keyfile.pem: /etc/aolserver4/certs/server.key
certfile.pem: /etc/aolserver4/certs/server.crt
ca.pem: /etc/aolserver4/certs/server.ca

You can override the ssl.tcl file with the config_ssl directive in domains.cfg.

database.tcl:

When a database directive is present in a server definition in domains.cfg this file is loaded. It configures three database pools as needed by OpenACS.

This can be overriden with the config_db directive in domains.cfg.

tdav.tcl:

This file is sourced when a dav_share directive is present in a server definition in domains.cfg. It requires a list of options to be followed, please read the example file.

You can specify several dav_shares in one server.

To make DAV access work, you also need to install our own version of:

tDAV.tcl:

the tDAV library. Put it into ${serverhome}/modules/tcl or into the tcllib of the respective virtual server.
Please note that this must be installed instead of the tDAV.tcl library provided by the CVS version of Aolserver.

nsperm_init.tcl:

This is a new styled initialization script for the nsperm module. nsperm provides HTTP/1.0 Basic Authentication for the tDAV module.
You can live however without nsperm_init.tcl, and configure the permissions the standard way by putting the files passwd, groups, hosts.allow and hosts.deny into the directory ${serverhome}/servers/${server}/modules/nsperm.

If you want to make use of nsperm_init.tcl you can configure the permissiones in one single file in the directory /etc/aolserver4/perms/${server}.tcl.
To make it work, you just copy nsperm_init.tcl over the file ${serverhome}/modules/tcl/nsperm/init.tcl. One benefit of nsperm_init.tcl is that after initialization of Aolserver, no file is read in, so you can chroot to your pageroot but have the permission files outside of it.

example_perms.tcl:

is an example permissions files for the new permissions configuration approach. You can put it into /etc/aolserver4/perms and create for each server you use the perms module a symlink with the name of the server.
example_perms.tcl provides exactly the same users, groups and passwords as the sample files from the original Aolserver perms module. The tdav.tcl module gives the nsadmin user permissons to access all DAV shares, and denies access to everyone else.

aolserver-php4-cgi-wrapper

This file should be copied to /usr/local/sbin/ to enable php cgi scripts without a php module.

aolconf-1.0.tgz

All the files packed together. Untar and run make install

Documentation

The domains.cfg file is rather extensively anotated. This is the primary source of information not counting the source code.

The setup has been developed and tested on Debian, and deals with the aolserver4 packages provided there. The supervise commands are installed from Gerrit Papes excellent packages. You can either install the unofficial daemontools package, or use the official runit package which is Gerrits GPL'ed drop in replacement.

CGI-Handling and PHP

Debian install CGI's in /usr/lib/cgi-bin and maps them to the url /cgi-bin, this behaviour is reproduced.

Since lot's of legacy utilities are available in PHP, but there is no php-module for aolserver4 in Debian, a Interps section and a wrapper script is provided. With these you can put .php files in any directory map´ed to the nscgi module and they just should work.
aolserver-php4-cgi-wrapper has to be installed under this same name in /usr/local/sbin.

Same has been done for Perl and .pl extensions, however this one needs no wrapper.

Please refer also to our Wiki, which you can find in the /services section of our website. Under "TipsAnd..." You can find setup instructions for Aolserver and OpenACS under the Gnu/Debian Operating System.

Wishlist

RequireSSL for DAV authentication.
ldap 3 support - note that tclLdap-pkg-1.2 seems to work fine.
Issues and Features
grep TODO:
```
  main.tcl:27:# TODO: platform compatibility
  main.tcl:212:    # TODO: if token http but value not yes, do not set up a http socket.
  run:24:# TODO: provide defaults if we don't find a config.
  server.tcl:33:# TODO: make it a parameter.
  server.tcl:101:# TODO: default configuration for other modules
  server.tcl:123:    # TODO: untested
  server.tcl:124:    # TODO: This is clearly not cross platform compatible
  ssl.tcl:7:# TODO: ca files, opcional
  tdav.tcl:31:# TODO: integrate this ones
  
```
- example_perms.tcl syntax is too complicated and elaborate. It should be changed to support something along the lines of:
```
    s_section ns/servers/${server}/modules/nsperm/users
    ns_param aleph     "ubphBI5lDzSYc:primary male"
    ns_param henry     "nopass:Henry Smith"
    ns_param noname    ""
    ...
    
```
- Some care has been taken, to make filename/path construction work across platforms. This has to be tested and expanded though.
- Multiple databases per server can be specified and will be checked by the startup script, however the aolserver configuration just works with one database setup right now.
- Multiple servers: The system is meant to be sourced in just one time, the use of the -s parameter is not supported. Workaround: you can use different directories to run different servers. Further Work to "improve" in this direction could be made upon request.
- No Oracle support.
- tDAV has to be tested and debugged. the "/" URL does not work at all. Clients have problems to access other shares as well.
- Revision of FHS compatibility: the tcl scripts are platform independent and have to go into /usr/share/aolserver4.
  tDAV locks into /var/run/aolserver4/dav/${server}
  tDAV properties into /var/lib/aolserver4/dav/${server}
Debian/sysvinit compatibility
All the .tcl files and run have to be put into the directory /usr/lib/aolserver4 unless you modify run and main.tcl acordingly. The file aolconf/debian-domains.cfg is prepared to start a default server at the loopback interface named main, just the same way as provided by the Debian aolserver4 packages. To make it work you need to create the main servers logdirectory though:
```
  install -d -m 2750 -o www-data -g adm /var/log/aolserver4/main
  
```

Files

Documentation

Wishlist

Issues and Features

Debian/sysvinit compatibility