Configuration

Configuration of PyMail is read from a file specified by the -c switch on the command line or from /etc/pymail if none is specified. The file is formatted in YAML. You only need to understand a couple of rules of this format:

• A comment can be inserted by prepending it with a hash sign. The rest of the line after the hash sign is comment
• A configuration entry consist of a key, a colon sign, a space and a value. The value has an implicit type:
  • boolean (truth value): true or false (can be uppercase: True or False)
  • integer: 0, 1, 2, ...
  • floating point: 0.1, 1.2, ...
  • string: xyzzy, spam, ... if a string value is desired, but would be misinterpreted, like an integer, it must be enclosed in quotes, like “33”
• A configuration entry can have more than one value. These values are specified with a prefix of a dash and a space and are written on their own line.
• Sections and subsections are denoted by a key, a colon sign followed by a number of indented lines

There are four sections in a configuration file:

• a ‘global section’ containing information for the server as a whole and default configuration entries for subsections
• a servers section with entries about connection interfaces (listening address, port) and TLS mode
• an authorisation section with information about users
• a destination section with information about where to route mail to

Let’s explain how to write a configuration file according to the following complete example:

description: Local Mail
address: local
domain: local
spoolfile: /var/spool/pymail
user: mail
group: mail
retries:
- 4*30
- 22*1h
- 4*1d
# A global tls section is valid for all servers but they can overwrite it
tls:
    enabled: True
    starttls: True
    key: mailkey.pem
    certificate: mailcert.pem
servers:
    smtp:
        interface: 0.0.0.0
        port: 25
        description: Plain Old SMTP
        # use global tls section
    smtps:
        interface: 0.0.0.0
        port: 465
        description: Old Secure SMTP
        address: mymail.org
        # overwrite global tls section - specifically disable STARTTLS feature
        # meaning to use TLS from the very beginning
        tls:
            enabled: True
            starttls: False
            key: mailkey.pem
            certificate: mailcert.pem
authorisation:
    users:
        john: password
        jack: jackpot
destinations:
    internet:
        # no priority means highest number = lowest priority
        # no domain means everything
        type: smtp
    local:
        priority: 1
        domain: local
        type: maildir
        directory: /home/{user}/.maildir

Global Section

Line 1 to 16 is the global section, with line 12 to 16 being a subsection named tls. The entries in the global section are:

description

a default description of the mail service, appearing in the greeting line (with 220 prefix). This is optional since it is not very interesting. This is only seen when analysing the SMTP protocol. Normal users never see this.

address

the official address (a fully qualified domain name) where this service is reachable. It can be overridden in a servers section entry. This entry is mandatory.

domain

the domain appended to a mail address without a domain. This should be the same as the domain where local mail is delivered, since a mail address without a domain can only mean a local address.

spoolfile

a file where mail jobs are stored until they are picked up by the delivery mechanism. Files like these are preferrably put in directory /var

user

on POSIX systems (Unix, Linux, etc) it’s good practice to change the user and group for security reasons. Here is the username to change to. The default is mail

group

the group name to change to. The default is mail

retries

a plan for retransmission of mail if a transmission failed. Each list entry specifies an optional repetition count followed by an asterisk and a time frame. If no count is given, 1 is assumed. The time frame has an optional single-letter suffix which denotes the time unit. If no suffix is given, m (minutes) is assumed.

Valid time units are:

• s for seconds
• m for minutes (default)
• h for hours
• d for days
• w for weeks
• M for months (30 days)
• y for years (365 days)

The plan starts immediately and the first ordinary try counts as a “retry”. The tries are therefore to be seen as before the wait time, not after it as one would assume. A plan of 2*1h thus means: make first try and retry once after one hour. You could read it as: “make two tries with a pause of one hour in between”.

tls

a subsection with the default TLS mode for server section not providing one. This section consists of the following entries:

enabled

whether TLS is enabled or not

starttls

whether STARTTLS is used. If false, TLS is used from the start

key

the path of a file containing the encryption key in PEM format

certificate

the path of a file containing the certificate for the encryption key in PEM format

Servers Section

In the servers section, one or more service interfaces can be specified, as shown in lines 17 to 34 in the example. Each service interface is defined as a subsection with an arbitrary name. Each such subsection is comprised of the following entries:

interface

the IP address (associated with a network interface) to listen on. To listen on all interfaces, use 0.0.0.0. This is also the default.

port

port to listen on

address

officially advertised address (fully qualified domain name) where this service is reachable. It should be specified here or in the global section. A global default will be overriden if provided here.

description

a text which will appear in the SMTP protocol greeting line (220 prefix). Can by defaulted by an entry in the global section. If given in a servers section, it will override a global default.

tls subsection

an optional subsection specifying the TLS mode to use. If not given, the default in the global section is used. A tls subsection provided in a servers section overrides a global definition. For a description of the configuration entries in this subsection see the Global Section.

Authorization Section

This section defines users and authentication credentials for local mailboxes and authorisation of mail transfer. Entries in this section consist of subsections with predefined names denoting the type of the subsection. A sample section is in lines 35 to 38 in the example. Currently the following types are defined:

user

a key/value list of users and their passwords. These are user definitions for quick testing purposes. Since the passwords are not encrypted, anyone with access to the configuration file can see the passwords. Use of this user definition scheme is therefore strongly discouraged.

Destinations Section

For every path to deliver mail to there is a subsection in the destinations section. When a mail is about to be delivered the spooler (the facility within PyMail to take care of mail delivery) scans all these subsections in the order specified by their priority entry for a match of the email’s destination domain with the subsection’s domain entry. If a match is found the mail is delivered according to the specifications in that subsection. If a subsection does not have a domain entry, everywhere is substituted, meaning it will always match. The value in the domain entry can be a regular expression. Omitting the domain entry is equal to specifying ”.*”, as seen in the example. It is important to understand that when omitting the domain entry (or specifying ”.*”) the subsection should have the lowest priority (denoted by a very high priority value), or else it will eclipse all subsections with a lower priority. To assign the lowest possible priority the section’s priority entry can be omitted, like in the example. The following types of destinations are currenty available:

smtp

the mail will be delivered via SMTP according to the rules specified in RFC 5321.

maildir

the mail will be delivered to a local MailDir mailbox. For this, an additional entry, directory is required which specifies the path to the MailDir directory where the mail is to be stored. In this path, a substitution can be made in the form {user}. PyMail will fill in the username for this construct. MailDir support will be provided in version 0.2 or later.