Configuration

Overview

Where does the configuration for a configuration server live? In itself, of course.

In fact, it lives in a dataset /vendor.infotrope.acapd/site/, which itself contains the internal ACAP server's configuration, and datasets for external libraries, such as SASL - in /vendor.infotrope.acapd/site/sasl/.

Default Configuration Overview

By default, the server listens to port 674 on ipv6 or ipv4. If this fails, it'll listen to port 1674, 2674, etc.

It'll use default SASL configuration - that is, it'll act as if there were no SASL configuration present, which there isn't.

It won't do STARTTLS. And it won't do auto-provisioning.

All these configuration areas are visible through ACAP.

Configuration

Listening

Any entry in the main dataset which looks like a listen will be treated as one - the only special one is "fallback", which is automatically generated if the server is unable to listen to any other configured listeners.

A listen should have the following attributes:

vendor.infotrope.acapd.network.family
The family, one of "ipv4", "ipv6", or "unix".
vendor.infotrope.acapd.network.address
The network address, in traditional form. Hence for ipv4, it'll be dotted quad, for ipv6, it'll be dead::beef
vendor.infotrope.acapd.transport.family
Ignored for UNIX. For ipv4 and ipv6, this must be "tcp".
vendor.infotrope.acapd.transport.address
Ignored for anything but "tcp", for which this must be a port number in decimal.

Listen entries may be called anything - they can even clash with existing option entries, although that's not really recommended.

Simple Options

Options have a single attribute, "vendor.infotrope.acapd.value". All SASL options are simple options, as well as many ACAP server options.

Auto provisioning

If the value of the option "auth_provision" is "1", then attempted authenticate commands with PLAIN with a non-existent user will cause the creation of that user, with the supplied password. If an attempt at authetication with another mechanism fails because the user doesn't exist, it'll issue TRANSITION-NEEDED, which (should) cause the client to retry with PLAIN.

If you're going to do this, make sure you're using auxprop/sasldb, and offer TLS.

TLS Configuration

For RFC2595 support, you'll need a single option "tls_certificate", with a value of a full path to the TLS certificate, in PEM format, with both public and private keys present. It's a bit naff, but enough to get it working.

I'll eventually sort this one out.

Backup configuration

The server writes dump files whenever it has to create or delete (or rename) a dataset, and then 'appends' tran files to these when an entry is created, deleted, or changed. Additionally, it now writes out a dump file as well as a tran file after every ten transactions.

By default, it'll keep 10 older dump files (and associated tran files) about, in case the last dump failed for some reason.

"max-dump-files" will change this. Changing it to 0 is not recommended, as you'll delete the dump file immediately after writing, which would be stupid.

The default, while not wholly sensible, isn't too bad. I'd set it at around 3.

SASL Configuration

It is highly recommended to either know what you're doing to an extreme level, or else, before tweaking SASL configuration, make absolutely certain you've backed up the data directory. (Just a 'cp' or 'tar' will do fine.)

General SASL options are held in /vendor.infotrope.acapd/site/sasl/, and options for specific mechanisms (and possibly plugins) are held within subdatasets named after the plugin. So, for instance, the DIGEST-MD5 options are held within /vendor.infotrope.acapd/site/sasl/DIGEST-MD5/.

You can change any of them, but some options may require a restart of the server to reinitialize SASL - killing the metaserver (or real server) with a HUP is enough to do this, although you can kill the real server with KILL just to show off stability if you like.

The options available are listed at http://asg.web.cmu.edu/cyrus/download/sasl/options.html.

Changing Configuration theough ACAP

See the example on the Bootstrap page.


Dave Cridland
Last modified: Tue Nov 30 10:40:06 GMT 2004