maddy

  1# Global configuration directives
  2
  3These directives can be specified outside of any
  4configuration blocks and they are applied to all modules.
  5
  6Some directives can be overridden on per-module basis (e.g. hostname).
  7
  8### state_dir _path_
  9Default: `/var/lib/maddy`
 10
 11The path to the state directory. This directory will be used to store all
 12persistent data and should be writable.
 13
 14---
 15
 16### runtime_dir _path_
 17Default: `/run/maddy`
 18
 19The path to the runtime directory. Used for Unix sockets and other temporary
 20objects. Should be writable.
 21
 22---
 23
 24### hostname _domain_ 
 25Default: not specified
 26
 27Internet hostname of this mail server. Typicall FQDN is used. It is recommended
 28to make sure domain specified here resolved to the public IP of the server.
 29
 30---
 31
 32### auth_map _module-reference_
 33Default: `identity`
 34
 35Use the specified table to translate SASL usernames before passing it to the
 36authentication provider.
 37
 38Before username is looked up, it is normalized using function defined by
 39`auth_map_normalize`.
 40
 41Note that `auth_map` does not affect the storage account name used. You probably
 42should also use `storage_map` in IMAP config block to handle this.
 43
 44This directive is useful if used authentication provider does not support
 45using emails as usernames but you still want users to have separate mailboxes
 46on separate domains. In this case, use it with `email_localpart` table:
 47
 48```
 49    auth_map email_localpart
 50```
 51
 52With this configuration, `user@example.org` and `user@example.com` will use
 53`user` credentials when authenticating, but will access `user@example.org` and
 54`user@example.com` mailboxes correspondingly. If you want to also accept
 55`user` as a username, use `auth_map email_localpart_optional`.
 56
 57If you want `user@example.org` and `user@example.com` to have the same mailbox,
 58also set `storage_map` in IMAP config block to use `email_localpart`
 59(or `email_localpart_optional` if you want to also accept just "user"):
 60
 61```
 62    storage_map email_localpart
 63```
 64
 65In this case you will need to create storage accounts without domain part in
 66the name:
 67
 68```
 69maddy imap-acct create user # instead of user@example.org
 70```
 71
 72---
 73
 74### auth_map_normalize _function_
 75Default: `auto`
 76
 77Normalization function to apply to SASL usernames before mapping
 78them to storage accounts.
 79
 80Available options:
 81
 82- `auto`                    `precis_casefold_email` for valid emails, `precis_casefold` otherwise.
 83- `precis_casefold_email`   PRECIS UsernameCaseMapped profile + U-labels form for domain
 84- `precis_casefold`         PRECIS UsernameCaseMapped profile for the entire string
 85- `precis_email`            PRECIS UsernameCasePreserved profile + U-labels form for domain
 86- `precis`                  PRECIS UsernameCasePreserved profile for the entire string
 87- `casefold`                Convert to lower case
 88- `noop`                    Nothing
 89
 90---
 91
 92### autogenerated_msg_domain _domain_
 93Default: not specified
 94
 95Domain that is used in From field for auto-generated messages (such as Delivery
 96Status Notifications).
 97
 98---
 99
100### tls `file` _cert-file_ _pkey-file_ | _module-reference_ | `off`
101Default: not specified
102
103Default TLS certificate to use for all endpoints.
104
105Must be present in either all endpoint modules configuration blocks or as
106global directive.
107
108You can also specify other configuration options such as cipher suites and TLS
109version. See maddy-tls(5) for details. maddy uses reasonable
110cipher suites and TLS versions by default so you generally don't have to worry
111about it.
112
113---
114
115### tls_client { ... }
116Default: not specified
117
118This is optional block that specifies various TLS-related options to use when
119making outbound connections. See TLS client configuration for details on
120directives that can be used in it. maddy uses reasonable cipher suites and TLS
121versions by default so you generally don't have to worry about it.
122
123---
124
125### log _targets..._ | `off`
126Default: `stderr`
127
128Write log to one of more "targets".
129
130The target can be one or the following:
131
132- `stderr` –  Write logs to stderr.
133- `stderr_ts` – Write logs to stderr with timestamps.
134- `syslog` – Send logs to the local syslog daemon.
135- _file path_ – Write (append) logs to file.
136
137Example:
138
139```
140log syslog /var/log/maddy.log
141```
142
143**Note:** Maddy does not perform log files rotation, this is the job of the
144logrotate daemon. Send SIGUSR1 to maddy process to make it reopen log files.
145
146---
147
148### debug _boolean_ 
149Default: `no`
150
151Enable verbose logging for all modules. You don't need that unless you are
152reporting a bug.
153