# table

## NAME



           **table** — format description for smtpd tables
    


## DESCRIPTION



           This manual page documents the file format for the various tables
           used in the _smtpd_(8) mail daemon.
    
           The format described here applies to tables as defined in
           _smtpd.conf_(5).
    


## TABLE TYPES



           There are two types of tables: lists and mappings.  A list
           consists of a series of values, while a mapping consists of a
           series of keys and their associated values.  The following
           illustrates how to declare them as static tables:
    
                 table mylist { value1, value2, value3 }
                 table mymapping { key1 = value1, key2 = value2, key3 = value3 }
    
           When using a ‘file’ table, a list will be written with each value
           on a line by itself.
    
                 value1
                 value2
                 value3
    
           A mapping will be written with each key and value on a line,
           whitespace and an optional colon separating both columns:
    
                 key1:   value1
                 key2    value2
                 key3    value3
    
           Blank lines, leading and trailing spaces and tabs are ignored.
           Lines whose first non-space character is a hash mark (‘#’) are
           comments and are ignored.  To force the parsing of a file table as
           a list rather than a mapping, use this special comment:
    
                 **# @list**
    
           A file table can be converted to a Berkeley database using the
           _makemap_(8) utility with no syntax change.
    
           Tables using a ‘file’ or Berkeley DB backend will be referenced as
           follows:
    
                 **table** _name_ **file** :_/path/to/file_
                 **table** _name_ **db** :_/path/to/file.db_
    
       **Aliasing tables**
           Aliasing tables are mappings that associate a recipient to one or
           many destinations.  They can be used in two contexts: primary
           domain aliases and virtual domain mapping.
    
                 **action** _name method_ **alias** <table>
                 **action** _name method_ **virtual** <table>
    
           In a primary domain context, the key is the user part of the
           recipient address, whilst the value is one or many recipients as
           described in _aliases_(5):
    
                 user1   otheruser
                 user2   otheruser1,otheruser2
                 user3   otheruser@example.com
    
           In a virtual domain context, the key is either a user part, a full
           email address or a catch-all, following selection rules described
           in _smtpd.conf_(5), and the value is one or many recipients as
           described in _aliases_(5):
    
                 user1                   otheruser
                 user2@example.org       otheruser1,otheruser2
                 @example.org            otheruser@example.com
                 @                       catchall@example.com
    
           The following directive shares the same table format, but with a
           different meaning.  Here, the user is allowed to send mail from
           the listed addresses:
    
                 **listen on** _interface_ **auth**[_..._] **senders** <_table_ >
    
       **Domain tables**
           Domain tables are simple lists of domains or hosts.
    
                 **match for domain** <table> **action** _name_
                 **match helo** <table> [_..._] **action** _name_
    
           In that context, the list of domains will be matched against the
           recipient domain or against the HELO name advertised by the
           sending host, respectively.  For ‘static’, ‘file’ and _dbopen_(3)
           backends, a wildcard may be used so the domain table may contain:
    
                 example.org
                 *.example.org
    
       **Credentials tables**
           Credentials tables are mappings of credentials.  They can be used
           in two contexts:
    
                 **listen on** _interface_ **tls**[_..._] **auth** <_table_ >
                 **action** _name_ **relay host** _relay-url_ **auth** <_table_ >
    
           In a listener context, the credentials are a mapping of username
           and encrypted passwords:
    
                 user1   $2b$10$hIJ4QfMcp.90nJwKqGbKM.MybArjHOTpEtoTV.DgLYAiThuoYmTSe
                 user2   $2b$10$bwSmUOBGcZGamIfRuXGTvuTo3VLbPG9k5yeKNMBtULBhksV5KdGsK
    
           The passwords are to be encrypted using the _smtpctl_(8) encrypt
           subcommand.
    
           In a relay context, the credentials are a mapping of labels and
           username:password pairs:
    
                 label1  user:password
    
           The label must be unique and is used as a selector for the proper
           credentials when multiple credentials are valid for a single
           destination.  The password is not encrypted as it must be provided
           to the remote host.
    
       **Netaddr tables**
           Netaddr tables are lists of IPv4 and IPv6 network addresses.  They
           can only be used in the following context:
    
                 **match from src** <_table_ > **action** _name_
    
           When used as a "from source", the address of a client is compared
           to the list of addresses in the table until a match is found.
    
           A netaddr table can contain exact addresses or netmasks, and looks
           as follow:
    
                 192.168.1.1
                 [::1]
                 192.168.1.0/24
    
           IPv6 addresses must be enclosed in square brackets.
    
       **Userinfo tables**
           Userinfo tables are used in rule context to specify an alternate
           userbase, mapping virtual users to local system users by UID, GID
           and home directory.
    
                 **action** _name method_ **userbase** <_table_ >
    
           A userinfo table looks as follows:
    
                 joe     1000:100:/home/virtual/joe
                 jack    1000:100:/home/virtual/jack
    
           In this example, both joe and jack are virtual users mapped to the
           local system user with UID 1000 and GID 100, but different home
           directories.  These directories may contain a _forward_(5) file.
           This can be used in conjunction with an alias table that maps an
           email address or the domain part to the desired virtual username.
           For example:
    
                 joe@example.org     joe
                 jack@example.com    jack
    
       **Source tables**
           Source tables are lists of IPv4 and IPv6 addresses.  They can only
           be used in the following context:
    
                 **action** _name_ **relay src** <_table_ >
    
           Successive queries to the source table will return the elements
           one by one.
    
           A source table looks as follow:
    
                 192.168.1.2
                 192.168.1.3
                 [::1]
                 [::2]
    
           IPv6 address must be enclosed in square brackets.
    
       **Mailaddr tables**
           Mailaddr tables are lists of email addresses.  They can be used in
           the following contexts:
    
                 **match mail-from** <_table_ > **action** _name_
                 **match rcpt-to** <_table_ > **action** _name_
    
           A mailaddr entry is used to match an email address against a
           username, a domain or a full email address.  A "*" wildcard may be
           used in part of the domain name.
    
           A mailaddr table looks as follow:
    
                 user
                 @domain
                 user@domain
                 user@*.domain
    
       **Addrname tables**
           Addrname tables are used to map IP addresses to hostnames.  They
           can be used in both listen context and relay context:
    
                 **listen on** _interface_ **hostnames** <_table_ >
                 **action** _name_ **relay helo-src** <_table_ >
    
           In listen context, the table is used to look up the server name to
           advertise depending on the local address of the socket on which a
           connection is accepted.  In relay context, the table is used to
           determine the hostname for the HELO sequence of the SMTP protocol,
           depending on the local address used for the outgoing connection.
    
           The format is a mapping from inet4 or inet6 addresses to
           hostnames:
    
                 [::1]           localhost
                 127.0.0.1       localhost
                 88.190.23.165   www.opensmtpd.org
    
           IPv6 addresses must be enclosed in square brackets.
    


* * *