mirrors/maddy
1
0
Fork 0
mirror of https://github.com/foxcpp/maddy.git synced 2025-04-04 21:47:40 +03:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #600 from cuu508/md_reformat

Browse source 
Improve Markdown formatting
This commit is contained in:
Max Mazurov 2023-07-17 01:54:23 +03:00 • committed by GitHub
commit 37bbd40189
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
39 changed files with 1110 additions and 797 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/reference/auth/dovecot_sasl.md
View file

@ -1,6 +1,6 @@
# Dovecot SASL # Dovecot SASL
The 'auth.dovecot\_sasl' module implements the client side of the Dovecot The 'auth.dovecot_sasl' module implements the client side of the Dovecot
authentication protocol, allowing maddy to use it as a credentials source. authentication protocol, allowing maddy to use it as a credentials source.
Currently SASL mechanisms support is limited to mechanisms supported by maddy Currently SASL mechanisms support is limited to mechanisms supported by maddy
@ -16,11 +16,11 @@ dovecot_sasl unix://socket_path
## Configuration directives ## Configuration directives
**Syntax**: endpoint _schema://address_ <br> ### endpoint _schema://address_
**Default**: not set Default: not set
Set the address to use to contact Dovecot SASL server in the standard endpoint Set the address to use to contact Dovecot SASL server in the standard endpoint
format. format.
tcp://10.0.0.1:2222 for TCP, unix:///var/lib/dovecot/auth.sock for Unix `tcp://10.0.0.1:2222` for TCP, `unix:///var/lib/dovecot/auth.sock` for Unix
domain sockets. domain sockets.

23
docs/reference/auth/external.md
View file

@ -1,12 +1,12 @@
# System command # System command
auth.external module for authentication using external helper binary. It looks for binary auth.external module for authentication using external helper binary. It looks for binary
named maddy-auth-helper in $PATH and libexecdir and uses it for authentication named `maddy-auth-helper` in $PATH and libexecdir and uses it for authentication
using username/password pair. using username/password pair.
The protocol is very simple: The protocol is very simple:
Program is launched for each authentication. Username and password are written Program is launched for each authentication. Username and password are written
to stdin, adding \\n to the end. If binary exits with 0 status code - to stdin, adding \n to the end. If binary exits with 0 status code -
authentication is considered successful. If the status code is 1 - authentication is considered successful. If the status code is 1 -
authentication is failed. If the status code is 2 - another unrelated error has authentication is failed. If the status code is 2 - another unrelated error has
happened. Additional information should be written to stderr. happened. Additional information should be written to stderr.
@ -21,19 +21,24 @@ auth.external {
## Configuration directives ## Configuration directives
**Syntax**: helper _file\_path\_ ### helper _file_path_
Location of the helper binary. **Required.** **Required.** <br>
Location of the helper binary.
**Syntax**: perdomain _boolean_ <br> ---
**Default**: no
### perdomain _boolean_
Default: `no`
Don't remove domain part of username when authenticating and require it to be Don't remove domain part of username when authenticating and require it to be
present. Can be used if you want user@domain1 and user@domain2 to be different present. Can be used if you want user@domain1 and user@domain2 to be different
accounts. accounts.
**Syntax**: domains _domains..._ <br> ---
**Default**: not specified
### domains _domains..._
Default: not specified
Domains that should be allowed in username during authentication. Domains that should be allowed in username during authentication.
@ -43,5 +48,5 @@ name in addition to just username.
If used without 'perdomain', domain part will be removed from login before If used without 'perdomain', domain part will be removed from login before
check with underlying auth. mechanism. If 'perdomain' is set, then check with underlying auth. mechanism. If 'perdomain' is set, then
domains must be also set and domain part WILL NOT be removed before check. domains must be also set and domain part **will not** be removed before check.

65
docs/reference/auth/ldap.md
View file

@ -8,7 +8,7 @@ directory search or template .
Note that storage backends conventionally use email addresses, if you use Note that storage backends conventionally use email addresses, if you use
non-email identifiers as usernames then you should map them onto non-email identifiers as usernames then you should map them onto
emails on delivery by using auth\_map (see documentation page for used storage backend). emails on delivery by using `auth_map` (see documentation page for used storage backend).
auth.ldap also can be a used as a table module. This way you can check auth.ldap also can be a used as a table module. This way you can check
whether the account exists. It works only if DN template is not used. whether the account exists. It works only if DN template is not used.
@ -42,72 +42,89 @@ auth.ldap ldap://maddy.test.389 {
## Configuration directives ## Configuration directives
**Syntax:** urls _servers...\_ ### urls _servers..._
REQUIRED. **Required.**
URLs of the directory servers to use. First available server URLs of the directory servers to use. First available server
is used - no load-balancing is done. is used - no load-balancing is done.
URLs should use 'ldap://', 'ldaps://', 'ldapi://' schemes. URLs should use `ldap://`, `ldaps://`, `ldapi://` schemes.
**Syntax:** bind off <br> ---
bind unauth <br>
bind external <br> ### bind `off` | `unauth` | `external` | `plain` _username_ _password_
bind plain _username_ _password_ <br>
**Default:** off Default: `off`
Credentials to use for initial binding. Required if DN lookup is used. Credentials to use for initial binding. Required if DN lookup is used.
'unauth' performs unauthenticated bind. 'external' performs external binding `unauth` performs unauthenticated bind. `external` performs external binding
which is useful for Unix socket connections (ldapi://) or TLS client certificate which is useful for Unix socket connections (`ldapi://`) or TLS client certificate
authentication (cert. is set using tls\_client directive). 'plain' performs a authentication (cert. is set using tls_client directive). `plain` performs a
simple bind using provided credentials. simple bind using provided credentials.
**Syntax:** dn\_template _template\_ ---
DN template to use for binding. '{username}' is replaced with the ### dn_template _template_
DN template to use for binding. `{username}` is replaced with the
username specified by the user. username specified by the user.
**Syntax:** base\_dn _dn\_ ---
### base_dn _dn_
Base DN to use for lookup. Base DN to use for lookup.
**Syntax:** filter _str\_ ---
DN lookup filter. '{username}' is replaced with the username specified ### filter _str_
DN lookup filter. `{username}` is replaced with the username specified
by the user. by the user.
Example: Example:
``` ```
(&(objectClass=posixAccount)(uid={username})) (&(objectClass=posixAccount)(uid={username}))
``` ```
Example (using ActiveDirectory): Example (using ActiveDirectory):
``` ```
(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName={username})(!(UserAccountControl:1.2.840.113556.1.4.803:=2))) (&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName={username})(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))
``` ```
Example: Example:
``` ```
(&(objectClass=Person)(mail={username})) (&(objectClass=Person)(mail={username}))
``` ```
**Syntax:** starttls _bool_ <br> ---
**Default:** off
### starttls _bool_
Default: `off`
Whether to upgrade connection to TLS using STARTTLS. Whether to upgrade connection to TLS using STARTTLS.
**Syntax:** tls\_client { ... } ---
### tls_client { ... }
Advanced TLS client configuration. See [TLS configuration / Client](/reference/tls/#client) for details. Advanced TLS client configuration. See [TLS configuration / Client](/reference/tls/#client) for details.
**Syntax:** connect\_timeout _duration_ <br> ---
**Default:** 1m
### connect_timeout _duration_
Default: `1m`
Timeout for initial connection to the directory server. Timeout for initial connection to the directory server.
**Syntax:** request\_timeout _duration_ <br> ---
**Default:** 1m
### request_timeout _duration_
Default: `1m`
Timeout for each request (binding, lookup). Timeout for each request (binding, lookup).

15
docs/reference/auth/netauth.md
View file

@ -9,7 +9,7 @@ mail address.
Note that storage backends conventionally use email addresses. Since Note that storage backends conventionally use email addresses. Since
NetAuth recommends *nix compatible usernames, you will need to map the NetAuth recommends *nix compatible usernames, you will need to map the
email identifiers to NetAuth Entity IDs using auth\_map (see email identifiers to NetAuth Entity IDs using `auth_map` (see
documentation page for used storage backend). documentation page for used storage backend).
auth.netauth also can be used as a table module. This way you can auth.netauth also can be used as a table module. This way you can
@ -33,15 +33,16 @@ auth.netauth {}
## Configuration directives ## Configuration directives
**Syntax:** require\_group _group_ ### require_group _group_
OPTIONAL. Optional.
Group that entities must possess to be able to use maddy services. Group that entities must possess to be able to use maddy services.
This can be used to provide email to just a subset of the entities This can be used to provide email to just a subset of the entities
present in NetAuth. present in NetAuth.
**Syntax** debug off <br> ---
debug on <br>
debug off <br> ### debug `on` | `off`
**Default:** off
Default: `off`

24
docs/reference/auth/pam.md
View file

@ -4,7 +4,8 @@ auth.pam module implements authentication using libpam. Alternatively it can be
use helper binary like auth.external module does. use helper binary like auth.external module does.
maddy should be built with libpam build tag to use this module without maddy should be built with libpam build tag to use this module without
'use\_helper' directive. 'use_helper' directive.
``` ```
go get -tags 'libpam' ... go get -tags 'libpam' ...
``` ```
@ -18,25 +19,28 @@ auth.pam {
## Configuration directives ## Configuration directives
**Syntax**: debug _boolean_ <br> ### debug _boolean_
**Default**: no Default: `no`
Enable verbose logging for all modules. You don't need that unless you are Enable verbose logging for all modules. You don't need that unless you are
reporting a bug. reporting a bug.
**Syntax**: use\_helper _boolean_ <br> ---
**Default**: no
Use LibexecDirectory/maddy-pam-helper instead of directly calling libpam. ### use_helper _boolean_
Default: `no`
Use `LibexecDirectory/maddy-pam-helper` instead of directly calling libpam.
You need to use that if: You need to use that if:
1. maddy is not compiled with libpam, but maddy-pam-helper is built separately.
2. maddy is running as an unprivileged user and used PAM configuration requires additional
privileges (e.g. when using system accounts).
For 2, you need to make maddy-pam-helper binary setuid, see 1. maddy is not compiled with libpam, but `maddy-pam-helper` is built separately.
2. maddy is running as an unprivileged user and used PAM configuration requires additional privileges (e.g. when using system accounts).
For 2, you need to make `maddy-pam-helper` binary setuid, see
README.md in source tree for details. README.md in source tree for details.
TL;DR (assuming you have the maddy group): TL;DR (assuming you have the maddy group):
``` ```
chown root:maddy /usr/lib/maddy/maddy-pam-helper chown root:maddy /usr/lib/maddy/maddy-pam-helper
chmod u+xs,g+x,o-x /usr/lib/maddy/maddy-pam-helper chmod u+xs,g+x,o-x /usr/lib/maddy/maddy-pam-helper

12
docs/reference/auth/pass_table.md
View file

@ -3,7 +3,7 @@
auth.pass_table module implements username:password authentication by looking up the auth.pass_table module implements username:password authentication by looking up the
password hash using a table module (maddy-tables(5)). It can be used password hash using a table module (maddy-tables(5)). It can be used
to load user credentials from text file (via table.file module) or SQL query to load user credentials from text file (via table.file module) or SQL query
(via table.sql\_table module). (via table.sql_table module).
Definition: Definition:
@ -30,15 +30,15 @@ smtp tcp://0.0.0.0:587 {
## Password hashes ## Password hashes
pass\_table expects the used table to contain certain structured values with pass_table expects the used table to contain certain structured values with
hash algorithm name, salt and other necessary parameters. hash algorithm name, salt and other necessary parameters.
You should use 'maddy hash' command to generate suitable values. You should use `maddy hash` command to generate suitable values.
See 'maddy hash --help' for details. See `maddy hash --help` for details.
## maddy creds ## maddy creds
If the underlying table is a "mutable" table (see maddy-tables(5)) then If the underlying table is a "mutable" table (see maddy-tables(5)) then
the 'maddy creds' command can be used to modify the underlying tables the `maddy creds` command can be used to modify the underlying tables
via pass\_table module. It will act on a "local credentials store" and will write via pass_table module. It will act on a "local credentials store" and will write
appropriate hash values to the table. appropriate hash values to the table.

11
docs/reference/auth/plain_separate.md
View file

@ -1,6 +1,6 @@
# Separate username and password lookup # Separate username and password lookup
auth.plain\_separate module implements authentication using username:password pairs but can auth.plain_separate module implements authentication using username:password pairs but can
use zero or more "table modules" (maddy-tables(5)) and one or more use zero or more "table modules" (maddy-tables(5)) and one or more
authentication providers to verify credentials. authentication providers to verify credentials.
@ -24,19 +24,22 @@ How it works:
## Configuration directives ## Configuration directives
***Syntax:*** user _table module\_ ### user _table-module_
Configuration block for any module from maddy-tables(5) can be used here. Configuration block for any module from maddy-tables(5) can be used here.
Example: Example:
``` ```
user file /etc/maddy/allowed_users user file /etc/maddy/allowed_users
``` ```
***Syntax:*** pass _auth provider\_ ---
### pass _auth-provider_
Configuration block for any auth. provider module can be used here, even Configuration block for any auth. provider module can be used here, even
'plain\_split' itself. 'plain_split' itself.
The used auth. provider must provide username:password pair-based The used auth. provider must provide username:password pair-based
authentication. authentication.

16
docs/reference/auth/shadow.md
View file

@ -12,23 +12,27 @@ auth.shadow {
## Configuration directives ## Configuration directives
**Syntax**: debug _boolean_ <br> ### debug _boolean_
**Default**: no
Default: `no`
Enable verbose logging for all modules. You don't need that unless you are Enable verbose logging for all modules. You don't need that unless you are
reporting a bug. reporting a bug.
**Syntax**: use\_helper _boolean_ <br> ---
**Default**: no
Use LibexecDirectory/maddy-shadow-helper instead of directly reading /etc/shadow. ### use_helper _boolean_
Default: `no`
Use `LibexecDirectory/maddy-shadow-helper` instead of directly reading `/etc/shadow`.
You need to use that if maddy is running as an unprivileged user You need to use that if maddy is running as an unprivileged user
privileges (e.g. when using system accounts). privileges (e.g. when using system accounts).
You need to make maddy-shadow-helper binary setuid, see You need to make `maddy-shadow-helper` binary setuid, see
cmd/maddy-shadow-helper/README.md in source tree for details. cmd/maddy-shadow-helper/README.md in source tree for details.
TL;DR (assuming you have maddy group): TL;DR (assuming you have maddy group):
``` ```
chown root:maddy /usr/lib/maddy/maddy-shadow-helper chown root:maddy /usr/lib/maddy/maddy-shadow-helper
chmod u+xs,g+x,o-x /usr/lib/maddy/maddy-shadow-helper chmod u+xs,g+x,o-x /usr/lib/maddy/maddy-shadow-helper

5
docs/reference/blob/fs.md
View file

@ -7,14 +7,15 @@ storage.blob.fs {
root <directory> root <directory>
} }
``` ```
``` ```
storage.blob.fs <directory> storage.blob.fs <directory>
``` ```
## Configuration directives ## Configuration directives
**Syntax:** root _path_ <br> ### root _path_
**Default:** not set Default: not set
Path to the FS directory. Must be readable and writable by the server process. Path to the FS directory. Must be readable and writable by the server process.
If it does not exist - it will be created (parent directory should be writable If it does not exist - it will be created (parent directory should be writable

56
docs/reference/blob/s3.md
View file

@ -18,6 +18,7 @@ storage.blob.s3 {
``` ```
Example: Example:
``` ```
storage.imapsql local_mailboxes { storage.imapsql local_mailboxes {
... ...
@ -34,53 +35,64 @@ storage.imapsql local_mailboxes {
## Configuration directives ## Configuration directives
**Syntax:** endpoint _address:port\_ ### endpoint _address:port_
REQUIRED. **Required**.
Root S3 endpoint. e.g. s3.amazonaws.com Root S3 endpoint. e.g. `s3.amazonaws.com`
**Syntax:** secure _boolean_ <br> ---
**Default:** yes
### secure _boolean_
Default: `yes`
Whether TLS should be used. Whether TLS should be used.
**Syntax:** access\_key _string_ <br> ---
**Syntax:** secret\_key _string\_
REQUIRED. ### access_key _string_<br>secret_key _string_
**Required**.
Static S3 credentials. Static S3 credentials.
**Syntax:** bucket _name\_ ---
REQUIRED. ### bucket _name_
**Required**.
S3 bucket name. The bucket must exist and S3 bucket name. The bucket must exist and
be read-writable. be read-writable.
**Syntax:** region _string_ <br> ---
**Default:** not set
S3 bucket location. May be called "endpoint" ### region _string_
in some manuals. Default: not set
**Syntax:** object\_prefix _string_ <br> S3 bucket location. May be called "endpoint" in some manuals.
**Default:** empty string
---
### object_prefix _string_
Default: empty string
String to add to all keys stored by maddy. String to add to all keys stored by maddy.
Can be useful when S3 is used as a file system. Can be useful when S3 is used as a file system.
**Syntax:** creds _string_ <br> ---
**Default:** access_key
### creds `access_key` | `file_minio` | `file_aws` | `iam`
Default: `access_key`
Credentials to use for accessing the S3 Bucket. Credentials to use for accessing the S3 Bucket.
Credential Types: Credential Types:
- access_key: use AWS access key and secret access key
- file_minio: use credentials for Minio present at ~/.mc/config.json - `access_key`: use AWS access key and secret access key
- file_aws: use credentials for AWS S3 present at ~/.aws/credentials - `file_minio`: use credentials for Minio present at ~/.mc/config.json
- iam: use AWS IAM instance profile for credentials. - `file_aws`: use credentials for AWS S3 present at ~/.aws/credentials
- `iam`: use AWS IAM instance profile for credentials.
By default, access_key is used with the access key and secret access key present in the config. By default, access_key is used with the access key and secret access key present in the config.

6
docs/reference/checks/actions.md
View file

@ -4,16 +4,16 @@ When a certain check module thinks the message is "bad", it takes some actions
depending on its configuration. Most checks follow the same configuration depending on its configuration. Most checks follow the same configuration
structure and allow following actions to be taken on check failure: structure and allow following actions to be taken on check failure:
- Do nothing ('action ignore') - Do nothing (`action ignore`)
Useful for testing deployment of new checks. Check failures are still logged Useful for testing deployment of new checks. Check failures are still logged
but they have no effect on message delivery. but they have no effect on message delivery.
- Reject the message ('action reject') - Reject the message (`action reject`)
Reject the message at connection time. No bounce is generated locally. Reject the message at connection time. No bounce is generated locally.
- Quarantine the message ('action quarantine') - Quarantine the message (`action quarantine`)
Mark message as 'quarantined'. If message is then delivered to the local Mark message as 'quarantined'. If message is then delivered to the local
storage, the storage backend can place the message in the 'Junk' mailbox. storage, the storage backend can place the message in the 'Junk' mailbox.

62
docs/reference/checks/authorize_sender.md
View file

@ -3,7 +3,7 @@
Module check.authorize_sender verifies that envelope and header sender addresses belong Module check.authorize_sender verifies that envelope and header sender addresses belong
to the authenticated user. Address ownership is established via table to the authenticated user. Address ownership is established via table
that maps each user account to a email address it is allowed to use. that maps each user account to a email address it is allowed to use.
There are some special cases, see user\_to\_email description below. There are some special cases, see `user_to_email` description below.
``` ```
check.authorize_sender { check.authorize_sender {
@ -28,16 +28,16 @@ check {
## Configuration directives ## Configuration directives
**Syntax:** user\_to\_email _table_ <br> ### user_to_email _table_
**Default:** identity Default: `identity`
Table that maps authorization username to the list of sender emails Table that maps authorization username to the list of sender emails
the user is allowed to use. the user is allowed to use.
In additional to email addresses, the table can contain domain names or In additional to email addresses, the table can contain domain names or
special string "\*" as a value. If the value is a domain - user special string "*" as a value. If the value is a domain - user
will be allowed to use any mailbox within it as a sender address. will be allowed to use any mailbox within it as a sender address.
If it is "\*" - user will be allowed to use any address. If it is "*" - user will be allowed to use any address.
By default, table.identity is used, meaning that username should By default, table.identity is used, meaning that username should
be equal to the sender email. be equal to the sender email.
@ -45,8 +45,10 @@ be equal to the sender email.
Before username is looked up via the table, normalization algorithm Before username is looked up via the table, normalization algorithm
defined by auth_normalize is applied to it. defined by auth_normalize is applied to it.
**Syntax:** prepare\_email _table_ <br> ---
**Default:** identity
### prepare_email _table_
Default: `identity`
Table that is used to translate email addresses before they Table that is used to translate email addresses before they
are matched against user_to_email values. are matched against user_to_email values.
@ -59,36 +61,48 @@ done in default configuration.
If table does not contain any mapping for the used sender If table does not contain any mapping for the used sender
address, it will be used as is. address, it will be used as is.
**Syntax:** check\_header _boolean_ <br> ---
**Default:** yes
### check_header _boolean_
Default: `yes`
Whether to verify header sender in addition to envelope. Whether to verify header sender in addition to envelope.
Either Sender or From field value should match the Either Sender or From field value should match the
authorization identity. authorization identity.
**Syntax:** unauth\_action _action_ <br> ---
**Default:** reject
### unauth_action _action_
Default: `reject`
What to do if the user is not authenticated at all. What to do if the user is not authenticated at all.
**Syntax:** no\_match\_action _action_ <br> ---
**Default:** reject
### no_match_action _action_
Default: `reject`
What to do if user is not allowed to use the sender address specified. What to do if user is not allowed to use the sender address specified.
**Syntax:** malformed\_action _action_ <br> ---
**Default:** reject
### malformed_action _action_
Default: `reject`
What to do if From or Sender header fields contain malformed values. What to do if From or Sender header fields contain malformed values.
**Syntax:** err\_action _action_ <br> ---
**Default:** reject
What to do if error happens during prepare\_email or user\_to\_email lookup. ### err_action _action_
Default: `reject`
**Syntax:** auth\_normalize _action_ <br> What to do if error happens during prepare_email or user_to_email lookup.
**Default:** auto
---
### auth_normalize _action_
Default: `auto`
Normalization function to apply to authorization username before Normalization function to apply to authorization username before
further processing. further processing.
@ -107,10 +121,12 @@ PRECIS profiles are defined by RFC 8265. In short, they make sure
that Unicode strings that look the same will be compared as if they were that Unicode strings that look the same will be compared as if they were
the same. CaseMapped profiles also convert strings to lower case. the same. CaseMapped profiles also convert strings to lower case.
**Syntax:** from\_normalize _action_ <br> ---
**Default:** auto
### from_normalize _action_
Default: `auto`
Normalization function to apply to email addresses before Normalization function to apply to email addresses before
further processing. further processing.
Available options are same as for auth\_normalize. Available options are same as for `auth_normalize`.

93
docs/reference/checks/command.md
View file

@ -23,47 +23,23 @@ system shell.
There is a set of special strings that are replaced with the corresponding There is a set of special strings that are replaced with the corresponding
message-specific values: message-specific values:
- {source\_ip} - `{source_ip}` – IPv4/IPv6 address of the sending MTA.
- `{source_host}` – Hostname of the sending MTA, from the HELO/EHLO command.
IPv4/IPv6 address of the sending MTA. - `{source_rdns}` – PTR record of the sending MTA IP address.
- `{msg_id}` – Internal message identifier. Unique for each delivery.
- {source\_host} - `{auth_user}` – Client username, if authenticated using SASL PLAIN
- `{sender}` – Message sender address, as specified in the MAIL FROM SMTP command.
Hostname of the sending MTA, from the HELO/EHLO command. - `{rcpts}` – List of accepted recipient addresses, including the currently handled
- {source\_rdns}
PTR record of the sending MTA IP address.
- {msg\_id}
Internal message identifier. Unique for each delivery.
- {auth\_user}
Client username, if authenticated using SASL PLAIN
- {sender}
Message sender address, as specified in the MAIL FROM SMTP command.
- {rcpts}
List of accepted recipient addresses, including the currently handled
one. one.
- `{address}` – Currently handled address. This is a recipient address if the command
is called during RCPT TO command handling (`run_on rcpt`) or a sender
address if the command is called during MAIL FROM command handling (`run_on
sender`).
- {address} If value is undefined (e.g. `{source_ip}` for a message accepted over a Unix
Currently handled address. This is a recipient address if the command
is called during RCPT TO command handling ('run\_on rcpt') or a sender
address if the command is called during MAIL FROM command handling ('run\_on
sender').
If value is undefined (e.g. {source\_ip} for a message accepted over a Unix
socket) or unavailable (the command is executed too early), the placeholder socket) or unavailable (the command is executed too early), the placeholder
is replaced with an empty string. Note that it can not remove the argument. is replaced with an empty string. Note that it can not remove the argument.
E.g. -i {source\_ip} will not become just -i, it will be -i "" E.g. `-i {source_ip}` will not become just `-i`, it will be `-i ""`
Undefined placeholders are not replaced. Undefined placeholders are not replaced.
@ -77,55 +53,44 @@ The header from stdout will be **prepended** to the message header.
## Configuration directives ## Configuration directives
**Syntax**: run\_on conn|sender|rcpt|body <br> ### run_on `conn` | `sender` | `rcpt` | `body`
**Default**: body Default: `body`
When to run the command. This directive also affects the information visible When to run the command. This directive also affects the information visible
for the message. for the message.
- conn - `conn`<br>
Run before the sender address (MAIL FROM) is handled.<br>
Run before the sender address (MAIL FROM) is handled.
**Stdin**: Empty <br> **Stdin**: Empty <br>
**Available placeholders**: {source\_ip}, {source\_host}, {msg\_id}, {auth\_user}. **Available placeholders**: {source_ip}, {source_host}, {msg_id}, {auth_user}.
- sender
Run during sender address (MAIL FROM) handling.
- `sender`<br>
Run during sender address (MAIL FROM) handling.<br>
**Stdin**: Empty <br> **Stdin**: Empty <br>
**Available placeholders**: conn placeholders + {sender}, {address}. **Available placeholders**: conn placeholders + {sender}, {address}.
The {address} placeholder contains the MAIL FROM address. The {address} placeholder contains the MAIL FROM address.
- rcpt - `rcpt`<br>
Run during recipient address (RCPT TO) handling. The command is executed Run during recipient address (RCPT TO) handling. The command is executed
once for each RCPT TO command, even if the same recipient is specified once for each RCPT TO command, even if the same recipient is specified
multiple times. multiple times.<br>
**Stdin**: Empty <br> **Stdin**: Empty <br>
**Available placeholders**: sender placeholders + {rcpts}. **Available placeholders**: sender placeholders + {rcpts}.
The {address} placeholder contains the recipient address. The {address} placeholder contains the recipient address.
- body - `body`<br>
Run during message body handling.<br>
Run during message body handling.
**Stdin**: The message header + body <br> **Stdin**: The message header + body <br>
**Available placeholders**: all except for {address}. **Available placeholders**: all except for {address}.
**Syntax**: <br> ---
code _integer_ ignore <br>
code _integer_ quarantine <br>
code _integer_ reject [SMTP code] [SMTP enhanced code] [SMTP message]
This directives specified the mapping from the command exit code _integer_ to ### code _integer_ ignore <br>code _integer_ quarantine <br>code _integer_ reject _smtp-code_ _smtp-enhanced-code_ _smtp-message_
This directive specifies the mapping from the command exit code _integer_ to
the message pipeline action. the message pipeline action.
Two codes are defined implicitly, exit code 1 causes the message to be rejected Two codes are defined implicitly, exit code 1 causes the message to be rejected
with a permanent error, exit code 2 causes the message to be quarantined. Both with a permanent error, exit code 2 causes the message to be quarantined. Both
action can be overridden using the 'code' directive. actions can be overridden using the 'code' directive.

28
docs/reference/checks/dkim.md
View file

@ -16,14 +16,16 @@ check.dkim {
} }
``` ```
**Syntax**: debug _boolean_ <br> ### debug _boolean_
**Default**: global directive value Default: global directive value
Log both successful and unsuccessful check executions instead of just Log both successful and unsuccessful check executions instead of just
unsuccessful. unsuccessful.
**Syntax**: required\_fields _string..._ <br> ---
**Default**: From Subject
### required_fields _string..._
Default: `From Subject`
Header fields that should be included in each signature. If signature Header fields that should be included in each signature. If signature
lacks any field listed in that directive, it will be considered invalid. lacks any field listed in that directive, it will be considered invalid.
@ -31,24 +33,30 @@ lacks any field listed in that directive, it will be considered invalid.
Note that From is always required to be signed, even if it is not included in Note that From is always required to be signed, even if it is not included in
this directive. this directive.
**Syntax**: no\_sig\_action _action_ <br> ---
**Default**: ignore (recommended by RFC 6376)
### no_sig_action _action_
Default: `ignore` (recommended by RFC 6376)
Action to take when message without any signature is received. Action to take when message without any signature is received.
Note that DMARC policy of the sender domain can request more strict handling of Note that DMARC policy of the sender domain can request more strict handling of
missing DKIM signatures. missing DKIM signatures.
**Syntax**: broken\_sig\_action _action_ <br> ---
**Default**: ignore (recommended by RFC 6376)
### broken_sig_action _action_
Default: `ignore` (recommended by RFC 6376)
Action to take when there are not valid signatures in a message. Action to take when there are not valid signatures in a message.
Note that DMARC policy of the sender domain can request more strict handling of Note that DMARC policy of the sender domain can request more strict handling of
broken DKIM signatures. broken DKIM signatures.
**Syntax**: fail\_open _boolean_ <br> ---
**Default**: no
### fail_open _boolean_
Default: `no`
Whether to accept the message if a temporary error occurs during DKIM Whether to accept the message if a temporary error occurs during DKIM
verification. Rejecting the message with a 4xx code will require the sender verification. Rejecting the message with a 4xx code will require the sender

65
docs/reference/checks/dnsbl.md
View file

@ -60,13 +60,15 @@ check {
## Configuration directives ## Configuration directives
**Syntax**: debug _boolean_ <br> ### debug _boolean_
**Default**: global directive value Default: global directive value
Enable verbose logging. Enable verbose logging.
**Syntax**: check\_early _boolean_ <br> ---
**Default**: no
### check_early _boolean_
Default: `no`
Check BLs before mail delivery starts and silently reject blacklisted clients. Check BLs before mail delivery starts and silently reject blacklisted clients.
@ -74,22 +76,27 @@ For this to work correctly, check should not be used in source/destination
pipeline block. pipeline block.
In particular, this means: In particular, this means:
- No logging is done for rejected messages. - No logging is done for rejected messages.
- No action is taken if quarantine\_threshold is hit, only reject\_threshold - No action is taken if `quarantine_threshold` is hit, only `reject_threshold`
applies. applies.
- defer\_sender\_reject from SMTP configuration takes no effect. - `defer_sender_reject` from SMTP configuration takes no effect.
- MAIL FROM is not checked, even if specified. - MAIL FROM is not checked, even if specified.
If you often get hit by spam attacks, it is recommended to enable this If you often get hit by spam attacks, it is recommended to enable this
setting to save server resources. setting to save server resources.
**Syntax**: quarantine\_threshold _integer_ <br> ---
**Default**: 1
### quarantine_threshold _integer_
Default: `1`
DNSBL score needed (equals-or-higher) to quarantine the message. DNSBL score needed (equals-or-higher) to quarantine the message.
**Syntax**: reject\_threshold _integer_ <br> ---
**Default**: 9999
### reject_threshold _integer_
Default: `9999`
DNSBL score needed (equals-or-higher) to reject the message. DNSBL score needed (equals-or-higher) to reject the message.
@ -110,46 +117,56 @@ Directive name and arguments specify the actual DNS zone to query when checking
the list. Using multiple arguments is equivalent to specifying the same the list. Using multiple arguments is equivalent to specifying the same
configuration separately for each list. configuration separately for each list.
**Syntax**: client\_ipv4 _boolean_ <br> ### client_ipv4 _boolean_
**Default**: yes Default: `yes`
Whether to check address of the IPv4 clients against the list. Whether to check address of the IPv4 clients against the list.
**Syntax**: client\_ipv6 _boolean_ <br> ---
**Default**: yes
### client_ipv6 _boolean_
Default: `yes`
Whether to check address of the IPv6 clients against the list. Whether to check address of the IPv6 clients against the list.
**Syntax**: ehlo _boolean_ <br> ---
**Default**: no
### ehlo _boolean_
Default: `no`
Whether to check hostname specified n the HELO/EHLO command Whether to check hostname specified n the HELO/EHLO command
against the list. against the list.
This works correctly only with domain-based DNSBLs. This works correctly only with domain-based DNSBLs.
**Syntax**: mailfrom _boolean_ <br> ---
**Default**: no
### mailfrom _boolean_
Default: `no`
Whether to check domain part of the MAIL FROM address against the list. Whether to check domain part of the MAIL FROM address against the list.
This works correctly only with domain-based DNSBLs. This works correctly only with domain-based DNSBLs.
**Syntax**: responses _cidr|ip..._ <br> ---
**Default**: 127.0.0.1/24
### responses _cidr_ | _ip..._
Default: `127.0.0.1/24`
IP networks (in CIDR notation) or addresses to permit in list lookup results. IP networks (in CIDR notation) or addresses to permit in list lookup results.
Addresses not matching any entry in this directives will be ignored. Addresses not matching any entry in this directives will be ignored.
**Syntax**: score _integer_ <br> ---
**Default**: 1
### score _integer_
Default: `1`
Score value to add for the message if it is listed. Score value to add for the message if it is listed.
If sum of list scores is equals or higher than quarantine\_threshold, the If sum of list scores is equals or higher than `quarantine_threshold`, the
message will be quarantined. message will be quarantined.
If sum of list scores is equals or higher than rejected\_threshold, the message If sum of list scores is equals or higher than `rejected_threshold`, the message
will be rejected. will be rejected.
It is possible to specify a negative value to make list act like a whitelist It is possible to specify a negative value to make list act like a whitelist

12
docs/reference/checks/milter.md
View file

@ -32,15 +32,17 @@ via. See below.
## Configuration directives ## Configuration directives
***Syntax:*** endpoint _scheme://path_ <br> ### endpoint _scheme://path_
***Default:*** not set Default: not set
Specifies milter protocol endpoint to use. Specifies milter protocol endpoint to use.
The endpoit is specified in standard URL-like format: The endpoit is specified in standard URL-like format:
'tcp://127.0.0.1:6669' or 'unix:///var/lib/milter/filter.sock' `tcp://127.0.0.1:6669` or `unix:///var/lib/milter/filter.sock`
***Syntax:*** fail\_open _boolean_ <br> ---
***Default:*** false
### fail_open _boolean_
Default: `false`
Toggles behavior on milter I/O errors. If false ("fail closed") - message is Toggles behavior on milter I/O errors. If false ("fail closed") - message is
rejected with temporary error code. If true ("fail open") - check is skipped. rejected with temporary error code. If true ("fail open") - check is skipped.

33
docs/reference/checks/misc.md
View file

@ -4,40 +4,45 @@
Following directives are defined for all modules listed below. Following directives are defined for all modules listed below.
**Syntax**: <br> ### fail_action `ignore` | `reject` | `quarantine`
fail\_action ignore <br> Default: `quarantine`
fail\_action reject <br>
fail\_action quarantine <br>
**Default**: quarantine
Action to take when check fails. See Check actions for details. Action to take when check fails. See [Check actions](../actions/) for details.
**Syntax**: debug _boolean_ <br> ---
**Default**: global directive value
### debug _boolean_
Default: global directive value
Log both successful and unsuccessful check executions instead of just Log both successful and unsuccessful check executions instead of just
unsuccessful. unsuccessful.
## require\_mx\_record ---
### require_mx_record
Check that domain in MAIL FROM command does have a MX record and none of them Check that domain in MAIL FROM command does have a MX record and none of them
are "null" (contain a single dot as the host). are "null" (contain a single dot as the host).
By default, quarantines messages coming from servers missing MX records, By default, quarantines messages coming from servers missing MX records,
use 'fail\_action' directive to change that. use `fail_action` directive to change that.
## require\_matching\_rdns ---
### require_matching_rdns
Check that source server IP does have a PTR record point to the domain Check that source server IP does have a PTR record point to the domain
specified in EHLO/HELO command. specified in EHLO/HELO command.
By default, quarantines messages coming from servers with mismatched or missing By default, quarantines messages coming from servers with mismatched or missing
PTR record, use 'fail\_action' directive to change that. PTR record, use `fail_action` directive to change that.
## require\_tls ---
### require_tls
Check that the source server is connected via TLS; either directly, or by using Check that the source server is connected via TLS; either directly, or by using
the STARTTLS command. the STARTTLS command.
By default, rejects messages coming from unencrypted servers. Use the By default, rejects messages coming from unencrypted servers. Use the
'fail\_action' directive to change that. `fail_action` directive to change that.

58
docs/reference/checks/rspamd.md
View file

@ -22,58 +22,76 @@ rspamd http://127.0.0.1:11333
## Configuration directives ## Configuration directives
**Syntax:** tls\_client { ... } <br> ### tls_client { ... }
**Default:** not set Default: not set
Configure TLS client if HTTPS is used. See [TLS configuration / Client](/reference/tls/#client) for details. Configure TLS client if HTTPS is used. See [TLS configuration / Client](/reference/tls/#client) for details.
**Syntax:** api\_path _url_ <br> ---
**Default:** http://127.0.0.1:11333
### api_path _url_
Default: `http://127.0.0.1:11333`
URL of HTTP API endpoint. Supports both HTTP and HTTPS and can include URL of HTTP API endpoint. Supports both HTTP and HTTPS and can include
path element. path element.
**Syntax:** settings\_id _string_ <br> ---
**Default:** not set
### settings_id _string_
Default: not set
Settings ID to pass to the server. Settings ID to pass to the server.
**Syntax:** tag _string_ <br> ---
**Default:** maddy
### tag _string_
Default: `maddy`
Value to send in MTA-Tag header field. Value to send in MTA-Tag header field.
**Syntax:** hostname _string_ <br> ---
**Default:** value of global directive
### hostname _string_ <br>
Default: value of global directive
Value to send in MTA-Name header field. Value to send in MTA-Name header field.
**Syntax:** io\_error\_action _action_ <br> ---
**Default:** ignore
### io_error_action _action_
Default: `ignore`
Action to take in case of inability to contact the rspamd server. Action to take in case of inability to contact the rspamd server.
**Syntax:** error\_resp\_action _action_ <br> ---
**Default:** ignore
### error_resp_action _action_
Default: `ignore`
Action to take in case of 5xx or 4xx response received from the rspamd server. Action to take in case of 5xx or 4xx response received from the rspamd server.
**Syntax:** add\_header\_action _action_ <br> ---
**Default:** quarantine
### add_header_action _action_
Default: `quarantine`
Action to take when rspamd requests to "add header". Action to take when rspamd requests to "add header".
X-Spam-Flag and X-Spam-Score are added to the header irregardless of value. X-Spam-Flag and X-Spam-Score are added to the header irregardless of value.
**Syntax:** rewrite\_subj\_action _action_ <br> ---
**Default:** quarantine
### rewrite_subj_action _action_
Default: `quarantine`
Action to take when rspamd requests to "rewrite subject". Action to take when rspamd requests to "rewrite subject".
X-Spam-Flag and X-Spam-Score are added to the header irregardless of value. X-Spam-Flag and X-Spam-Score are added to the header irregardless of value.
**Syntax:** flags _string list..._ <br> ---
**Default:** pass\_all
### flags _string-list..._
Default: `pass_all`
Flags to pass to the rspamd server. Flags to pass to the rspamd server.
See [https://rspamd.com/doc/architecture/protocol.html](https://rspamd.com/doc/architecture/protocol.html) for details. See [https://rspamd.com/doc/architecture/protocol.html](https://rspamd.com/doc/architecture/protocol.html) for details.

50
docs/reference/checks/spf.md
View file

@ -14,12 +14,12 @@ Authentication-Results field is generated irregardless of status.
It is recommended by the DMARC standard to don't fail delivery based solely on It is recommended by the DMARC standard to don't fail delivery based solely on
SPF policy and always check DMARC policy and take action based on it. SPF policy and always check DMARC policy and take action based on it.
If enforce\_early is no, check.spf module will not take any action on SPF If `enforce_early` is `no`, check.spf module will not take any action on SPF
policy failure if sender domain does have a DMARC record with 'quarantine' or policy failure if sender domain does have a DMARC record with 'quarantine' or
'reject' policy. Instead it will rely on DMARC support to take necesary 'reject' policy. Instead it will rely on DMARC support to take necesary
actions using SPF results as an input. actions using SPF results as an input.
Disabling enforce\_early without enabling DMARC support will make SPF policies Disabling `enforce_early` without enabling DMARC support will make SPF policies
no-op and is considered insecure. no-op and is considered insecure.
## Configuration directives ## Configuration directives
@ -35,49 +35,63 @@ check.spf {
} }
``` ```
**Syntax**: debug _boolean_ <br> ### debug _boolean_
**Default**: global directive value Default: global directive value
Enable verbose logging for check.spf. Enable verbose logging for check.spf.
**Syntax**: enforce\_early _boolean_ <br> ---
**Default**: no
### enforce_early _boolean_
Default: `no`
Make policy decision on MAIL FROM stage (before the message body is received). Make policy decision on MAIL FROM stage (before the message body is received).
This makes it impossible to apply DMARC override (see above). This makes it impossible to apply DMARC override (see above).
**Syntax**: none\_action reject|quarantine|ignore <br> ---
**Default**: ignore
### none_action `reject` | `quarantine` | `ignore`
Default: `ignore`
Action to take when SPF policy evaluates to a 'none' result. Action to take when SPF policy evaluates to a 'none' result.
See [https://tools.ietf.org/html/rfc7208#section-2.6](https://tools.ietf.org/html/rfc7208#section-2.6) for meaning of See [https://tools.ietf.org/html/rfc7208#section-2.6](https://tools.ietf.org/html/rfc7208#section-2.6) for meaning of
SPF results. SPF results.
**Syntax**: neutral\_action reject|quarantine|ignore <br> ---
**Default**: ignore
### neutral_action `reject` | `quarantine` | `ignore`
Default: `ignore`
Action to take when SPF policy evaluates to a 'neutral' result. Action to take when SPF policy evaluates to a 'neutral' result.
See [https://tools.ietf.org/html/rfc7208#section-2.6](https://tools.ietf.org/html/rfc7208#section-2.6) for meaning of See [https://tools.ietf.org/html/rfc7208#section-2.6](https://tools.ietf.org/html/rfc7208#section-2.6) for meaning of
SPF results. SPF results.
**Syntax**: fail\_action reject|quarantine|ignore <br> ---
**Default**: quarantine
### fail_action `reject` | `quarantine` | `ignore`
Default: `quarantine`
Action to take when SPF policy evaluates to a 'fail' result. Action to take when SPF policy evaluates to a 'fail' result.
**Syntax**: softfail\_action reject|quarantine|ignore <br> ---
**Default**: ignore
### softfail_action `reject` | `quarantine` | `ignore`
Default: `ignore`
Action to take when SPF policy evaluates to a 'softfail' result. Action to take when SPF policy evaluates to a 'softfail' result.
**Syntax**: permerr\_action reject|quarantine|ignore <br> ---
**Default**: reject
### permerr_action `reject` | `quarantine` | `ignore`
Default: `reject`
Action to take when SPF policy evaluates to a 'permerror' result. Action to take when SPF policy evaluates to a 'permerror' result.
**Syntax**: temperr\_action reject|quarantine|ignore <br> ---
**Default**: reject
### temperr_action `reject` | `quarantine` | `ignore`
Default: `reject`
Action to take when SPF policy evaluates to a 'temperror' result. Action to take when SPF policy evaluates to a 'temperror' result.

16
docs/reference/config-syntax.md
View file

@ -182,21 +182,15 @@ Also note that the following is not valid, unlike Duration values syntax:
32M5K 32M5K
``` ```
# ADDRESS DEFINITIONS ## Address Definitions
Maddy configuration uses URL-like syntax to specify network addresses. Maddy configuration uses URL-like syntax to specify network addresses.
- unix://file\_path - `unix://file_path` – Unix domain socket. Relative paths are relative to runtime directory (`/run/maddy`).
Unix domain socket. Relative paths are relative to runtime directory - `tcp://ADDRESS:PORT` – TCP/IP socket.
(/run/maddy). - `tls://ADDRESS:PORT` – TCP/IP socket using TLS.
- tcp://ADDRESS:PORT ## Dummy Module
TCP/IP socket.
- tls://ADDRESS:PORT
TCP/IP socket using TLS.
# DUMMY MODULE
No-op module. It doesn't need to be configured explicitly and can be referenced No-op module. It doesn't need to be configured explicitly and can be referenced
using "dummy" name. It can act as a delivery target or auth. using "dummy" name. It can act as a delivery target or auth.

61
docs/reference/endpoints/imap.md
View file

@ -27,11 +27,12 @@ imap tcp://0.0.0.0:143 tls://0.0.0.0:993 {
} }
``` ```
**Syntax**: tls _certificate\_path_ _key\_path_ { ... } <br> ### tls _certificate-path_ _key-path_ { ... }
**Default**: global directive value Default: global directive value
TLS certificate & key to use. Fine-tuning of other TLS properties is possible TLS certificate & key to use. Fine-tuning of other TLS properties is possible
by specifying a configuration block and options inside it: by specifying a configuration block and options inside it:
``` ```
tls cert.crt key.key { tls cert.crt key.key {
protocols tls1.2 tls1.3 protocols tls1.2 tls1.3
@ -40,36 +41,50 @@ tls cert.crt key.key {
See [TLS configuration / Server](/reference/tls/#server-side) for details. See [TLS configuration / Server](/reference/tls/#server-side) for details.
**Syntax**: io\_debug _boolean_ <br> ---
**Default**: no
### io_debug _boolean_
Default: `no`
Write all commands and responses to stderr. Write all commands and responses to stderr.
**Syntax**: io\_errors _boolean_ <br> ---
**Default**: no
### io_errors _boolean_
Default: `no`
Log I/O errors. Log I/O errors.
**Syntax**: debug _boolean_ <br> ---
**Default**: global directive value
### debug _boolean_
Default: global directive value
Enable verbose logging. Enable verbose logging.
**Syntax**: insecure\_auth _boolean_ <br> ---
**Default**: no (yes if TLS is disabled)
**Syntax**: auth _module\_reference\_ ### insecure_auth _boolean_
Default: `no` (`yes` if TLS is disabled)
---
### auth _module-reference_
**Required.**
Use the specified module for authentication. Use the specified module for authentication.
**Required.**
**Syntax**: storage _module\_reference\_ ---
### storage _module-reference_
**Required.**
Use the specified module for message storage. Use the specified module for message storage.
**Required.**
**Syntax**: storage\_map _module\_reference_ <br> ---
**Default**: identity
### storage_map _module-reference_
Default: `identity`
Use the specified table to map SASL usernames to storage account names. Use the specified table to map SASL usernames to storage account names.
@ -78,6 +93,7 @@ Before username is looked up, it is normalized using function defined by
This directive is useful if you want users user@example.org and user@example.com This directive is useful if you want users user@example.org and user@example.com
to share the same storage account named "user". In this case, use to share the same storage account named "user". In this case, use
``` ```
storage_map email_localpart storage_map email_localpart
``` ```
@ -88,6 +104,7 @@ authentication provider.
It also does not affect how message delivery is handled, you should specify It also does not affect how message delivery is handled, you should specify
`delivery_map` in storage module to define how to map email addresses `delivery_map` in storage module to define how to map email addresses
to storage accounts. E.g. to storage accounts. E.g.
``` ```
storage.imapsql local_mailboxes { storage.imapsql local_mailboxes {
... ...
@ -95,13 +112,17 @@ to storage accounts. E.g.
} }
``` ```
**Syntax**: storage\_map_normalize _function_ <br> ---
**Default**: auto
### storage_map_normalize _function_
Default: `auto`
Same as `auth_map_normalize` but for `storage_map`. Same as `auth_map_normalize` but for `storage_map`.
**Syntax**: auth\_map_normalize _function_ <br> ---
**Default**: auto
### auth_map_normalize _function_
Default: `auto`
Overrides global `auth_map_normalize` value for this endpoint. Overrides global `auth_map_normalize` value for this endpoint.

1
docs/reference/endpoints/openmetrics.md
View file

@ -4,6 +4,7 @@ Various server statistics are provided in OpenMetrics format by the
"openmetrics" module. "openmetrics" module.
To enable it, add the following line to the server config: To enable it, add the following line to the server config:
``` ```
openmetrics tcp://127.0.0.1:9749 { } openmetrics tcp://127.0.0.1:9749 { }
``` ```

140
docs/reference/endpoints/smtp.md
View file

@ -36,8 +36,8 @@ smtp tcp://0.0.0.0:25 {
## Configuration directives ## Configuration directives
**Syntax**: hostname _string_ <br> ### hostname _string_
**Default**: global directive value Default: global directive value
Server name to use in SMTP banner. Server name to use in SMTP banner.
@ -45,11 +45,14 @@ Server name to use in SMTP banner.
220 example.org ESMTP Service Ready 220 example.org ESMTP Service Ready
``` ```
**Syntax**: tls _certificate\_path_ _key\_path_ { ... } <br> ---
**Default**: global directive value
### tls _certificate-path_ _key-path_ { ... }
Default: global directive value
TLS certificate & key to use. Fine-tuning of other TLS properties is possible TLS certificate & key to use. Fine-tuning of other TLS properties is possible
by specifying a configuration block and options inside it: by specifying a configuration block and options inside it:
``` ```
tls cert.crt key.key { tls cert.crt key.key {
protocols tls1.2 tls1.3 protocols tls1.2 tls1.3
@ -58,94 +61,107 @@ tls cert.crt key.key {
See [TLS configuration / Server](/reference/tls/#server-side) for details. See [TLS configuration / Server](/reference/tls/#server-side) for details.
---
**Syntax**: io\_debug _boolean_ <br> ### io_debug _boolean_
**Default**: no Default: `no`
Write all commands and responses to stderr. Write all commands and responses to stderr.
**Syntax**: debug _boolean_ <br> ---
**Default**: global directive value
### debug _boolean_
Default: global directive value
Enable verbose logging. Enable verbose logging.
**Syntax**: insecure\_auth _boolean_ <br> ---
**Default**: no (yes if TLS is disabled)
### insecure_auth _boolean_
Default: `no` (`yes` if TLS is disabled)
Allow plain-text authentication over unencrypted connections. Not recommended! Allow plain-text authentication over unencrypted connections. Not recommended!
**Syntax**: read\_timeout _duration_ <br> ---
**Default**: 10m
### read_timeout _duration_
Default: `10m`
I/O read timeout. I/O read timeout.
**Syntax**: write\_timeout _duration_ <br> ---
**Default**: 1m
### write_timeout _duration_
Default: `1m`
I/O write timeout. I/O write timeout.
**Syntax**: max\_message\_size _size_ <br> ---
**Default**: 32M
### max_message_size _size_
Default: `32M`
Limit the size of incoming messages to 'size'. Limit the size of incoming messages to 'size'.
**Syntax**: max\_header\_size _size_ <br> ---
**Default**: 1M
### max_header_size _size_
Default: `1M`
Limit the size of incoming message headers to 'size'. Limit the size of incoming message headers to 'size'.
**Syntax**: auth _module\_reference_ <br> ---
**Default**: not specified
### auth _module-reference_
Default: not specified
Use the specified module for authentication. Use the specified module for authentication.
**Syntax**: defer\_sender\_reject _boolean_ <br> ---
**Default**: yes
### defer_sender_reject _boolean_
Default: `yes`
Apply sender-based checks and routing logic when first RCPT TO command Apply sender-based checks and routing logic when first RCPT TO command
is received. This allows maddy to log recipient address of the rejected is received. This allows maddy to log recipient address of the rejected
message and also improves interoperability with (improperly implemented) message and also improves interoperability with (improperly implemented)
clients that don't expect an error early in session. clients that don't expect an error early in session.
**Syntax**: max\_logged\_rcpt\_errors _integer_ <br> ---
**Default**: 5
### max_logged_rcpt_errors _integer_
Default: `5`
Amount of RCPT-time errors that should be logged. Further errors will be Amount of RCPT-time errors that should be logged. Further errors will be
handled silently. This is to prevent log flooding during email dictionary handled silently. This is to prevent log flooding during email dictionary
attacks (address probing). attacks (address probing).
**Syntax**: max\_received _integer_ <br> ---
**Default**: 50
### max_received _integer_
Default: `50`
Max. amount of Received header fields in the message header. If the incoming Max. amount of Received header fields in the message header. If the incoming
message has more fields than this number, it will be rejected with the permanent error message has more fields than this number, it will be rejected with the permanent error
5.4.6 ("Routing loop detected"). 5.4.6 ("Routing loop detected").
**Syntax**: <br> ---
buffer ram <br>
buffer fs _[path]_ <br> ### buffer `ram`<br>buffer `fs` _path_ <br>buffer `auto` _max-size_ _path_
buffer auto _max\_size_ _[path]_ <br> Default: `auto 1M StateDirectory/buffer`
**Default**: auto 1M StateDirectory/buffer
Temporary storage to use for the body of accepted messages. Temporary storage to use for the body of accepted messages.
- ram - `ram` – Store the body in RAM.
- `fs` – Write out the message to the FS and read it back as needed.
Store the body in RAM.
- fs
Write out the message to the FS and read it back as needed.
_path_ can be omitted and defaults to StateDirectory/buffer. _path_ can be omitted and defaults to StateDirectory/buffer.
- `auto` – Store message bodies smaller than `_max_size_` entirely in RAM,
otherwise write them out to the FS. _path_ can be omitted and defaults to `StateDirectory/buffer`.
- auto ---
Store message bodies smaller than _max\_size_ entirely in RAM, otherwise write ### smtp_max_line_length _integer_
them out to the FS. Default: `4000`
_path_ can be omitted and defaults to StateDirectory/buffer.
**Syntax**: smtp\_max\_line\_length _integer_ <br>
**Default**: 4000
The maximum line length allowed in the SMTP input stream. If client sends a The maximum line length allowed in the SMTP input stream. If client sends a
longer line - connection will be closed and message (if any) will be rejected longer line - connection will be closed and message (if any) will be rejected
@ -157,26 +173,31 @@ to handle longer lines correctly but some senders may produce them.
Unless BDAT extension is used by the sender, this limitation also applies to Unless BDAT extension is used by the sender, this limitation also applies to
the message body. the message body.
**Syntax**: dmarc _boolean_ <br> ---
**Default**: yes
### dmarc _boolean_
Default: `yes`
Enforce sender's DMARC policy. Due to implementation limitations, it is not a Enforce sender's DMARC policy. Due to implementation limitations, it is not a
check module. check module.
**NOTE**: Report generation is not implemented now. **Note**: Report generation is not implemented now.
**NOTE**: DMARC needs SPF and DKIM checks to function correctly. **Note**: DMARC needs SPF and DKIM checks to function correctly.
Without these, DMARC check will not run. Without these, DMARC check will not run.
---
## Rate & concurrency limiting ## Rate & concurrency limiting
**Syntax**: limits _config block_ <br> ### limits { ... }
**Default**: no limits Default: no limits
This allows configuring a set of message flow restrictions including This allows configuring a set of message flow restrictions including
max. concurrency and rate per-endpoint, per-source, per-destination. max. concurrency and rate per-endpoint, per-source, per-destination.
Limits are specified as directives inside the block: Limits are specified as directives inside the block:
``` ```
limits { limits {
all rate 20 all rate 20
@ -186,16 +207,14 @@ limits {
Supported limits: Supported limits:
- Rate limit ### _scope_ rate _burst_ _period_
**Syntax**: _scope_ rate _burst_ _[period]_ <br> Rate limit. Restrict the amount of messages processed in _period_ to
Restrict the amount of messages processed in _period_ to _burst_ messages. _burst_ messages. If period is not specified, 1 second is used.
If period is not specified, 1 second is used.
- Concurrency limit ### _scope_ concurrency _max_
Concurrency limit. Restrict the amount of messages processed in parallel
**Syntax**: _scope_ concurrency _max_ <br> to _max_.
Restrict the amount of messages processed in parallel to _max\_.
For each supported limitation, _scope_ determines whether it should be applied For each supported limitation, _scope_ determines whether it should be applied
for all messages ("all"), per-sender IP ("ip"), per-sender domain ("source") or for all messages ("all"), per-sender IP ("ip"), per-sender domain ("source") or
@ -212,6 +231,7 @@ on outbound messages, do so using 'limits' directive for the 'table.remote' modu
It is possible to share limit counters between multiple endpoints (or any other It is possible to share limit counters between multiple endpoints (or any other
modules). To do so define a top-level configuration block for module "limits" modules). To do so define a top-level configuration block for module "limits"
and reference it where needed using standard & syntax. E.g. and reference it where needed using standard & syntax. E.g.
``` ```
limits inbound_limits { limits inbound_limits {
all rate 20 all rate 20
@ -227,6 +247,7 @@ submission tls://0.0.0.0:465 {
... ...
} }
``` ```
Using an "all rate" restriction in such way means that no more than 20 Using an "all rate" restriction in such way means that no more than 20
messages can enter the server through both endpoints in one second. messages can enter the server through both endpoints in one second.
@ -259,7 +280,6 @@ lmtp unix://lmtp.sock {
## Limitations of LMTP implementation ## Limitations of LMTP implementation
- Can't be used with TCP. - Can't be used with TCP.
- Delivery to 'sql' module storage is always atomic, either all recipients will - Delivery to 'sql' module storage is always atomic, either all recipients will
succeed or none of them will. succeed or none of them will.

88
docs/reference/global-config.md
View file

@ -5,26 +5,32 @@ configuration blocks and they are applied to all modules.
Some directives can be overridden on per-module basis (e.g. hostname). Some directives can be overridden on per-module basis (e.g. hostname).
**Syntax**: state\_dir _path_ <br> ### state_dir _path_
**Default**: /var/lib/maddy Default: `/var/lib/maddy`
The path to the state directory. This directory will be used to store all The path to the state directory. This directory will be used to store all
persistent data and should be writable. persistent data and should be writable.
**Syntax**: runtime\_dir _path_ <br> ---
**Default**: /run/maddy
### runtime_dir _path_
Default: `/run/maddy`
The path to the runtime directory. Used for Unix sockets and other temporary The path to the runtime directory. Used for Unix sockets and other temporary
objects. Should be writable. objects. Should be writable.
**Syntax**: hostname _domain_ <br> ---
**Default**: not specified
### hostname _domain_
Default: not specified
Internet hostname of this mail server. Typicall FQDN is used. It is recommended 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. to make sure domain specified here resolved to the public IP of the server.
**Syntax**: auth\_map _module\_reference_ <br> ---
**Default**: identity
### auth_map _module-reference_
Default: `identity`
Use the specified table to translate SASL usernames before passing it to the Use the specified table to translate SASL usernames before passing it to the
authentication provider. authentication provider.
@ -38,9 +44,11 @@ should also use `storage_map` in IMAP config block to handle this.
This directive is useful if used authentication provider does not support This directive is useful if used authentication provider does not support
using emails as usernames but you still want users to have separate mailboxes 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: on separate domains. In this case, use it with `email_localpart` table:
``` ```
auth_map email_localpart auth_map email_localpart
``` ```
With this configuration, `user@example.org` and `user@example.com` will use With this configuration, `user@example.org` and `user@example.com` will use
`user` credentials when authenticating, but will access `user@example.org` and `user` credentials when authenticating, but will access `user@example.org` and
`user@example.com` mailboxes correspondingly. If you want to also accept `user@example.com` mailboxes correspondingly. If you want to also accept
@ -49,17 +57,22 @@ With this configuration, `user@example.org` and `user@example.com` will use
If you want `user@example.org` and `user@example.com` to have the same mailbox, 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` also set `storage_map` in IMAP config block to use `email_localpart`
(or `email_localpart_optional` if you want to also accept just "user"): (or `email_localpart_optional` if you want to also accept just "user"):
``` ```
storage_map email_localpart storage_map email_localpart
``` ```
In this case you will need to create storage accounts without domain part in In this case you will need to create storage accounts without domain part in
the name: the name:
``` ```
maddy imap-acct create user # instead of user@example.org maddy imap-acct create user # instead of user@example.org
``` ```
**Syntax**: auth\_map_normalize _function_ <br> ---
**Default**: auto
### auth_map_normalize _function_
Default: `auto`
Normalization function to apply to SASL usernames before mapping Normalization function to apply to SASL usernames before mapping
them to storage accounts. them to storage accounts.
@ -74,17 +87,18 @@ Available options:
- `casefold` Convert to lower case - `casefold` Convert to lower case
- `noop` Nothing - `noop` Nothing
**Syntax**: autogenerated\_msg\_domain _domain_ <br> ---
**Default**: not specified
### autogenerated_msg_domain _domain_
Default: not specified
Domain that is used in From field for auto-generated messages (such as Delivery Domain that is used in From field for auto-generated messages (such as Delivery
Status Notifications). Status Notifications).
**Syntax**: <br> ---
tls file _cert\_file_ _pkey\_file_ <br>
tls _module reference_ <br> ### tls `file` _cert-file_ _pkey-file_ | _module-reference_ | `off`
tls off <br> Default: not specified
**Default**: not specified
Default TLS certificate to use for all endpoints. Default TLS certificate to use for all endpoints.
@ -96,40 +110,32 @@ 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 cipher suites and TLS versions by default so you generally don't have to worry
about it. about it.
**Syntax**: tls\_client { ... } <br> ---
**Default**: not specified
### tls_client { ... }
Default: not specified
This is optional block that specifies various TLS-related options to use when This is optional block that specifies various TLS-related options to use when
making outbound connections. See TLS client configuration for details on making outbound connections. See TLS client configuration for details on
directives that can be used in it. maddy uses reasonable cipher suites and TLS 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. versions by default so you generally don't have to worry about it.
**Syntax**: <br> ---
log _targets..._ <br>
log off <br> ### log _targets..._ | `off`
**Default**: stderr Default: `stderr`
Write log to one of more "targets". Write log to one of more "targets".
The target can be one or the following: The target can be one or the following:
- stderr - `stderr` – Write logs to stderr.
- `stderr_ts` – Write logs to stderr with timestamps.
Write logs to stderr. - `syslog` – Send logs to the local syslog daemon.
- _file path_ – Write (append) logs to file.
- stderr\_ts
Write logs to stderr with timestamps.
- syslog
Send logs to the local syslog daemon.
- _file path_
Write (append) logs to file.
Example: Example:
``` ```
log syslog /var/log/maddy.log log syslog /var/log/maddy.log
``` ```
@ -137,8 +143,10 @@ log syslog /var/log/maddy.log
**Note:** Maddy does not perform log files rotation, this is the job of the **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. logrotate daemon. Send SIGUSR1 to maddy process to make it reopen log files.
**Syntax**: debug _boolean_ <br> ---
**Default**: no
### debug _boolean_
Default: `no`
Enable verbose logging for all modules. You don't need that unless you are Enable verbose logging for all modules. You don't need that unless you are
reporting a bug. reporting a bug.

122
docs/reference/modifiers/dkim.md
View file

@ -13,10 +13,10 @@ key for the first domain will be used. If domain in envelope sender
does not match any of loaded keys, message will not be signed. does not match any of loaded keys, message will not be signed.
Additionally, for each messages From header is checked to Additionally, for each messages From header is checked to
match MAIL FROM and authorization identity (username sender is logged in as). match MAIL FROM and authorization identity (username sender is logged in as).
This can be controlled using require\_sender\_match directive. This can be controlled using require_sender_match directive.
Generated private keys are stored in unencrypted PKCS#8 format Generated private keys are stored in unencrypted PKCS#8 format
in state_directory/dkim_keys (/var/lib/maddy/dkim_keys). in state_directory/dkim_keys (`/var/lib/maddy/dkim_keys`).
In the same directory .dns files are generated that contain In the same directory .dns files are generated that contain
public key for each domain formatted in the form of a DNS record. public key for each domain formatted in the form of a DNS record.
@ -24,6 +24,7 @@ public key for each domain formatted in the form of a DNS record.
domains and selector can be specified in arguments, so actual modify.dkim use can domains and selector can be specified in arguments, so actual modify.dkim use can
be shortened to the following: be shortened to the following:
``` ```
modify { modify {
dkim example.org selector dkim example.org selector
@ -48,34 +49,39 @@ modify.dkim {
} }
``` ```
**Syntax**: debug _boolean_ <br> ### debug _boolean_
**Default**: global directive value Default: global directive value
Enable verbose logging. Enable verbose logging.
**Syntax**: domains _string list_ <br> ---
**Default**: not specified
### domains _string-list_
**Required**. <br>
Default: not specified
**REQUIRED.**
ADministrative Management Domains (ADMDs) taking responsibility for messages. ADministrative Management Domains (ADMDs) taking responsibility for messages.
Should be specified either as a directive or as an argument. Should be specified either as a directive or as an argument.
**Syntax**: selector _string_ <br> ---
**Default**: not specified
**REQUIRED.** ### selector _string_
**Required**. <br>
Default: not specified
Identifier of used key within the ADMD. Identifier of used key within the ADMD.
Should be specified either as a directive or as an argument. Should be specified either as a directive or as an argument.
**Syntax**: key\_path _string_ <br> ---
**Default**: dkim\_keys/{domain}\\_{selector}.key
### key_path _string_
Default: `dkim_keys/{domain}_{selector}.key`
Path to private key. It should be in PKCS#8 format wrapped in PAM encoding. Path to private key. It should be in PKCS#8 format wrapped in PAM encoding.
If key does not exist, it will be generated using algorithm specified If key does not exist, it will be generated using algorithm specified
in newkey\_algo. in newkey_algo.
Placeholders '{domain}' and '{selector}' will be replaced with corresponding Placeholders '{domain}' and '{selector}' will be replaced with corresponding
values from domain and selector directives. values from domain and selector directives.
@ -84,16 +90,19 @@ Additionally, keys in PKCS#1 ("RSA PRIVATE KEY") and
RFC 5915 ("EC PRIVATE KEY") can be read by modify.dkim. Note, however that RFC 5915 ("EC PRIVATE KEY") can be read by modify.dkim. Note, however that
newly generated keys are always in PKCS#8. newly generated keys are always in PKCS#8.
**Syntax**: oversign\_fields _list..._ <br> ---
**Default**: see below
### oversign_fields _list..._
Default: see below
Header fields that should be signed n+1 times where n is times they are Header fields that should be signed n+1 times where n is times they are
present in the message. This makes it impossible to replace field present in the message. This makes it impossible to replace field
value by prepending another field with the same name to the message. value by prepending another field with the same name to the message.
Fields specified here don't have to be also specified in sign\_fields. Fields specified here don't have to be also specified in `sign_fields`.
Default set of oversigned fields: Default set of oversigned fields:
- Subject - Subject
- To - To
- From - From
@ -107,14 +116,17 @@ Default set of oversigned fields:
- Autocrypt - Autocrypt
- Openpgp - Openpgp
**Syntax**: sign\_fields _list..._ <br> ---
**Default**: see below
### sign_fields _list..._
Default: see below
Header fields that should be signed n+1 times where n is times they are Header fields that should be signed n+1 times where n is times they are
present in the message. For these fields, additional values can be prepended present in the message. For these fields, additional values can be prepended
by intermediate relays, but existing values can't be changed. by intermediate relays, but existing values can't be changed.
Default set of signed fields: Default set of signed fields:
- List-Id - List-Id
- List-Help - List-Help
- List-Unsubscribe - List-Unsubscribe
@ -128,72 +140,86 @@ Default set of signed fields:
- Resent-From - Resent-From
- Resent-Cc - Resent-Cc
**Syntax**: header\_canon relaxed|simple <br> ---
**Default**: relaxed
Canonicalization algorithm to use for header fields. With 'relaxed', whitespace within ### header_canon `relaxed` | `simple`
fields can be modified without breaking the signature, with 'simple' no Default: `relaxed`
Canonicalization algorithm to use for header fields. With `relaxed`, whitespace within
fields can be modified without breaking the signature, with `simple` no
modifications are allowed. modifications are allowed.
**Syntax**: body\_canon relaxed|simple <br> ---
**Default**: relaxed
Canonicalization algorithm to use for message body. With 'relaxed', whitespace within ### body_canon `relaxed` | `simple`
can be modified without breaking the signature, with 'simple' no Default: `relaxed`
Canonicalization algorithm to use for message body. With `relaxed`, whitespace within
can be modified without breaking the signature, with `simple` no
modifications are allowed. modifications are allowed.
**Syntax**: sig\_expiry _duration_ <br> ---
**Default**: 120h
### sig_expiry _duration_
Default: `120h`
Time for which signature should be considered valid. Mainly used to prevent Time for which signature should be considered valid. Mainly used to prevent
unauthorized resending of old messages. unauthorized resending of old messages.
**Syntax**: hash _hash_ <br> ---
**Default**: sha256
### hash _hash_
Default: `sha256`
Hash algorithm to use when computing body hash. Hash algorithm to use when computing body hash.
sha256 is the only supported algorithm now. sha256 is the only supported algorithm now.
**Syntax**: newkey\_algo rsa4096|rsa2048|ed25519 <br> ---
**Default**: rsa2048
### newkey_algo `rsa4096` | `rsa2048` | `ed25519`
Default: `rsa2048`
Algorithm to use when generating a new key. Algorithm to use when generating a new key.
Currently ed25519 is NOT supported by most platforms. Currently ed25519 is **not** supported by most platforms.
**Syntax**: require\_sender\_match _ids..._ <br> ---
**Default**: envelope auth
### require_sender_match _ids..._
Default: `envelope auth`
Require specified identifiers to match From header field and key domain, Require specified identifiers to match From header field and key domain,
otherwise - don't sign the message. otherwise - don't sign the message.
If From field contains multiple addresses, message will not be If From field contains multiple addresses, message will not be
signed unless allow\_multiple\_from is also specified. In that signed unless `allow_multiple_from` is also specified. In that
case only first address will be compared. case only first address will be compared.
Matching is done in a case-insensitive way. Matching is done in a case-insensitive way.
Valid values: Valid values:
- off
Disable check, always sign. - `off` – Disable check, always sign.
- envelope - `envelope` – Require MAIL FROM address to match From header.
Require MAIL FROM address to match From header. - `auth` – If authorization identity contains @ - then require it to
- auth
If authorization identity contains @ - then require it to
fully match From header. Otherwise, check only local-part fully match From header. Otherwise, check only local-part
(username). (username).
**Syntax**: allow\_multiple\_from _boolean_ <br> ---
**Default**: no
### allow_multiple_from _boolean_
Default: `no`
Allow multiple addresses in From header field for purposes of Allow multiple addresses in From header field for purposes of
require\_sender\_match checks. Only first address will be checked, however. `require_sender_match` checks. Only first address will be checked, however.
**Syntax**: sign\_subdomains _boolean_ <br> ---
**Default**: no
### sign_subdomains _boolean_
Default: `no`
Sign emails from subdomains using a top domain key. Sign emails from subdomains using a top domain key.
Allows only one domain to be specified (can be worked around by using modify.dkim Allows only one domain to be specified (can be worked around by using `modify.dkim`
multiple times). multiple times).

5
docs/reference/modifiers/envelope.md
View file

@ -1,6 +1,6 @@
# Envelope sender / recipient rewriting # Envelope sender / recipient rewriting
'replace\_sender' and 'replace\_rcpt' modules replace SMTP envelope addresses `replace_sender` and `replace_rcpt` modules replace SMTP envelope addresses
based on the mapping defined by the table module (maddy-tables(5)). It is possible based on the mapping defined by the table module (maddy-tables(5)). It is possible
to specify 1:N mappings. This allows, for example, implementing mailing lists. to specify 1:N mappings. This allows, for example, implementing mailing lists.
@ -17,6 +17,7 @@ multiple times to a single recipient. However, used delivery target can apply
such deduplication (imapsql storage does it). such deduplication (imapsql storage does it).
Definition: Definition:
``` ```
replace_rcpt <table> [table arguments] { replace_rcpt <table> [table arguments] {
[extended table config] [extended table config]
@ -27,6 +28,7 @@ replace_sender <table> [table arguments] {
``` ```
Use examples: Use examples:
``` ```
modify { modify {
replace_rcpt file /etc/maddy/aliases replace_rcpt file /etc/maddy/aliases
@ -40,6 +42,7 @@ modify {
``` ```
Possible contents of /etc/maddy/aliases in the example above: Possible contents of /etc/maddy/aliases in the example above:
``` ```
# Replace 'cat' with any domain to 'dog'. # Replace 'cat' with any domain to 'dog'.
# E.g. cat@example.net -> dog@example.net # E.g. cat@example.net -> dog@example.net

140
docs/reference/smtp-pipeline.md
View file

@ -16,40 +16,41 @@ The pipeline is responsible for
message. message.
Message handling flow is as follows: Message handling flow is as follows:
- Execute checks referenced in top-level 'check' blocks (if any) - Execute checks referenced in top-level `check` blocks (if any)
- Execute modifiers referenced in top-level 'modify' blocks (if any) - Execute modifiers referenced in top-level `modify` blocks (if any)
- If there are 'source' blocks - select one that matches message sender (as - If there are `source` blocks - select one that matches message sender (as
specified in MAIL FROM). If there are no 'source' blocks - entire specified in MAIL FROM). If there are no `source` blocks - entire
configuration is assumed to be the 'default\_source' block. configuration is assumed to be the `default_source` block.
- Execute checks referenced in 'check' blocks inside selected 'source' block - Execute checks referenced in 'check' blocks inside selected 'source' block
(if any). (if any).
- Execute modifiers referenced in 'modify' blocks inside selected 'source' - Execute modifiers referenced in `modify` blocks inside selected `source`
block (if any). block (if any).
Then, for each recipient: Then, for each recipient:
- Select 'destination' block that matches it. If there are - Select `destination` block that matches it. If there are
no 'destination' blocks - entire used 'source' block is interpreted as if it no `destination` blocks - entire used `source` block is interpreted as if it
was a 'default\_destination' block. was a `default_destination` block.
- Execute checks referenced in 'check' block inside selected 'destination' block - Execute checks referenced in `check` block inside selected `destination` block
(if any). (if any).
- Execute modifiers referenced in 'modify' block inside selected 'destination' - Execute modifiers referenced in `modify` block inside selected `destination`
block (if any). block (if any).
- If used block contains 'reject' directive - reject the recipient with - If used block contains `reject` directive - reject the recipient with
specified SMTP status code. specified SMTP status code.
- If used block contains 'deliver\_to' directive - pass the message to the - If used block contains `deliver_to` directive - pass the message to the
specified target module. Only recipients that are handled specified target module. Only recipients that are handled
by used block are visible to the target. by used block are visible to the target.
Each recipient is handled only by a single 'destination' block, in case of Each recipient is handled only by a single `destination` block, in case of
overlapping 'destination' - first one takes priority. overlapping `destination` - first one takes priority.
``` ```
destination example.org { destination example.org {
deliver_to targetA deliver_to targetA
@ -58,30 +59,34 @@ destination example.org { # ambiguous and thus not allowed
deliver_to targetB deliver_to targetB
} }
``` ```
Same goes for 'source' blocks, each message is handled only by a single block.
Each recipient block should contain at least one 'deliver\_to' directive or Same goes for `source` blocks, each message is handled only by a single block.
'reject' directive. If 'destination' blocks are used, then
'default\_destination' block should also be used to specify behavior for Each recipient block should contain at least one `deliver_to` directive or
unmatched recipients. Same goes for source blocks, 'default\_source' should be `reject` directive. If `destination` blocks are used, then
used if 'source' is used. `default_destination` block should also be used to specify behavior for
unmatched recipients. Same goes for source blocks, `default_source` should be
used if `source` is used.
That is, pipeline configuration should explicitly specify behavior for each That is, pipeline configuration should explicitly specify behavior for each
possible sender/recipient combination. possible sender/recipient combination.
Additionally, directives that specify final handling decision ('deliver\_to', Additionally, directives that specify final handling decision (`deliver_to`,
'reject') can't be used at the same level as source/destination rules. `reject`) can't be used at the same level as source/destination rules.
Consider example: Consider example:
``` ```
destination example.org { destination example.org {
deliver_to local_mboxes deliver_to local_mboxes
} }
reject reject
``` ```
It is not obvious whether 'reject' applies to all recipients or
It is not obvious whether `reject` applies to all recipients or
just for non-example.org ones, hence this is not allowed. just for non-example.org ones, hence this is not allowed.
Complete configuration example using all of the mentioned directives: Complete configuration example using all of the mentioned directives:
``` ```
check { check {
# Run a check to make sure source SMTP server identification # Run a check to make sure source SMTP server identification
@ -114,8 +119,9 @@ default_source {
## Directives ## Directives
**Syntax**: check _block name_ { ... } <br>
**Context**: pipeline configuration, source block, destination block ### check _block name_ { ... }
Context: pipeline configuration, source block, destination block
List of the module references for checks that should be executed on List of the module references for checks that should be executed on
messages handled by block where 'check' is placed in. messages handled by block where 'check' is placed in.
@ -126,6 +132,7 @@ be rejected for all recipients which is not what you usually want when using
such configurations. such configurations.
Example: Example:
``` ```
check { check {
# Reference implicitly defined default configuration for check. # Reference implicitly defined default configuration for check.
@ -141,6 +148,7 @@ check {
It is also possible to define the block of checks at the top level It is also possible to define the block of checks at the top level
as "checks" module and reference it using & syntax. Example: as "checks" module and reference it using & syntax. Example:
``` ```
checks inbound_checks { checks inbound_checks {
spf spf
@ -154,9 +162,11 @@ checks inbound_checks {
} }
``` ```
**Syntax**: modify { ... } <br> ---
**Default**: not specified <br>
**Context**: pipeline configuration, source block, destination block ### modify { ... }
Default: not specified<br>
Context: pipeline configuration, source block, destination block
List of the module references for modifiers that should be executed on List of the module references for modifiers that should be executed on
messages handled by block where 'modify' is placed in. messages handled by block where 'modify' is placed in.
@ -177,6 +187,7 @@ affect the message header will affect it for all recipients.
It is also possible to define the block of modifiers at the top level It is also possible to define the block of modifiers at the top level
as "modiifers" module and reference it using & syntax. Example: as "modiifers" module and reference it using & syntax. Example:
``` ```
modifiers local_modifiers { modifiers local_modifiers {
replace_rcpt file /etc/maddy/aliases replace_rcpt file /etc/maddy/aliases
@ -189,12 +200,10 @@ modifiers local_modifiers {
} }
``` ```
**Syntax**: <br> ---
reject _smtp\_code_ _smtp\_enhanced\_code_ _error\_description_ <br>
reject _smtp\_code_ _smtp\_enhanced\_code_ <br> ### reject _smtp-code_ _smtp-enhanced-code_ _error-description_ <br>reject _smtp-code_ _smtp-enhanced-code_ <br>reject _smtp-code_ <br>reject
reject _smtp\_code_ <br> Context: destination block
reject <br>
**Context**: destination block
Messages handled by the configuration block with this directive will be Messages handled by the configuration block with this directive will be
rejected with the specified SMTP error. rejected with the specified SMTP error.
@ -203,30 +212,36 @@ If you aren't sure which codes to use, use 541 and 5.4.0 with your message or
just leave all arguments out, the error description will say "message is just leave all arguments out, the error description will say "message is
rejected due to policy reasons" which is usually what you want to mean. rejected due to policy reasons" which is usually what you want to mean.
'reject' can't be used in the same block with 'deliver\_to' or `reject` can't be used in the same block with `deliver_to` or
'destination/source' directives. `destination`/`source` directives.
Example: Example:
``` ```
reject 541 5.4.0 "We don't like example.org, go away" reject 541 5.4.0 "We don't like example.org, go away"
``` ```
**Syntax**: deliver\_to _target-config-block_ <br> ---
**Context**: pipeline configuration, source block, destination block
### deliver_to _target-config-block_
Context: pipeline configuration, source block, destination block
Deliver the message to the referenced delivery target. What happens next is Deliver the message to the referenced delivery target. What happens next is
defined solely by used target. If deliver\_to is used inside 'destination' defined solely by used target. If `deliver_to` is used inside `destination`
block, only matching recipients will be passed to the target. block, only matching recipients will be passed to the target.
**Syntax**: source\_in _table reference_ { ... } <br> ---
**Context**: pipeline configuration
### source_in _table-reference_ { ... }
Context: pipeline configuration
Handle messages with envelope senders present in the specified table in Handle messages with envelope senders present in the specified table in
accordance with the specified configuration block. accordance with the specified configuration block.
Takes precedence over all 'sender' directives. Takes precedence over all `sender` directives.
Example: Example:
``` ```
source_in file /etc/maddy/banned_addrs { source_in file /etc/maddy/banned_addrs {
reject 550 5.7.0 "You are not welcome here" reject 550 5.7.0 "You are not welcome here"
@ -237,10 +252,12 @@ source example.org {
... ...
``` ```
See 'destination\_in' documentation for note about table configuration. See `destination_in` documentation for note about table configuration.
**Syntax**: source _rules..._ { ... } <br> ---
**Context**: pipeline configuration
### source _rules..._ { ... }
Context: pipeline configuration
Handle messages with MAIL FROM value (sender address) matching any of the rules Handle messages with MAIL FROM value (sender address) matching any of the rules
in accordance with the specified configuration block. in accordance with the specified configuration block.
@ -249,6 +266,7 @@ in accordance with the specified configuration block.
'rules', first one takes priority. Matching is case-insensitive. 'rules', first one takes priority. Matching is case-insensitive.
Example: Example:
``` ```
# All messages coming from example.org domain will be delivered # All messages coming from example.org domain will be delivered
# to local_mailboxes. # to local_mailboxes.
@ -261,8 +279,10 @@ default_source {
} }
``` ```
**Syntax**: reroute { ... } <br> ---
**Context**: pipeline configuration, source block, destination block
### reroute { ... }
Context: pipeline configuration, source block, destination block
This directive allows to make message routing decisions based on the This directive allows to make message routing decisions based on the
result of modifiers. The block can contain all pipeline directives and they result of modifiers. The block can contain all pipeline directives and they
@ -271,6 +291,7 @@ will use the final recipient and sender values (e.g. after all modifiers are
applied). applied).
Here is the concrete example how it can be useful: Here is the concrete example how it can be useful:
``` ```
destination example.org { destination example.org {
modify { modify {
@ -288,15 +309,17 @@ destination example.org {
``` ```
This configuration allows to specify alias local addresses to remote ones This configuration allows to specify alias local addresses to remote ones
without being an open relay, since remote\_queue can be used only if remote without being an open relay, since remote_queue can be used only if remote
address was introduced as a result of rewrite of local address. address was introduced as a result of rewrite of local address.
**WARNING**: If you have DMARC enabled (default), results generated by SPF **Warning**: If you have DMARC enabled (default), results generated by SPF
and DKIM checks inside a reroute block **will not** be considered in DMARC and DKIM checks inside a reroute block **will not** be considered in DMARC
evaluation. evaluation.
**Syntax**: destination\_in _table reference_ { ... } <br> ---
**Context**: pipeline configuration, source block
### destination_in _table-reference_ { ... }
Context: pipeline configuration, source block
Handle messages with envelope recipients present in the specified table in Handle messages with envelope recipients present in the specified table in
accordance with the specified configuration block. accordance with the specified configuration block.
@ -304,6 +327,7 @@ accordance with the specified configuration block.
Takes precedence over all 'destination' directives. Takes precedence over all 'destination' directives.
Example: Example:
``` ```
destination_in file /etc/maddy/remote_addrs { destination_in file /etc/maddy/remote_addrs {
deliver_to smtp tcp://10.0.0.7:25 deliver_to smtp tcp://10.0.0.7:25
@ -316,6 +340,7 @@ destination example.com {
Note that due to the syntax restrictions, it is not possible to specify Note that due to the syntax restrictions, it is not possible to specify
extended configuration for table module. E.g. this is not valid: extended configuration for table module. E.g. this is not valid:
``` ```
destination_in sql_table { destination_in sql_table {
dsn ... dsn ...
@ -327,6 +352,7 @@ destination_in sql_table {
In this case, configuration should be specified separately and be referneced In this case, configuration should be specified separately and be referneced
using '&' syntax: using '&' syntax:
``` ```
table.sql_table remote_addrs { table.sql_table remote_addrs {
dsn ... dsn ...
@ -340,8 +366,10 @@ whatever {
} }
``` ```
**Syntax**: destination _rule..._ { ... } <br> ---
**Context**: pipeline configuration, source block
### destination _rule..._ { ... }
Context: pipeline configuration, source block
Handle messages with RCPT TO value (recipient address) matching any of the Handle messages with RCPT TO value (recipient address) matching any of the
rules in accordance with the specified configuration block. rules in accordance with the specified configuration block.
@ -354,6 +382,7 @@ they have recipients matched by multiple blocks. Each block will see the
message only with recipients matched by its rules. message only with recipients matched by its rules.
Example: Example:
``` ```
# Messages with recipients at example.com domain will be # Messages with recipients at example.com domain will be
# delivered to local_mailboxes target. # delivered to local_mailboxes target.
@ -370,9 +399,10 @@ default_destination {
## Reusable pipeline snippets (msgpipeline module) ## Reusable pipeline snippets (msgpipeline module)
The message pipeline can be used independently of the SMTP module in other The message pipeline can be used independently of the SMTP module in other
contexts that require a delivery target via "msgpipeline" module. contexts that require a delivery target via `msgpipeline` module.
Example: Example:
``` ```
msgpipeline local_routing { msgpipeline local_routing {
destination whatever.com { destination whatever.com {

131
docs/reference/storage/imapsql.md
View file

@ -3,7 +3,7 @@
The imapsql module implements database for IMAP index and message The imapsql module implements database for IMAP index and message
metadata using SQL-based relational database. metadata using SQL-based relational database.
Message contents are stored in an "blob store" defined by msg\_store Message contents are stored in an "blob store" defined by msg_store
directive. By default this is a file system directory under /var/lib/maddy. directive. By default this is a file system directory under /var/lib/maddy.
Supported RDBMS: Supported RDBMS:
@ -25,7 +25,7 @@ storage.imapsql {
imapsql module also can be used as a lookup table. imapsql module also can be used as a lookup table.
It returns empty string values for existing usernames. This might be useful It returns empty string values for existing usernames. This might be useful
with destination\_in directive e.g. to implement catch-all with `destination_in` directive e.g. to implement catch-all
addresses (this is a bad idea to do so, this is just an example): addresses (this is a bad idea to do so, this is just an example):
``` ```
destination_in &local_mailboxes { destination_in &local_mailboxes {
@ -46,20 +46,20 @@ Specify the driver and DSN.
## Configuration directives ## Configuration directives
**Syntax**: driver _string_ <br> ### driver _string_
**Default**: not specified **Required.**<br>
Default: not specified
REQUIRED.
Use a specified driver to communicate with the database. Supported values: Use a specified driver to communicate with the database. Supported values:
sqlite3, postgres. sqlite3, postgres.
Should be specified either via an argument or via this directive. Should be specified either via an argument or via this directive.
**Syntax**: dsn _string_ <br> ---
**Default**: not specified
REQUIRED. ### dsn _string_
**Required.**<br>
Default: not specified
Data Source Name, the driver-specific value that specifies the database to use. Data Source Name, the driver-specific value that specifies the database to use.
@ -68,118 +68,141 @@ For PostgreSQL: [https://godoc.org/github.com/lib/pq#hdr-Connection\_String\_Par
Should be specified either via an argument or via this directive. Should be specified either via an argument or via this directive.
**Syntax**: msg\_store _store_ <br> ---
**Default**: fs messages/
### msg_store _store_
Default: `fs messages/`
Module to use for message bodies storage. Module to use for message bodies storage.
See "Blob storage" section for what you can use here. See "Blob storage" section for what you can use here.
**Syntax**: <br> ---
compression off <br>
compression _algorithm_ <br> ### compression `off`<br>compression _algorithm_<br>compression _algorithm_ _level_
compression _algorithm_ _level_ <br> Default: `off`
**Default**: off
Apply compression to message contents. Apply compression to message contents.
Supported algorithms: lz4, zstd. Supported algorithms: `lz4`, `zstd`.
**Syntax**: appendlimit _size_ <br> ---
**Default**: 32M
### appendlimit _size_
Default: `32M`
Don't allow users to add new messages larger than 'size'. Don't allow users to add new messages larger than 'size'.
This does not affect messages added when using module as a delivery target. This does not affect messages added when using module as a delivery target.
Use 'max\_message\_size' directive in SMTP endpoint module to restrict it too. Use `max_message_size` directive in SMTP endpoint module to restrict it too.
**Syntax**: debug _boolean_ <br> ---
**Default**: global directive value
### debug _boolean_
Default: global directive value
Enable verbose logging. Enable verbose logging.
**Syntax**: junk\_mailbox _name_ <br> ---
**Default**: Junk
### junk_mailbox _name_
Default: `Junk`
The folder to put quarantined messages in. Thishis setting is not used if user The folder to put quarantined messages in. Thishis setting is not used if user
does have a folder with "Junk" special-use attribute. does have a folder with "Junk" special-use attribute.
**Syntax**: disable\_recent _boolean_ <br> ---
*Default: true
### disable_recent _boolean_
Default: `true`
Disable RFC 3501-conforming handling of \Recent flag. Disable RFC 3501-conforming handling of \Recent flag.
This significantly improves storage performance when SQLite3 or CockroackDB is This significantly improves storage performance when SQLite3 or CockroackDB is
used at the cost of confusing clients that use this flag. used at the cost of confusing clients that use this flag.
**Syntax**: sqlite\_cache\_size _integer_ <br> ---
**Default**: defined by SQLite
### sqlite_cache_size _integer_
Default: defined by SQLite
SQLite page cache size. If positive - specifies amount of pages (1 page - 4 SQLite page cache size. If positive - specifies amount of pages (1 page - 4
KiB) to keep in cache. If negative - specifies approximate upper bound KiB) to keep in cache. If negative - specifies approximate upper bound
of cache size in KiB. of cache size in KiB.
**Syntax**: sqlite\_busy\_timeout _integer_ <br> ---
**Default**: 5000000
### sqlite_busy_timeout _integer_
Default: `5000000`
SQLite-specific performance tuning option. Amount of milliseconds to wait SQLite-specific performance tuning option. Amount of milliseconds to wait
before giving up on DB lock. before giving up on DB lock.
**Syntax**: imap\_filter { ... } <br> ---
**Default**: not set
### imap_filter { ... }
Default: not set
Specifies IMAP filters to apply for messages delivered from SMTP pipeline. Specifies IMAP filters to apply for messages delivered from SMTP pipeline.
Ex. Ex.
``` ```
imap_filter { imap_filter {
command /etc/maddy/sieve.sh {account_name} command /etc/maddy/sieve.sh {account_name}
} }
``` ```
**Syntax:** delivery\_map **table** <br> ---
**Default:** identity
### delivery_map _table_
Default: `identity`
Use specified table module to map recipient Use specified table module to map recipient
addresses from incoming messages to mailbox names. addresses from incoming messages to mailbox names.
Normalization algorithm specified in delivery\_normalize is appied before Normalization algorithm specified in `delivery_normalize` is appied before
delivery\_map. `delivery_map`.
**Syntax:** delivery\_normalize _name_ <br> ---
**Default:** precis\_casefold\_email
### delivery_normalize _name_
Default: `precis_casefold_email`
Normalization function to apply to email addresses before mapping them Normalization function to apply to email addresses before mapping them
to mailboxes. to mailboxes.
See auth\_normalize. See `auth_normalize`.
**Syntax**: auth\_map **table** <br> ---
**Default**: identity
**DEPRECATED:** Use `storage_map` in imap config instead. ### auth_map _table_
**Deprecated:** Use `storage_map` in imap config instead.<br>
Default: `identity`
Use specified table module to map authentication Use specified table module to map authentication
usernames to mailbox names. usernames to mailbox names.
Normalization algorithm specified in auth\_normalize is applied before Normalization algorithm specified in auth_normalize is applied before
auth\_map. auth_map.
**Syntax**: auth\_normalize _name_ <br> ---
**Default**: precis\_casefold\_email
**DEPRECATED:** Use `storage_map_normalize` in imap config instead. ### auth_normalize _name_
**Deprecated:** Use `storage_map_normalize` in imap config instead.<br>
**Default**: `precis_casefold_email`
Normalization function to apply to authentication usernames before mapping Normalization function to apply to authentication usernames before mapping
them to mailboxes. them to mailboxes.
Available options: Available options:
- precis\_casefold\_email PRECIS UsernameCaseMapped profile + U-labels form for domain
- precis\_casefold PRECIS UsernameCaseMapped profile for the entire string - `precis_casefold_email` PRECIS UsernameCaseMapped profile + U-labels form for domain
- precis\_email PRECIS UsernameCasePreserved profile + U-labels form for domain - `precis_casefold` PRECIS UsernameCaseMapped profile for the entire string
- precis PRECIS UsernameCasePreserved profile for the entire string - `precis_email` PRECIS UsernameCasePreserved profile + U-labels form for domain
- casefold Convert to lower case - `precis` PRECIS UsernameCasePreserved profile for the entire string
- noop Nothing - `casefold` Convert to lower case
- `noop` Nothing
Note: On message delivery, recipient address is unconditionally normalized Note: On message delivery, recipient address is unconditionally normalized
using precis\_casefold\_email function. using `precis_casefold_email` function.

7
docs/reference/table/chain.md
View file

@ -16,12 +16,14 @@ in /etc/maddy/emails list.
## Configuration directives ## Configuration directives
**Syntax**: step _table\_ ### step _table_
Adds a table module to the chain. If input value is not in the table Adds a table module to the chain. If input value is not in the table
(e.g. file) - return "not exists" error. (e.g. file) - return "not exists" error.
**Syntax**: optional\_step _table\_ ---
### optional_step _table_
Same as step but if input value is not in the table - it is passed to the Same as step but if input value is not in the table - it is passed to the
next step without changes. next step without changes.
@ -29,6 +31,7 @@ next step without changes.
Example: Example:
Something like this can be used to map emails to usernames Something like this can be used to map emails to usernames
after translating them via aliases map: after translating them via aliases map:
``` ```
table.chain { table.chain {
optional_step file /etc/maddy/aliases optional_step file /etc/maddy/aliases

7
docs/reference/table/email_localpart.md
View file

@ -1,11 +1,12 @@
# Email local part # Email local part
The module 'table.email\_localpart' extracts and unescapes local ("username") part The module `table.email_localpart` extracts and unescapes local ("username") part
of the email address. of the email address.
E.g. E.g.
test@example.org => test
"test @ a"@example.org => test @ a * `test@example.org` => `test`
* `"test @ a"@example.org` => `test @ a`
Mappings for invalid emails are not defined (will be treated as non-existing Mappings for invalid emails are not defined (will be treated as non-existing
values). values).

6
docs/reference/table/email_with_domains.md
View file

@ -1,6 +1,6 @@
# Email with domain # Email with domain
The table module 'table.email\_with\_domain' appends one or more The table module `table.email_with_domain` appends one or more
domains (allowing 1:N expansion) to the specified value. domains (allowing 1:N expansion) to the specified value.
``` ```
@ -9,6 +9,7 @@ table.email_with_domains DOMAIN DOMAIN... { }
It can be used to implement domain-level expansion for aliases if used together It can be used to implement domain-level expansion for aliases if used together
with `table.chain`. Example: with `table.chain`. Example:
``` ```
modify { modify {
replace_rcpt chain { replace_rcpt chain {
@ -17,17 +18,20 @@ modify {
} }
} }
``` ```
This configuration will alias `anything@anydomain` to `anything@example.org` This configuration will alias `anything@anydomain` to `anything@example.org`
and `anything@example.com`. and `anything@example.com`.
It is also useful with `authorize_sender` to authorize sending using multiple It is also useful with `authorize_sender` to authorize sending using multiple
addresses under different domains if non-email usernames are used for addresses under different domains if non-email usernames are used for
authentication: authentication:
``` ```
check.authorize_sender { check.authorize_sender {
... ...
user_to_email email_with_domain example.org example.com user_to_email email_with_domain example.org example.com
} }
``` ```
This way, user authenticated as `user` will be allowed to use This way, user authenticated as `user` will be allowed to use
`user@example.org` or `user@example.com` as a sender address. `user@example.org` or `user@example.com` as a sender address.

25
docs/reference/table/regexp.md
View file

@ -18,8 +18,9 @@ table.regexp <regexp> [replacement] {
Note that [replacement] is optional. If it is not included - table.regexp Note that [replacement] is optional. If it is not included - table.regexp
will return the original string, therefore acting as a regexp match check. will return the original string, therefore acting as a regexp match check.
This can be useful in combination in destination\_in for This can be useful in combination in `destination_in` for
advanced matching: advanced matching:
``` ```
destination_in regexp ".*-bounce+.*@example.com" { destination_in regexp ".*-bounce+.*@example.com" {
... ...
@ -28,27 +29,31 @@ destination_in regexp ".*-bounce+.*@example.com" {
## Configuration directives ## Configuration directives
***Syntax***: full\_match _boolean_ <br> ### full_match _boolean_
***Default***: yes Default: `yes`
Whether to implicitly add start/end anchors to the regular expression. Whether to implicitly add start/end anchors to the regular expression.
That is, if 'full\_match' is yes, then the provided regular expression should That is, if `full_match` is `yes`, then the provided regular expression should
match the whole string. With no - partial match is enough. match the whole string. With `no` - partial match is enough.
***Syntax***: case\_insensitive _boolean_ <br> ---
***Default***: yes
### case_insensitive _boolean_
Default: `yes`
Whether to make matching case-insensitive. Whether to make matching case-insensitive.
***Syntax***: expand\_placeholders _boolean_ <br> ---
***Default***: yes
### expand_placeholders _boolean_
Default: `yes`
Replace '$name' and '${name}' in the replacement string with contents of Replace '$name' and '${name}' in the replacement string with contents of
corresponding capture groups from the match. corresponding capture groups from the match.
To insert a literal $ in the output, use $$ in the template. To insert a literal $ in the output, use $$ in the template.
# Identity table (table.identity) ## Identity table (table.identity)
The module 'identity' is a table module that just returns the key looked up. The module 'identity' is a table module that just returns the key looked up.

46
docs/reference/table/sql_query.md
View file

@ -1,8 +1,9 @@
# SQL query mapping # SQL query mapping
The table.sql\_query module implements table interface using SQL queries. The table.sql_query module implements table interface using SQL queries.
Definition: Definition:
``` ```
table.sql_query { table.sql_query {
driver <driver name> driver <driver name>
@ -19,6 +20,7 @@ table.sql_query {
``` ```
Usage example: Usage example:
``` ```
# Resolve SMTP address aliases using PostgreSQL DB. # Resolve SMTP address aliases using PostgreSQL DB.
modify { modify {
@ -32,22 +34,26 @@ modify {
## Configuration directives ## Configuration directives
***Syntax***: driver _driver name_ <br> ### driver _driver name_
***REQUIRED*** **Required.**
Driver to use to access the database. Driver to use to access the database.
Supported drivers: postgres, sqlite3 (if compiled with C support) Supported drivers: `postgres`, `sqlite3` (if compiled with C support)
***Syntax***: dsn _data source name_ <br> ---
***REQUIRED***
### dsn _data source name_
**Required.**
Data Source Name to pass to the driver. For SQLite3 this is just a path to DB Data Source Name to pass to the driver. For SQLite3 this is just a path to DB
file. For Postgres, see file. For Postgres, see
[https://pkg.go.dev/github.com/lib/pq?tab=doc#hdr-Connection\_String\_Parameters](https://pkg.go.dev/github.com/lib/pq?tab=doc#hdr-Connection\_String\_Parameters) [https://pkg.go.dev/github.com/lib/pq?tab=doc#hdr-Connection\_String\_Parameters](https://pkg.go.dev/github.com/lib/pq?tab=doc#hdr-Connection\_String\_Parameters)
***Syntax***: lookup _query_ <br> ---
***REQUIRED***
### lookup _query_
**Required.**
SQL query to use to obtain the lookup result. SQL query to use to obtain the lookup result.
@ -58,12 +64,15 @@ rows, they will be ignored. If there are more columns, lookup will fail. If
there are no rows, lookup returns "no results". If there are any error - lookup there are no rows, lookup returns "no results". If there are any error - lookup
will fail. will fail.
***Syntax***: init _queries..._ <br> ---
***Default***: empty
### init _queries..._
Default: empty
List of queries to execute on initialization. Can be used to configure RDBMS. List of queries to execute on initialization. Can be used to configure RDBMS.
Example, to improve SQLite3 performance: Example, to improve SQLite3 performance:
``` ```
table.sql_query { table.sql_query {
driver sqlite3 driver sqlite3
@ -74,8 +83,10 @@ table.sql_query {
} }
``` ```
**Syntax:** named\_args _boolean_ <br> ---
**Default:** yes
### named_args _boolean_
Default: `yes`
Whether to use named parameters binding when executing SQL queries Whether to use named parameters binding when executing SQL queries
or not. or not.
@ -84,11 +95,10 @@ Note that maddy's PostgreSQL driver does not support named parameters and
SQLite3 driver has issues handling numbered parameters: SQLite3 driver has issues handling numbered parameters:
[https://github.com/mattn/go-sqlite3/issues/472](https://github.com/mattn/go-sqlite3/issues/472) [https://github.com/mattn/go-sqlite3/issues/472](https://github.com/mattn/go-sqlite3/issues/472)
***Syntax:*** add _query_ <br> ---
***Syntax:*** list _query_ <br>
***Syntax:*** set _query_ <br> ### add _query_<br>list _query_<br>set _query_ <br>del _query_
***Syntax:*** del _query_ <br> Default: none
***Default:*** none
If queries are set to implement corresponding table operations - table becomes If queries are set to implement corresponding table operations - table becomes
"mutable" and can be used in contexts that require writable key-value store. "mutable" and can be used in contexts that require writable key-value store.
@ -105,6 +115,6 @@ entry in the database.
'del' query gets :key argument - key and should remove it from the database. 'del' query gets :key argument - key and should remove it from the database.
If named\_args is set to "no" - key is passed as the first numbered parameter If `named_args` is set to `no` - key is passed as the first numbered parameter
($1), value is passed as the second numbered parameter ($2). ($1), value is passed as the second numbered parameter ($2).

2
docs/reference/table/static.md
View file

@ -13,7 +13,7 @@ table.static {
## Configuration directives ## Configuration directives
***Syntax***: entry _key_ _value\_ ### entry _key_ _value_
Add an entry to the table. Add an entry to the table.

45
docs/reference/targets/queue.md
View file

@ -33,38 +33,45 @@ target.queue {
} }
``` ```
**Syntax**: target _block\_name_ <br> ### target _block_name_
**Default**: not specified **Required.** <br>
Default: not specified
REQUIRED.
Delivery target to use for final delivery. Delivery target to use for final delivery.
**Syntax**: location _directory_ <br> ---
**Default**: StateDirectory/configuration\_block\_name
### location _directory_
Default: `StateDirectory/configuration_block_name`
File system directory to use to store queued messages. File system directory to use to store queued messages.
Relative paths are relative to the StateDirectory. Relative paths are relative to the StateDirectory.
**Syntax**: max\_parallelism _integer_ <br> ---
**Default**: 16
### max_parallelism _integer_
Default: `16`
Start up to _integer_ goroutines for message processing. Basically, this option Start up to _integer_ goroutines for message processing. Basically, this option
limits amount of messages tried to be delivered concurrently. limits amount of messages tried to be delivered concurrently.
**Syntax**: max\_tries _integer_ <br> ---
**Default**: 20
### max_tries _integer_
Default: `20`
Attempt delivery up to _integer_ times. Note that no more attempts will be done Attempt delivery up to _integer_ times. Note that no more attempts will be done
is permanent error occurred during previous attempt. is permanent error occurred during previous attempt.
Delay before the next attempt will be increased exponentially using the Delay before the next attempt will be increased exponentially using the
following formula: 15mins \* 1.2 ^ (n - 1) where n is the attempt number. following formula: 15mins * 1.2 ^ (n - 1) where n is the attempt number.
This gives you approximately the following sequence of delays: This gives you approximately the following sequence of delays:
18mins, 21mins, 25mins, 31mins, 37mins, 44mins, 53mins, 64mins, ... 18mins, 21mins, 25mins, 31mins, 37mins, 44mins, 53mins, 64mins, ...
**Syntax**: bounce { ... } <br> ---
**Default**: not specified
### bounce { ... }
Default: not specified
This configuration contains pipeline configuration to be used for generated DSN This configuration contains pipeline configuration to be used for generated DSN
(Delivery Status Notification) messages. (Delivery Status Notification) messages.
@ -72,13 +79,17 @@ This configuration contains pipeline configuration to be used for generated DSN
If this is block is not present in configuration, DSNs will not be generated. If this is block is not present in configuration, DSNs will not be generated.
Note, however, this is not what you want most of the time. Note, however, this is not what you want most of the time.
**Syntax**: autogenerated\_msg\_domain _domain_ <br> ---
**Default**: global directive value
### autogenerated_msg_domain _domain_
Default: global directive value
Domain to use in sender address for DSNs. Should be specified too if 'bounce' Domain to use in sender address for DSNs. Should be specified too if 'bounce'
block is specified. block is specified.
**Syntax**: debug _boolean_ <br> ---
**Default**: no
### debug _boolean_
Default: `no`
Enable verbose logging. Enable verbose logging.

118
docs/reference/targets/remote.md
View file

@ -15,27 +15,33 @@ target.remote {
} }
``` ```
**Syntax**: hostname _domain_ <br> ### hostname _domain_
**Default**: global directive value Default: global directive value
Hostname to use client greeting (EHLO/HELO command). Some servers require it to Hostname to use client greeting (EHLO/HELO command). Some servers require it to
be FQDN, SPF-capable servers check whether it corresponds to the server IP be FQDN, SPF-capable servers check whether it corresponds to the server IP
address, so it is better to set it to a domain that resolves to the server IP. address, so it is better to set it to a domain that resolves to the server IP.
**Syntax**: limits _config block_ <br> ---
**Default**: no limits
### limits { ... }
Default: no limits
See ['limits' directive for SMTP endpoint](/reference/endpoints/smtp/#rate-concurrency-limiting). See ['limits' directive for SMTP endpoint](/reference/endpoints/smtp/#rate-concurrency-limiting).
It works the same except for address domains used for It works the same except for address domains used for
per-source/per-destination are as observed when message exits the server. per-source/per-destination are as observed when message exits the server.
**Syntax**: local\_ip _IP address_ <br> ---
**Default**: empty
### local_ip _ip-address_
Default: empty
Choose the local IP to bind for outbound SMTP connections. Choose the local IP to bind for outbound SMTP connections.
**Syntax**: force\_ipv4 _boolean_ <br> ---
**Default**: false
### force_ipv4 _boolean_
Default: `false`
Force resolving outbound SMTP domains to IPv4 addresses. Some server providers Force resolving outbound SMTP domains to IPv4 addresses. Some server providers
do not offer a way to properly set reverse PTR domains for IPv6 addresses; this do not offer a way to properly set reverse PTR domains for IPv6 addresses; this
@ -45,8 +51,10 @@ its IPv4 address.
Warning: this may break sending outgoing mail to IPv6-only SMTP servers. Warning: this may break sending outgoing mail to IPv6-only SMTP servers.
**Syntax**: connect\_timeout _duration_ <br> ---
**Default**: 5m
### connect_timeout _duration_
Default: `5m`
Timeout for TCP connection establishment. Timeout for TCP connection establishment.
@ -56,8 +64,10 @@ lookup + TCP handshake) and another for "initial greeting". This directive
configures the former. The latter is not configurable and is hardcoded to be configures the former. The latter is not configurable and is hardcoded to be
5 minutes. 5 minutes.
**Syntax**: command\_timeout _duration_ <br> ---
**Default**: 5m
### command_timeout _duration_
Default: `5m`
Timeout for any SMTP command (EHLO, MAIL, RCPT, DATA, etc). Timeout for any SMTP command (EHLO, MAIL, RCPT, DATA, etc).
@ -66,28 +76,36 @@ If STARTTLS is used this timeout also applies to TLS handshake.
RFC 5321 recommends 5 minutes for MAIL/RCPT and 3 minutes for RFC 5321 recommends 5 minutes for MAIL/RCPT and 3 minutes for
DATA. DATA.
**Syntax**: submission\_timeout _duration_ <br> ---
**Default**: 12m
### submission_timeout _duration_
Default: `12m`
Time to wait after the entire message is sent (after "final dot"). Time to wait after the entire message is sent (after "final dot").
RFC 5321 recommends 10 minutes. RFC 5321 recommends 10 minutes.
**Syntax**: debug _boolean_ <br> ---
**Default**: global directive value
### debug _boolean_
Default: global directive value
Enable verbose logging. Enable verbose logging.
**Syntax**: requiretls\_override _boolean_ <br> ---
**Default**: true
### requiretls_override _boolean_
Default: `true`
Allow local security policy to be disabled using 'TLS-Required' header field in Allow local security policy to be disabled using 'TLS-Required' header field in
sent messages. Note that the field has no effect if transparent forwarding is sent messages. Note that the field has no effect if transparent forwarding is
used, message body should be processed before outbound delivery starts for it used, message body should be processed before outbound delivery starts for it
to take effect (e.g. message should be queued using 'queue' module). to take effect (e.g. message should be queued using 'queue' module).
**Syntax**: relaxed\_requiretls _boolean_ <br> ---
**Default**: true
### relaxed_requiretls _boolean_
Default: `true`
This option disables strict conformance with REQUIRETLS specification and This option disables strict conformance with REQUIRETLS specification and
allows forwarding of messages 'tagged' with REQUIRETLS to MXes that are not allows forwarding of messages 'tagged' with REQUIRETLS to MXes that are not
@ -96,54 +114,66 @@ need to have support from all servers. It is based on the assumption that
server referenced by MX record is likely the final destination and therefore server referenced by MX record is likely the final destination and therefore
there is only need to secure communication towards it and not beyond. there is only need to secure communication towards it and not beyond.
**Syntax**: conn\_reuse\_limit _integer_ <br> ---
**Default**: 10
### conn_reuse_limit _integer_
Default: `10`
Amount of times the same SMTP connection can be used. Amount of times the same SMTP connection can be used.
Connections are never reused if the previous DATA command failed. Connections are never reused if the previous DATA command failed.
**Syntax**: conn\_max\_idle\_count _integer_ <br> ---
**Default**: 10
### conn_max_idle_count _integer_
Default: `10`
Max. amount of idle connections per recipient domains to keep in cache. Max. amount of idle connections per recipient domains to keep in cache.
**Syntax**: conn\_max\_idle\_time _integer_ <br> ---
**Default**: 150 (2.5 min)
### conn_max_idle_time _integer_
Default: `150` (2.5 min)
Amount of time the idle connection is still considered potentially usable. Amount of time the idle connection is still considered potentially usable.
---
## Security policies ## Security policies
**Syntax**: mx\_auth _config block_ <br> ### mx_auth { ... }
**Default**: no policies Default: no policies
'remote' module implements a number of of schemes and protocols necessary to 'remote' module implements a number of of schemes and protocols necessary to
ensure security of message delivery. Most of these schemes are concerned with ensure security of message delivery. Most of these schemes are concerned with
authentication of recipient server and TLS enforcement. authentication of recipient server and TLS enforcement.
To enable mechanism, specify its name in the mx\_auth directive block: To enable mechanism, specify its name in the `mx_auth` directive block:
``` ```
mx_auth { mx_auth {
dane dane
mtasts mtasts
} }
``` ```
Additional configuration is possible if supported by the mechanism by Additional configuration is possible if supported by the mechanism by
specifying additional options as a block for the corresponding mechanism. specifying additional options as a block for the corresponding mechanism.
E.g. E.g.
``` ```
mtasts { mtasts {
cache ram cache ram
} }
``` ```
If the mx\_auth directive is not specified, no mechanisms are enabled. Note If the `mx_auth` directive is not specified, no mechanisms are enabled. Note
that, however, this makes outbound SMTP vulnerable to a numerous downgrade that, however, this makes outbound SMTP vulnerable to a numerous downgrade
attacks and hence not recommended. attacks and hence not recommended.
It is possible to share the same set of policies for multiple 'remote' module It is possible to share the same set of policies for multiple 'remote' module
instances by defining it at the top-level using 'mx\_auth' module and then instances by defining it at the top-level using `mx_auth` module and then
referencing it using standard & syntax: referencing it using standard & syntax:
``` ```
mx_auth outbound_policy { mx_auth outbound_policy {
dane dane
@ -166,6 +196,8 @@ deliver_to remote {
} }
``` ```
---
### MTA-STS ### MTA-STS
Checks MTA-STS policy of the recipient domain. Provides proper authentication Checks MTA-STS policy of the recipient domain. Provides proper authentication
@ -182,8 +214,8 @@ mtasts {
} }
``` ```
**Syntax**: cache fs|ram <br> ### cache `fs` | `ram`
**Default**: fs Default: `fs`
Storage to use for MTA-STS cache. 'fs' is to use a filesystem directory, 'ram' Storage to use for MTA-STS cache. 'fs' is to use a filesystem directory, 'ram'
to store the cache in memory. to store the cache in memory.
@ -192,11 +224,13 @@ It is recommended to use 'fs' since that will not discard the cache (and thus
cause MTA-STS security to disappear) on server restart. However, using the RAM cause MTA-STS security to disappear) on server restart. However, using the RAM
cache can make sense for high-load configurations with good uptime. cache can make sense for high-load configurations with good uptime.
**Syntax**: fs\_dir _directory_ <br> ### fs_dir _directory_
**Default**: StateDirectory/mtasts\_cache Default: `StateDirectory/mtasts_cache`
Filesystem directory to use for policies caching if 'cache' is set to 'fs'. Filesystem directory to use for policies caching if 'cache' is set to 'fs'.
---
### DNSSEC ### DNSSEC
Checks whether MX records are signed. Sets MX level to "dnssec" is they are. Checks whether MX records are signed. Sets MX level to "dnssec" is they are.
@ -213,6 +247,8 @@ have the /etc/resolv.conf file in the standard format.
dnssec { } dnssec { }
``` ```
---
### DANE ### DANE
Checks TLSA records for the recipient MX. Provides downgrade-resistant TLS Checks TLSA records for the recipient MX. Provides downgrade-resistant TLS
@ -227,6 +263,8 @@ See above for notes on DNSSEC. DNSSEC support is required for DANE to work.
dane { } dane { }
``` ```
---
### Local policy ### Local policy
Checks effective TLS and MX levels (as set by other policies) against local Checks effective TLS and MX levels (as set by other policies) against local
@ -239,17 +277,17 @@ local_policy {
} }
``` ```
Using 'local\_policy off' is equivalent to setting both directives to 'none'. Using `local_policy off` is equivalent to setting both directives to `none`.
**Syntax**: min\_tls\_level none|encrypted|authenticated <br> ### min_tls_level `none` | `encrypted` | `authenticated`
**Default**: none Default: `none`
Set the minimal TLS security level required for all outbound messages. Set the minimal TLS security level required for all outbound messages.
See [Security levels](../../seclevels) page for details. See [Security levels](../../seclevels) page for details.
**Syntax**: min\_mx\_level: none|mtasts|dnssec <br> ### min_mx_level `none` | `mtasts` | `dnssec`
**Default**: none Default: `none`
Set the minimal MX security level required for all outbound messages. Set the minimal MX security level required for all outbound messages.

87
docs/reference/targets/smtp.md
View file

@ -3,6 +3,7 @@
Module that implements transparent forwarding of messages over SMTP. Module that implements transparent forwarding of messages over SMTP.
Use in pipeline configuration: Use in pipeline configuration:
``` ```
deliver_to smtp tcp://127.0.0.1:5353 deliver_to smtp tcp://127.0.0.1:5353
# or # or
@ -34,81 +35,81 @@ target.smtp {
} }
``` ```
**Syntax**: debug _boolean_ <br> ### debug _boolean_
**Default**: global directive value Default: global directive value
Enable verbose logging. Enable verbose logging.
**Syntax**: tls\_client { ... } <br> ---
**Default**: not specified
### tls_client { ... }
Default: not specified
Advanced TLS client configuration options. See [TLS configuration / Client](/reference/tls/#client) for details. Advanced TLS client configuration options. See [TLS configuration / Client](/reference/tls/#client) for details.
**Syntax**: attempt\_starttls _boolean_ <br> ---
**Default**: yes (no for target.lmtp)
### attempt_starttls _boolean_
Default: `yes` (`no` for `target.lmtp`)
Attempt to use STARTTLS if it is supported by the remote server. Attempt to use STARTTLS if it is supported by the remote server.
If TLS handshake fails, connection will be retried without STARTTLS If TLS handshake fails, connection will be retried without STARTTLS
unless 'require\_tls' is also specified. unless `require_tls` is also specified.
**Syntax**: require\_tls _boolean_ <br> ---
**Default**: no
### require_tls _boolean_
Default: `no`
Refuse to pass messages over plain-text connections. Refuse to pass messages over plain-text connections.
**Syntax**: <br> ---
auth off <br>
plain _username_ _password_ <br> ### auth `off` | `plain` _username_ _password_ | `forward` | `external`
forward <br> Default: `off`
external <br>
**Default**: off
Specify the way to authenticate to the remote server. Specify the way to authenticate to the remote server.
Valid values: Valid values:
- off - `off` – No authentication.
- `plain` – Authenticate using specified username-password pair.
No authentication. **Don't use** this without enforced TLS (`require_tls`).
- `forward` – Forward credentials specified by the client.
- plain **Don't use** this without enforced TLS (`require_tls`).
- `external` – Request "external" SASL authentication. This is usually used for
Authenticate using specified username-password pair.
**Don't use** this without enforced TLS ('require\_tls').
- forward
Forward credentials specified by the client.
**Don't use** this without enforced TLS ('require\_tls').
- external
Request "external" SASL authentication. This is usually used for
authentication using TLS client certificates. See [TLS configuration / Client](/reference/tls/#client) for details. authentication using TLS client certificates. See [TLS configuration / Client](/reference/tls/#client) for details.
**Syntax**: targets _endpoints..._ <br> ---
**Default:** not specified
REQUIRED. ### targets _endpoints..._
**Required.**<br>
Default: not specified
List of remote server addresses to use. See [Address definitions](/reference/config-syntax/#address-definitions) List of remote server addresses to use. See [Address definitions](/reference/config-syntax/#address-definitions)
for syntax to use. Basically, it is 'tcp://ADDRESS:PORT' for syntax to use. Basically, it is `tcp://ADDRESS:PORT`
for plain SMTP and 'tls://ADDRESS:PORT' for SMTPS (aka SMTP with Implicit for plain SMTP and `tls://ADDRESS:PORT` for SMTPS (aka SMTP with Implicit
TLS). TLS).
Multiple addresses can be specified, they will be tried in order until connection to Multiple addresses can be specified, they will be tried in order until connection to
one succeeds (including TLS handshake if TLS is required). one succeeds (including TLS handshake if TLS is required).
**Syntax**: connect\_timeout _duration_ <br> ---
**Default**: 5m
### connect_timeout _duration_
Default: `5m`
Same as for target.remote. Same as for target.remote.
**Syntax**: command\_timeout _duration_ <br> ---
**Default**: 5m
### command_timeout _duration_
Default: `5m`
Same as for target.remote. Same as for target.remote.
**Syntax**: submission\_timeout _duration_ <br> ---
**Default**: 12m
### submission_timeout _duration_
Default: `12m`
Same as for target.remote. Same as for target.remote.

68
docs/reference/tls-acme.md
View file

@ -2,9 +2,10 @@
Maddy supports obtaining certificates using ACME protocol. Maddy supports obtaining certificates using ACME protocol.
To use it, create a configuration name for tls.loader.acme To use it, create a configuration name for `tls.loader.acme`
and reference it from endpoints that should use automatically and reference it from endpoints that should use automatically
configured certificates: configured certificates:
``` ```
tls.loader.acme local_tls { tls.loader.acme local_tls {
email put-your-email-here@example.org email put-your-email-here@example.org
@ -17,8 +18,10 @@ smtp tcp://127.0.0.1:25 {
... ...
} }
``` ```
You can also use a global `tls` directive to use automatically You can also use a global `tls` directive to use automatically
obtained certificates for all endpoints: obtained certificates for all endpoints:
``` ```
tls { tls {
loader acme { loader acme {
@ -29,8 +32,9 @@ tls {
} }
``` ```
Currently the only supported challenge is dns-01 one therefore Currently the only supported challenge is `dns-01` one therefore
you also need to configure the DNS provider: you also need to configure the DNS provider:
``` ```
tls.loader.acme local_tls { tls.loader.acme local_tls {
email maddy-acme@example.org email maddy-acme@example.org
@ -41,6 +45,7 @@ tls.loader.acme local_tls {
} }
} }
``` ```
See below for supported providers and necessary configuration See below for supported providers and necessary configuration
for each. for each.
@ -60,41 +65,52 @@ tls.loader.acme {
} }
``` ```
**Syntax:** debug _boolean_ <br> ### debug _boolean_
**Default:** global directive value Default: global directive value
Enable debug logging. Enable debug logging.
**Syntax:** hostname _str_ <br> ---
**Default:** global directive value
Domain name to issue certificate for. Required. ### hostname _str_
**Required.**<br>
Default: global directive value
**Syntax:** store\_path _path_ <br> Domain name to issue certificate for.
**Default:** state\_dir/acme
---
### store_path _path_
Default: `state_dir/acme`
Where to store issued certificates and associated metadata. Where to store issued certificates and associated metadata.
Currently only filesystem-based store is supported. Currently only filesystem-based store is supported.
**Syntax:** ca _url_ <br> ---
**Default:** Let's Encrypt production CA
### ca _url_
Default: Let's Encrypt production CA
URL of ACME directory to use. URL of ACME directory to use.
**Syntax:** test\_ca _url_ <br> ---
**Default:** Let's Encrypt staging CA
### test_ca _url_
Default: Let's Encrypt staging CA
URL of ACME directory to use for retries should URL of ACME directory to use for retries should
primary CA fail. primary CA fail.
maddy will keep attempting to issues certificates maddy will keep attempting to issues certificates
using test\_ca until it succeeds then it will switch using `test_ca` until it succeeds then it will switch
back to the one configured via 'ca' option. back to the one configured via 'ca' option.
This avoids rate limit issues with production CA. This avoids rate limit issues with production CA.
**Syntax:** override\_domain _domain_ <br> ---
**Default:** not set
### override_domain _domain_
Default: not set
Override the domain to set the TXT record on for DNS-01 challenge. Override the domain to set the TXT record on for DNS-01 challenge.
This is to delegate the challenge to a different domain. This is to delegate the challenge to a different domain.
@ -102,18 +118,24 @@ This is to delegate the challenge to a different domain.
See https://www.eff.org/deeplinks/2018/02/technical-deep-dive-securing-automation-acme-dns-challenge-validation See https://www.eff.org/deeplinks/2018/02/technical-deep-dive-securing-automation-acme-dns-challenge-validation
for explanation why this might be useful. for explanation why this might be useful.
**Syntax:** email _str_ <br> ---
**Default:** not set
### email _str_
Default: not set
Email to pass while registering an ACME account. Email to pass while registering an ACME account.
**Syntax:** agreed _boolean_ <br> ---
**Default:** false
### agreed _boolean_
Default: false
Whether you agreed to ToS of the CA service you are using. Whether you agreed to ToS of the CA service you are using.
**Syntax:** challenge dns-01 <br> ---
**Default:** not set
### challenge `dns-01`
Default: not set
Challenge(s) to use while performing domain verification. Challenge(s) to use while performing domain verification.
@ -121,7 +143,7 @@ Challenge(s) to use while performing domain verification.
Support for some providers is not provided by standard builds. Support for some providers is not provided by standard builds.
To be able to use these, you need to compile maddy To be able to use these, you need to compile maddy
with "libdns\_PROVIDER" build tag. with "libdns_PROVIDER" build tag.
E.g. E.g.
``` ```
./build.sh -tags 'libdns_googleclouddns' ./build.sh -tags 'libdns_googleclouddns'

130
docs/reference/tls.md
View file

@ -26,79 +26,73 @@ tls {
### Available certificate loaders ### Available certificate loaders
- file - `file` – Accepts argument pairs specifying certificate and then key.
E.g. `tls file certA.pem keyA.pem certB.pem keyB.pem`.
Accepts argument pairs specifying certificate and then key.
E.g. 'tls file certA.pem keyA.pem certB.pem keyB.pem'
If multiple certificates are listed, SNI will be used. If multiple certificates are listed, SNI will be used.
- `acme` – Automatically obtains a certificate using ACME protocol (Let's Encrypt)
- acme - `off` – Not really a loader but a special value for tls directive,
explicitly disables TLS for endpoint(s).
Automatically obtains a certificate using ACME protocol (Let's Encrypt)
- off
Not really a loader but a special value for tls directive, explicitly disables TLS for
endpoint(s).
## Advanced TLS configuration ## Advanced TLS configuration
**Note: maddy uses secure defaults and TLS handshake is resistant to active downgrade attacks.** **Note: maddy uses secure defaults and TLS handshake is resistant to active downgrade attacks. There is no need to change anything in most cases.**
**There is no need to change anything in most cases.**
**Syntax**: <br> ---
protocols _min\_version_ _max\_version_ <br>
protocols _version_ <br> ### protocols _min-version_ _max-version_ | _version_
**Default**: tls1.0 tls1.3 Default: `tls1.0 tls1.3`
Minimum/maximum accepted TLS version. If only one value is specified, it will Minimum/maximum accepted TLS version. If only one value is specified, it will
be the only one usable version. be the only one usable version.
Valid values are: tls1.0, tls1.1, tls1.2, tls1.3 Valid values are: `tls1.0`, `tls1.1`, `tls1.2`, `tls1.3`
**Syntax**: ciphers _ciphers..._ <br> ---
**Default**: Go version-defined set of 'secure ciphers', ordered by hardware
### ciphers _ciphers..._
Default: Go version-defined set of 'secure ciphers', ordered by hardware
performance performance
List of supported cipher suites, in preference order. Not used with TLS 1.3. List of supported cipher suites, in preference order. Not used with TLS 1.3.
Valid values: Valid values:
- RSA-WITH-RC4128-SHA - `RSA-WITH-RC4128-SHA`
- RSA-WITH-3DES-EDE-CBC-SHA - `RSA-WITH-3DES-EDE-CBC-SHA`
- RSA-WITH-AES128-CBC-SHA - `RSA-WITH-AES128-CBC-SHA`
- RSA-WITH-AES256-CBC-SHA - `RSA-WITH-AES256-CBC-SHA`
- RSA-WITH-AES128-CBC-SHA256 - `RSA-WITH-AES128-CBC-SHA256`
- RSA-WITH-AES128-GCM-SHA256 - `RSA-WITH-AES128-GCM-SHA256`
- RSA-WITH-AES256-GCM-SHA384 - `RSA-WITH-AES256-GCM-SHA384`
- ECDHE-ECDSA-WITH-RC4128-SHA - `ECDHE-ECDSA-WITH-RC4128-SHA`
- ECDHE-ECDSA-WITH-AES128-CBC-SHA - `ECDHE-ECDSA-WITH-AES128-CBC-SHA`
- ECDHE-ECDSA-WITH-AES256-CBC-SHA - `ECDHE-ECDSA-WITH-AES256-CBC-SHA`
- ECDHE-RSA-WITH-RC4128-SHA - `ECDHE-RSA-WITH-RC4128-SHA`
- ECDHE-RSA-WITH-3DES-EDE-CBC-SHA - `ECDHE-RSA-WITH-3DES-EDE-CBC-SHA`
- ECDHE-RSA-WITH-AES128-CBC-SHA - `ECDHE-RSA-WITH-AES128-CBC-SHA`
- ECDHE-RSA-WITH-AES256-CBC-SHA - `ECDHE-RSA-WITH-AES256-CBC-SHA`
- ECDHE-ECDSA-WITH-AES128-CBC-SHA256 - `ECDHE-ECDSA-WITH-AES128-CBC-SHA256`
- ECDHE-RSA-WITH-AES128-CBC-SHA256 - `ECDHE-RSA-WITH-AES128-CBC-SHA256`
- ECDHE-RSA-WITH-AES128-GCM-SHA256 - `ECDHE-RSA-WITH-AES128-GCM-SHA256`
- ECDHE-ECDSA-WITH-AES128-GCM-SHA256 - `ECDHE-ECDSA-WITH-AES128-GCM-SHA256`
- ECDHE-RSA-WITH-AES256-GCM-SHA384 - `ECDHE-RSA-WITH-AES256-GCM-SHA384`
- ECDHE-ECDSA-WITH-AES256-GCM-SHA384 - `ECDHE-ECDSA-WITH-AES256-GCM-SHA384`
- ECDHE-RSA-WITH-CHACHA20-POLY1305 - `ECDHE-RSA-WITH-CHACHA20-POLY1305`
- ECDHE-ECDSA-WITH-CHACHA20-POLY1305 - `ECDHE-ECDSA-WITH-CHACHA20-POLY1305`
**Syntax**: curves _curves..._ <br> ---
**Default**: defined by Go version
### curves _curves..._
Default: defined by Go version
The elliptic curves that will be used in an ECDHE handshake, in preference The elliptic curves that will be used in an ECDHE handshake, in preference
order. order.
Valid values: p256, p384, p521, X25519. Valid values: `p256`, `p384`, `p521`, `X25519`.
## Client ## Client
tls\_client directive allows to customize behavior of TLS client implementation, `tls_client` directive allows to customize behavior of TLS client implementation,
notably adjusting minimal and maximal TLS versions and allowed cipher suites, notably adjusting minimal and maximal TLS versions and allowed cipher suites,
enabling TLS client authentication. enabling TLS client authentication.
@ -114,42 +108,48 @@ tls_client {
} }
``` ```
**Syntax**: <br> ---
protocols _min\_version_ _max\_version_ <br>
protocols _version_ <br> ### protocols _min-version_ _max-version_ | _version_
**Default**: tls1.0 tls1.3 Default: `tls1.0 tls1.3`
Minimum/maximum accepted TLS version. If only one value is specified, it will Minimum/maximum accepted TLS version. If only one value is specified, it will
be the only one usable version. be the only one usable version.
Valid values are: tls1.0, tls1.1, tls1.2, tls1.3 Valid values are: `tls1.0`, `tls1.1`, `tls1.2`, `tls1.3`
**Syntax**: ciphers _ciphers..._ <br> ---
**Default**: Go version-defined set of 'secure ciphers', ordered by hardware
### ciphers _ciphers..._
Default: Go version-defined set of 'secure ciphers', ordered by hardware
performance performance
List of supported cipher suites, in preference order. Not used with TLS 1.3. List of supported cipher suites, in preference order. Not used with TLS 1.3.
See TLS server configuration for list of supported values. See TLS server configuration for list of supported values.
**Syntax**: curves _curves..._ <br> ---
**Default**: defined by Go version
### curves _curves..._
Default: defined by Go version
The elliptic curves that will be used in an ECDHE handshake, in preference The elliptic curves that will be used in an ECDHE handshake, in preference
order. order.
Valid values: p256, p384, p521, X25519. Valid values: `p256`, `p384`, `p521`, `X25519`.
**Syntax**: root\_ca _paths..._ <br> ---
**Default**: system CA pool
### root_ca _paths..._
Default: system CA pool
List of files with PEM-encoded CA certificates to use when verifying List of files with PEM-encoded CA certificates to use when verifying
server certificates. server certificates.
**Syntax**: <br> ---
cert _cert\_path_ <br>
key _key\_path_ <br> ### cert _cert-path_ <br> key _key-path_
**Default**: not specified Default: not specified
Present the specified certificate when server requests a client certificate. Present the specified certificate when server requests a client certificate.
Files should use PEM format. Both directives should be specified. Files should use PEM format. Both directives should be specified.