// Import the plugin stored in the `plugins` directory.
import "plugins/libvsmtp_plugin_ldap" as ldap;

export const directory = ldap::connect(#{
    url: "ldap://ds.example.com:389 ",
    timeout: "1m",
    connections: 10,
});

import "services/ds" as srv;

#{
    rcpt: [
        rule "check recipient in DS" || {
            let address = rcpt();
            let user = recipient.local_part();

            const results = srv::directory.search(
                "ou=People,dc=example,dc=com",

                // Search the whole tree.
                "sub",

                // Match on the user id and address.
                `(|(uid=${user})(mail=${address}))`

                // Get all attributes from the entries.
                ["*"]
            );

            // ...
        }
    ],
}
</div>

</div>
</br>

<div markdown="span" style='box-shadow: 0 4px 8px 0 rgba(0,0,0,0.2); padding: 15px; border-radius: 5px;'>

<h2 class="func-name"> <code>fn</code> compare </h2>

```rust,ignore
fn compare(database: Ldap, dn: String, attr: String, val: String) -> bool

Compare the value(s) of the attribute attr within an entry named by dn with the value val.

• dn - name of the entry.
• attr - The attribute use to compare the value.
• val - expected value of the attribute.

True, if the attribute matches, false otherwise.

Build a service in services/ds.vsl;

// Import the plugin stored in the `plugins` directory.
import "plugins/libvsmtp_plugin_ldap" as ldap;

export const directory = ldap::connect(#{
    url: "ldap://ds.example.com:389 ",
    timeout: "1m",
    connections: 10,
});

Compare an entry attribute during filtering.

import "services/ds" as srv;

#{
    rcpt: [
        rule "check recipient in DS" || {
            let address = rcpt();
            let user = recipient.local_part();

            if srv::directory.compare(
                // Find the user in our directory.
                `uid=${user},ou=People,dc=example,dc=org`,
                // Compare the "address" attribute.
                "address",
                // Check if the given recipient address is the same as
                // the one registered in the directory.
                address.to_string(),
            ) {
                log("info", `${user} email address is registered in the directory.`);
            } else {
                log("warn", `${user}'s email address does not match the one registered in the directory.`);
            }
        }
    ],
}
</div>

</div>
</br>

vsmtp

vsmtp is the binary executed by the vsmtp.service daemon. It is usually run as a daemon but it can be used with commands to manage the configuration.

$ vsmtp --help
vsmtp 1.0.0
Team viridIT <https://viridit.com/>
Next-gen MTA. Secured, Faster and Greener

USAGE:
    vsmtp [OPTIONS] [SUBCOMMAND]

OPTIONS:
    -c, --config <CONFIG>      Path of the vSMTP configuration file ("vsl" format)
    -h, --help                 Print help information
    -n, --no-daemon            Do not run the program as a daemon
    -t, --timeout <TIMEOUT>    Make the server stop after a delay (human readable format)
    -V, --version              Print version information

SUBCOMMANDS:
    config-diff    Show the difference between the loaded config and the default one
    config-show    Show the loaded config (as serialized json format)
    help           Print this message or the help of the given subcommand(s)

Managing configuration

Loaded configurations can be checked using the config-diff and config-show commands.

$ sudo vsmtp -c /etc/vsmtp/vsmtp.vsl config-show
Loading configuration at path='/etc/vsmtp/vsmtp.vsl'
Loaded configuration: {
  "server": {
    "domain": "testserver.com",
    "addr": "0.0.0.0:25",
    "addr_submission": "0.0.0.0:587",
    "addr_submissions": "0.0.0.0:465",
    "thread_count": 10
  },
  "log": {
    "file": "/var/log/vsmtp/vsmtp.log",
    "level": {
      "receiver": "INFO",
      "rules": "WARN",
      "default": "WARN",
      "resolver": "WARN"
    }
  },
 
  "reply_codes": {
    "Code214": "214 my custom help message\r\n",
    "Code220": "220 testserver.com ESMTP Service ready\r\n",
   
    ... // etc.
  }
}

$ sudo vsmtp -c /etc/vsmtp/vsmtp.vsl config-diff
Loading configuration at path='/etc/vsmtp/vsmtp.vsl'
 {
   "server": {
     "domain": "testserver.com",
     "addr": "0.0.0.0:25",
     "addr_submission": "0.0.0.0:587",
     "addr_submissions": "0.0.0.0:465",
-    "thread_count": 2                      // DEFAULT configuration
+    "thread_count": 10                     // CURRENT configuration
   },
   "log": {
-    "file": "./trash/log.log",             // DEFAULT configuration            
+    "file": "/var/log/vsmtp/vsmtp.log",    // CURRENT configuration
     "level": {
-      "default": "OFF"                     
+      "resolver": "WARN",                  
+      "default": "WARN",                   // etc.
+      "rules": "WARN",
+      "receiver": "INFO"
     }
   },

   "reply_codes": {
-    "Code214": "214 joining us https://viridit.com/support\r\n",
-    "Code220": "220 testserver.com Service ready\r\n",
+    "Code214": "214 my custom help message\r\n",
+    "Code220": "220 testserver.com ESMTP Service ready\r\n",

        ... // etc.
    }
 }

vqueue

vqueue is a cli utility that is used to inspect and manage vSMTP’s queues.

Managing queues

Internal and user defined queues can be managed using the vqueue command with root privileges.

The vqueue show subcommand displays a summary of vSMTP queues in a Postfix qshape way. The -c option allows vqueue to parse queues and quarantines defined in the configuration.

WORKING    is at '/var/spool/vsmtp/working' : <EMPTY>

DELIVER    is at '/var/spool/vsmtp/deliver' :
                T    5   10   20   40   80  160  320  640 1280 1280+
       TOTAL    4    0    0    0    0    0    0    0    0    4    0
example1.com    1    0    0    0    0    0    0    0    0    1    0
example2.com    1    0    0    0    0    0    0    0    0    1    0
example3.com    1    0    0    0    0    0    0    0    0    1    0
example4.com    1    0    0    0    0    0    0    0    0    1    0

DEFERRED   is at '/var/spool/vsmtp/deferred' : <EMPTY>

DEAD       is at '/var/spool/vsmtp/dead' : <EMPTY>

Managing messages

Like queues, messages are also managed using the vqueue command.

• vqueue msg <msg-id> show [json | eml] : Print the content of a message.
• vqueue msg <msg-id> move <queue> : Move a message to a queue.
• vqueue msg <msg-id> remove : Remove a message from disk.

Doe’s family: Step-by-step tutorial

In this tutorial we suppose that Doe’s family (John, Jane and their children Jimmy and Jenny) wants to self-host their mailboxes.

Context

They use a router/firewall to route and secure their home network. They also setup a small server in the DMZ to manage the family website, emails, etc.

{ Internet ISP } --- Firewall --- { DMZ }
                        |
              { Internal Network }

Does family network setup

They also rented a domain name doe-family.com. They decided to prefix their mailboxes with the common standard “first_name.last_name” like jenny.doe@doe-family.com

Network configuration

vSMTP is installed on an Ubuntu server 20.04 virtual instance hosted by the DMZ server.

{ Internet ISP } --- Firewall --- { DMZ : MTA }
                        |
              { Internal Network }


- Public IP : 80.80.80.80
- MTA IP : 192.168.1.254/32 - fqdn : mta.doe-family.com
- Internal Network : 192.168.0.0/24

Network setup

# Pseudo code - depends on your FW
#
# Allow SMTP and IMAP from Internet to MTA
Public IP > MTA : TCP/SMTP 25, TCP/SMTP 465, TCP/SMTP 587
# Allow viewing family emails using IMAP/ssl from the Internet
Public IP > MTA : IMAP/ssl 993
# Outgoing SMTP traffic
Internal NET > MTA : TCP/SMTP 25, TCP/SMTP 465, TCP/SMTP 587
MTA > {Internet} : TCP/SMTP 25, TCP/SMTP 465
# DNS traffic from MTA
MTA > {Internet} : UDP/DNS 53, TCP/DNS 53

Firewall rules

MX preference = 1, mail exchanger = vsmtp.doe-family.com

DNS setup

John generated a certificate through the Let’s Encrypt Certificate Authority for vSMTP server.

sudo certbot certonly --manual --preferred-challenges=dns \
    --agree-tos -d mta.doe-family.com

Creating the certificate

Basic configuration

vSMTP Configuration

Let’s build a vSMTP configuration step by step.

When installing vSMTP, the package manager creates the following basic configuration.

/etc/vsmtp
+┣ vsmtp.vsl
+┗ conf.d/
+      ┗ config.vsl

vSMTP default configuration

Configure vSMTP

Modify the /etc/vsmtp/conf.d/config.vsl file with this configuration:

fn on_config(config) {
  // Name of the server.
  config.server.name = "doe-family.com";

  // addresses that the server will listen to.
  // (change `192.168.1.254` for the desired address)
  config.server.interfaces = #{
    addr: ["192.168.1.254:25"],
    addr_submission: ["192.168.1.254:587"],
    addr_submissions: ["192.168.1.254:465"],
  };

  config
}

Configuring vSMTP

For complex configurations, it is recommended to split the file into Rhai modules.

To get an exhaustive list of parameters that can be changed in the configuration, see the Configuration Reference chapter.

The server can now listen and serve SMTP connections.

Filtering objects

Let’s define all the required objects for John Doe’s MTA. Those objects are used to configure vSMTP and simplify filtering rules.

Create the /etc/vsmtp/objects/family.vsl file with following objects:

// Doe's family domain name.
export const domain = fqdn("doe-family.com");

// Mailboxes.
export const john = address("john.doe@doe-family.com");
export const jane = address("jane.doe@doe-family.com");
export const jimmy = address("jimmy.doe@doe-family.com");
export const jenny = address("jenny.doe@doe-family.com");

export const addresses = [john, jane, jimmy, jenny];

// Paths for quarantines.
export const virus_queue = "virus";
export const untrusted_queue = "untrusted";

// A user blacklist file
export const blacklist = file("domain-available/example.com/blacklist.txt", "fqdn");

Objects that will be used during filtering

See the Object chapter for more information.

Blacklist

Define a blacklist file at /etc/vsmtp/domain-available/example.com/blacklist.txt with the following contents:

domain-spam.com
spam-domain.org
domain-spammers.com
foobar-spam-pro.org

Blacklist content

Listen and serve

The file structure of /etc/vsmtp should now look like this.

/etc/vsmtp/
 ┣ vsmtp.vsl
 ┣ conf.d/
 ┃      ┗ config.vsl
 ┣ domain-available/
+┃      ┗ example.com/
+┃          ┗ blacklist.txt
+┗ objects/
+       ┗ family.vsl

Adding objects and the blacklist to the configuration directory

If no interface is specified, the server listens on localhost on port 25, 465 and 587. Remote connections are therefore refused.

$> sudo systemd restart vsmtp
$> telnet 192.168.1.254:25
# 220 doe-family.com Service ready
# 554 permanent problems with the remote server

Test by opening a connexion to the server

Filtering

By default, the server will deny any SMTP transaction. We have to define filtering rules to accept connections and filter messages.

In this chapter, we will get a glimpse of vSMTP’s filtering system. To create filtering rules, we recommend checking out the vSL reference, focussing on the following chapters:

• Rules
• SMTP Stages
• Transaction context

For this example, we will configure the following rules:

• Messages from blacklisted domain will be rejected.
• As Jenny is 11 years old, Jane wants her address to be added as a blind carbon copy of messages destined to her daughter.
• Messages sent to the family must be delivered in Mailbox format.

Configuration

Let’s first add our filters in the /etc/vsmtp/conf.d/config.vsl script.

  fn on_config(config) {
    // Name of the server.
    config.server.name = "doe-family.com";

    // addresses that the server will listen to.
    // (change `192.168.1.254` for the desired address)
    config.server.interfaces = #{
      addr: ["192.168.1.254:25"],
      addr_submission: ["192.168.1.254:587"],
      addr_submissions: ["192.168.1.254:465"],
    };

+  // Root filter.
+  config.app.vsl.filter_path = "/etc/vsmtp/filter.vsl";
+  // Domain specific filters.
+  config.app.vsl.domain_dir = "/etc/vsmtp/domain-enabled";

    config
  }

Root Filter

Let’s define the root filter for incoming emails.

/etc/vsmtp/
 ┣ vsmtp.vsl
+┣ filter.vsl
 ┣ conf.d/
 ┃      ┣ config.vsl
 ┃      ┗ *.vsl
 ┗ objects/
        ┗ family.vsl

Adding the root filtering script

The filter.vsl script is responsible for handling clients that just connected to vSMTP.

Add anti-relaying

Let’s setup anti-relaying by adding the following rule. (See the Root Filter section in the Transaction Context chapter for more details)

#{
  rcpt: [
    rule "anti relaying" || state::deny(),
  ]
}

/etc/vsmtp/filter.vsl

Use the blacklist

We can add the blacklist we defined in the Blacklist section to filter out sender domains that we do not trust.

// Importing objects that we defined in the last chapter.
+import "objects/family" as family;

#{
+ mail: [
+   rule "do not deliver untrusted domains" || {
+       if ctx::mail_from().domain in family::blacklist {
+           state::quarantine(family::untrusted_queue)
+       } else {
+           state::next()
+       }
+   },
+ ],

  rcpt: [
    rule "anti relaying" || state::deny(),
  ]
}

/etc/vsmtp/filter.vsl

The do not deliver untrusted domains rule will save any email from senders found in the blacklist in a quarantine folder named “untrusted” and will not deliver the email.

Filtering for doe-family.com

Let’s create filtering rules for the doe-family.com domain.

/etc/vsmtp
  ┣ vsmtp.vsl
  ┣ filter.vsl
  ┣ conf.d/
  ┃      ┣ config.vsl
  ┃      ┗ *.vsl
+ ┣ domain-available/
+ ┃      ┗ doe-family.com/
+ ┃         ┣ incoming.vsl
+ ┃         ┣ outgoing.vsl
+ ┃         ┗ internal.vsl
+ ┣ domain-enabled/
  ┗ objects/
       ┗ family.vsl

adding filtering scripts for the `doe-family.com` domain

Since we specified in the configuration that the domain-enabled directory was our domain filtering directory, we need to create a symbolic link to domain-available/doe-family.com to enable filtering for doe-family.com.

/etc/vsmtp
  ┣ vsmtp.vsl
  ┣ filter.vsl
  ┣ conf.d/
  ┃      ┣ config.vsl
  ┃      ┗ *.vsl
  ┣ domain-available/
  ┃      ┗ doe-family.com/
  ┃         ┣ incoming.vsl
  ┃         ┣ outgoing.vsl
  ┃         ┗ internal.vsl
  ┣ domain-enabled/
+ ┃     ┗ example.com -> /etc/vsmtp/domain-available/doe-family.com
  ┗ objects/
       ┗ family.vsl

Enabling the `example.com` domain filtering

vSMTP will pickup incoming.vsl, outgoing.vsl and internal.vsl scripts under a folder with a fully qualified domain name. Those rules will be run following vSMTP’s transaction logic. Let’s define rules for each cases.

Incoming messages

The doe-family.com/incoming.vsl script is run when the sender of the domain is not doe-family.com and that recipients domains are doe-family.com.

Thus, when this script is run, all recipients are guaranteed to have the doe-family.com domain. We can then deliver emails locally using the Mailbox protocol.

import "objects/family" as family;

#{
  delivery: [
    action "setup delivery" || {
      for rcpt in ctx::rcpt_list() {
        // Deliver locally using Mailbox if the recipient is from Doe's family.
        if rcpt in family::addresses { transport::mailbox(rcpt) }
      }
    }
  ],
}

doe-family.com/incoming.vsl

Jane wants a blind copy of her Jenny’s messages. Let’s create a Rhai function that does exactly that.

/etc/vsmtp
 ┣ vsmtp.vsl
 ┣ filter.vsl
 ┣ conf.d/
 ┃      ┣ config.vsl
 ┃      ┗ *.vsl
 ┣ domain-available/
 ┃      ┗ doe-family.com/
+┃         ┣ bcc.vsl
 ┃         ┣ incoming.vsl
 ┃         ┣ outgoing.vsl
 ┃         ┗ internal.vsl
 ┣ domain-enabled/
 ┃     ┗ example.com -> ...
 ┗ objects/
       ┗ family.vsl

adding a new script to the domain

import "objects/family" as family;

fn bcc_jenny() {
  // add Jane as a blind carbon copy if the current recipient is Jenny.
  if ctx::rcpt() == family::jenny {
    bcc(family::jane)
  }
}

doe-family.com/bcc.vsl

Now, let’s plug this function to our filtering rules by importing the bcc.vsl script.

+ import "domain-available/doe-family.com/bcc" as bcc;
  import "objects/family" as family;

  #{
+   rcpt: [
+     action "bcc jenny" || bcc::bcc_jenny(),
+   ],

    delivery: [
      action "setup delivery" || {
        for rcpt in ctx::rcpt_list() {
          // Deliver locally using Mailbox if the recipient is from Doe's family.
          if rcpt in family::family_addr { transport::mailbox(rcpt) }
        }
      }
    ],
  }

doe-family.com/incoming.vsl

With Rhai modules and functions, it becomes easy to reuse code across different rules.

Outgoing messages

doe-family.com/outgoing.vsl is run when the sender of the domain is doe-family.com and that recipients domains are not doe-family.com.

Here, a member of Doe’s family is sending an email to someone else. We just have to verify that the sender is legitimate by asking the client to authenticate itself to vSMTP. If the authentication fails, this probably means that a spammer tried to use our server as a relay. The auth::unix_user() function automatically denies the transaction if the authentication failed.

#{
  authenticate: [
    rule "sasl authentication" || auth::unix_user(),
  ],

  mail: [
    rule "deny unauthenticated" || {
      if auth::is_authenticated() {
        state::next()
      } else {
        state::deny(code(530, "5.7.0", "Authentication required\r\n"))
      }
    }
  ]
}

/etc/vsmtp/domain-available/doe-family.com/outgoing.vsl

⚠️ The auth::unix_user function uses the testsaslauthd program under the hood, itself calling the saslauthd daemon. Make sure to install the Cyrus sasl binary package for the targeted distribution and configure the saslauthd daemon with MECHANISM="shadow" in /etc/default/saslauthd.

See the auth::is_authenticated and auth::unix_user reference for more details.

Internal messages

doe-family.com/internal.vsl is run when the sender and recipients domains are both doe-family.com.

Since we already authenticated clients in outgoing.vsl, we simply have to setup delivery.

// let's reuse our bcc code to add Jane as a blind carbon copy.
import "domain-available/doe-family.com/bcc" as bcc;

#{
  rcpt: [
      action "bcc jenny" || bcc::bcc_jenny(),
  ],

  delivery: [
      // Deliver all recipients locally.
      action "setup delivery" || transport::mailbox_all(),
  ],
}

/etc/vsmtp/domain-available/doe-family.com/internal.vsl

Now that all filtering rules are set for the doe-family.com domain, let’s restart the server to apply all rules.

sudo systemd restart vsmtp

SSL/TLS

ℹ️ To use SMTPS, you will need a valid TLS certificate and a private key for your server.

vSMTP support X.509 certificates and RSA/PKCS8/EC keys stored in .pem files.

TLS can be initiated right after connect on the address submissions, or with the STARTTLS mechanism.

fn on_config(config) {
  // Add root TLS settings.
  config.server.tls = #{
    preempt_cipherlist: false,
    handshake_timeout: "1000ms",
    protocol_version: ["TLSv1.2", "TLSv1.3"],
  };

  config
}

Adding tls configuration to `/etc/vsmtp/conf.d/config.vsl`

Policy

Rules can then be added to filter out unsecure transactions.

#{
  mail: [
    rule "deny unencrypted" || {
      // It is possible to customize the policy to whitelist some ip for example.
      if ctx::is_secured() {
        state::next()
      } else {
        state::deny(code(451, "5.7.3", "Must issue a STARTTLS command first\r\n"))
      }
    }
  ]
}

Adding rules to check if the transaction is secured in `/etc/vsmtp/filter.vsl`

See the ctx::is_secured reference for more details.

Certificate / SNI

You can host multiple domains on the same server. The certificate resolution of the server is based on the SNI extension.

By default, SNI is required. Meaning both these commands will produce an error.

openssl s_client -starttls smtp -crlf -connect 192.168.1.254:25
openssl s_client -crlf -connect 192.168.1.254:465

To support TLS for a virtual server, add those lines to your configuration.

fn on_domain_config(config) {
  config.tls = #{
    certificate: "/etc/vsmtp/certs/fullchain.pem",
    private_key: "/etc/vsmtp/certs/privkey.pem",
  };

  config
}

`/etc/vsmtp/domain-available/example.com/config.vsl`

You can then test the connection with the following command:

openssl s_client -starttls smtp -crlf -connect 192.168.1.254:25 -servername example.com
openssl s_client -crlf -connect 192.168.1.254:465 -servername example.com

Default domain

You can specify the certificate and the private key to use by default when no SNI is provided.

fn on_config(config) {
  // ...

  config.server.tls = #{
    // ...
    certificate: "/etc/vsmtp/certs/fullchain.pem",
    private_key: "/etc/vsmtp/certs/privkey.pem",
  };

  config
}

Set a default domain `/etc/vsmtp/conf.d/config.vsl`

These command will now work.

openssl s_client -starttls smtp -crlf -connect 192.168.1.254:25
openssl s_client -crlf -connect 192.168.1.254:465

Filtering with the Sender Policy Framework

SPF is an authentication standard used to link a domain name and an email address. it allows email clients to verify that incoming email from a domain comes from a host authorized by the administrator of this domain.

Add a DNS TXT record for SPF

A new DNS record is added into the doe-family.com DNS zone. It declares that only the server specified in the MX record is allowed to send messages on behalf of Doe’s family.

doe-family.com.          TXT "v=spf1 +mx -all"

TODO: add commands

For incoming messages, SPF is configured to check that the sending host is authorized to use the doe-family.com according to published SPF policy. Rules are executed at the mail stage.

Edit the /etc/vsmtp/domain-enabled/filter.vsl file and add the following rule.

#{
  mail: [
    rule "check spf" || spf::check("both", "soft"),
  ]
}

Preventing spams using SPF

See the spf::check reference for more details.

Filtering with DKIM

DKIM is an open standard for email authentication used to check the integrity of the content of an email. A signature header is added to the messages. This signature is secured by a key pair (private/public).

We will configure these rules:

• If the sender is an account from Doe’s family, add DKIM signature to the message.
• If the recipient is an account from Doe’s family, verify DKIM signatures.

Add a DKIM record

A new DNS record is added into the doe-family.com DNS zone. It declares the public key usable to verify the messages.

TODO: add an example.

Configure vSMTP for DKIM

Add the following line to the on_config function body in the root configuration.

fn on_config(config) {
  config.server.dkim.private_key = ["/path/to/private-key"];

  config
}

`/etc/vsmtp/conf.d/config.vsl`

Add signatures

The dkim_sign function is used to sign the email. Use it in the postq stage like so:

#{
  // ... previous rules ...

  postq: [
    action "sign dkim" || {
      // Iterate over all the private keys defined for the server 'doe-family.com'

      for key in dkim::get_private_keys("doe-family.com") {
        dkim::sign(
          // Selector of the DNS record.
          "2022-09",
          // The private key associated with the public key in `{selector}._domainkey.{sdid}`
          // Or `2022-09._domainkey.doe-family.com.` in that case
          key,
          // Headers to sign with.
          ["From", "To", "Date", "Subject", "From"],
          // Canonicalization algorithm to use.
          "simple/relaxed"
        );
      }
    }
  ],
}

/etc/vsmtp/domain-available/doe-family.com/outgoing.vsl

See the dkim::sign reference for more details.

Verify signatures

#{
  // ... previous rules ...

  postq: [
    rule "verify DKIM signatures" || {
      if dkim::verify().status == "pass" {
        state::accept()
      } else {
        state::deny()
      }
    }
  ],
}

/etc/vsmtp/domain-available/doe-family.com/incoming.vsl

See the dkim::verify reference for more details.

Adding an antivirus

Malware remains a scourge. As John is aware of security issues, he decides to add a layer of antivirus directly on the MTA. He installed ClamAV which comes with the clamsmtpd antivirus daemon.

vSMTP support security delegation via the SMTP protocol using .vsl scripts. In the following tutorial, we are going to setup a delegation workflow that looks like the following.

{ Incoming msg }  ---> vSMTP server ---> { Delivered msg }
                        |       ^
                        |       |
      clamsmtpd socket  |       |   vSMTP socket
         (delegator)    |       |    (receiver)
       127.0.0.1:10026  |       |  127.0.0.1:10025
                        |       |
                        v       |
                  { clamsmtpd daemon } <-> { ClamAV }

Delegating emails to clamav and getting back the results

ClamAV setup

The following example assumes that the clamsmtpd service is loaded and started with the following configuration:

# The address to send scanned mail to.
# This option is required unless TransparentProxy is enabled
OutAddress: 10025

# Address to listen on (defaults to all local addresses on port 10025)
Listen: 127.0.0.1:10026

# Tells clamav to forward the email to vsmtp
# event thought it found a virus. (it drops the email by default)
Action: pass

clamav configuration at `/etc/clamsmtpd.conf`

sudo systemctl start clamsmtp
sudo systemctl start clamav-daemon

Starting clamav

SMTP Service

Let’s create a smtp service in the /etc/vsmtp/services/smtp.vsl script to send incoming emails to clamsmtpd and receive them back on a specific address.

export const clamsmtpd = smtp::connect(#{
  delegator: #{
    address: "127.0.0.1:10026",
    timeout: "60s",
  },
  receiver: "127.0.0.1:10025",
});

Declaring a SMTP service

The receiver’s socket must be enabled in the root config.

fn on_config(config) {
  config.server.interfaces = #{
    addr: [
      // Receiver for clients.
      "192.168.1.254:25",
      // Receiver for delegation results from clamav.
      "127.0.0.1:10025"
    ],
  };

  config
}

Update the root configuration with a receiver for clamav

Filtering

Create the antivirus passthrough using the delegate keyword in the /etc/vsmtp/domain-available/doe-family.com/incoming.vsl script.

import "objects/family" as family;
import "services/smtp" as srv;

{
  postq: [
    delegate srv::clamsmtpd "check email for virus" || {
      // this is executed once the delegation result are received.
      log("debug", "email analyzed by clamsmtpd.");

      // ClamAV inserts the "X-Virus-Infected" header if it found a virus.
      if msg::has_header("X-Virus-Infected") {
        state::quarantine(family::virus_queue)
      } else {
        state::next()
      }
    }
  ],
}

Moving infected emails in the `virus_queue` quarantine queue.

Compromised emails are quarantined in the virus_queue folder.

Check out the Delegation chapter for more details.

Greylist

Greylisting is one method to defend a SMTP server against spam.

The goal is to temporarily reject emails from a sender that is not yet in registered in a database, then accepting it back if the sender retries.

To build a greylist, create a database and a vSMTP service. For this tutorial, we will use the mysql database.

The database

Install MySQL

Please follow this great tutorial to install MySQL.

This setup has been tested on Ubuntu 22.04, check out the MySQL website for other systems.

# Install mysql.
$ sudo apt update
$ sudo apt install mysql-server
$ sudo systemctl start mysql.service

# Login as root.
$ sudo mysql

# Replace auth_socket authentication by a simple password.
mysql> ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your-password';
mysql> exit

# Update root password & remove unnecessary stuff.
$ sudo mysql_secure_installation

# Connect as root with the password.
mysql -u root -p

# Reset auth to auth_socket, this way you can connect with `sudo mysql`
mysql> ALTER USER 'root'@'localhost' IDENTIFIED WITH auth_socket;

Setting up MySQL

Setup a user

To manage your database, you should create a new user with restricted privileges instead of relying on root.

# Here we use localhost as our host but you could also setup your database on another server.
mysql> CREATE USER 'greylist-manager'@'localhost' IDENTIFIED BY 'your-password';

Creating a user named 'greylist-manager'

Setup the database and a table

To create the database, simply put the content of this sql code into a greylist.sql file.

CREATE DATABASE greylist;

CREATE TABLE greylist.sender(
    address varchar(500) NOT null primary key,
    user varchar(500) NOT null,
    domain varchar(500) NOT null
);

Template for the greylist database

And then run the mysql command as root to generate the database.

sudo mysql < greylist.sql

Grant necessary privileges to your user on the newly create table.

mysql> GRANT SELECT, INSERT ON greylist.sender TO 'greylist-manager'@'localhost';

The greylist database is now operational.

Setup vSMTP

To setup vSMTP, you first need to create a mysql service, that will enable you to query your database. You can, for example, write it in a services.vsl file where your main.vsl is located.

export const greylist = mysql::connect(#{
    // Change this url to the url of your database, or keep it like this if the 'greylist-manager' user is setup on localhost.
    url: "mysql://localhost/?user=greylist-manager&password=your-password",
});

`services/db.vsl`

The query function from the mysql service is used to query a mysql database. Variables are passed to the query using string interpolation.

⚠️ String interpolation can lead to SQL injection if not used properly. Make sure to sanitize your inputs, set only required privileges to the mysql user, and check what kind of data you are injecting.

Create a greylist rule in your root filter.vsl file.

import "services/db" as db;

#{
    // The greylist is effective in the "mail" stage, because the sender
    // of the email is received at this stage.
    mail: [
        rule "greylist" || {
            let sender = ctx::mail_from();

            // if the sender is not recognized in our database,
            // we deny the transaction and write the sender into
            // the database.
            if db::greylist.query(`SELECT * FROM greylist.sender WHERE address = '${sender}';`) == [] {
                // Writing the sender into the database.
                db::greylist.query(`
                    INSERT INTO greylist.sender (user, domain, address)
                    values ("${sender.local_part}", "${sender.domain}", "${sender}");
                `);

                // vsl exposes a built-in `greylist` error code.
                state::deny(code::c451_7_1())
            } else {
                // the user is known by the server, the transaction
                // can proceed.
                state::accept()
            }
        }
    ]
}

Declaring a greylist rule

Using the Sender Policy Framework

SPF is an authentication standard used to link a domain name and an email address. it allows email clients to verify that incoming email from a domain comes from a host authorized by the administrator of this domain.

In this tutorial, we will set up SPF for the example.com domain by:

• Adding DNS TXT records for SPF.
• Add filtering for incoming and outgoing emails using SPF.

Feel free to replace example.com by your own domain.

Add a DNS TXT record for SPF

A new DNS record is added into the example.com DNS zone. It declares that only the server specified in the MX record is allowed to send messages on behalf of the domain.

example.com.          TXT "v=spf1 +mx -all"

A TXT record with SPF specifications for the `example.com` domain

TODO: add commands

Filtering with SPF

For incoming messages, SPF is configured to check that the sending host is authorized to use the example.com domain according to published SPF policy. Rules are executed at the mail stage.

Edit the /etc/vsmtp/filter.vsl script and add the following rule.

#{
  mail: [
    rule "check spf" || spf::check("both", "soft"),
  ]
}

Preventing spams using SPF

See the spf::check reference for more details.

To check if DKIM is working correctly, check out this site.

Using DKIM

DKIM is an open standard for email authentication used to check the integrity of the content of an email. In this tutorial, we will set up DKIM by:

• Adding DNS TXT records for DKIM.
• Generate keys to encrypt and verify emails.
• Add filtering for incoming and outgoing emails using DKIM.

We will use the example.com domain for this example, but feel free to replace it by your own domain.

Configure the DNS

A new DNS record is added into the example.com DNS zone. This record declares the public key usable to verify the messages. (See the What is DKIM chapter for more details)

TODO: add command line example.

Generate Keys

TODO: add commands using lets encrypt.

vSMTP root configuration

The path to private keys for DKIM can be specified in the /etc/vsmtp/conf.d/config.vsl script:

fn on_config(config) {
  config.server.dkim.private_key = ["/path/to/private-key-1", "/path/to/private-key-2", ...];
  config
}

Configuring DKIM keys

It is also possible to configure keys per domain.

fn on_domain_config(config) {
  config.dkim.private_key = ["/path/to/private-key-1", "/path/to/private-key-2", ...];
  config
}

Configuring DKIM keys for a specific domain (f.e. example.com)

If a key cannot be found for a specific domain, the root dkim keys are used instead.

Add signatures

Sign an email using the dkim::sign function for outgoing emails.

#{
  postq: [
    action "sign dkim" || {
      // Iterate over all the private keys defined for the server 'example.com'

      for key in dkim::get_private_keys("example.com") {
        dkim::sign(
          // Selector of the DNS record.
          "2022-09",
          // The private key associated with the public key in `{selector}._domainkey.{sdid}`
          // Or `2022-09._domainkey.example.com.` in that case
          key,
          // Headers to sign with.
          ["From", "To", "Date", "Subject", "From"],
          // Canonicalization algorithm to use.
          "simple/relaxed"
        );
      }
    }
  ],
}

/etc/vsmtp/domain-available/example.com/outgoing.vsl

Verify signatures

Verify DKIM signatures of incoming emails by calling the dkim::verify function.

#{
  // ... previous rules ...

  postq: [
    rule "verify DKIM signatures" || {
      if dkim::verify().status == "pass" {
        state::accept()
      } else {
        state::deny()
      }
    }
  ],
}

/etc/vsmtp/domain-available/example.com/incoming.vsl

To check if DKIM is working correctly, check out this site.

Using DMARC

DMARC (Domain-based Message Authentication, Reporting and Conformance) allows email administrators to prevent hackers from impersonating their organization. This type of attack is also called “spoofing” because the message appears to come from the spoofed organization or domain.

This document specifies the vSMTP implementation of the Domain-based Message Authentication, Reporting and Conformance (DMARC) protocol described in RFC 7489.

<!> DMARC reporting and DMARC feedback system are not implemented.

In order to counter spoofing attacks, DMARC uses SPF and DKIM protocols.

When a message appears to come from an organization, but does not pass authentication checks or does not meet the authentication criteria, DMARC policy tells mail servers what action to perform.

The DMARC implementation of vSMTP support the Mail Receiver part, and apply the policy specified in the DNS record.

We will setup DMARC in this tutorial by:

• Setting up SPF.
• Setting up DKIM.
• Adding filtering using DMARC.

We will use the example.com domain for this example, but feel free to replace it by your own domain.

Setup SPF

See the Using SPF tutorial.

Setup DKIM

See the Using SPF tutorial.

Filtering with DMARC

Add this rule to the domain-available/example.com/incoming.vsl script.

#{
  preq: [
    rule "check dmarc" || dmarc::check(),
  ]
}

Filter emails using DMARC

This rule will conducts SPF and DKIM authentication checks by passing the necessary data to their respective modules. The results of these are passed to the DMARC module along with the Author’s domain. The DMARC module attempts to retrieve a policy from the DNS for that domain. If a policy is found, it is combined with the Author’s domain and the SPF and DKIM results to produce a DMARC policy result (“pass” or “fail”).

Trouble shooting

This section is Under construction.

No logs available (daemon mode)

Sometimes, logs do not get initialized fast enough in daemon mode, leading to vSMTP not starting on error. To fix this, use the server with the --no-daemon option, it will log error messages on stderr.

$ sudo systemctl start vsmtp
$ sudo systemctl status vsmtp
# this prints a failed start status.

$ vsmtp -c /path/to/config.vsl --no-daemon
# this will print errors on stderr.

Running vsmtp with the `--no-daemon` flag to redirect logs to stderr

Mail Agent

This chapter describes Mail Agents and their purpose in the email ecosystem.

   +-----+   +-----+   +------------+
   | MUA |-->| MSA |-->| Border MTA |
   +-----+   +-----+   +------------+
                             |
                             |
                             V
                        +----------+
                        | Internet |
                        +----------+
                             |
                             |
                             V
+------------------+   +------------+
| Intermediate MTA |<--| Border MTA |
+------------------+   +------------+
          |
          |
          V
       +-----+   +-----+
       | MDA |-->| MUA |
       +-----+   +-----+

Flow of emails in the mail ecosystem

MUA (Mail User Agent)

Client application that allows receiving and sending emails. It can be a desktop application such as Microsoft Outlook/Thunderbird/… or web-based such as Gmail/Hotmail/… (the latter is also called Webmail).

MSA (Mail Submission Agent)

The MSA is responsible for the incoming traffic in the mail system.

A server program that receives mail from an MUA, checks for any errors, and transfers it (via SMTP) to a MTA.

MTA (Mail Transfer Agent)

The MTA is responsible to deliver the mails to the recipients’s mail exchange, using the DNS logics.

A server application that receives mail from the MSA, or from another MTA. It will find (through name servers and the DNS) the MX record from the recipient domain’s DNS zone in order to know how to transfer the mail. It then transfers the mail (with SMTP) to another MTA (which is known as SMTP relaying) or, if the recipient’s server has been reached, to the MDA.

• A “border MTA” is an MTA that acts as a gateway between the general Internet and the users within an organizational boundary.
• A “delivery MTA” (or Mail Delivery Agent or MDA) is an MTA that actually enacts delivery of a message to a user’s inbox or other final delivery.
• An “intermediate MTA” is any MTA that is not a delivery MTA and is also not the first MTA to handle the message.

MDA (Mail Delivery Agent)

A server program that receives mail from the server’s MTA, and stores it into the mailbox. MDA is also known as LDA (Local Delivery Agent).

An example is Dovecot, which is mainly a POP3 and IMAP server allowing an MUA to retrieve mail, but also includes an MDA which takes mail from an MTA and delivers it to the server’s mailbox.

Email Authentication Mechanisms

Prevent scammers from usurping an identity by using its domain name is a must nowadays. This is where the SPF, DKIM and DMARC authentication protocols come into play.

This chapter described how to define vSMTP as a legitimate sender and receiver.

SPF and DKIM : what’s that all about ?

Sender Policy Framework (SPF) specifies the authorized senders in a given domain. It thus allows email clients to check that incoming email from a domain comes from a host authorized by the administrator of this domain.

SPF is an authentication standard that links a domain name and an email address.

The DomainKeys Identified Mail (DKIM) protocol allows the sender to sign its message with its domain name. The DKIM protocol is used to attest that the domain name has not been usurped, and that the message has not been altered during its transmission.

DKIM is an authentication protocol that links a domain name to a message.

The simultaneous use of this two protocols is one of the most effective way to prevent phishers and other fraudsters from impersonating a legitimate sender using its domain name.

The implementation of these protocols improves email deliverability, since senders are better identified by the ISPs (Internet Service Providers) and email clients of your recipients. You then optimize your chances that your emails will

These two protocols are now widely used. A message sent without an SPF and/or DKIM signature is viewed with suspicion by the various email analysis tools and may be flagged as a “spam”.

SPF and DKIM : limitations

SPF has limits. If a message is forwarded, the verification may not be performed, since the address of the sender of the forwarded message is not necessarily included in the list of addresses agreed by the SPF evaluation.

DKIM also has limits. The DKIM signature does not prevent the sender from being considered a spammer if good emailing practices are not applied.

Moreover, SPF and DKIM do not specify the action to apply in case of verification failure. The DMARC protocol comes in, tells the recipient’s server how it should act if the sender’s authentication processes fail.

DMARC standard

Domain-based Message Authentication, Reporting and Conformance, or DMARC, is an authentication standard complementary to SPF and DKIM intended to fight more efficiently against phishing and other spamming practices.

DMARC allows domain holders to tell ISPs and email clients what to do when a signed message from their domain is not formally identified by a SPF or a DKIM mechanism.

ARC (extension to DMARC)

Parts of legitimate messages (subject tags, footers, etc.) can be altered due to forwarding (mailing list, virus scanner, etc.) and thus no longer succeed commonly accepted authentication checks. It can happen when an Internet domain publishes a strict DMARC policy.

ARC captures and conveys authentication results and allows the final recipient to check the authentication status of the message when it arrives at the first ARC-aware MTA.

BIMI

Brand Indicators for Message Identification (BIMI) is a future standard that makes it easier to identify the sender of an email. BIMI coordinates e-mail publishers and domain name owners to allow the latter to display their logos directly at the level of their customers’ e-mail boxes, i.e. next to the name of the issuer. BIMI requires DMARC.

For brands, BIMI is an opportunity to protect their identities by e-mail (fight against “phishing”) and to increase the reach and visibility of their logos. Because these logos are only included in DMARC-authenticated emails, consumers’ trust in their brands is also enhanced.

What is SPF ?

This document describes the vSMTP implementation of the Sender Policy Framework (SPF) protocol. SPF specifications are available in the RFC 7208 document.

SPF is an authentication standard used to link a domain name and an email address. it allows email clients to verify that incoming email from a domain comes from a host authorized by the administrator of this domain.

The SPF framework allows the ADministrative Management Domains (ADMDs) to explicitly authorize hosts to send email. The authorization list is published in the DNS records of the sender’s domain.

DNS records

The type of a SPF record is TXT. There should be only one SPF record per domain. In case of multiple SPF records, an error may be raised.

Here is a basic SPF record example: “only servers in the range 123.123.123.0/24 and MTA (MX) are authorized to send emails from my domain example.com. All other senders are considered unauthorized.”

example.com.          TXT "v=spf1 +mx ip4:123.123.123.0/24 -all"

There is also a tilde version: ~all. It warns that other senders are not allowed, but must still be accepted. This “Soft Fail” statement was first introduced for testing purposes, but is now used by various hosting providers.

Use of wildcard records for publishing is discouraged.

Please refer to RFC 7208 for further details.

vSMTP implementation

HELO/EHLO Identity

The RFC 7208 does not enforce a HELO/EHLO verification.

“It is RECOMMENDED that SPF verifiers not only check the “MAIL FROM” identity but also separately check the “HELO” identity […] Additionally, since SPF records published for “HELO” identities refer to a single host, when available, they are a very reliable source of host authorization status. Checking “HELO” before “MAIL FROM” is the RECOMMENDED sequence if both are checked.“

The RFC 5321 tends to normalize the HELO/EHLO arguments to represent the fully qualified domain name of the SMTP client. However the vSMTP SPF verifier is prepared for the identity to be an IP address literal or simply be malformed.

“SPF check can only be performed when the “HELO” string is a valid, multi-label domain name.“

MAIL FROM identity

According to the RFC, “MAIL FROM” check occurs when :

“SPF verifiers MUST check the “MAIL FROM” identity if a “HELO” check either has not been performed or has not reached a definitive policy result.“

Note that RFC5321 allows the reverse-path to be null. In this case, the RFC 7208 defines the “MAIL FROM” identity as the local-part “postmaster” and the “HELO” identity.

Location of checks

As defined by the RFC :

“The authorization check SHOULD be performed during the processing of the SMTP transaction that receives the mail. This reduces the complexity of determining the correct IP address to use as an input to check_host() and allows errors to be returned directly to the sending MTA by way of SMTP replies.”

vSMTP allows the use of the SPF framework only at the “MAIL FROM” stage.

Results of Evaluation

The vSMTP SPF verifier implements results semantically equivalent to the RFC.

Result	Description
none	(a) no syntactically valid DNS domain name was extracted from the SMTP session that could be used as the one to be or (b) no SPF records were retrieved from the DNS.
neutral	The ADMD has explicitly stated that it is not asserting whether the IP address is authorized.
pass	The client is authorized to inject mail with the given identity.
fail	The client is not authorized to use the domain in the given identity.
softfail	The host is probably not authorized but the ADMD has not published a stronger policy.
temperror	A transient (generally DNS) error while performing the check.
permerror	The domain’s published records (DNS) could not be correctly interpreted.
policy	Added by RFC 8601, Section 2.4 - indicate that some local policy mechanism was applied that augments or even replaces (i.e., overrides) the result returned by the authentication mechanism. The property and value in this case identify the local policy that was applied and the result it returned.

Results headers

Results should be recorded in the message header. Two options are available according to the RFC:

1. The “Received-SPF” header

Received-SPF: pass (mybox.example.org: domain of myname@example.com
  designates 192.0.2.1 as permitted sender)
  receiver=mybox.example.org; client-ip=192.0.2.1;
  envelope-from="myname@example.com"; helo=foo.example.com;

1. The “Authentication-Results” header described in RFC 8601 : Message Header Field for Indicating Message Authentication Status.

Authentication-Results: example.com; spf=pass smtp.mailfrom=example.net

SPF failure codes

The RFC 7372 “Email Auth Status Codes” introduces new status codes for reporting the DKIM and SPF mechanisms.

Code	X.7.23
Text	SPF validation failed
Basic status code	550
Description	A message completed an SPF check that produced a “fail” result
Used in place of	5.7.1, as described in Section 8.4 of RFC 7208.

Code	X.7.24
Text	SPF validation error
Basic status code	451/550
Description	Evaluation of SPF relative to an arriving message resulted in an error.
Used in place of	4.4.3 or 5.5.2, as described in Sections 8.6 and 8.7 of RFC 7208.

The following error codes can also be sent by the SPF framework.

Code	X.7.25
Text	Reverse DNS validation failed
Basic status code	550
Description	An SMTP client’s IP address failed a reverse DNS validation check, contrary to local policy requirements.
Used in place of	n/a

Code	X.7.26
Text	Multiple authentication checks failed
Basic status code	500
Description	A message failed more than one message authentication check, contrary to local policy requirements. The particular mechanisms that failed are not specified.
Used in place of	n/a

What is DKIM ?

The vSMTP implementation of the DomainKeys Identified Mail Signatures (DKIM) protocol is described in RFC 6376.

DKIM is an open standard for email authentication used to check the integrity of the content. A signature header is added to the messages. This signature is secured by a key pair (private/public).

DKIM signatures work like a watermark. Therefore, they survive forwarding, which is not the case for SPF.

Assertion of responsibility is validated through a cryptographic signature and by querying the Signer’s domain to retrieve the appropriate public key.

DNS records

DKIM relies on a DNS TXT record inserted into the sender domain’s DNS zone. The record contains the public key for the DKIM settings. The private key held by the sending mail server can be verified against the public key by the receiving mail server.

Unlike SPF record, several DKIM records can be linked to a domain. A domain can have several public keys if it has several mail servers (each mail server has its own private key that matches only one public key). The recipient’s mail server uses an attribute called selector of the DKIM signature to find the correct public key in the sender’s DNS zone.

A DKIM record must follow the syntax : [selector]._domainkey.[domain]. and the query on may only result in one TXT type record maximum.

Here is an example of a DKIM record:

mail._domainkey.example.com. 86400 IN TXT "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG...

DKIM keys are not meant to be changed frequently. A high time-to-live (TTL) value of 86400 seconds or more is not uncommon.

For detailed information about fields in a DKIM record please check the RFC 6376.

vSMTP implementation

vSMTP can act as DKIM signer or verifier.

Results of Evaluation

The vSMTP DKIM verifier implements results semantically equivalent to the RFC.

Result	Description
none	The message was not signed.
pass	The message was signed, the signature or signatures were acceptable to the ADMD, and the signature(s) passed verification tests.
fail	The message was signed and the signature or signatures were acceptable to the ADMD, but they failed the verification test(s).
policy	The message was signed, but some aspect of the signature or signatures was not acceptable to the ADMD.
neutral	The message was signed, but the signature or signatures contained syntax errors or were not otherwise able to be processed. This result is also used for other failures not covered elsewhere in this list.
temperror	The message could not be verified due to some error that is likely transient in nature, such as a temporary inability to retrieve a public key. A later attempt may produce a final result.
permerror	The message could not be verified due to some error that is unrecoverable, such as a required header field being absent. A later attempt is unlikely to produce a final result.

Results headers

Results should be recorded in the message header before any existing DKIM-Signature or preexisting authentication status header fields in the header field block.

There’s no specific DKIM header. The Authentication-Results header described in RFC 8601 should be used.

Authentication-Results: example.com;
            dkim=pass (good signature) header.d=example.com
Received: from mail-router.example.com
                (mail-router.example.com [192.0.2.1])
            by auth-checker.example.com (8.11.6/8.11.6)
                with ESMTP id i7PK0sH7021929;
            Fri, Feb 15 2002 17:19:22 -0800
DKIM-Signature:  v=1; a=rsa-sha256; s=gatsby; d=example.com;
            t=1188964191; c=simple/simple; h=From:Date:To:Subject:
            Message-Id:Authentication-Results;
            bh=sEuZGD/pSr7ANysbY3jtdaQ3Xv9xPQtS0m70;
            b=EToRSuvUfQVP3Bkz ... rTB0t0gYnBVCM=

DKIM failure codes

The RFC 7372 “Email Auth Status Codes” introduces new status codes to report the DKIM and SPF mechanisms results.

Code	X.7.20
Text	No passing DKIM signature found
Basic status code	550
Description	A message did not contain any passing DKIM signatures.

Code	X.7.21
Text	No acceptable DKIM signature found
Basic status code	550
Description	A message contains one or more passing DKIM signatures, but none are acceptable.

Code	X.7.22
Text	No valid author-matched DKIM signature found.
Basic status code	550
Description	A message contains one or more passing DKIM signatures, but none are acceptable because none have an identifier(s) that matches the author address(es) found in the From header field.

The following error codes can also be sent by the DKIM framework.

Code	X.7.25
Text	Reverse DNS validation failed
Basic status code	550
Description	An SMTP client’s IP address failed a reverse DNS validation check, contrary to local policy requirements.
Used in place of	n/a

Code	X.7.26
Text	Multiple authentication checks failed
Basic status code	500
Description	A message failed more than one message authentication check, contrary to local policy requirements. The particular mechanisms that failed are not specified.
Used in place of	n/a

Null MX record

Section 5 of RFC5321 covers the sequence to identify a server that accepts email for a domain. The SMTP client first looks up a DNS MX RR, and if is not found, falls back to a DNS A or AAAA request. If a CNAME record is found, the resulting name is processed as if it were the initial name.

This mechanism suffers from two major drawbacks.

• A DNS overload because of an email service semantic.
• If there are no SMTP listeners at the A/AAAA addresses, message delivery will be attempted repeatedly many times before the sending Mail Transfer Agent (MTA) gives up, implying:
  • a delay notification to the sender in the case of misdirected mail,
  • a waste of IT resources at the sender.

The “Null MX” protocol solves these issues. It is used to state that mail services are disabled in a given domain. The protocol is described in RFC 7505.

When a specific DNS record (a null MX) is effectively defined in the DNS zone of a given domain, all mail delivery attempts fail immediately.

DNS record

The null MX RR is an ordinary MX record with an RDATA section consisting of preference number 0 and a “.” as the exchange domain, to denote that there exists no mail exchanger.

nomail.example.com. 86400 IN MX 0 "."

A domain that advertises a null MX must not advertise any other MX RR.

Sender with Null MX records

As Null MX is primarily intended for domains that do not send or receive any mail, vSMTP default behavior rejects mail that has an invalid return address.

Mail systems should not publish a null MX record for domains that they use in MAIL FROM (RFC5321) or From (RFC5322) directives.

Return codes

The RFC 7505 defines two specific return codes.

Code	X.1.10
Text	Recipient address has null MX
Basic status code	556
Description	The associated address is marked as invalid using a null MX.

Code	X.7.27
Text	Sender address has null MX
Basic status code	550
Description	The associated sender address has a null MX, and the SMTP receiver is configured to reject mail from such sender (e.g., because it could not return a DSN).

Dealing with Null MX records

Currently, MX records are automatically checked on delivery. If the destination server provides a NULL MX record, the message is immediately moved into the dead queue.

In future release, it will be possible to configure rules to check for null MX records using filtering and decide what to do with the email.

Installing vSMTP from source

• Linux
• FreeBSD
• NetBSD help wanted
• OpenBSD help wanted

Download the source code

All versions of the software are available on the release page.

It is possible to get the latest release using git. (via the main branch)

git clone -b main --single-branch https://github.com/viridIT/vSMTP.git

Or get the latest unstable version of vSMTP. (via the develop branch)

git clone -b develop --single-branch https://github.com/viridIT/vSMTP.git

Linux installation

The installation described below was performed on an Ubuntu Server 20.04. Slight changes may be needed for other distributions.

Install Rust language

See the official website https://www.rust-lang.org/tools/install

Check dependencies

vSMTP requires the libc libraries and the GCC compiler/linker. On a Debian system, they are contained in the build-essential package.

sudo apt update
sudo apt install pkg-config build-essential sasl2-bin

Install vSMTP's dependencies

vSMTP compilation

cargo (Rust package manager) downloads all required dependencies and compile the source code in conformance to the current environment.

$> cargo build --workspace --release
[...]
$> cargo run -- --help
vsmtp 2.1.0
Team viridIT <https://viridit.com/>
Next-gen MTA. Secured, Faster and Greener

USAGE:
    vsmtp [OPTIONS] [SUBCOMMAND]

OPTIONS:
    -c, --config <CONFIG>      Path of the vSMTP configuration file ("vsl" format)
    -h, --help                 Print help information
    -n, --no-daemon            Do not run the program as a daemon
    -t, --timeout <TIMEOUT>    Make the server stop after a delay (human readable format)
    -V, --version              Print version information

SUBCOMMANDS:
    config-diff    Show the difference between the loaded config and the default one
    config-show    Show the loaded config (as serialized json format)
    help           Print this message or the help of the given subcommand(s)

Building and running the source code using `cargo`

By default Rust/Cargo use static linking to compile. All libraries required are compiled into the executable, allowing vSMTP to be a standalone application.

Configure the Operating System for vSMTP

For security purpose, vSMTP should run using a dedicated account with minimum privileges.

$ sudo adduser --system --shell /usr/sbin/nologin --no-create-home \
    --uid 9999 --group --disabled-password --disabled-login vsmtp

Create a user to run vSMTP

Adding system user 'vsmtp' (UID 9999) ...
Adding new group 'vsmtp' (GID 9999) ...
Adding new user 'vsmtp' (UID 9999) with group 'vsmtp' ...
Not creating home directory '/home/vsmtp'.

vSMTP binaries and config files should be located in:

┣ /usr/sbin/           : binaries
┣ /etc/vsmtp/
┃    ┣ vsmtp.vsl       : default configuration file
┃    ┗ rules/          : rules
┣ /var/spool/vsmtp/    : internal queues
┣ /var/log/
┃    ┣ vsmtp.log/      : internal logs and trace
┃    ┗ app.log         : application logs
┗ /home/<user>/Maildir : local IMAP delivery

These default locations may be changed in the /etc/vsmtp/vsmtp.vsl configuration file which is called by the service startup /etc/systemd/system/vsmtp.service file.

sudo mkdir /etc/vsmtp /etc/vsmtp/rules /etc/vsmtp/certs /var/log/vsmtp /var/spool/vsmtp
sudo cp ./target/release/vsmtp /usr/sbin/
sudo cp ./target/release/vqueue /usr/sbin/

Create vSMTP directories

A minimal vsmtp.vsl configuration file that matches vsmtp version (i.e. 2.1.0) must be created.

cat > /etc/vsmtp/vsmtp.vsl <<EOF
import "conf.d/config.vsl" as cfg;
let config = cfg::config;
config.version_requirement = ">=2.1.0";
EOF

Create a minimal configuration file

sudo chown -R vsmtp:vsmtp /var/log/vsmtp /etc/vsmtp/* /var/spool/vsmtp

Grant rights to vSMTP files and directories

If required, add private key and certificate to /etc/vsmtp/certs and grant reading rights to the vsmtp user.

Configuring the MTA service

Check and disable current MTA

Check if a mail transfer agent service is running and disable it.

$ sudo ss -ltpn | grep ":25"
tcp        0      0 127.0.0.1:25              127.0.0.1:*               LISTEN      39423/master

$ sudo systemctl status postfix
● postfix.service - Postfix Mail Transport Agent
     Loaded: loaded (/lib/systemd/system/postfix.service; enabled; vendor preset: enabled)
     Active: active (exited) since Fri 2021-12-10 11:10:58 CET; 5min ago
    Process: 39426 ExecStart=/bin/true (code=exited, status=0/SUCCESS)
   Main PID: 39426 (code=exited, status=0/SUCCESS)

$ sudo systemctl stop postfix
$ sudo systemctl disable postfix
Synchronizing state of postfix.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install disable postfix
Removed /etc/systemd/system/multi-user.target.wants/postfix.service.

Disabling a postfix instance that was running on port 25

☞ | Depending on Linux distributions, use the ss or netstat -ltpn commands.

Add vSMTP as a systemd service

Copy the daemon configuration file in /etc/systemd/system.

sudo cp ./tools/install/deb/vsmtp.service /etc/systemd/system/vsmtp.service

Please note that vSMTP drops privileges at startup. The service type must be set to forking.

Do not modify this file unless you know what you are doing.

Enable and activate vSMTP service

$ sudo systemctl enable vsmtp.service
Created symlink /etc/systemd/system/multi-user.target.wants/vsmtp.service → /etc/systemd/system/vsmtp.service.

$ sudo systemctl start vsmtp

$ sudo systemctl status vsmtp
● vsmtp.service - vSMTP Mail Transfer Agent
     Loaded: loaded (/etc/systemd/system/vsmtp.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2021-12-10 11:32:15 CET; 21s ago
   Main PID: 2164 (vsmtp)
      Tasks: 25 (limit: 38287)
     Memory: 39.9M
     CGroup: /system.slice/vsmtp.service
             └─2164 /usr/sbin/vsmtp -c /etc/vsmtp/vsmtp.vsl

Check that vSMTP is working properly

$ ss -ltpn | grep vsmtp
State    Recv-Q   Send-Q     Local Address:Port     Peer Address:Port   Process
LISTEN   0        128        127.0.0.1:587           127.0.0.1:*       users:(("vsmtp",pid=2127,fd=5))
LISTEN   0        128        127.0.0.1:465           127.0.0.1:*       users:(("vsmtp",pid=2127,fd=6))
LISTEN   0        128        127.0.0.1:25            127.0.0.1:*       users:(("vsmtp",pid=2127,fd=4))

$ nc -C localhost 25
220 mydomain.com Service ready
451 Timeout - closing connection.

FreeBSD installation

The installation described above was performed on an FreeBSD 13.0 server.

Installing Rust language

Rust port, packages and information can be found on the freshports website. Find more information about packages and port in the FreeBSD handbook.

pkg install lang/rust

Rust 1.60+ package is required. It may be necessary to switch to the latest ports branch. Please refer to the freeBSD wiki.

Dependencies

FreeBSD 13.x includes all required dependencies. Check that sasl is included in the used release. (See Linux dependencies)

vSMTP compilation

$> cargo build --workspace --release
[...]
$> cargo run -- --help
vsmtp 1.4
Team viridIT <https://viridit.com/>
Next-gen MTA. Secured, Faster and Greener

USAGE:
    vsmtp [OPTIONS] [SUBCOMMAND]

OPTIONS:
    -c, --config <CONFIG>      Path of the vSMTP configuration file ("vsl" format)
    -h, --help                 Print help information
    -n, --no-daemon            Do not run the program as a daemon
    -t, --timeout <TIMEOUT>    Make the server stop after a delay (human readable format)
    -V, --version              Print version information

SUBCOMMANDS:
    config-diff    Show the difference between the loaded config and the default one
    config-show    Show the loaded config (as serialized json format)
    help           Print this message or the help of the given subcommand(s)

Configuring the Operating System for vSMTP

Create the directories and change the owner and group.

mkdir /etc/vsmtp /etc/vsmtp/rules /etc/vsmtp/certs /var/log/vsmtp /var/spool/vsmtp
cp ./target/release/vsmtp /usr/sbin/
cp ./target/release/vqueue /usr/sbin/
cp ./examples/config/minimal.vsl /etc/vsmtp/vsmtp.vsl
chown -R vsmtp:vsmtp /var/log/vsmtp /etc/vsmtp/* /var/spool/vsmtp

Create a minimal vsmtp.vsl configuration file that matches vsmtp version (i.e. 1.0.0)

cat > /etc/vsmtp/vsmtp.vsl <<EOF
import "conf.d/config.vsl" as cfg;
let config = cfg::config;
config.version_requirement = ">=1.0.0";
EOF

Grant rights to files and folders.

chmod 555 /usr/sbin/vsmtp
sudo chown -R vsmtp:vsmtp /var/log/vsmtp /etc/vsmtp/* /var/spool/vsmtp

If required, add private key and certificate to /etc/vsmtp/certs and grant reading rights to the vsmtp user.

Disabling sendmail

Sendmail may have been disabled during FreeBSD installation. If not, add the following lines in the /etc/rc.conf file and reboot the system.

sendmail_enable="NO"
sendmail_submit_enable="NO"
sendmail_outbound_enable="NO"
sendmail_msp_queue_enable="NO"

Use sockstat command to check that sendmail is disabled.

Add vSMTP user:group

pw groupadd vsmtp -g 999
pw useradd vsmtp -u 999 -d /noexistent -g vsmtp -s /sbin/nologin
chown -R vsmtp:vsmtp /var/log/vsmtp /etc/vsmtp/* /var/spool/vsmtp

Adding a vSMTP as a system service

vSMTP drops privileges at startup. User ACLs are no longer needed.

Please add:

• the flag `vsmtp_enable=“YES” in /etc/rc.conf.
• the vsmtp script in /usr/local/etc/rc.d

cp ./tools/install/freebsd/freebsd-vsmtp.service /usr/local/etc/rc.d/vsmtp

#! /bin/sh

# PROVIDE: vsmtp
# REQUIRE: DAEMON
# KEYWORD: shutdown

#
# Add the following lines to /etc/rc.conf to enable vsmtp:
#
# vsmtp_enable="YES"

. /etc/rc.subr

name="vsmtp"
rcvar="${name}_enable"

load_rc_config $name

: ${vsmtp_enable:=NO}
: ${vsmtp_config:=/etc/vsmtp/vsmtp.vsl}
: ${vsmtp_flags:=--config}

command="/usr/sbin/vsmtp"
command_args="${vsmtp_config}"

run_rc_command "$1"

Starting with a non privileged user

To start with an other mechanism please follow these instructions:

• Grant the rights to the user to bind on ports <1024.
• kernel must be updated to support network ACL.
• Add to these options to the KERNEL file and rebuild it.

options MAC
options MAC_PORTACL

cd /usr/src
make buildkernel KERNCONF=MYKERNEL
make installkernel KERNCONF=MYKERNEL

$ sysctl security.mac
security.mac.portacl.rules:
security.mac.portacl.port_high: 1023
security.mac.portacl.autoport_exempt: 1
security.mac.portacl.suser_exempt: 1
security.mac.portacl.enabled: 1
security.mac.mmap_revocation_via_cow: 0
security.mac.mmap_revocation: 1
security.mac.labeled: 0
security.mac.max_slots: 4
security.mac.version: 4

$ sysctl security.mac.portacl.rules=uid:999:tcp:25,uid:999:tcp:587,uid:999:tcp:465
security.mac.portacl.rules: uid:999:tcp:25, -> uid:999:tcp:25,uid:999:tcp:587,uid:999:tcp:465
$ sysctl security.mac.portacl.rules
security.mac.portacl.rules: uid:999:tcp:25,uid:999:tcp:587,uid:999:tcp:465
$ sysctl net.inet.ip.portrange.reservedlow=0
net.inet.ip.portrange.reservedlow: 0 -> 0
$ sysctl net.inet.ip.portrange.reservedhigh=0
net.inet.ip.portrange.reservedhigh: 1023 -> 0

The user with uid 999 should now be authorized to bind on standard SMTP ports (25, 587, 465).

Queue System

Queues are active in postq & delivery stages.

How messages are transferred between queues at the end of a SMTP stage

Create plugins

🚧 This chapter is still incomplete.

vSMTP plugins are Rust crates compiled as dynamic libraries that extends vSMTP base features.

They can be imported directly in filtering scripts.

Requirements

• First, make sure that Rust and Cargo are installed on the system.
• The Rust community as created a cargo command called Cargo generate which is used to fetch Rust project templates from Github. Make sure to install it too.
• Rhai imports a crate called ahash to hash types and function signatures to look them up at runtime. Therefore, plugin functions signatures must be hashed with the exact same seed than the core of vSMTP, so that Rhai can call the right functions. See the rhai-dylib crate for more details.

Get the plugin template

A Rhai dylib template is available to easily create plugins.

cargo generate --git https://github.com/ltabis/rhai-dylib-template.git

🤷   Project Name : vsmtp-plugin-awesome
🔧   Destination: /path/vsmtp-plugin-awesome ...
🔧   Generating template ...
🤷   What is the ahash key of program that will load this module ? [default: [1, 2, 3, 4]]: [1, 2, 3, 4]
[1/7]   Done: .cargo/config.toml
[2/7]   Skipped: .cargo
[3/7]   Done: .gitignore
[4/7]   Done: Cargo.toml
[5/7]   Done: README.md
[6/7]   Done: src/lib.rs
[7/7]   Skipped: src
🔧   Moving generated files into: `/path/vsmtp-plugin-awesome`...
💡   Initializing a fresh Git repository
✨   Done! New project created /path/vsmtp-plugin-awesome

cargo generate will prompt for a project name (It is recommended to use the vsmtp-plugin-* nomenclature to name vSMTP plugins) and a ahash seed. (To get more detail on what are ahash seeds and what they are used for, check out the rhai-dylib crate)

Overview

#![allow(unused)]
fn main() {
use rhai::plugin::*;

#[export_module]
mod vsmtp_plugin_awesome {
    // Build the module here.
}

/// Export the vsmtp_plugin_awesome module.
#[no_mangle]
pub extern "C" fn module_entrypoint() -> rhai::Shared<rhai::Module> {
    // The seed must be the same as the one used in the program that will
    // load this module.
    rhai::config::hashing::set_ahash_seed(Some([1, 2, 3, 4])).unwrap();

    rhai::exported_module!(vsmtp_plugin_awesome).into()
}
}

Generated Rust code using `cargo generate`, in vsmtp-plugin-awesome/src/lib.rs

cargo generate created a basic Rust project called vsmtp-plugin-awesome. It contains a module_entrypoint function that returns a Rhai module. Once this plugin is imported in vSMTP via the Rhai import statement, the module_entrypoint function is called and the returned Rhai module is used to extend .vsl scripts.

The module_entrypoint function must be present in the crate, otherwise vSMTP will not run the plugin.

[package]
name = "vsmtp_plugin_awesome"
version = "0.1.0"
edition = "2021"
authors = ["user <user@example.com>"]

[lib]
crate-type = ["cdylib"]

[dependencies]
rhai = { version = "1.11" }

Generated Cargo.toml file

Has specified in the manifest file generated for the project, the configured crate type is cdylib.

crate-type = ["cdylib"]

With this option, the crate can be compiled into a dynamic library, and vSMTP can access the plugin via the module_entrypoint function at runtime.

Acknowledgements

The development of vSMTP is made possible thanks to the following projects:

• Rust: the programming language used to develop vSMTP.
• tokio: the asynchronous runtime and the logging framework.
• rhai: the scripting language used in vSMTP.
• trust-dns: the DNS resolver.
• rustls: the TLS library.
• serde: the serialization framework used in vSMTP.
• rsasl: the SASL framework.

And the contributors who helped to improve vSMTP.