Maddy

https://maddy.email
Admin
Maddy is a composable all-in-one mail server that handles sending, receiving, and storing emails via...
Tokens:37,228
Snippets:608
Trust Score:8.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Build and Install Maddy

Source: https://maddy.email/tutorials/building-from-source

Compiles the Maddy binary using the provided build script and then installs it to the system. The 'install' command typically requires root privileges.

```bash
./build.sh

```

```bash
sudo ./build.sh install

```

--------------------------------

### Start Maddy Server

Source: https://maddy.email/upgrading

After completing the migration and configuration updates, start the Maddy server using this command.

```bash
systemctl start maddy
```

--------------------------------

### Start Maddy Service

Source: https://maddy.email/tutorials/setting-up

Use this command to start the Maddy email server daemon.

```bash
systemctl start maddy

```

--------------------------------

### Complete Pipeline Configuration Example

Source: https://maddy.email/reference/smtp-pipeline

A comprehensive example demonstrating the use of check, source, destination, default_destination, and default_source blocks for routing and handling emails.

```maddy
check {
    # Run a check to make sure source SMTP server identification
    # is legit.
    spf
}

# Messages coming from senders at example.org will be handled in
# accordance with the following configuration block.
source example.org {
    # We are example.com, so deliver all messages with recipients
    # at example.com to our local mailboxes.
    destination example.com {
        deliver_to &local_mailboxes
    }

    # We don't do anything with recipients at different domains
    # because we are not an open relay, thus we reject them.
    default_destination {
        reject 521 5.0.0 "User not local"
    }
}

# We do our business only with example.org, so reject all
# other senders.
default_source {
    reject
}

```

--------------------------------

### Ubuntu PAM configuration example for maddy

Source: https://maddy.email/tutorials/pam

An example PAM configuration for maddy on Ubuntu that includes common authentication, account, and session management modules.

```pam
#%PAM-1.0

@include common-auth
@include common-account
@include common-session

```

--------------------------------

### SQLite3 Initialization Example

Source: https://maddy.email/reference/table/sql_query

Demonstrates how to configure SQLite3 for improved performance using PRAGMA statements during initialization.

```maddyconfig
table.sql_query {
    driver sqlite3
    dsn whatever.db
    init "PRAGMA journal_mode=WAL" \
        "PRAGMA synchronous=NORMAL"
    lookup "SELECT alias FROM aliases WHERE address = $1"
}

```

--------------------------------

### Alias Configuration Example

Source: https://maddy.email/tutorials/alias-to-remote

Example of an aliases file entry to forward messages from a local address to a remote address.

```maddy
foxcpp@example.org: foxcpp@example.com

```

--------------------------------

### Install System Dependencies (Debian-based)

Source: https://maddy.email/tutorials/building-from-source

Installs the required Go toolchain, C compiler, and Make utility on Debian-based systems. Ensure you have sufficient permissions to run apt-get.

```bash
apt-get install golang-1.23 gcc libc6-dev make

```

--------------------------------

### Storage Map Configuration Example

Source: https://maddy.email/reference/endpoints/imap

Demonstrates using `storage_map` to map SASL usernames to storage account names. This example uses the `email_localpart` function for mapping.

```maddy
storage_map email_localpart

```

--------------------------------

### SMTP Target Configuration Example

Source: https://maddy.email/reference/targets/smtp

Example of detailed configuration for an SMTP target, including debug, TLS client settings, STARTTLS, authentication, target endpoints, and timeouts.

```maddy
target.smtp {
    debug no
    tls_client {
        ...
    }
    attempt_starttls yes
    require_tls no
    auth off
    targets tcp://127.0.0.1:2525
    connect_timeout 5m
    command_timeout 5m
    submission_timeout 12m
}
```

--------------------------------

### Build maddy with libpam support

Source: https://maddy.email/tutorials/pam

Compile maddy from source with libpam support. Ensure you have the libpam development files installed.

```bash
./build.sh --tags 'libpam'

```

--------------------------------

### Delivery Map Configuration Example

Source: https://maddy.email/reference/endpoints/imap

Shows how to configure `delivery_map` within a storage module to map email addresses to storage accounts. This example delivers to a mailbox for the local part of the email address.

```maddy
storage.imapsql local_mailboxes {
    ...
    delivery_map email_localpart # deliver "user@*" to mailbox for "user"
}

```

--------------------------------

### Module Configuration Equivalence

Source: https://maddy.email/reference/modules

Provides an example showing that a module configuration can be specified directly or using a top-level configuration block, demonstrating their equivalence.

```maddy
storage.imapsql {
    driver sqlite3
    dsn all.db
}

```

--------------------------------

### Install ACME.sh Certificate for Maddy

Source: https://maddy.email/tutorials/setting-up

Use acme.sh to obtain and install TLS certificates, specifying the key and fullchain file paths for maddy.

```bash
mkdir -p /etc/maddy/certs/mx1.example.org
acme.sh --force --install-cert -d mx1.example.org \
  --key-file       /etc/maddy/certs/mx1.example.org/privkey.pem  \
  --fullchain-file /etc/maddy/certs/mx1.example.org/fullchain.pem
```

--------------------------------

### SQL Query Usage Example

Source: https://maddy.email/reference/table/sql_query

An example of using the sql_query table interface to resolve SMTP address aliases from a PostgreSQL database.

```maddyconfig
# Resolve SMTP address aliases using PostgreSQL DB.
modify {
    replace_rcpt sql_query {
        driver postgres
        dsn "dbname=maddy user=maddy"
        lookup "SELECT alias FROM aliases WHERE address = $1"
    }
}

```

--------------------------------

### Install and set permissions for maddy-pam-helper

Source: https://maddy.email/tutorials/pam

Copy the compiled helper executable to the appropriate directory and set its ownership and permissions. Making it setuid-root allows it to read sensitive files like /etc/shadow.

```bash
chown root:maddy /usr/lib/maddy/maddy-pam-helper
chmod u+xs,g+x,o-x /usr/lib/maddy/maddy-pam-helper

```

--------------------------------

### SPF Check Configuration Example

Source: https://maddy.email/reference/checks/spf

This snippet shows a typical configuration for the `check.spf` module, specifying actions for various SPF results and the `enforce_early` setting.

```maddy
check.spf {
    debug no
    enforce_early no
    fail_action quarantine
    softfail_action ignore
    permerr_action reject
    temperr_action reject
}

```

--------------------------------

### Minimal PAM configuration for maddy

Source: https://maddy.email/tutorials/pam

Create a PAM configuration file for maddy, typically located at /etc/pam.d/maddy. This example uses the `pam_unix.so` module for authentication and account management.

```pam
#%PAM-1.0
auth    required    pam_unix.so
account required    pam_unix.so

```

--------------------------------

### Quick Maddy Docker Setup

Source: https://maddy.email/docker

This TL;DR provides a quick way to set up Maddy using Docker. It creates a named volume for persistent data, runs the Maddy container with specified environment variables and port mappings, and outlines the next steps for TLS certificate configuration.

```bash
docker volume create maddydata
docker run \
  --name maddy \
  -e MADDY_HOSTNAME=mx.maddy.test \
  -e MADDY_DOMAIN=maddy.test \
  -v maddydata:/data \
  -p 25:25 \
  -p 143:143 \
  -p 465:465 \
  -p 587:587 \
  -p 993:993 \
  foxcpp/maddy:0.7
```

--------------------------------

### File Syntax: Basic Key-Value Pair

Source: https://maddy.email/reference/table/file

Demonstrates a simple key-value pair in the mapping file. Lines starting with '#' are ignored.

```maddy
# Lines starting with # are ignored.

# And so are lines only with whitespace.

# Whenever 'aaa' is looked up, return 'bbb'
aaa: bbb

    # Trailing and leading whitespace is ignored.
    ccc: ddd

# If there is no colon, the string is translated into ""
# That is, the following line is equivalent to
#   aaa:
aaa
```

--------------------------------

### Example: SMTP auth with pass_table from file

Source: https://maddy.email/reference/auth/pass_table

Configure SMTP server to use username:password authentication by reading credentials from a specified text file.

```maddy
smtp tcp://0.0.0.0:587 {
    auth pass_table file /etc/maddy/smtp_passwd
    ...
}
```

--------------------------------

### Basic DKIM Configuration

Source: https://maddy.email/reference/modifiers/dkim

Example of basic DKIM configuration using arguments for domain and selector.

```maddy
modify {
    dkim example.org selector
}
```

--------------------------------

### Chain Tables with Regexp and File Lookup

Source: https://maddy.email/reference/table/chain

This example strips a +prefix from an email address before looking it up in a file. It uses `step` to ensure both operations are successful.

```maddy
table.chain {
    step regexp "(.+)(\\+[^+\"@]+)?@example.org" "$1@example.org"
    step file /etc/maddy/emails
}

```

--------------------------------

### Configure External Authentication Helper

Source: https://maddy.email/reference/auth/external

Example configuration for the auth.external module, specifying the helper binary path, per-domain setting, and allowed domains.

```toml
auth.external {
    helper /usr/bin/ldap-helper
    perdomain no
    domains example.org
}

```

--------------------------------

### Configure Name.com DNS provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the Name.com DNS provider. Requires user credentials and an API token.

```maddy
dns namedotcom {
    user "..."
    token "..."
}

```

--------------------------------

### Configure external table reference

Source: https://maddy.email/reference/smtp-pipeline

When extended configuration is needed for table modules, define it separately and reference it using '&'. This example shows configuring a 'sql_table'.

```maddy
table.sql_table remote_addrs {
    dsn ...
    driver ...
}

whatever {
    destination_in &remote_addrs {
        deliver_to whatever
    }
}
```

--------------------------------

### Configure Leaseweb DNS provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the Leaseweb DNS provider. Requires an API key.

```maddy
dns leaseweb {
    api_key "key"
}

```

--------------------------------

### Compile Maddy with specific libdns provider

Source: https://maddy.email/reference/tls-acme

Example command to compile Maddy with support for a specific libdns provider, such as Google Cloud DNS. This is necessary for using certain DNS providers.

```bash
./build.sh --tags 'libdns_googleclouddns'

```

--------------------------------

### Handle recipients by domain

Source: https://maddy.email/reference/smtp-pipeline

Use 'destination' with a domain name to route messages. This example routes messages for 'example.com' to local mailboxes and rejects others using 'default_destination'.

```maddy
# Messages with recipients at example.com domain will be
# delivered to local_mailboxes target.
destination example.com {
    deliver_to &local_mailboxes
}

# Messages with other recipients will be rejected.
default_destination {
    rejected 541 5.0.0 "User not local"
}
```

--------------------------------

### Configure Metaname DNS provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the Metaname DNS provider. Requires an API key and account reference.

```maddy
dns metaname {
    api_key "key"
    account_ref "reference"
}

```

--------------------------------

### Configure Hetzner DNS provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the Hetzner DNS provider. Requires an API token for authentication.

```maddy
dns hetzner {
    api_token "..."
}

```

--------------------------------

### Configure Gandi DNS provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the Gandi DNS provider. Requires an API token for authentication.

```maddy
dns gandi {
    api_token "token"
}

```

--------------------------------

### Use imapsql as a lookup table for catch-all addresses

Source: https://maddy.email/reference/storage/imapsql

Demonstrates using the imapsql module as a lookup table with the `destination_in` directive to implement catch-all addresses. This is an example and not recommended for production.

```maddy
destination_in &local_mailboxes {
    deliver_to &local_mailboxes
}
destination example.org {
    modify {
        replace_rcpt regexp ".*" "catchall@example.org"
    }
    deliver_to &local_mailboxes
}

```

--------------------------------

### User Table Configuration

Source: https://maddy.email/reference/auth/plain_separate

Example of configuring a 'user' directive to specify a file-based table for allowed users. Ensure the specified file exists and is accessible.

```maddy
user file /etc/maddy/allowed_users
```

--------------------------------

### Configure Alibaba Cloud DNS (alidns) provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the Alibaba Cloud DNS provider. Requires Key ID and Key Secret.

```maddy
dns alidns {
    key_id "..."
    key_secret "..."
}

```

--------------------------------

### Chain Tables with Optional File Lookup and Regexp

Source: https://maddy.email/reference/table/chain

This example demonstrates using `optional_step` to map emails to usernames after translating them via an aliases map. If the alias is not found, the regexp step is still attempted.

```maddy
table.chain {
    optional_step file /etc/maddy/aliases
    step regexp "(.+)@(.+)" "$1"
}

```

--------------------------------

### Configure ACME DNS provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the ACME DNS provider. Requires username, password, subdomain, and server URL.

```maddy
dns acmedns {
    username "..."
    password "..."
    subdomain "..."
    server_url "..."
}

```

--------------------------------

### Configure imapsql storage

Source: https://maddy.email/reference/storage/imapsql

Configure the imapsql module with a driver, data source name, and message store location. This example uses SQLite.

```maddy
storage.imapsql {
    driver sqlite3
    dsn imapsql.db
    msg_store fs messages/
}

```

--------------------------------

### Queue Target Configuration Example

Source: https://maddy.email/reference/targets/queue

This configuration sets up a queue target that forwards messages to a remote target. It specifies retry parameters, bounce settings for DSNs, and the domain for autogenerated DSN messages.

```hcl
target.queue {
    target remote
    location ...
    max_parallelism 16
    max_tries 4
    bounce {
        destination example.org {
            deliver_to &local_mailboxes
        }
        default_destination {
            reject
        }
    }

    autogenerated_msg_domain example.org
    debug no
}


```

--------------------------------

### Domain Expansion for Aliases

Source: https://maddy.email/reference/table/email_with_domain

Use table.email_with_domain with table.chain to implement domain-level expansion for email aliases. This example aliases any recipient to example.org and example.com.

```plaintext
modify {
    replace_rcpt chain {
        step email_local_part
        step email_with_domain example.org example.com
    }
}
```

--------------------------------

### Define Primary and Local Domains

Source: https://maddy.email/multiple-domains

Set the primary domain and list all domains Maddy should manage. This is the basic setup for handling multiple domains independently.

```maddy
$(primary_domain) = example.org
$(local_domains) = $(primary_domain) example.com

```

--------------------------------

### Configure Google Cloud DNS provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the Google Cloud DNS provider. Requires project ID and path to the service account JSON file.

```maddy
dns googleclouddns {
    project "project_id"
    service_account_json "path"
}

```

--------------------------------

### LDAP DN Lookup Filter Example

Source: https://maddy.email/reference/auth/ldap

Example of a DN lookup filter for posixAccount.

```maddy
filter "(&(objectClass=posixAccount)(uid={username}))"

```

--------------------------------

### Configure Namecheap DNS provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the Namecheap DNS provider. Requires API key and username. Optionally, an endpoint and client IP can be specified.

```maddy
dns namecheap {
    api_key "..."
    api_username "..."

    # optional: API endpoint, production one is used if not set.
    endpoint "https://api.namecheap.com/xml.response"

    # optional: your public IP, discovered using icanhazip.com if not set
    client_ip 1.2.3.4
}

```

--------------------------------

### Active Directory DN Lookup Filter Example

Source: https://maddy.email/reference/auth/ldap

Example DN lookup filter for Active Directory.

```maddy
filter "(&(objectCategory=Person)(memberOf=CN=user-group,OU=example,DC=example,DC=org)(sAMAccountName={username})(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))"

```

--------------------------------

### Configure RFC2136 DNS provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the RFC2136 DNS provider (dynamic DNS updates). Requires key name, secret key, algorithm, and server address.

```maddy
dns rfc2136 {
    key_name "..."
    # Secret
    key "..."
    # HMAC algorithm used to generate the key, lowercase, e.g. hmac-sha512
    key_alg "..."
    # server to which the dynamic update will be sent, e.g. 127.0.0.1
    # you can also specify the port: 127.0.0.1:53
    server "..."
}

```

--------------------------------

### Maddy Aliases File Format

Source: https://maddy.email/reference/modifiers/envelope

Examples of entries in an Maddy aliases file, showing simple replacements, domain-specific replacements, and handling of multiple aliases per entry. Supports comma-separated lists for multiple aliases.

```maddy
# Replace 'cat' with any domain to 'dog'.
# E.g. cat@example.net -> dog@example.net
cat: dog

# Replace cat@example.org with cat@example.com.
# Takes priority over the previous line.
cat@example.org: cat@example.com

# Using aliases in multiple lines
cat2: dog
cat2: mouse
cat2@example.org: cat@example.com
cat2@example.org: cat@example.net
# Comma-separated aliases in multiple lines
cat3: dog , mouse
cat3@example.org: cat@example.com , cat@example.net
```

--------------------------------

### LDAP Person Object DN Lookup Filter Example

Source: https://maddy.email/reference/auth/ldap

Example DN lookup filter for Person objects.

```maddy
filter "(&(objectClass=Person)(mail={username}))"

```

--------------------------------

### Set Up Recent Go Toolchain

Source: https://maddy.email/tutorials/building-from-source

Downloads and configures a recent Go toolchain (version 1.21 or newer) if your system's default Go version is older. This ensures compatibility for building Maddy. It sets the GOROOT and PATH environment variables.

```bash
wget "https://go.dev/dl/go1.23.5.linux-amd64.tar.gz"
tar xf "go1.23.5.linux-amd64.tar.gz"
export GOROOT="$PWD/go"
export PATH="$PWD/go/bin:$PATH"

```

--------------------------------

### Build maddy-pam-helper executable

Source: https://maddy.email/tutorials/pam

Clone the maddy repository and compile the `maddy-pam-helper` executable using gcc. This is necessary if maddy requires privileged access for PAM authentication.

```bash
git clone https://github.com/foxcpp/maddy
cd maddy/cmd/maddy-pam-helper
gcc pam.c main.c -lpam -o maddy-pam-helper

```

--------------------------------

### Dovecot SASL Endpoint Configuration Example

Source: https://maddy.email/reference/auth/dovecot_sasl

Set the address to contact the Dovecot SASL server. Examples include TCP/IP addresses and ports, or Unix domain socket paths.

```maddy
tcp://10.0.0.1:2222
```

```maddy
unix:///var/lib/dovecot/auth.sock
```

--------------------------------

### Configure maddy for helper executable PAM support

Source: https://maddy.email/tutorials/pam

Replace the default `local_authdb` implementation with `auth.pam` and set `use_helper` to `yes` when using the helper executable.

```maddy
auth.pam local_authdb {
    use_helper yes
}

```

--------------------------------

### Referencing Modules with Named Configuration Blocks

Source: https://maddy.email/reference/modules

Shows how to define a module configuration in a separate named block and reference it using '&'. This is recommended for expensive-to-initialize modules like storage backends.

```maddy
storage.imapsql local_mailboxes {
    driver sqlite3
    dsn all.db
}

smtp ... {
    deliver_to &local_mailboxes
}

```

--------------------------------

### Reload systemd Daemon

Source: https://maddy.email/tutorials/setting-up

Reload the systemd service manager configuration after installing or modifying service unit files.

```bash
systemctl daemon-reload
```

--------------------------------

### Run Database Migration Utility

Source: https://maddy.email/upgrading

Execute the compiled migration utility, providing the path to the `imapsql.db` file. This converts the 0.2 database to a format compatible with 0.3.

```bash
./migrate-db-0.2 /var/lib/maddy/imapsql.db
```

--------------------------------

### Configure Vultr DNS provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the Vultr DNS provider. Requires an API token for authentication.

```maddy
dns vultr {
    api_token "..."
}

```

--------------------------------

### Configure DigitalOcean DNS provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the DigitalOcean DNS provider. Requires an API token for authentication.

```maddy
dns digitalocean {
    api_token "..."
}

```

--------------------------------

### Compile Database Migration Utility

Source: https://maddy.email/upgrading

Clone the Maddy repository, checkout the target version (v0.3.0), navigate to the migration utility directory, and build the binary. This utility is specific to SQLite databases.

```bash
git clone https://github.com/foxcpp/maddy.git
cd maddy/
git checkout v0.3.0
cd cmd/migrate-db-0.2
go build
```

--------------------------------

### File Syntax: Multiple Values for Same Key

Source: https://maddy.email/reference/table/file

Shows how to define multiple values for a single key. The module will return all values when queried.

```maddy
# If the same key is used multiple times - table.file will return
# multiple values when queries.
ddd: firstvalue
ddd: secondvalue
```

--------------------------------

### Configure Cloudflare DNS provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the Cloudflare DNS provider. Refer to the libdns/cloudflare documentation for authentication details.

```maddy
dns cloudflare {
    api_token "..."
}

```

--------------------------------

### Create Accounts with Shared Credentials and Mailboxes

Source: https://maddy.email/multiple-domains

When using `email_localpart_optional` for both authentication and storage, create a single credential and a single IMAP account for the local part.

```bash
maddy creds create user
maddy imap-acct create user

```

--------------------------------

### Replace Recipient using File Mapping

Source: https://maddy.email/reference/table/file

Example of using the file module to replace recipient addresses based on a mapping file.

```maddy
# Resolve SMTP address aliases using text file mapping.
modify {
    replace_rcpt file /etc/maddy/aliases
}
```

--------------------------------

### Define destination for a domain

Source: https://maddy.email/reference/smtp-pipeline

Use 'destination' to specify delivery targets for a given domain. This example shows delivery to local mailboxes for 'example.com'.

```maddy
destination example.com {
    deliver_to &local_mailboxes
}
```

--------------------------------

### Configure Maddy Hostname and Primary Domain

Source: https://maddy.email/tutorials/setting-up

Set the server's hostname and primary domain in the maddy configuration file. Replace placeholders with your actual values.

```maddy
$(hostname) = mx1.example.org
$(primary_domain) = example.org
```

--------------------------------

### Set File Permissions for Let's Encrypt Certificates

Source: https://maddy.email/tutorials/setting-up

Ensure the 'maddy' user can read Let's Encrypt certificate and key directories. This is necessary for maddy to access them.

```bash
$ sudo setfacl -R -m u:maddy:rX /etc/letsencrypt/{live,archive}
```

--------------------------------

### IMAP Filter Command Output: Change Folder

Source: https://maddy.email/reference/storage/imap-filters

Example of system command output where the first line specifies the destination folder for the message.

```text
Junk
```

--------------------------------

### Backup Database Files

Source: https://maddy.email/upgrading

Create a backup of the `imapsql.db*` files located in the Maddy state directory. This is a crucial step before migrating to a new version that may alter database structures.

```bash
mkdir backup
cp /var/lib/maddy/imapsql.db* backup/
```

--------------------------------

### Set permissions for maddy-pam-helper

Source: https://maddy.email/reference/auth/pam

Configure the 'maddy-pam-helper' binary for setuid execution. This is necessary when Maddy runs as an unprivileged user and PAM requires elevated privileges, such as accessing system accounts.

```bash
chown root:maddy /usr/lib/maddy/maddy-pam-helper
chmod u+xs,g+x,o-x /usr/lib/maddy/maddy-pam-helper
```

--------------------------------

### Build Maddy with libpam support

Source: https://maddy.email/reference/auth/pam

Build Maddy with the 'libpam' tag to enable direct libpam integration. This is required to use the auth.pam module without the 'use_helper' directive.

```bash
go get -tags 'libpam' ...
```

--------------------------------

### Configure Auth Map with Optional Localpart

Source: https://maddy.email/reference/global-config

Use `email_localpart_optional` to allow authentication using both full email addresses and just the local part of the email address.

```maddy
auth_map email_localpart_optional
```

--------------------------------

### Maddy Configuration: Using replace_rcpt with different sources

Source: https://maddy.email/reference/modifiers/envelope

Demonstrates how to use the `replace_rcpt` module with various mapping sources: a file, static entries, and regular expressions. Multiple `replace_rcpt` directives can be chained.

```maddy
modify {
    replace_rcpt file /etc/maddy/aliases
    replace_rcpt static {
        entry a@example.org b@example.org
        entry c@example.org c1@example.org c2@example.org
    }
    replace_rcpt regexp "(.+)@example.net" "$1@example.org"
    replace_rcpt regexp "(.+)@example.net" "$1@example.org" "$1@example.com"
}
```

--------------------------------

### Create Maddy User and Group

Source: https://maddy.email/tutorials/setting-up

Create a dedicated 'maddy' user and group for running the mail server. This user should not have root privileges.

```bash
useradd -mrU -s /sbin/nologin -d /var/lib/maddy -c "maddy mail server" maddy
```

--------------------------------

### Invalid Data Size Value Example

Source: https://maddy.email/reference/config-syntax

Unlike duration values, data size values do not allow direct concatenation of multiple values with different units.

```maddyconfig
32M5K
```

--------------------------------

### Top-Level Configuration Block Definition

Source: https://maddy.email/reference/modules

Illustrates the syntax for defining a top-level configuration block for a module, which can then be referenced by name.

```maddy
namespace.module_name config_block_name... {
    module_configuration
}

```

--------------------------------

### Configure maddy for built-in PAM support

Source: https://maddy.email/tutorials/pam

Replace the default `local_authdb` implementation with `auth.pam` when using maddy's built-in libpam support.

```maddy
auth.pam local_authdb {
    use_helper no
}

```

--------------------------------

### Basic Directive Structure

Source: https://maddy.email/reference/config-syntax

Configuration consists of newline-delimited directives, each potentially having zero or more arguments.

```maddyconfig
directive0
directive1 arg0 arg1
```

--------------------------------

### Configure DNSBL List with Responses

Source: https://maddy.email/reference/checks/dnsbl

Example of configuring a DNSBL list, specifying allowed response IPs and a flat score. This configuration is used when per-response-code scoring is not defined.

```maddy
dnsbl.example.org dnsbl.example.com {
    client_ipv4 yes
    client_ipv6 no
    ehlo no
    mailfrom no
    responses 127.0.0.1/24
    score 1
}

```

--------------------------------

### Configure Storage Map for Shared Mailboxes

Source: https://maddy.email/reference/global-config

Use `email_localpart` with `storage_map` to ensure that users authenticating with `user@example.org` and `user@example.com` access the same mailbox. This requires creating storage accounts without the domain part.

```maddy
storage_map email_localpart
```

--------------------------------

### Configure MTA-STS Cache

Source: https://maddy.email/reference/targets/remote

Configures the filesystem cache for MTA-STS policies. Use 'fs' for persistent caching across restarts, recommended for most setups. 'ram' is an alternative for high-load scenarios.

```maddy
mtasts {
    cache fs
    fs_dir StateDirectory/mtasts_cache
}

```

--------------------------------

### Auth Shadow Module Configuration

Source: https://maddy.email/reference/auth/shadow

Basic configuration for the auth.shadow module, disabling debug logging and helper binary usage.

```maddy
auth.shadow {
    debug no
    use_helper no
}

```

--------------------------------

### TLSA (DANE) Record Example

Source: https://maddy.email/tutorials/setting-up

Set a TLSA record for DANE validation. Use a tool like https://www.huque.com/bin/gen_tlsa to generate it, specifying port 25 and transport protocol 'tcp'.

```dns
_25._tcp.mx1.example.org. TLSA 3 1 1 7f59d873a70e224b184c95a4eb54caa9621e47d48b4a25d312d83d96e3498238

```

--------------------------------

### Configure ACME with DNS-01 challenge and provider

Source: https://maddy.email/reference/tls-acme

Specify the `dns-01` challenge for ACME and configure a DNS provider for challenge validation. Replace 'PROVIDER_NAME' with the actual provider and configure its specific parameters.

```maddy
tls.loader.acme local_tls {
    email maddy-acme@example.org
    agreed
    challenge dns-01
    dns PROVIDER_NAME {
        ...
    }
}

```

--------------------------------

### Run Maddy Management Utility Container

Source: https://maddy.email/docker

Use this command to run temporary containers for Maddy management tasks like creating credentials or mail accounts. Ensure the container uses the same image version as your running Maddy server.

```bash
docker run --rm -it -v maddydata:/data foxcpp/maddy:0.7 creds create foxcpp@maddy.test
```

```bash
docker run --rm -it -v maddydata:/data foxcpp/maddy:0.7 imap-acct create foxcpp@maddy.test
```

--------------------------------

### Configure Route53 DNS provider for ACME

Source: https://maddy.email/reference/tls-acme

Example configuration for the AWS Route53 DNS provider. Requires access key ID and secret access key, or can use environment variables.

```maddy
dns route53 {
    secret_access_key "..."
    access_key_id "..."
    # or use environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
}

```

--------------------------------

### Create Maddy Credentials

Source: https://maddy.email/tutorials/setting-up

Register user credentials for email accounts using the 'maddy creds create' command. The username must be a full email address.

```bash
$ maddy creds create postmaster@example.org

```

--------------------------------

### Select Maddy Version

Source: https://maddy.email/tutorials/building-from-source

Checks out a specific version of the Maddy repository. Choose a specific release tag for stability, 'master' for the latest bugfixes, or 'dev' for the latest features.

```bash
git checkout v0.8.0      # a specific release

```

```bash
git checkout master      # next bugfix release

```

```bash
git checkout dev         # next feature release

```

--------------------------------

### Configure Dovecot SASL Authentication

Source: https://maddy.email/reference/auth/dovecot_sasl

Configure maddy to use Dovecot SASL for authentication by specifying the endpoint for the Dovecot authentication server. This example shows a Unix domain socket configuration.

```maddy
auth.dovecot_sasl {
    endpoint unix://socket_path
}

dovecot_sasl unix://socket_path

```

--------------------------------

### Define File Mapping with Path

Source: https://maddy.email/reference/table/file

Use this syntax to specify the path to the text file for mapping.

```maddy
file <file path>
```

--------------------------------

### Configure S3 Message Store in imapsql

Source: https://maddy.email/reference/blob/s3

This example shows how to integrate S3 as a message store within the storage.imapsql configuration. It specifies the S3 endpoint, credentials, bucket, and region for storing messages.

```toml
storage.imapsql local_mailboxes {
    ...
    msg_store s3 {
        endpoint s3.amazonaws.com
        access_key "..."
        secret_key "..."
        bucket maddy-messages
        region us-west-2
        creds access_key
    }
}
```

--------------------------------

### LDAP Authentication with URL

Source: https://maddy.email/reference/auth/ldap

Basic LDAP authentication configuration using a direct URL.

```maddy
auth.ldap ldap://maddy.test.389 {
    ...
}

```
Tokens:
Raw