1.\" $OpenBSD: table.5,v 1.5 2015/11/30 17:03:05 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: November 30 2015 $ 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: 45.Bd -literal -offset indent 46value1 47value2 48value3 49.Ed 50.Pp 51A mapping will be written with each key and value on a line, 52whitespaces separating both columns: 53.Bd -literal -offset indent 54key1 value1 55key2 value2 56key3 value3 57.Ed 58.Pp 59A file table can be converted to a Berkeley database using the 60.Xr makemap 8 61utility with no syntax change. 62.Pp 63Tables using a 64.Ql file 65or Berkeley DB backend will be referenced as follows: 66.Bd -literal -offset indent 67table name file:/path/to/file 68table name db:/path/to/file.db 69.Ed 70.Ss Aliasing tables 71Aliasing tables are mappings that associate a recipient to one or many 72destinations. 73They can be used in two contexts: primary domain aliases and virtual domain 74mapping. 75.Bd -literal -offset indent 76accept for domain example.org alias <myaliases> deliver to mbox 77accept for domain example.org virtual <myaliases> deliver to mbox 78.Ed 79.Pp 80In a primary domain context, the key is the user part of the recipient address, 81whilst the value is one or many recipients as described in 82.Xr aliases 5 : 83.Bd -literal -offset indent 84user1 otheruser 85user2 otheruser1,otheruser2 86user3 otheruser@example.com 87.Ed 88.Pp 89In a virtual domain context, the key is either a user part, a full email 90address or a catch all, following selection rules described in 91.Xr smtpd.conf 5 , 92and the value is one or many recipients as described in 93.Xr aliases 5 : 94.Bd -literal -offset indent 95user1 otheruser 96user2@example.org otheruser1,otheruser2 97@example.org otheruser@example.com 98@ catchall@example.com 99.Ed 100.Ss Domain tables 101Domain tables are simple lists of domains. 102They can only be used in one context: 103.Bd -literal -offset indent 104accept for domain <mydomains> deliver to mbox 105.Ed 106.Pp 107In that context, the list of domains will be matched against the recipient 108domain. 109For 110.Ql static , 111.Ql file 112and 113.Xr dbopen 3 114backends, a wildcard may be used so the domain table may contain: 115.Bd -literal -offset indent 116example.org 117*.example.org 118.Ed 119.Ss Credentials tables 120Credentials tables are mappings of credentials. 121They can be used in two contexts: 122.Bd -literal -offset indent 123listen on tls [...] auth <credentials> 124accept for any relay tls+auth://label@host auth <credentials> 125.Ed 126.Pp 127In a listener context, the credentials are a mapping of username and encrypted 128passwords: 129.Bd -literal -offset indent 130user1 $2a$06$hIJ4QfMcp.90nJwKqGbKM.MybArjHOTpEtoTV.DgLYAiThuoYmTSe 131user2 $2a$06$bwSmUOBGcZGamIfRuXGTvuTo3VLbPG9k5yeKNMBtULBhksV5KdGsK 132.Ed 133.Pp 134The passwords are to be encrypted using the 135.Xr smtpctl 8 136encrypt subcommand. 137.Pp 138In a relay context, the credentials are a mapping of labels and 139username:password pairs, 140where the username may be omitted if identical to the label: 141.Bd -literal -offset indent 142label1 user:password 143label2 password 144.Ed 145.Pp 146The label must be unique and is used as a selector for the proper credentials 147when multiple credentials are valid for a single destination. 148The password is not encrypted as it must be provided to the remote host. 149.Ss Netaddr tables 150Netaddr tables are lists of IPv4 and IPv6 network addresses. 151They can only be used in the following context: 152.Bd -literal -offset indent 153accept from source <netaddr> for domain example.org deliver to mbox 154.Ed 155.Pp 156When used as a "from source", the address of a client is compared to the list 157of addresses in the table until a match is found. 158.Pp 159A netaddr table can contain exact addresses or netmasks, and looks as follow: 160.Bd -literal -offset indent 161192.168.1.1 162::1 163ipv6:::1 164192.168.1.0/24 165.Ed 166.Ss Userinfo tables 167User info tables are used to described virtual system users. 168They are used in rule context to specify an alternate user base, mapping 169virtual users to local system UID, GID and home directory. 170.Bd -literal -offset indent 171accept for domain example.org userbase <userinfo> deliver to maildir 172.Ed 173.Pp 174The userinfo table is a mapping from virtual user names to a set of system user 175ID, group ID and path to home directory. 176.Pp 177A userinfo table looks as follows: 178.Bd -literal -offset indent 179joe 1000:100:/home/virtual/joe 180jack 1000:100:/home/virtual/jack 181.Ed 182.Pp 183In this example, both joe and jack are virtual users mapped to the local 184system user with UID 1000 and GID 100, but different home directories. 185These directories may contain a 186.Xr forward 5 187file. 188.Ss Source tables 189Source tables are lists of IPv4 and IPv6 addresses. 190They can only be used in the following context: 191.Bd -literal -offset indent 192accept for domain example.org relay source <addresses> 193.Ed 194.Pp 195Successive queries to the source table will return the elements one by one. 196.Pp 197A source table looks as follow: 198.Bd -literal -offset indent 199192.168.1.2 200192.168.1.3 201::1 202::2 203ipv6:::3 204ipv6:::4 205.Ed 206.Ss Mailaddr tables 207Mailaddr tables are lists of email addresses. 208They can be used in the following contexts: 209.Bd -literal -offset indent 210accept sender <senders> for domain example.org deliver to mbox 211accept for domain example.org recipient <recipients> deliver to mbox 212.Ed 213.Pp 214A mailaddr entry is used to match an email address against a username, 215a domain or a full email address. 216A "*" wildcard may be used in part of the domain name. 217.Pp 218A mailaddr table looks as follow: 219.Bd -literal -offset indent 220user 221@domain 222user@domain 223user@*.domain 224.Ed 225.Ss Addrname tables 226Addrname tables are used to map IP addresses to hostnames. 227They can be used in both listen context and relay context: 228.Bd -literal -offset indent 229listen on 0.0.0.0 hostnames <addrname> 230accept for any relay hostnames <addrname> 231.Ed 232.Pp 233In listen context, the table is used to look up the server name to advertise 234depending on the local address of the socket on which a connection is accepted. 235In relay context, the table is used to determine the hostname for the HELO 236sequence of the SMTP protocol, depending on the local address used for the 237outgoing connection. 238.Pp 239The format is a mapping from inet4 or inet6 addresses to hostnames: 240.Bd -literal -offset indent 241::1 localhost 242127.0.0.1 localhost 24388.190.23.165 www.opensmtpd.org 244.Ed 245.Sh SEE ALSO 246.Xr smtpd.conf 5 , 247.Xr makemap 8 , 248.Xr smtpd 8 249