missing manpage, spotted by jmc@

2 files changed, 259 insertions, 2 deletions

diff --git a/usr.sbin/smtpd/smtpd/Makefile b/usr.sbin/smtpd/smtpd/Makefile
index 20813ce4d06..b43ab0139f0 100644
--- a/usr.sbin/smtpd/smtpd/Makefile
+++ b/usr.sbin/smtpd/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/usr.sbin/smtpd/table.5 b/usr.sbin/smtpd/table.5
new file mode 100644
index 00000000000..94f9cc9b63f
--- /dev/null
+++ b/usr.sbin/smtpd/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