LDP/LDP/howto/docbook/Ldap-Implementation-HOWTO/section-sendmail.sgml

<SECT1 ID="SENDMAIL"><TITLE>Sendmail</TITLE>
<SECT2><TITLE>Ldap support in sendmail</TITLE>
<PARA>Sendmail has support for ldap since somewhere around version 8.8.x using the map type <EMPHASIS>ldapx</EMPHASIS>.From version 8.10 and up an ldap database type <EMPHASIS>ldap</EMPHASIS> is supported. Please note that the ldap map support is not enabled per default in the RedHat package. Debian versions 2.2 and later do have ldap support in their sendmail, I am told. If you have to compile it yourself, please read the file <FILENAME MOREINFO="NONE">sendmail/README</FILENAME> from the sendmail sources. It contains valuable information about how to compile in the ldap support.</PARA>
<PARA>Both the old and the new ldap map type have the ability to look up entries in an ldap database. There is one thing that must be noted however. When a search is being done, only one result should be returned. If more results are found, only the first is used. Additionally, is multiple return values for that result are found, only the first is returned. Let's take a look at the following example ldif file:</PARA>
<PARA><PROGRAMLISTING FORMAT="LINESPECIFIC">
dn: cn=mailuser1,ou=mail,dc=company,dc=com
objectclass: top
objectclass: foo
cn: mailuser1
mail: mailuser1@company.com
mail: info@company.com</PROGRAMLISTING></PARA>
<PARA>If a search is performed with a simple search filter like <EMPHASIS>cn=mailuser1</EMPHASIS>, and the attribute that is asked for is <EMPHASIS>mail</EMPHASIS>, only <EMPHASIS>mailuser1@company.com</EMPHASIS>, is returned. To get both results, they should we stored in a single-valued attribute with comma-separated values, like this:</PARA>
<PARA><PROGRAMLISTING FORMAT="LINESPECIFIC">mail: mailuser1@company.com, info@company.com</PROGRAMLISTING></PARA>
<PARA>An email message containing information related to this subject can be found at the <ULINK URL="http://devel.linvision.com/doc/lih/alias_issues">LIH home</ULINK>.</PARA></SECT2>
<SECT2><TITLE>System layout.</TITLE>
<PARA>When ldap maps are available, almost anything can be looked up in an ldap database. What we would like to do is to simplify the configuration of the following setup.</PARA>
<PARA>Let's say we have a medium-sized or large network where we recieve for  many domains. We have two mailhosts and two or three fallback hosts. This setup will normally have four places where three types of information are stored. <ITEMIZEDLIST><LISTITEM><PARA>The mailhosts both need a file <FILENAME MOREINFO="NONE"></FILENAME>, or traditionally <FILENAME MOREINFO="NONE">sendmail.cw</FILENAME>, to store the domains for which they should recieve mail. The fallback hosts keep the same information in the <FILENAME MOREINFO="NONE">access</FILENAME> file, but they use it to list the domains for which they should relay any incoming mail.</PARA></LISTITEM>
<LISTITEM><PARA>The mailhosts both have a <FILENAME MOREINFO="NONE">virtusers</FILENAME> file, which maps multiple adresses (or entire domains) to a single virtual or local user.</PARA></LISTITEM>
<LISTITEM><PARA>The mailhosts both have an <FILENAME MOREINFO="NONE">aliases</FILENAME> file, which maps virtual users to one or more mail addresses or local users.</PARA></LISTITEM></ITEMIZEDLIST>If this information is stored in a single database, each host will read its configuration from that database, which improves both the manageability and the scaleability of the network. One could even think of a single host which carries all data, mapped to with nfs. In such a case it makes no difference anymore to which host we are connecting. To a user, they appear to be all the same.</PARA></SECT2>
<SECT2><TITLE>Sendmail configuration file</TITLE>
<PARA>To understand how this information is read from an ldap database instead of the regular files a little background knowledge of the <FILENAME MOREINFO="NONE">sendmail.cf</FILENAME> file is neccesary. The information we're dealing with here is stored in two different ways. The <FILENAME MOREINFO="NONE">local-host-names</FILENAME> file is read into a class (class w, to be exactly, hence the old extension cw), while the virtusers file is used through a simple map. The aliases file is also a map, but it is defined in a different manner and used internally, instead of being referred to in rules.</PARA>
<PARA>When information is retrieved from a ldap database, it always ends up being in a map. This is somewhat problematic with the information stored in the <FILENAME MOREINFO="NONE">local-host-names</FILENAME> file, because this used to be a class. I have been unable to fill the class with the information from the map or something alike. That would be the easy way, but I think it's not possible. (If I'm incorrect about this, please let me know). Therefore, I had to define a new map, and insert rules in the sendmail configuration to make sure that (almost) every time when a value is looked up in the class, the new map is searched for the value too.</PARA>
<PARA>For the maps, the change of configuration is easy. A map is normally defined with a name and database type, and some database-specific options, (like the location of the file, for the normally used newdb database types). So for maps, it suffices to change the definition of the map and voila, we're done. Ldap maps have a few more options, some of which can be predefined. They are explained in the following list (largely taken from Booker Bense's document):<VARIABLELIST><TITLE>Ldap-specific map options in sendmail.cf</TITLE>
<VARLISTENTRY><TERM>-h</TERM>
<LISTITEM><PARA>Defines a space-separated list with hostnames of ldap servers. All machines will be queried in this order, until a result is found. This can be configured globally.</PARA></LISTITEM></VARLISTENTRY>
<VARLISTENTRY><TERM>-b</TERM>
<LISTITEM><PARA>Defines the ldap search base, e.g. the ldap directory you are going to search in. This can be configured globally.</PARA></LISTITEM></VARLISTENTRY>
<VARLISTENTRY><TERM>-k</TERM>
<LISTITEM><PARA>Defines the ldap search filter. It is a "sprintf" style string that defines how the map takes it's input value and constructs an ldap search. It has the form of an ordinary ldap search filter, with %s replaced by the value that is searched for. To learn more about ldap search filters please see <ULINK URL="http://www.cis.ohio-state.edu/htbin/rfc/rfc2254.html">RFC 2254</ULINK>. The search filter and the search base used above should define a search that returns at most one entry. The ldap map will only use the first entry it recieves. </PARA></LISTITEM></VARLISTENTRY>
<VARLISTENTRY><TERM>-v</TERM>
<LISTITEM><PARA>Defines the ldap attribute of which the value will be returned by the map lookup. Explained in detail later.</PARA></LISTITEM></VARLISTENTRY></VARIABLELIST></PARA>
<PARA>PLease note that all ldap options must be double-quoted and must immediately follow the sendmail option. Here is an example:</PARA>
<PARA><PROGRAMLISTING FORMAT="LINESPECIFIC">Kldapexamplemap ldap -h"localhost ldap.myorg.com" -b"ou=mail,dc=myorg,dc=com" -k"(&(objectclass=mailstuff)(uid=%s))" -v"mailaddress"</PROGRAMLISTING></PARA></SECT2>
<SECT2><TITLE>Schema</TITLE>
<PARA>For this particular setup I have defined a subtree <EMPHASIS>mail</EMPHASIS> in the ldap directory, under which all mail-related information will be stored. I t would have been possible to store some of the user-related mail-information in the <EMPHASIS>ou=Users</EMPHASIS> subtree, but I have specificalle chosen not to do this. When using a separate subtree, all information for sendmail is stored in a single place, and, when having many users, searches may be faster, because not the entire <EMPHASIS>ou=Users</EMPHASIS> subtree needs to be searched, but only the <EMPHASIS>ou=mail</EMPHASIS> subtree.</PARA>
<PARA>In this subtree two kinds of records will appear.<ORDEREDLIST INHERITNUM="IGNORE" CONTINUATION="RESTARTS"><LISTITEM><PARA>Entries that hold mappings from the <FILENAME MOREINFO="NONE">virtuser</FILENAME> file and <FILENAME MOREINFO="NONE">aliases</FILENAME> file, for a single virtual user. I have chosen to store both mappings in a single entry, because this clarifies the effect and configuration used. For this I have defined an objectclass <EMPHASIS>inetmailrecipient</EMPHASIS>, and three attributes, <EMPHASIS>mailid</EMPHASIS>, <EMPHASIS>mailacceptinggeneralid</EMPHASIS> and <EMPHASIS>maildrop</EMPHASIS>.</PARA>
<PARA><VARIABLELIST><VARLISTENTRY><TERM>inetmailrecipient</TERM>
<LISTITEM><PARA>This is a classification that tells us the entry is some form of mapping from one or more real mail addresses and/or mail domains to one or more real users.</PARA></LISTITEM></VARLISTENTRY>
<VARLISTENTRY><TERM>mailid</TERM>
<LISTITEM><PARA>This describes the mail addresses that this virtual user recieves mail for. Can be in the form of normail addresses, like <EMPHASIS>foo@myorg.com</EMPHASIS>, or complete domains like <EMPHASIS>@my2nd.org</EMPHASIS>. Multiple of these attributes may be present, but they should all contain only one value. For each of these id's mail is sent to <EMPHASIS>mailacceptinggeneralid</EMPHASIS>.</PARA>
<PARA>Here you'll put what you used to put at the left side in the <FILENAME MOREINFO="NONE">virtusers</FILENAME> file.</PARA></LISTITEM></VARLISTENTRY>
<VARLISTENTRY><TERM>mailacceptinggeneralid</TERM>
<LISTITEM><PARA>Defines a virtual user. This is in fact the link between the <FILENAME MOREINFO="NONE">virtusers</FILENAME> and <FILENAME MOREINFO="NONE">aliases</FILENAME> file. In each entry, one attribute of this type must be present, but no more than one may be present, and the attribute may contain only one value. This can either be a local username, or a virtual user. In the second case, a maildrop attribute must be present, in the first case, it does not.</PARA>
<PARA>Here you'll put what you used to put in the <FILENAME MOREINFO="NONE">virtusers</FILENAME> file, and at the left side in the <FILENAME MOREINFO="NONE">aliases</FILENAME> file.</PARA></LISTITEM></VARLISTENTRY>
<VARLISTENTRY><TERM>maildrop</TERM>
<LISTITEM><PARA>Defines the addresses and/or users that mail received for  should be delivered to. Only one attribute of this type may be present, but it may contain a comma-separated list of addresses and/or users. If the value of <EMPHASIS>mailacceptinggeneralid</EMPHASIS> is a virtual user, this attribute must be present. If the value is a real user, this entry may be omitted.</PARA>
<PARA>Here you'll put what you used to put at the right side in the <FILENAME MOREINFO="NONE">aliases</FILENAME> file.</PARA></LISTITEM></VARLISTENTRY></VARIABLELIST></PARA>
<PARA>In general, one could say that the <EMPHASIS>mailid</EMPHASIS> and <EMPHASIS>mailacceptinggeneralid</EMPHASIS> together provide the functionality of the <FILENAME MOREINFO="NONE">virtusers</FILENAME> file, and <EMPHASIS>mailacceptinggeneralid</EMPHASIS> and <EMPHASIS>maildrop</EMPHASIS> together provide the functionality of the <FILENAME MOREINFO="NONE">aliases</FILENAME> file.</PARA></LISTITEM>
<LISTITEM><PARA>One or more entries that hold the domain names which would normally apear in the <FILENAME MOREINFO="NONE">sendmail.cw</FILENAME> and <FILENAME MOREINFO="NONE">access</FILENAME> files. For this I have defined an objectclass <EMPHASIS>inetmaildomain</EMPHASIS>, and three attributes, <EMPHASIS>maildomain</EMPHASIS>, <EMPHASIS>sendmailislokalkey</EMPHASIS> and <EMPHASIS>sendmailaccesskey</EMPHASIS>.</PARA>
<PARA><VARIABLELIST><VARLISTENTRY><TERM>inetmaildomain</TERM>
<LISTITEM><PARA>This is a classification that tells us the entry lists mail domains which belong to our system, and either should be delivered locally, or be relayed to another host.</PARA></LISTITEM></VARLISTENTRY>
<VARLISTENTRY><TERM>maildomain</TERM>
<LISTITEM><PARA>Defines the mail domain. Multiple of these attributes may be presentin a single entry. The value should be the domain without the "@".</PARA>
<PARA>For each of the dmain entries in the <EMPHASIS>local-host-names</EMPHASIS> file, one of these attributes should be present.</PARA></LISTITEM></VARLISTENTRY>
<VARLISTENTRY><TERM>sendmailislocalkey</TERM>
<LISTITEM><PARA>This defines a simple key that is used in the sendmail rules to determine if a domain is local. It can be anything really, but is must be the exact string you will use in your sendmail rules. For now I have used <EMPHASIS><SGMLTAG CLASS="STARTTAG">LDAPLOCAL</SGMLTAG></EMPHASIS>. One attribute of this type must be present, and no more than one may be present in each entry.</PARA></LISTITEM></VARLISTENTRY>
<VARLISTENTRY><TERM>sendmailaccesskey</TERM>
<LISTITEM><PARA>This defines the key that is used in the sendmail rules to determine what action needs t be taken for the specified domain. It can be one of <EMPHASIS>RELAY</EMPHASIS>, <EMPHASIS>OK</EMPHASIS>, <EMPHASIS>REJECT</EMPHASIS>, <EMPHASIS>DISCARD</EMPHASIS> or an error indicator. (For detailed information see the <FILENAME MOREINFO="NONE">cf/README</FILENAME> file from the sendmail sources.)</PARA></LISTITEM></VARLISTENTRY></VARIABLELIST></PARA>
<NOTE><PARA>PLease note that in this particular setup I will only be using entire domains in the <EMPHASIS>access</EMPHASIS> file. That means that in this case I can use the <EMPHASIS>maildomain</EMPHASIS> attribute for both the information used in the <EMPHASIS>access</EMPHASIS> file and the information used in the <EMPHASIS>local-host-names</EMPHASIS>. If you want a finer control over your access list, you should define a separate entry to hold that information, instead of using the <EMPHASIS>maildomain</EMPHASIS> attribute.</PARA></NOTE></LISTITEM></ORDEREDLIST></PARA></SECT2>
<SECT2><TITLE>More information.</TITLE>
<PARA>Here are a few sources of information that might be useful:<ITEMIZEDLIST><LISTITEM><PARA>Booker Bense has written a <ULINK URL="http://www.stanford.edu/~bbense/ldap/Inst.html">document</ULINK> about the usage of ldap with sendmail 8.9.3. He says it's the wrong place to start when learning about using sendmail and ldap, but it has been of great help to me.</PARA></LISTITEM>
<LISTITEM><PARA><ULINK URL="http://ldapman.org/articles/index.html">New articles</ULINK> about ldap and sendmail are being published on <ULINK URL="http://www.sendmail.net">sendmail.net</ULINK>, written by Michael Donnelly, originating from <ULINK URL="http:///www.ldapmap.org">ldapmap.org</ULINK>, which has also a lot of general interesting ldap-related information.</PARA></LISTITEM></ITEMIZEDLIST></PARA></SECT2></SECT1>