1.\" $OpenBSD: smtpd-tables.7,v 1.4 2024/06/09 10:13:05 gilles Exp $ 2.\" 3.\" Copyright (c) 2008 Janne Johansson <jj@openbsd.org> 4.\" Copyright (c) 2009 Jacek Masiulaniec <jacekm@dobremiasto.net> 5.\" Copyright (c) 2012 Gilles Chehade <gilles@poolp.org> 6.\" Copyright (c) 2024 Omar Polo <op@openbsd.org> 7.\" 8.\" Permission to use, copy, modify, and distribute this software for any 9.\" purpose with or without fee is hereby granted, provided that the above 10.\" copyright notice and this permission notice appear in all copies. 11.\" 12.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 13.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 14.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 15.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 16.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 17.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 18.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 19.\" 20.\" 21.Dd $Mdocdate: June 9 2024 $ 22.Dt SMTPD-TABLES 7 23.Os 24.Sh NAME 25.Nm smtpd-tables 26.Nd table API for the smtpd daemon 27.Sh DESCRIPTION 28The 29.Xr smtpd 8 30daemon provides a Simple Mail Transfer Protocol (SMTPD) implementation, 31which allows ordinary machines to become Mail eXchangers (MX). 32Some features that are commonly used by MX, 33such as querying databases for user credentials, 34are outside of the scope of SMTP and too complex to fit in 35.Xr smtpd 8 . 36.Pp 37Because an MX may need to provide these features, 38.Xr smtpd 8 39provides an API to implement 40.Xr table 5 41backends with a simple text-based protocol. 42.Sh DESIGN 43.Nm 44are programs that run as unique standalone processes, 45they do not share 46.Xr smtpd 8 47address space. 48They are executed by 49.Xr smtpd 8 50at startup and expected to run in an infinite loop, 51reading events and queries from standard input and 52writing responses to standard output. 53They are not allowed to terminate. 54.Pp 55Because 56.Nm 57are standalone programs that communicate with 58.Xr smtpd 8 , 59they may run as different users than 60.Xr smtpd 8 61and may be written in any language. 62.Nm 63must not use blocking I/O, 64they must support answering asynchronously to 65.Xr smtpd 8 . 66.Sh PROTOCOL 67The protocol consist of human-readable lines exchanged between 68.Nm 69and 70.Xr smtpd 8 . 71.Pp 72The protocol begins with a handshake. 73First, 74.Xr smtpd 8 75provides 76.Nm 77with general configuration information in the form of 78key-value lines, terminated by 79.Ql config|ready . 80For example: 81.Bd -literal -offset indent 82config|smtpd-version|7.5.0 83config|protocol|0.1 84config|tablename|devs 85config|ready 86.Ed 87.Pp 88Then, 89.Nm 90register the supported services, terminating with 91.Ql register|ready . 92For example: 93.Bd -literal -offset indent 94register|alias 95register|credentials 96register|ready 97.Ed 98.Pp 99Finally, 100.Xr smtpd 8 101can start querying the table. 102For example: 103.Bd -literal -offset indent 104table|0.1|1713795082.354255|devs|lookup|alias|b72508d|op 105.Ed 106.Pp 107The 108.Dq | 109character is used to separate the fields and may only appear 110verbatim in the last field of the payload, in which case it 111should be considered a regular character and not a separator. 112No other field may contain a 113.Dq | . 114.Pp 115Each request has a common set of fields, followed by some 116other fields that are operation-specific. 117The common format consists of a protocol prefix 118.Sq table , 119the protocol version, the timestamp and the table name. 120For example: 121.Bd -literal -offset indent 122table|0.1|1713795091.202157|devs 123.Ed 124.Pp 125The protocol is inherently asynchronous, so multiple request 126may be sent without waiting for the table to reply. 127All the replies have a common prefix, followed by the 128operation-specific response. 129The common format consist of a prefix with the operation name 130in followed by 131.Sq -result , 132and the unique ID of the request. 133For example: 134.Bd -literal -offset indent 135lookup-result|b72508d 136.Ed 137.Pp 138The list of operations, operation-specific parameters and 139responses are as follows: 140.Bl -tag -width Ds 141.It Cm update Ar id 142Ask the table to reload its configuration. 143The result is either 144.Sq ok 145on success or 146.Sq error 147and a message upon a failure to do so. 148.It Cm check Ar service id query 149Check whether 150.Ar query 151is present in the table. 152The result is 153.Sq found 154if found, 155.Sq not-found 156if not, or 157.Sq error 158and a message upon an error. 159.It Cm lookup Ar service id query 160Look up a value in the table for given the 161.Ar query . 162The result is 163.Sq found 164and the value if found, 165.Sq not-found 166if not found, or 167.Sq error 168and a message upon an error. 169.It Cm fetch Ar service id 170Fetch the next item from the table, eventually wrapping around. 171It is only supported for the 172.Ic source 173and 174.Ic relayhost 175services. 176The result is 177.Sq found 178and the value if found, 179.Sq not-found 180if the table is empty, or 181.Sq error 182and a message upon an error. 183.El 184.Pp 185Each service has a specific format for the result. 186The exact syntax for the values and eventually the keys are 187described in 188.Xr table 5 . 189The services and their result format are as follows: 190.Pp 191.Bl -tag -width mailaddrmap -compact 192.It Ic alias 193One or more aliases separated by a comma. 194.It Ic auth 195Only usable for check. 196Lookup key is username and cleartext password separated by 197.Sq \&: . 198.It Ic domain 199A domain name. 200.\" XXX are wildcards allowed? 201.It Ic credentials 202The user name, followed by 203.Sq \&: 204and the encrypted password as per 205.Xr smtpctl 8 206.Cm encrypt 207subcommand. 208.It Ic netaddr 209IPv4 and IPv6 address or netmask. 210.It Ic userinfo 211The user id, followed by 212.Sq \&: 213then the group id, then 214.Sq \&: 215and finally the home directory. 216.It Ic source 217IPv4 and IPv6 address. 218.It Ic mailaddr 219An username, a domain or a full email address. 220.It Ic addrname 221Used to map IP addresses to hostnames. 222.\" .It Ic mailaddrmap 223.\" XXX missing K_RELAYHOST, K_STRING and K_REGEX 224.El 225.Sh EXAMPLES 226Assuming the table is called 227.Dq devs , 228here's an example of a failed 229.Cm update 230transaction: 231.Bd -literal -offset indent 232table|0.1|1713795097.394049|devs|update|478ff0d2 233update-result|478ff0d2|error|failed to connect to the database 234.Ed 235.Pp 236A 237.Cm check 238request for the 239.Ic netaddr 240service for the 192.168.0.7 IPv4 address which is 241not in the table: 242.Bd -literal -offset indent 243table|0.1|1713795103.314423|devs|check|netaddr|e5862859|192.168.0.7 244check-result|e5862859|not-found 245.Ed 246.Pp 247A successful 248.Cm lookup 249request for the 250.Ic userinfo 251service for the user 252.Sq op : 253.Bd -literal -offset indent 254table|0.1|1713795110.354921|devs|lookup|userinfo|f993c74|op 255lookup-result|f993c74|found|1000:1000:/home/op 256.Ed 257.Pp 258A series of 259.Cm fetch 260requests for the 261.Cm source 262service that wraps around: 263.Bd -literal -offset indent 264table|0.1|1713795116.227321|devs|fetch|source|189bd3ee 265lookup-result|189bd3ee|found|192.168.1.7 266table|0.1|1713795120.162438|devs|fetch|source|9e4c56d4 267lookup-result|9e4c56d4|found|10.0.0.8 268table|0.1|1713795122.930928|devs|fetch|source|f2c8b906 269lookup-result|f2c8b906|found|192.168.1.7 270.Ed 271.Sh SEE ALSO 272.Xr smtpd 8 273.Sh HISTORY 274.Nm 275first appeared in 276.Ox 7.6 . 277