archiveopteryx.conf(5) Archiveopteryx Documentation archiveopteryx.conf(5)NAMEarchiveopteryx.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 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 clients.
This is 2 by default.
The server-processes setting should be about as large as the
number of CPU cores 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, to which
the jail-user should have minimal rights (only o+x permissions).
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://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 you set use-security, message-copy-
directory must be a subdirectory of jail-directory.
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 with 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.
use-imap-quota
must be enabled for archiveopteryx(8) to support the IMAP QUOTA
extension. This quota is not enforced and is recommended to be
disabled on large mailboxes. The default is true.
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.
use-pops
controls whether archiveopteryx(8) should also accept SSL-
wrapped POP connections. The default is false (and the use of
STARTTLS over the standard POP port is strongly recommended
instead).
pops-address
is the address where archiveopteryx(8) listens for new SSL-
wrapped connections. As with pop-address, the default is an
empty string, which means all available IPv4 and IPv6 addresses.
pops-port
is the port where archiveopteryx(8) accepts SSL-wrapped
connections, 995 by default.
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.
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.pem.
tls-certificate-label
is not used in 3.1.4.
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.2.0, released 2014-03-10,
http://archiveopteryx.org/3.2.0
SEE ALSOarchiveopteryx(8), deliver(8), logd(8), http://archiveopteryx.org
aox.org 2014-03-10 archiveopteryx.conf(5)
