archiveopteryx.conf(5)

NAME
archiveopteryx.conf - configuration file for Archiveopteryx.

SYNOPSIS
/usr/local/etc/archiveopteryx/archiveopteryx.conf

DESCRIPTION

The archiveopteryx.conf file contains most global configuration settings for Archiveopteryx. It is read by each server at startup. Syntax errors, unknown variables, and other errors are logged via logd(8).

archiveopteryx.conf and its sibling aoxsuper.conf(5) are usually created at installation time, by running /usr/local/libexec/aox/installer.

There is only one required variable, namely db-password.

SECURITY NOTE
Anyone who can read archiveopteryx.conf can see the database user password, and use this password to read all mail and in many cases even delete mail.

By default, archiveopteryx.conf is readable only by root.

SETTINGS

All settings share a common format:

    name = value # comment

For the *-address variables, the value may be either a hostname, an IPv4 or IPv6 address, the fully-qualified path to a Unix socket. For imap-address and a few other variables, the empty string is also allowed, meaning "all IPv4/6 addresses of this host".

  General Settings

hostname
    Most of the servers need to know the fully-qualified hostname. The default is computed at runtime and is normally acceptable.

    Note that if the name is "localhost", there may be problems with TLS. An IMAP/POP/SMTP/HTTP client may refuse a server certificate for "localhost" if it already has seen a different certificate for "localhost". We strongly suggest using a different hostname.

use-ipv4
    decides whether the various servers accept IPv4 connections. true by default.

use-ipv6
    decides whether the various servers accept IPv6 connections. true by default.

undelete-time
    is the number of days a message can be undeleted after being deleted, 49 by default.

server-processes
    is the number of processes started to serve IMAP/POP/HTTP clients. This is 1 by default. 1 is suitable for a small server.

    The server-processes setting should be about as large as the number of CPUs available, perhaps a little larger. We advise asking info@aox.org in unusual cases.

  Database Access

db  The type of database. The default, postgres, is currently the only supported value.

db-address
    The address of the database server. The default is 127.0.0.1.

db-port
    The port number of the database server. The default is 5432.

db-name
    The name of the database to use. The default is archiveopteryx.

db-schema
    The name of the schema in the database where the database objects are installed. The default is public. It is safe to ignore this setting.

db-user
    The name of the unprivileged Postgres user that the servers ordinarily use. The default is aox.

db-password
    The database password used for the db-user. The default is an empty string.

    Unless a password is specified, Archiveopteryx sets up a randomly-chosen password and writes it to the configuration file during installation.

db-max-handles
    The maximum number of database handles that Archiveopteryx may open. The default is 4.

    The server creates one handle at startup, and may create others if the load justifies it (and as controlled by db-handle-interval). Note, however, that when running with security=on, new database handles can be created only if you connect to the server using TCP/IP, not via Unix sockets. In the latter case, the server must use the first handle throughout its lifetime, since the socket is no longer accessible after chroot.

db-handle-interval
    The minimum interval (in seconds) between the creation of new database handles. The default is 120.

  Logging

log-address
    The address of the log server. The default is 127.0.0.1.

log-port
    The port number at which logd(8) listens, and to which the other servers connect. The default is 2054.

logfile
    tells logd(8) where to write log events. It may be set to an absolute file name (starting with '/'), or to "syslog/category" (e.g. "syslog/local2"), which logs via syslog(2), or to -, which causes everything to be logged to stdout. The default is to log to syslog/mail.

logfile-mode
    is 400 by default and controls the permissions used by logd(8) if it creates logfile. The format (three octal digits) is the same as that used by chmod(1).

log-level
    may be set to debug, info, significant, or error, in increasing order of severity (it is significant by default). If a message is logged with this severity or above, the log server writes it to the logfile immediately. Messages with lower severity are discarded.

  Security

security
    is enabled by default, and should be enabled whenever Archiveopteryx is used in production. It causes the servers to lock themselves into a chroot jail and run with very limited unix and database privileges. Most notably, they cannot open files or delete messages.

    Turning security off has exactly one advantage: it simplifies debugging.

allow-plaintext-access
    controls whether it is possible to read mail via an unencrypted connection. The default value is always. If this is changed to localhost, plaintext connections are permitted only from the host itself. If it is changed to never, TLS is necessary to read mail.

jail-directory
    is /var/db/aox/jail by default. On startup, each secure server uses chroot(2) to jail themselves into this directory, which should be empty and unreadable to jail-user.

jail-user
    is the user name under which the servers run, and is aox by default. On startup, the servers change UID to this user. This user should not have read or write access to the jail directory.

jail-group
    is the group name under which the servers run, and is aox by default. On startup, the servers change GID to this user.

entropy-source
    is the fully-qualified name of a file that acts as a source for random bytes, whenever they are needed (e.g. SASL challenges). Set to /dev/urandom by default. If this is instead set to /dev/random, Archiveopteryx never uses anything less than perfectly random numbers. In this case, make sure that there's enough entropy, or else a series of rapid login attempts can block the entire server.

  User Authentication
http://www.archiveopteryx.org/sasl describes SASL and authentication in more detail.

allow-plaintext-passwords
    controls whether the servers permit plaintext passwords, and how such passwords are handled. May be set to always (which is the default) or never. (Future versions of Archiveopteryx will offer more settings.)

auth-digest-md5
    controls whether the servers offer the digest-md5 SASL mechanism. Disabled by default due to interoperability problems.

auth-cram-md5
    controls whether the servers offer the cram-md5 SASL mechanism. Enabled by default.

auth-plain
    controls whether the servers offer the plain-text SASL mechanism. Enabled by default.

    Note that disabling auth-plain doesn't disable all plaintext passwords, since SASL isn't always used. To disable plaintext passwords, use the allow-plaintext-passwords variable above.

auth-anonymous
    controls whether the servers offer anonymous login, disabled by default.

  Mail delivery

use-lmtp
    controls whether archiveopteryx(8) should accept mail via LMTP (RFC 2033). The default is enabled.

lmtp-address
    specifies the address where archiveopteryx(8) should listen for LMTP connections, and to which deliver(8) should connect. The default is 127.0.0.1.

lmtp-port
    specifies which port archiveopteryx(8) should listen to, and which port deliver(8) should connect to. The default is 2026.

use-smtp
    controls whether archiveopteryx(8) should accept mail via SMTP/ESMTP (RFC 2821/1869). SMTP is disabled by default.

smtp-address
    specifies the address where archiveopteryx(8) should listen for SMTP connections The default is an empty string, which means all available IPv4 and IPv6 interfaces.

smtp-port
    specifies which port archiveopteryx(8) should listen to. The default is 25.

use-subaddressing
    controls whether messages addressed to user+tag@example.org are accepted for delivery to user@example.org (if the latter is a valid recipient address). The default is false.

address-separator
    is the character that separates the username from the subaddress in a localpart, e.g. the + in user+tag@example.org. The default, which you should not need to change, is +. This setting is relevant only if use-subaddressing is true.

soft-bounce
    specifies whether a delivery problem causes a message to be rejected permanently (soft-bounce disabled) or queued at the MTA (soft-bounce enabled). This is enabled by default. We recommend disabling it when you are confident that mail delivery works.

message-copy
    specifies whether or not to keep filesystem copies of incoming messages, e.g. to burn a mail log to CD/DVD regularly. The default value of none means that no copies are ever made.

    Setting it to delivered keeps copies of all delivered messages, a value of errors keeps only those messages that could not be delivered because of errors, and all keeps copies of all messages.

message-copy-directory
    specifies a directory to which mail delivered via LMTP/SMTP is copied, if message-copy is set. Its default value is /var/db/aox/messages.

    If message-copy-directory does not exist or is not writable, Archiveopteryx logs an error at startup and exits.

    Each file in message-copy-directory contains one or more header lines, namely Error, From and To, then an empty line, then the verbatim received mail message. If there is an Error line, the message was not delivered, and the rest of the line describes the problem.

    The file's name is a unique string of numbers and hyphens. It ends with "-err" if there was an error injecting the message into the database.

  SMTP Submission

use-smtp-submit
    controls whether archiveopteryx(8) should accept mail via SMTP-Submit (RFC 4409). The default is enabled.

check-sender-addresses
    controls whether archiveopteryx(8) should check whether the sender is authorised to use the addresses in the message. From, Sender, Return-Path (SMTP Mail From) and Reply-To are all checked. The default is disabled.

submit-copy-to-sender
    controls whether archiveopteryx(8) should ensure that the sender receives a copy of outgoing mail. The default is disabled. This can be used to ensure that all outgoing mail is archived.

    If the sender already receives a copy of the message, submit-copy-to-sender has no effect. Senders will not receive two copies. The copy is always sent to the user who sends the message, even if the From and/or Return-Path is different. The sender's copy will be delivered through the configured smarthost, as with any other outgoing message.

smtp-submit-address
    specifies the address where archiveopteryx(8) should listen for Submit connections. The default, an empty string, means to listen on all available IPv4 and IPv6 addresses. 127.0.0.1.

smtp-submit-port
    specifies which port archiveopteryx(8) should listen to. The default is 587.

smarthost-address
    specifies the address of the SMTP server which is used to relay mail to remote recipients. The default is 127.0.0.1.

smarthost-port
    specifies the port to use when forwarding mail to a smarthost. The default is 25. (These defaults thus conflict with the default values of smtp-address and smtp-port when use-smtp is enabled.)

use-smtps
    controls whether archiveopteryx(8) should accept SSL-wrapped SMTP connections. The default is false (and the use of STARTTLS with SMTP Submit is strongly recommended instead).

smtps-address
    is the address where archiveopteryx(8) listens for new SSL-wrapped SMTP connections. As for smtp-address, the default is an empty string, which means all available IPv4 and IPv6 addresses.

smtps-port
    is the port where archiveopteryx(8) accepts SSL-wrapped SMTP connections, 465 by default.

  IMAP

use-imap
    must be enabled for archiveopteryx(8) to accept IMAP connections. The default is true.

imap-address
    is the address where archiveopteryx(8) listens for new connections. The default, an empty string, means to listen on all available IPv4 and IPv6 addresses.

imap-port
    is the port where archiveopteryx(8) accepts connections, 143 by default.

use-imaps
    controls whether archiveopteryx(8) should also accept SSL-wrapped IMAP connections. The default is false (and the use of STARTTLS over the standard IMAP port is strongly recommended instead).

imaps-address
    is the address where archiveopteryx(8) listens for new SSL-wrapped connections. As for imap-address, the default is an empty string, which means all available IPv4 and IPv6 addresses.

imaps-port
    is the port where archiveopteryx(8) accepts SSL-wrapped connections, 993 by default.

  POP

use-pop
    must be enabled for archiveopteryx(8) to accept POP3 connections. The default is false.

pop-address
    is the address where archiveopteryx(8) listens for new connections. The default, an empty string, means to listen on all available IPv4 and IPv6 addresses.

pop-port
    is the port where archiveopteryx(8) accepts connections, 110 by default.

  HTTP

use-http
    decides whether Archiveopteryx offers HTTP service at all, and is no by default.

http-address
    is the address where archiveopteryx(8) listens for new connections. The default is 127.0.0.1.

http-port
    is the port where archiveopteryx(8) accepts connections, 8808 by default.

use-https
    decides whether Archiveopteryx offers HTTPS (SSL-wrapped HTTP) service, and is no by default.

https-address
    is the address where archiveopteryx(8) listens for new HTTPS connections. The default is 127.0.0.1.

https-port
    is the port where archiveopteryx(8) accepts connections, 8443 by default.

accept-any-http-host
    decides whether archiveopteryx(8) accepts any hostname supplied by the client, and is enabled by default. Properly speaking, it would be better to disable this, but that would add complexity without giving anything in return.

use-web-archive
    decides whether archiveopteryx provides web-visible archives of world-readable mailboxes. The default is false and for the moment we recommend leaving it at false. This code is not ready for production use.

archive-prefix
    is the common prefix for all URLs offering archive access to mailboxes via the web. These mailboxes must be readable by the anonymous user. The default value is empty.

use-webmail
    ldecides whether archiveopteryx provides webmail access. The default is false and we strongly recommend leaving it at false. Don't enable this.

webmail-prefix
    is the common prefix for all URLs offering authenticated webmail access to mailboxes via the web. The default value is /webmail.

webmail-css-url
    points to the style sheet used for webmail and archive pages. The default value is http://www.archiveopteryx.org/webmail/default.css. By using a different URL you can change the appearance of the pages completely.

webmail-js-url
    points to a javascript which will be included in all webmail and archive pages. The default is an empty string, which means to not include any external javascript. This can be used together with webmail-css-url to change the behaviour of the webmail and archive pages.

favicon-url
    is the URL of the favicon displayed for your site by many web browsers. The default value is http://www.archiveopteryx.org/favicon.ico, but you can change it to anything. When the browser requests the favicon, archiveopteryx(8) responds with a redirect to this URL.

  SIEVE

use-sieve
    controls whether or not the managesieve server is started. The default is enabled.

managesieve-address
    specifies the address where archiveopteryx(8) should listen for connections. The default is an empty string, which means to listen on all available IPv4 and IPv6 addresses. anempt

managesieve-port
    specifies which port archiveopteryx(8) should listen to. The default is 2000.

  TLS

use-tls
    regulates whether Archiveopteryx supports TLS at all. The default is enabled.

tls-certificate
    is the absolute file name of the TLS private key and signed certificate, e.g. /usr/local/etc/archiveopteryx/imap.p15. If tls-certificate is not specified, tlsproxy generates a private key and a self-signed certificate at runtime and stores both in /usr/local/etc/archiveopteryx/automatic-key.p15.

tls-certificate-label
    is a label that uniquely identifies the key and certificate to use in the PKCS #15 key file identified by tls-certificate (which can contain multiple key pairs). By default, this is empty, and the current hostname is used as a label.

tls-certificate-secret
    is a secret password used to access the appropriate key and certificate in the PKCS #15 key file identified by tls-certificate.

tlsproxy-address
    is the address where tlsproxy(8) listens for new connections. The default is 127.0.0.1.

tlsproxy-port
    is the port where tlsproxy(8) accepts connections, 2061 by default.

SYNTAX

The name is case insensitive, as shown:

    hostname = test1.example.com
    HOSTNAME = mailserver.example.org

The value is case insensitive wherever possible. (Exceptions include logfile, db-user and db-password.)

There are three datatypes: Strings, numbers and toggles.

Strings may be written as a single unquoted word or quoted with either single or double quotes, as shown in these three examples:

    db-password = single.word
    db-password = "rock'n'roll" # a 12-character password
    db-password = 'two words, quoted' # a 17-character one

Only single-line strings can be used. Single-word strings may contain the characters a-z, A-Z, 0-9, dot, hyphen and slash.

Numbers are integers not smaller than 0 and not larger than 2147483647 (ie. 31-bit unsigned integers).

Toggles are written as a single word. Yes, true, on, 1, and enabled all mean that the toggle is enabled, while no, false, off, 0, and disabled unsurprisingly mean disabled. Toggles are case-insensitive.

    use-lmtp = yes
    crash-and-delete-all-the-mail = off

Spaces are allowed at the start of the line, before and after '=', and after the value. Comments extend from '#' to the end of the line.

    # this is a comment
    hostname=stuff.nonsense.example.com # also a comment
     logfile = /dev/null# and this is a comment
    # empty lines are ignored

AUTHOR
The Archiveopteryx Developers, info@aox.org.

VERSION
This man page covers Archiveopteryx version 3.1.3, released 2010-03-10, http://www.archiveopteryx.org/3.1.3

SEE ALSO
archiveopteryx(8), deliver(8), logd(8), tlsproxy(8), http://www.archiveopteryx.org