1.\" $OpenBSD: table.5,v 1.12 2021/02/13 08:05:57 jmc Exp $ 2.\" 3.\" Copyright (c) 2013 Eric Faurot <eric@openbsd.org> 4.\" Copyright (c) 2013 Gilles Chehade <gilles@poolp.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.\" 19.Dd $Mdocdate: February 13 2021 $ 20.Dt TABLE 5 21.Os 22.Sh NAME 23.Nm table 24.Nd format description for smtpd tables 25.Sh DESCRIPTION 26This manual page documents the file format for the various tables used in the 27.Xr smtpd 8 28mail daemon. 29.Pp 30The format described here applies to tables as defined in 31.Xr smtpd.conf 5 . 32.Sh TABLE TYPES 33There are two types of tables: lists and mappings. 34A list consists of a series of values, 35while a mapping consists of a series of keys and their associated values. 36The following illustrates how to declare them as static tables: 37.Bd -literal -offset indent 38table mylist { value1, value2, value3 } 39table mymapping { key1 = value1, key2 = value2, key3 = value3 } 40.Ed 41.Pp 42When using a 43.Ql file 44table, a list will be written with each value on a line by itself. 45Comments can be put anywhere in the file using a hash mark 46.Pq Sq # , 47and extend to the end of the current line. 48.Bd -literal -offset indent 49value1 50value2 51value3 52.Ed 53.Pp 54A mapping will be written with each key and value on a line, 55whitespaces separating both columns: 56.Bd -literal -offset indent 57key1 value1 58key2 value2 59key3 value3 60.Ed 61.Pp 62A file table can be converted to a Berkeley database using the 63.Xr makemap 8 64utility with no syntax change. 65.Pp 66Tables using a 67.Ql file 68or Berkeley DB backend will be referenced as follows: 69.Bd -unfilled -offset indent 70.Ic table Ar name Cm file : Ns Pa /path/to/file 71.Ic table Ar name Cm db : Ns Pa /path/to/file.db 72.Ed 73.Ss Aliasing tables 74Aliasing tables are mappings that associate a recipient to one or many 75destinations. 76They can be used in two contexts: primary domain aliases and virtual domain 77mapping. 78.Bd -unfilled -offset indent 79.Ic action Ar name method Cm alias Pf < table Ns > 80.Ic action Ar name method Cm virtual Pf < table Ns > 81.Ed 82.Pp 83In a primary domain context, the key is the user part of the recipient address, 84whilst the value is one or many recipients as described in 85.Xr aliases 5 : 86.Bd -literal -offset indent 87user1 otheruser 88user2 otheruser1,otheruser2 89user3 otheruser@example.com 90.Ed 91.Pp 92In a virtual domain context, the key is either a user part, a full email 93address or a catch-all, following selection rules described in 94.Xr smtpd.conf 5 , 95and the value is one or many recipients as described in 96.Xr aliases 5 : 97.Bd -literal -offset indent 98user1 otheruser 99user2@example.org otheruser1,otheruser2 100@example.org otheruser@example.com 101@ catchall@example.com 102.Ed 103.Pp 104The following directive shares the same table format, 105but with a different meaning. 106Here, the user is allowed to send mail from the listed addresses: 107.Bd -unfilled -offset indent 108.Ic listen on Ar interface Cm auth Oo Ar ... Oc Cm senders Pf < Ar table Ns > 109.Ed 110.Ss Domain tables 111Domain tables are simple lists of domains or hosts. 112.Bd -unfilled -offset indent 113.Ic match Cm for domain Pf < table Ns > Cm action Ar name 114.Ic match Cm helo Pf < table Ns > Oo Ar ... Oc Cm action Ar name 115.Ed 116.Pp 117In that context, the list of domains will be matched against the recipient 118domain or against the HELO name advertised by the sending host, 119respectively. 120For 121.Ql static , 122.Ql file 123and 124.Xr dbopen 3 125backends, a wildcard may be used so the domain table may contain: 126.Bd -literal -offset indent 127example.org 128*.example.org 129.Ed 130.Ss Credentials tables 131Credentials tables are mappings of credentials. 132They can be used in two contexts: 133.Bd -unfilled -offset indent 134.Ic listen on Ar interface Cm tls Oo Ar ... Oc Cm auth Pf < Ar table Ns > 135.Ic action Ar name Cm relay host Ar relay-url Cm auth Pf < Ar table Ns > 136.Ed 137.Pp 138In a listener context, the credentials are a mapping of username and encrypted 139passwords: 140.Bd -literal -offset indent 141user1 $2b$10$hIJ4QfMcp.90nJwKqGbKM.MybArjHOTpEtoTV.DgLYAiThuoYmTSe 142user2 $2b$10$bwSmUOBGcZGamIfRuXGTvuTo3VLbPG9k5yeKNMBtULBhksV5KdGsK 143.Ed 144.Pp 145The passwords are to be encrypted using the 146.Xr smtpctl 8 147encrypt subcommand. 148.Pp 149In a relay context, the credentials are a mapping of labels and 150username:password pairs: 151.Bd -literal -offset indent 152label1 user:password 153.Ed 154.Pp 155The label must be unique and is used as a selector for the proper credentials 156when multiple credentials are valid for a single destination. 157The password is not encrypted as it must be provided to the remote host. 158.Ss Netaddr tables 159Netaddr tables are lists of IPv4 and IPv6 network addresses. 160They can only be used in the following context: 161.Pp 162.D1 Ic match Cm from src Pf < Ar table Ns > Cm action Ar name 163.Pp 164When used as a "from source", the address of a client is compared to the list 165of addresses in the table until a match is found. 166.Pp 167A netaddr table can contain exact addresses or netmasks, and looks as follow: 168.Bd -literal -offset indent 169192.168.1.1 170::1 171ipv6:::1 172192.168.1.0/24 173.Ed 174.Ss Userinfo tables 175Userinfo tables are used in rule context to specify an alternate userbase, 176mapping virtual users to local system users by UID, GID and home directory. 177.Pp 178.D1 Ic action Ar name method Cm userbase Pf < Ar table Ns > 179.Pp 180A userinfo table looks as follows: 181.Bd -literal -offset indent 182joe 1000:100:/home/virtual/joe 183jack 1000:100:/home/virtual/jack 184.Ed 185.Pp 186In this example, both joe and jack are virtual users mapped to the local 187system user with UID 1000 and GID 100, but different home directories. 188These directories may contain a 189.Xr forward 5 190file. 191This can be used in conjunction with an alias table 192that maps an email address or the domain part to the desired virtual 193username. 194For example: 195.Bd -literal -offset indent 196joe@example.org joe 197jack@example.com jack 198.Ed 199.Ss Source tables 200Source tables are lists of IPv4 and IPv6 addresses. 201They can only be used in the following context: 202.Pp 203.D1 Ic action Ar name Cm relay src Pf < Ar table Ns > 204.Pp 205Successive queries to the source table will return the elements one by one. 206.Pp 207A source table looks as follow: 208.Bd -literal -offset indent 209192.168.1.2 210192.168.1.3 211::1 212::2 213ipv6:::3 214ipv6:::4 215.Ed 216.Ss Mailaddr tables 217Mailaddr tables are lists of email addresses. 218They can be used in the following contexts: 219.Bd -unfilled -offset indent 220.Ic match Cm mail\-from Pf < Ar table Ns > Cm action Ar name 221.Ic match Cm rcpt\-to Pf < Ar table Ns > Cm action Ar name 222.Ed 223.Pp 224A mailaddr entry is used to match an email address against a username, 225a domain or a full email address. 226A "*" wildcard may be used in part of the domain name. 227.Pp 228A mailaddr table looks as follow: 229.Bd -literal -offset indent 230user 231@domain 232user@domain 233user@*.domain 234.Ed 235.Ss Addrname tables 236Addrname tables are used to map IP addresses to hostnames. 237They can be used in both listen context and relay context: 238.Bd -unfilled -offset indent 239.Ic listen on Ar interface Cm hostnames Pf < Ar table Ns > 240.Ic action Ar name Cm relay helo\-src Pf < Ar table Ns > 241.Ed 242.Pp 243In listen context, the table is used to look up the server name to advertise 244depending on the local address of the socket on which a connection is accepted. 245In relay context, the table is used to determine the hostname for the HELO 246sequence of the SMTP protocol, depending on the local address used for the 247outgoing connection. 248.Pp 249The format is a mapping from inet4 or inet6 addresses to hostnames: 250.Bd -literal -offset indent 251::1 localhost 252127.0.0.1 localhost 25388.190.23.165 www.opensmtpd.org 254.Ed 255.Sh SEE ALSO 256.Xr smtpd.conf 5 , 257.Xr makemap 8 , 258.Xr smtpd 8 259