table-ldap.5

.\"
.\" Copyright (c) 2013 Eric Faurot <eric@openbsd.org>
.\" Copyright (c) Philipp Takacs <philipp+openbsd@bureaucracy.de>
.\"
.\" 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: September 2 2024 $
.Dt TABLE_LDAP 5
.Os
.Sh NAME
.Nm table_ldap
.Nd format description for smtpd LDAP tables
.Sh DESCRIPTION
This manual page documents the file format of LDAP 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 LDAP TABLE
A ldap table allows to access userinfo, aliases, domains, and mailaddresses
that are stored in a directory and are provided by an LDAP implementation.
.Pp
The table is used by
.Xr smtpd 8
when user information such as user-id and/or
home directory is required for a delivery, when a domain lookup may be
required, and/or when looking for an alias.
.Pp
A LDAP table consists of a LDAP tree starting from a base.
Each table lookup will search for the matching objects.
.Sh LDAP TABLE CONFIG FILE
.Ss COMMON OPTIONS
.Bl -tag -width Ds
.It Ic url : Ar url
This is the LDAP url which is used to connect to your LDAP server.
For example:
.Bd -literal -offset indent
url: ldap://ldap.example.com
.Ed
.It Ic username : Ar binddn
The Distinguished Name which is used to bind to the ldap server.
For example:
.Bd -literal -offset indent
username: cn=smtpd,cn=sysaccounts,cn=etc,dc=example,dc=com
.Ed
.It Ic password : Ar password
The password for the binddn.
For example :
.Bd -literal -offset indent
password: OpenSMTPDRules!
.Ed
.It Ic basedn : Ar basedn
The basedn used for each LDAP search request.
For example:
.Bd -literal -offset indent
basedn: cn=users,cn=accounts,dc=example,dc=com
.Ed
.El
.Ss SERVICE OPTIONS
For each service there are two options:
A ldap filter and a list of the attributes.
.Bl -tag -width Ds
.It Ic alias_filter : Ar filter
This filter is used when the table is used in an alias (or virtual
alias) context.
The filter should match all entries for this particular alias.
.It Ic alias_attributes : Ar recipient_atribute
The attribute which holds the recipients for an alias.
When the attribute is present multiple times,
then all attribute values are returned.
.It Ic credentials_filter : Ar filter
This filter is used to look up credentials for a specific user.
The filter should match exactly one object.
When the filter match multiple objects only the last object returned
by the server is used.
.It Xo
.Ic credentials_attributes :
.Ar username_attribute , passwordhash_attribute
.Xc
The attributes for username and password hash.
The password hash must be encoded like the output of
.Xr smtpctl 8
encrypt subcommand.
When one attribute is missing the object is ignored.
When a attribute is present multiple times,
then only the first one is used.
.It Ic domain_filter : Ar filter
The filter for domains is used to lookup a domain.
.Xr smtpd 8
currently only checks if a domain exists in the table.
.It Ic domain_attributes : Ar attribute
This attribute is currently not used, because
.Xr smtpd 8
does only check if the domain exists.
.It Ic userinfo_filter : Ar filter
This filter is to lookup the userinfo for an userbase.
The filter should match exactly one object.
When the filter match multiple objects only the last object returned
by the server is used.
When a attribute is present multiple times,
then only the first one is used.
.It Xo
.Ic userinfo_attributes :
.Ar uid_attribute , gid_attribute , home_attribute
.Xc
The attributes for uid, gid, and the home directory of the user.
When one attribute is missing the object is ignored.
When a attribute is present multiple times,
then only the first one is used.
.It Ic mailaddr_filter : Ar filter
This filter is to match mailaddres.
.Xr smtpd 8
currently only checks if a domain exists in the table.
.It Ic mailaddr_attributes : Ar attribute
This attribute is currently not used, because
.Xr smtpd 8
does only check if the mailaddr exists.
.It Ic mailaddrmap_filter : Ar filter
This filter is to map users to mailaddresses.
The filter should return all object containing the mailaddress of the user.
.It Ic mailaddrmap_attributes : Ar mail_attribute
The attribute contains the mailaddresses of the user.
When the attribute is present multiple times,
then all attribute values are returned.
.El
.Sh FORMAT SPECIFIERS
The filter options are designed to allow per request
Filters allow some specifiers in the attribute values of the filter.
The following speciers are defined:
.Pp
.Bl -tag -offset Ds -width Ds -compact
.It Ic %u
The key of the request.
.It Ic %h
The name of the table.
.It Ic %%
The literal
.Sq % .
.It Ic %s
Deprecated alias for the the key.
.El
.Pp
When a not defined specier is used the filter will not work.
.Sh EXAMPLES
.Ss USERS EXAMPLE
This example show how to use the ldap table for user accounts stored in ldap.
Mails for local users are deliverd to a lmtp server.
Most of the example works with a normal ldap schema.
Only for the smtpPassword a schemaextention is required.
.Pp
.Pa /etc/mail/ldap_users.conf
.Bd -literal -offset indent
url: ldap.example.com
username: uid=smtpd,cn=services,dc=example,dc=com
password: OpenSMTPDRules!
basedn: cn=users,dc=example,dc=com

alias_filter: (&(objectclass=posixaccount)(mail=%u))
alias_attributes: uid

credentials_filter: (&(objectclass=posixaccount)(uid=%u))
credentials_attributes: uid, smtpPassword

userinfo_filter: (&(objectclass=posixaccount)(uid=%u))
userinfo_attributes: uidNumber, gidNumber, homedir

mailaddr_filter: (&(objectclass=posixaccount)(mail=%s))
mailaddr_attributes: mail

mailaddrmap_filter: (&(objectclass=posixaccount)(uid=%s))
mailaddrmap_attributes: mail
.Ed
.Pp
.Pa /etc/mail/smtpd.conf
.Bd -literal -offset indent
table users ldap:/etc/mail/ldap_users.conf

pki mail.example.com cert "/etc/ssl/mail.example.com.crt"
pki mail.example.com key "/etc/ssl/private/mail.example.com.key"

listen on egress port 25 tls pki mail.example.com
listen on egress port 587 tls-require pki mail.example.com \e
    senders <users> auth <users>

match for rcpt-to <users> action "ldapusers"
match from auth for any action "relay"
match from any reject

action "ldapusers" lmtp "lmtp.example.com:1234" userbase <users> \e
    virtual <users>
action "relay" relay
.Ed
.Pp
With this example a user can auth against the credentials stored in ldap.
The user can send mails with the addresses specified in ldap as sender.
Mails for the addresses specified in ldap are mapped to the user and
deliverd over lmtp.
.Sh SEE ALSO
.Xr encrypt 1 ,
.Xr crypt 3 ,
.Xr smtpd.conf 5 ,
.Xr smtpctl 8 ,
.Xr smtpd 8
.Sh STANDARDS
.Rs
.%A J. Sermersheim
.%D June 2006
.%R RFC 4511
.%T Lightweight Directory Access Protocol (LDAP): The Protocol
.Re
.Rs
.%A M. Smith
.%A T. Howes
.%D June 2006
.%R RFC 4515
.%T Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters
.Re
.Sh BUGS
Currently only check and lookup requests are implemented.
Fetch and update should also be supported.
.Pp
The auth request is not supported so the password must be readable by the
binddn and formatted for smtpd.
.Pp
Pagination is currently not supported.