diff options
| -rw-r--r-- | smtpd/Makefile | 4 | ||||
| -rw-r--r-- | table.5 | 257 |
2 files changed, 259 insertions, 2 deletions
diff --git a/smtpd/Makefile b/smtpd/Makefile index 20813ce4..b43ab013 100644 --- a/smtpd/Makefile +++ b/smtpd/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.66 2013/08/06 19:05:57 miod Exp $ +# $OpenBSD: Makefile,v 1.67 2013/11/07 09:24:17 eric Exp $ .PATH: ${.CURDIR}/.. @@ -34,7 +34,7 @@ SRCS+= scheduler_null.c SRCS+= scheduler_proc.c SRCS+= stat_ramstat.c -MAN= smtpd.8 smtpd.conf.5 +MAN= smtpd.8 smtpd.conf.5 table.5 BINDIR= /usr/sbin LDADD+= -levent -lutil -lssl -lcrypto -lm -lz diff --git a/table.5 b/table.5 new file mode 100644 index 00000000..94f9cc9b --- /dev/null +++ b/table.5 @@ -0,0 +1,257 @@ +.\" $OpenBSD: table.5,v 1.1 2013/11/07 09:24:17 eric Exp $ +.\" +.\" Copyright (c) 2013 Eric Faurot <eric@openbsd.org> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" +.Dd $Mdocdate: November 7 2013 $ +.Dt TABLE 5 +.Os +.Sh NAME +.Nm table +.Nd format description for smtpd tables +.Sh DESCRIPTION +This manual page documents the file format for the various tables used in the +.Xr smtpd 8 +mail daemon. +.Pp +The format described here applies to tables as defined in +.Xr smtpd.conf 5 . +.Sh 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 seriesof keys and their associated values. +The following illustrates how to declare them as static tables: +.Bd -literal -offset indent +table mylist { value1, value2, value3 } +table mymapping { key1 = value1, key2 = value2, key3 = value3 } +.Ed +.Pp +When using a +.Ql file +table, a list will be written with each value on a line by itself: +.Bd -literal -offset indent +value1 +value2 +value3 +.Ed +.Pp +A mapping will be written with each key and value on a line, +whitespaces separating both columns: +.Bd -literal -offset indent +key1 value1 +key2 value2 +key3 value3 +.Ed +.Pp +A file table can be converted to a +.Xr db 3 +database using the +.Xr makemap 8 +utility with no syntax change. +.Pp +Tables using a +.Ql file +or +.Xr db 3 +backend will be referenced as follows: +.Bd -literal -offset indent +table name file:/path/to/file +table name db:/path/to/file.db +.Ed +.Ss 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. +.Bd -literal -offset indent +accept for domain example.org alias <myaliases> deliver to mbox +accept for domain example.org virtual <myaliases> deliver to mbox +.Ed +.Pp +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 +.Xr aliases 5 : +.Bd -literal -offset indent +user1 otheruser +user2 otheruser1,otheruser2 +user3 otheruser@example.com +.Ed +.Pp +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 +.Xr smtpd.conf 5 , +and the value is one or many recipients as described in +.Xr aliases 5 : +.Bd -literal -offset indent +user1 otheruser +user2@example.org otheruser1,otheruser2 +@example.org otheruser@example.com +@ catchall@example.com +.Ed +.Ss Domain tables +Domain tables are simple lists of domains. +They can only be used in one context: +.Bd -literal -offset indent +accept for domain <mydomains> deliver to mbox +.Ed +.Pp +In that context, the list of domains will be matched against the recipient +domain. +For +.Ql static , +.Ql file +and +.Xr db 3 +backends, a wildcard may be used so the domain table may contain: +.Bd -literal -offset indent +example.org +*.example.org +.Ed +.Ss Credentials tables +Credentials tables are mappings of credentials. +They can be used in two contexts: +.Bd -literal -offset indent +listen on tls [...] auth <credentials> +accept for any relay tls+auth://label@host auth <credentials> +.Ed +.Pp +In a listener context, the credentials are a mapping of username and encrypted +passwords: +.Bd -literal -offset indent +user1 $2a$06$hIJ4QfMcp.90nJwKqGbKM.MybArjHOTpEtoTV.DgLYAiThuoYmTSe +user2 $2a$06$bwSmUOBGcZGamIfRuXGTvuTo3VLbPG9k5yeKNMBtULBhksV5KdGsK +.Ed +.Pp +The passwords are encrypted using the +.Xr crypt 3 +function provided by the host. +On +.Ox , +the +.Xr encrypt 1 +utility may be used; +on other systems the +.Ql mkpasswd +utility is the most common method for obtaining a proper password. +.Pp +In a relay context, the credentials are a mapping of labels and +username:password pairs, +where the username may be omitted if identical to the label: +.Bd -literal -offset indent +label1 user:password +label2 password +.Ed +.Pp +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. +.Ss Netaddr tables +Netaddr tables are lists of IPv4 and IPv6 network addresses. +They can only be used in the following context: +.Bd -literal -offset indent +accept from source <netaddr> for domain example.org deliver to mbox +.Ed +.Pp +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. +.Pp +A netaddr table can contain exact addresses or netmasks, and looks as follow: +.Bd -literal -offset indent +192.168.1.1 +::1 +ipv6:::1 +192.168.1.0/24 +.Ed +.Ss Userinfo tables +User info tables are used to described virtual system users. +They are used in rule context to specify an alternate user base, mapping +virtual users to local system UID, GID and home directory. +.Bd -literal -offset indent +accept for domain example.org userbase <userinfo> deliver to maildir +.Ed +.Pp +The userinfo table is a mapping from virtual user names to a set of system user +ID, group ID and path to home directory. +.Pp +A userinfo table looks as follows: +.Bd -literal -offset indent +joe 1000:100:/home/virtual/joe +jack 1000:100:/home/virtual/jack +.Ed +.Pp +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 +.Xr forward 5 +file. +.Ss Source tables +Source tables are lists of IPv4 and IPv6 addresses. +They can only be used in the following context: +.Bd -literal -offset indent +accept for domain example.org relay source <addresses> +.Ed +.Pp +Successive queries to the source table will return the elements one by one. +.Pp +A source table looks as follow: +.Bd -literal -offset indent +192.168.1.2 +192.168.1.3 +::1 +::2 +ipv6:::3 +ipv6:::4 +.Ed +.Ss Mailaddr tables +Mailaddr tables are lists of email addresses. +They can be used in the following contexts: +.Bd -literal -offset indent +accept sender <senders> for domain example.org deliver to mbox +accept for domain example.org recipient <recipients> deliver to mbox +.Ed +.Pp +A mailaddr entry is used to match an email address against a username, +a domain or a full email address. +.Pp +A mailaddr table looks as follow: +.Bd -literal -offset indent +user +@domain +user@domain +.Ed +.Ss Addrname tables +Addrname tables are used to map IP addresses to hostnames. +They can be used in both listen context and relay context: +.Bd -literal -offset indent +listen on 0.0.0.0 hostnames <addrname> +accept for any relay hostnames <addrname> +.Ed +.Pp +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. +.Pp +The format is a mapping from inet4 or inet6 addresses to hostnames: +.Bd -literal -offset indent +::1 localhost +127.0.0.1 localhost +88.190.23.165 www.opensmtpd.org +.Ed +.Sh SEE ALSO +.Xr smtpd.conf 5 , +.Xr makemap 8 , +.Xr smtpd 8 |