Archiveopteryx configuration

Archiveopteryx has almost a hundred configuration variables now, which can be set in two different configuration files.

Configuration files

installer generates default configuration files, but you may want to change them.

Both files are located in CONFIGDIR, which is often /usr/local/archiveopteryx but may have another value. The command aox show build reports the compiled-in value.

archiveopteryx.conf is the main configuration file. It governs almost all operations of the archiveopteryx server and its helpers. It must be readable for the server, but should not be readable for ordinary users, since it contains a valuable password (db-password).

aoxsuper.conf contains a few variables which the server should not be allowed to access, most importantly db-owner-password. Anyone who knows that password can delete mail. The aox administration program accesses aoxsuper.conf.

General Settings

hostname is detected at server startup, and is usually correct.

use-ipv4 and use-ipv6 are both true by default, although use-ipv6 is set to false if there is a problem with IPv6.

undelete-time decides how long the command aox undelete can recover deleted mail. The default is usually good.

memory-limit specifies how much RAM Archiveopteryx can use. Archiveopteryx tries to keep below the limit, but may be above sometimes.

Database Access

db is the type of database, only Postgres. db-address and db-port determine where to connect to the Postgres server. db-name is the name of the database where mail is stored, and db-schema is the schema used by all Archiveopteryx tables.

db-user and db-password are the login data the archiveopteryx server uses to connect to the database. This should provide some access, but not too much. aox grant privileges ensures that the correct privileges are present.

db-max-handles and db-handle-interval govern how many connections Archiveopteryx can open to the database, and how quickly the number of connections should adapt to changing load.


logfile decides where logging is stored. You may want to change this, and perhaps add it to logrotate, newsyslog or similar. You can also use syslog by setting the right value here.

log-level decides how verbosely Archiveopteryx logs.

The other three variables are usually acceptable: log-address and log-port ser the address of the internal log server, logfile-mode is the permissions of the created logfile (inoperative if syslog is used).

A monitoring interface allows Nagios, rrdtool and similar tools to log detailed inforation about Archiveopteryx. In order to use this, use-statistics has to be enabled, and statistics-address and statistics-port may need changing.


security is enabled by default, and we strongly suggest leaving it enabled.

If security is enabled, the server runs in a chroot jail and performs various checks to ensure that it cannot do much harm. For example, it checks that it cannot delete mail.

jail-directory, jail-user and jail-group are used to drop privileges.

allow-plaintext-access decides whether mail access is permitted without encryption.

entropy-source is usually /dev/urandom, but can be set to /dev/random if desired.

Cluster Configuration

server-processes only needs to be changed on servers with several CPUs, where Archiveopteryx should use more than one.

User Authentication

Five variables determine which SASL mechanisms are offered: auth-digest-md5, auth-cram-md5, auth-login, auth-plain and auth-anonymous. The defaults are usually good.

allow-plaintext-passwords determine whether Archiveopteryx accepts a cleartext password or not. If e.g. auth-plain is enabled but allow-plaintext-passwords is not, then auth-plain is available only on encrypted connections.

Starting with Archiveopteryx 3.1, it is possible to use an LDAP server for authentication as well as storing passwords in the database. The ldap-server-address and ldap-server-port addresses determine which LDAP server Archiveopteryx uses.

Mail delivery

The usual way to deliver mail into Archiveopteryx is via LMTP. use-lmtp determines whether Archiveopteryx serves LMTP, and lmtp-address and lmtp-port determines the server address. The defaults are usually fine.

It is also possible to use SMTP in place of LMTP, since some MTAs do not include LMTP clients. In that case, use-smtp must be enabled. smtp-address and smtp-port should be fine.

Archiveopteryx supports subaddressing. User Nirmala with main address can create subaddresses such or and use them at once. These subaddresses do not have to be registered anywhere.

If use-subaddressing is enabled, Archiveopteryx divides the localpart into two (nirmala and amazon in the example) using the address-separator and delivers the mail to nirmala. Nirmala can handle the subaddress (amazon) in her Sieve script using the Subaddress extension.

The default address-separator is magic (starting with 3.1.3), and you can use both + and -. We recommend leaving the default untouched.

The soft-bounce variable can be used to limit the consequences of a configuration problem. If enabled, all permanent errors become temporary, so that the LMTP/SMTP client will retry later.

Archiveopteryx can store copies of some or all incoming mail to the file system before parsing, if message-copy is set. The copies are stored in message-copy-directory.

SMTP Submission

Archiveopteryx can function as a submission server for outgoing mail. The submission documentation includes a discussion of whether you should use this feature.

use-smtp-submit must be enabled to support SMTP submission. smtp-submit-address and smtp-submit-port determine where users connect to Archiveopteryx to submit their mail. smarthost-address and smarthost-port determine where Archiveopteryx to forward the mail.

Some clients (most notably Microsoft Outlook) prefers to use a protocol called SMTPS instead of SMTP submission. Archiveopteryx supports it if use-smtps is enabled. smtps-address and smtps-port determine where Archiveopteryx will listen.

If either use-smtp-submit or use-smtps is enabled, then two more variables come into play:

check-sender-addresses restricts the sender addresses users can use. If this is enabled, then outgoing mail can safely be signed by the site using e.g. DKIM.

If submit-copy-to-sender is enabled, then the sender always gets a copy of his/her own outgoing mail. This can be useful to ensure that the mail archive is complete.


The IMAP protocol is the usual way to access mail stored by Archiveopteryx. use-imap determines whether to serve IMAP, and use-imaps whether to serve IMAP over SSL (port 993). imap-address and imap-port determine where Archiveopteryx listen for IMAP connections, and imaps-address and imaps-port do the same for IMAP over SSL.

The defaults are normally fine, perhaps except for use-imaps.


The POP server in Archiveopteryx is perfectly adequate, if accessing the main inbox is all that's needed. POP does not offer a way to access other mailboxes.

use-pop, pop-address and pop-port work as for IMAP. There is normally no need to change them.


Sieve is the script language Archiveopteryx uses to process inbound mail and decide whether and where to file, forward or otherwise respond to it.

There are only three variables, none of which should need changing: use-sieve. managesieve-address and managesieve-port.


use-tls determines whether Archiveopteryx offers to use TLS, and tls-certificate names the file containing its certificate and private key.

About this page

Last modified: 2011-05-17