maddy/docs/reference/global-config.md

Global configuration directives

These directives can be specified outside of any configuration blocks and they are applied to all modules.

Some directives can be overridden on per-module basis (e.g. hostname).

Syntax: state_dir path
Default: /var/lib/maddy

The path to the state directory. This directory will be used to store all persistent data and should be writable.

Syntax: runtime_dir path
Default: /run/maddy

The path to the runtime directory. Used for Unix sockets and other temporary objects. Should be writable.

Syntax: hostname domain
Default: not specified

Internet hostname of this mail server. Typicall FQDN is used. It is recommended to make sure domain specified here resolved to the public IP of the server.

Syntax: auth_map module_reference
Default: identity

Use the specified table to translate SASL usernames before passing it to the authentication provider.

Before username is looked up, it is normalized using function defined by auth_map_normalize.

Note that auth_map does not affect the storage account name used. You probably should also use storage_map in IMAP config block to handle this.

This directive is useful if used authentication provider does not support using emails as usernames but you still want users to have separate mailboxes on separate domains. In this case, use it with email_localpart table:

    auth_map email_localpart

With this configuration, user@example.org and user@example.com will use user credentials when authenticating, but will access user@example.org and user@example.com mailboxes correspondingly. If you want to also accept user as a username, use auth_map email_localpart_optional.

If you want user@example.org and user@example.com to have the same mailbox, also set storage_map in IMAP config block to use email_localpart (or email_localpart_optional if you want to also accept just "user"):

    storage_map email_localpart

In this case you will need to create storage accounts without domain part in the name:

maddy imap-acct create user # instead of user@example.org

Syntax: auth_map_normalize function
Default: auto

Normalization function to apply to SASL usernames before mapping them to storage accounts.

Available options:

• auto precis_casefold_email for valid emails, precise_casefold otherwise.
• precis_casefold_email PRECIS UsernameCaseMapped profile + U-labels form for domain
• precis_casefold PRECIS UsernameCaseMapped profile for the entire string
• precis_email PRECIS UsernameCasePreserved profile + U-labels form for domain
• precis PRECIS UsernameCasePreserved profile for the entire string
• casefold Convert to lower case
• noop Nothing

Syntax: autogenerated_msg_domain domain
Default: not specified

Domain that is used in From field for auto-generated messages (such as Delivery Status Notifications).

Syntax:
tls file cert_file pkey_file
tls module reference
tls off
Default: not specified

Default TLS certificate to use for all endpoints.

Must be present in either all endpoint modules configuration blocks or as global directive.

You can also specify other configuration options such as cipher suites and TLS version. See maddy-tls(5) for details. maddy uses reasonable cipher suites and TLS versions by default so you generally don't have to worry about it.

Syntax: tls_client { ... }
Default: not specified

This is optional block that specifies various TLS-related options to use when making outbound connections. See TLS client configuration for details on directives that can be used in it. maddy uses reasonable cipher suites and TLS versions by default so you generally don't have to worry about it.

Syntax:
log targets...
log off
Default: stderr

Write log to one of more "targets".

The target can be one or the following:

• stderr

  Write logs to stderr.

• stderr_ts

  Write logs to stderr with timestamps.

• syslog

  Send logs to the local syslog daemon.

• file path

  Write (append) logs to file.

Example:

log syslog /var/log/maddy.log

Note: Maddy does not perform log files rotation, this is the job of the logrotate daemon. Send SIGUSR1 to maddy process to make it reopen log files.

Syntax: debug boolean
Default: no

Enable verbose logging for all modules. You don't need that unless you are reporting a bug.