Basic Configuration

This document contains information for initial and/or basic configuration of
automx.

automx reads runtime behaviour and all settings controlling a domains account
provisioning from a single configuration file. By default automx expects to
find this file at /etc/automx.conf.

Format

The general format of the automx.conf file is as follows:

  • The basic element contained in an INI file is the property. Every property
    has a name and a value, delimited by an equals sign (“=”). The name appears
    to the left of the equals sign.
  • Properties are grouped into sections. The section name appears on a line by
    itself, in square brackets (“[” and “]”). All properties after the section
    declaration are associated with that section. There is no explicit “end of
    section” delimiter; sections end at the next section declaration, or the
    end of the file. Sections may not be nested.
  • Section and property names are case sensitive.
  • A line with a number sign (“#”) begins a comment. Anything following a
    number sign will be ignored by automx.

Sections

Sections create a namespace in which properties specific to a domain are
defined. The section name identifies the domain. The three section names
[automx], [DEFAULT] and [global] are reserved for special purposes within
automx.

[automx]

Controlling automx Runtime Behaviour

This section is mandatory - it lists all options controlling automx runtime
behaviour. The properties provider and domains are also mandatory. Usage of
memcache and all of its associated properties is highly recommended.

[automx]

The following example shows a typical [automx] section setup:

[automx]
provider = example.com  1
domains = *  2
logfile = /var/log/automx/automx.log  3
debug = yes  4
memcache = 127.0.0.1:11211  5
memcache_ttl = 86400
client_error_limit = 5  6
rate_limit_exception_networks = 127.0.0.0/8, ::1/128  7

1
    The provider property configures automx to identify the webservice as
    example.com.
2
    The wildcard option * used in domains instructs automx to answer any
    configuration request regardless of the domain sent by the mail client.
3
    All log information should go to /var/log/automx/automx.log.
4
    Debugging is enabled and infos will be sent to logfile.
5
    Statistical data controlling errors caused by clients accessing database
    backends will be sent to the specified memcache service.
6
    In this example a client may not cause more than 5 errors before automx
    will refuse to answer further queries.
7
    Clients listed in rate_limit_exception_networks are excluded from rate
    limiting.

[DEFAULT]

Properties present in all other sections

This section is optional. Settings in this section define properties which will
be present in all other sections. It is useful to avoid redundancy.

[DEFAULT]

The following example shows a typical [DEFAULT] section setup:

[DEFAULT]
action = settings  1
account_type = email  2
account_name = Example Inc.  3
account_name_short = Example  4

1

    The default action for automx is to provide account settings.

    Note

    The Microsoft schema forsees other actions that account provisioning.

2
    The account_type should be an email account.
3
    The account should show up as Example Inc. in the clients account list.
4
    The accounts short name should be Example.

[global]

A global backend

Setting this section is mandatory, but it may remain empty. It provides a
backend, which will be used whenever automx should serve a domain, but no
section with domain-specific settings has been specified.

Other sections may either explicitly or implicitly refer to the [global]
section as a whole. An explicit reference specifies global as backend property.
Implicit references simply announce the domain in automx' domains list and omit
an explicit section definition for that domain.

    Note

    This is useful when many domains should use the same backend or when automx
    domain property configures it to run as wildcard service.

[global]

The following example configures automx to query a LDAP directory service.
Refer to automx_ldap(5) for a detailed discussion of parameters and their
meaning:

[global]
backend = ldap

account_name = ${cn} (Example Inc.)
display_name = ${givenName} ${sn}

smtp = yes
smtp_server = mail.example.com
smtp_port = 587
smtp_encryption = starttls
smtp_auth = plaintext
smtp_auth_identity = ${mail}
smtp_expiration_date = 2012-12-31
smtp_refresh_ttl = 0
smtp_default = yes

imap = yes
imap_server = mail.example.com
imap_port = 993
imap_encryption = ssl
imap_auth = plaintext
imap_auth_identity = ${mail}
imap_expiration_date = 2012-12-31
imap_refresh_ttl = 0

pop = no
pop_server = mail.example.com
pop_port = 995
pop_encryption = ssl
pop_auth = plaintext
pop_auth_identity = ${mail}
pop_expiration_date = 2012-12-31
pop_refresh_ttl = 0

host = ldap://ldap.example.com
base = ou=people,dc=example,dc=com
result_attrs = mail, cn, givenName, sn
scope = sub
filter = (&(objectClass=*)(uniqueIdentifier=%s))

bindmethod = sasl
saslmech = EXTERNAL
usetls = yes
reqcert = demand
cert = /etc/ssl/certs/mail.example.com.crt.pem
key = /etc/ssl/private/mail.example.com.key.pem
cacert = /etc/ssl/certs/ca-certificates.crt

Authors

Christian Rößner <cr@sys4.de>
    Wrote the program.
Patrick Ben Koetter <p@sys4.de>
    Wrote the documentation.