table-passwd.5

.\"
.\" Copyright (c) 2014 Gilles Chehade <gilles@poolp.org>
.\" Copyright (c) 2016 Joerg Jung <jung@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: April 4 2024 $
.Dt TABLE_PASSWD 5
.Os
.Sh NAME
.Nm table_passwd
.Nd format description for smtpd passwd tables
.Sh DESCRIPTION
This manual page documents the file format of "passwd" tables used by the
.Xr smtpd 8
mail daemon.
.Pp
The format described here applies to tables as defined in
.Xr smtpd.conf 5 .
.Sh PASSWD TABLE
A "passwd" table stores information regarding local users.
The information is encoded using the traditional
.Xr passwd 5
format and allows the sharing of a user database across different software
supporting this format.
.Pp
The table is used by
.Xr smtpd 8
when authenticating a user or when user information such as user-id or
home directory is required for a delivery.
.Pp
A "passwd" table consists of a flat file containing the user entries, each
one on a line by itself, with fields separated by a colon:
.Bd -literal -offset indent
gilles:*:1000:1000:Gilles:/home/gilles:/sbin/nologin
eric:*:1001:1001:Eric:/home/eric:/sbin/nologin
chl:*:1002:1002:Charles:/home/chl:/sbin/nologin
.Ed
.Pp
Besides the first username field and depending on the table type, fields are
optional and might be empty.
The gecos and the shell field are not used and ignored.
.Pp
If the table is used for authentication, the second field should contain a
password encrypted using the
.Xr crypt 3
function.
Such passwords can be generated using the
.Xr encrypt 1
utility or
.Xr smtpctl 8
encrypt command.
.Pp
If the table is used for user information, user-id, group-id, and home
directory fields are required.
.Pp
In favor of supporting shared authentication with the Dovecot Passwd-file
format, extra fields after the last shell field are allowed (and ignored).
.Sh SEE ALSO
.Xr passwd 5 ,
.Xr smtpd.conf 5 ,
.Xr smtpctl 8 ,
.Xr smtpd 8
.Sh HISTORY
The first version of
.Nm
was written in 2013.
It was converted to the stdio table protocol in 2024.
.Sh AUTHORS
.An -nosplit
.Nm
was initially written by
.An Gilles Chehade Aq Mt gilles@poolp.org
and further improved by
.An Joerg Jung Aq Mt jung@openbsd.org .
The conversion to the stdio table protocol was done by
.An Omar Polo Aq Mt op@openbsd.org .