1. Douglas Gray Stephens Senior Directory Architect Schlumberger
4/16/2017
Using Exim with LDAP
Douglas Gray Stephens
Senior Directory Architect Schlumberger
This is a note

2. Topics What is LDAP; What is LDAP designed for;
4/16/2017
Topics
What is LDAP;
What is LDAP designed for;
How is LDAP integrated into Exim;
Case study of using Exim with LDAP;
How to trouble shoot Exim with LDAP;
2 DGS
23 Feb 2005

3. What is LDAP Light weight Directory Access Protocol;
4/16/2017
What is LDAP
Light weight Directory Access Protocol;
(X.500 is DAP, so more heavy weight);
Communications protocol :
no specification for back end server system;
Standards based;
Defacto standard for internet white pages (c.f. http for on line documents).
Current version is LDAPv3 (ratified in 2000)
3 DGS
23 Feb 2005

4. What is LDAP designed for
4/16/2017
What is LDAP designed for
Systems where there are few writes, but many reads;
Storing any data;
Fast response for queries;
Redundancy (i.e automatic fail over);
4 DGS
23 Feb 2005

5. What is LDAP not designed for
4/16/2017
What is LDAP not designed for
It is not a relational database;
Is not efficient for systems with frequent writes;
Server may return unexpected (e.g. no) results if attribute not indexed.
5 DGS
23 Feb 2005

6. How is data stored in LDAP (DIT)
4/16/2017
How is data stored in LDAP (DIT)
LDAP is a tree structure (Document Information Tree):
6 DGS
23 Feb 2005

7. How is data stored in LDAP (objects)
4/16/2017
How is data stored in LDAP (objects)
LDAP has several containers (objectclasses)
Each objectclass has required and/or allowable attributes (fields), e.g.
person (OID )
Required Attributes
Allowed Attributes
objectclass
cn (commonName)
sn (surName)
description
seeAlso
telephoneNumber
userPassword
7 DGS
23 Feb 2005

8. Object Identifiers (OIDs)
4/16/2017
Object Identifiers (OIDs)
Each LDAP objectclass and attribute has a definition;
The definition can be registered;
Normally has an associated OID;
OIDs allocated by IANA, ANSA, BSI as in dot notation, e.g.
is the top of the Internet OID branch (RFC 1065)
is the top of the Internet Enterprise OID branch
is Schlumberger’s OID for LDAP
OIDs can be private, but you can walk the tree from
8 DGS
23 Feb 2005

9. Activedirectory (Windows 2000)
4/16/2017
Activedirectory (Windows 2000)
Windows 2000 server comes with Activedirectory;
Activedirectory has an LDAP interface;
Implementation of LDAP is not 100% standard compliant;
If you have Windows 2000, then LDAP provides a usable standards based interface to access account details;
May need to modify Activedirectory ACLs to enable LDAP access.
9 DGS
23 Feb 2005

10. LDAP searches Require Server to search (where to look);
4/16/2017
LDAP searches
Require
Server to search (where to look);
Search root (part of DIT to start searching from);
Scope (how far to look ─ base, one level, or sub tree);
Filter (what to look for);
Attribute(s) to return;
10 DGS
23 Feb 2005

11. LDAP search example
4/16/2017
E.g. ldapsearch –h myhost: –b dc=company1,dc=com –s sub “(cn=douglas gray stephens)” cn sn givenname mail
Returns dn: cn=Douglas Gray Stephens,ou=employee,dc=company1,dc=com
cn: Douglas Gray Stephens
cn: Douglas Gray-Stephens
cn: Grey Stevens
sn: Gray Stephens
givenName: Douglas
mail:
11 DGS
23 Feb 2005

12. LDAP filters Components of filter nested within brackets “(…..)”;
4/16/2017
LDAP filters
Components of filter nested within brackets “(…..)”;
Items can be ANDed together (with “&”);
Items can be ORed together (with “|”);
Items can be negated (with “!”);
Searches can include wild cards (with “*”);
RFC 2254 gives full details.
12 DGS
23 Feb 2005

13. LDAP filter example E.g. “(&(mail=*)(c=gb)(!(l=london))(cn=douglas*))”
4/16/2017
LDAP filter example
E.g. “(&(mail=*)(c=gb)(!(l=london))(cn=douglas*))”
Means
Find all records with an mail attribute
that are in the United Kingdom (GB)
and are do not have London as the city
and have a common name starting with douglas
13 DGS
23 Feb 2005

14. 4/16/2017
LDAP URLs
An LDAP URL begins with the protocol prefix "ldap" and is defined by the following grammar, as defined in RFC 2255:
<ldapurl> ::= "ldap://" [ <host:port> ] "/" <dn> [ "?" <attributes>
[ "?" <scope> "?" <filter> ] ]
<host:port> ::= <hostname> [ ":" <portnumber> ]
<dn> ::= a string as defined in RFC 2253
<attributes> ::= NULL | <attributelist>
<attributelist> ::= <attributetype>
| <attributetype> [ "," <attributelist> ]
<attributetype> ::= a string as defined in RFC 1777
<scope> ::= "base" | "one" | "sub"
<filter> ::= a string as defined in RFC 2254
14 DGS
23 Feb 2005

15. LDAP URL example Specifies that
4/16/2017
LDAP URL example
ldap://server1 server2:387/dc=com?cn,mail?sub?(&(cn=douglas*)(l=cambridge))
Specifies that
there are two servers to try (server1, then server2). Note the second server is on a non standard port (387);
a search root of “dc=com”;
attributes “cn” and “mail” should be returned;
the sub tree should be searched;
using a filter “(&(cn=douglas*)(l=cambridge))”;
15 DGS
23 Feb 2005

16. LDAP authentication LDAP has 3 types of authentication (binding)
4/16/2017
LDAP authentication
LDAP has 3 types of authentication (binding)
Anonymous (client gives no DN or password);
Unauthenticated (client gives a DN that may or may not exist and no password (a null password);
Authenticated (client gives a DN that must exist, and the correct password for that DN).
16 DGS
23 Feb 2005

17. Building Exim Requires that the LDAP libraries be available
4/16/2017
Building Exim
Requires that the LDAP libraries be available
OpenLDAP (
SunOne (previously Netscape/iPlanet) ( rvr_ee/ )
Specify in Makefile
LOOKUP_LDAP=yes
LDAP_LIB_TYPE=OPENLDAP1/OPENLDAP2/NETSCAPE/SOLARIS
LOOKUP_INCLUDE=-I /???/include
LOOKUP_LIBS=-L/???/lib -lldap -llber
The examples use the perl interpreter, so the Local/Makefile also included “EXIM_PERL=perl.o”
17 DGS
23 Feb 2005

18. Configuring Exim Location of LDAP servers
4/16/2017
Configuring Exim
Location of LDAP servers
ldap_default_servers = “\
localhost::389 : \
server1::389 : \
server2::387”
Some router/transport commands to make use of LDAP (use anywhere that you would use the exim lookup functionality).
18 DGS
23 Feb 2005

19. LDAP lookups in Exim Types of lookups:
4/16/2017
LDAP lookups in Exim
Types of lookups:
ldap requires the result to contain just one entry; if there are more, it gives an error.
ldapdn also requires the result to contain just one entry, but it is the Distinguished Name that is returned rather than any attribute values.
ldapm permits the result to contain more than one entry; the attributes from all of them are returned; each entry in result string is on a separate line;
19 DGS
23 Feb 2005

20. LDAP lookup results ldap:///o=base?attr1?sub?(uid=frederic)
4/16/2017
LDAP lookup results
ldap:///o=base?attr1?sub?(uid=frederic)
value1.1, value1.2
ldap:///o=base?attr2?sub?(uid=frederic)
value two
ldap:///o=base?attr1,attr2?sub?(uid=frederic)
attr1="value1.1, value1.2" attr2="value two"
ldap:///o=base?objectclass,cn,sn?sub?(uid=frede ric)
objectClass="top, person" cn=“Frederic Smith, Fred Smith" sn=“Smith“
ldapm:///o=base??sub?(uid=fred*)
objectClass="top,person" attr1="value1.1, value1.2" attr2="value two“
objectClass="top,person" …. Etc. for the second match
20 DGS
23 Feb 2005

21. 4/16/2017
Case study
Objective
Look up names in LDAP and forward to appropriate person;
Handle instance when multiple matches;
Handle instance when there is no address;
Enable user to control lookup options (so limiting spam).
21 DGS
23 Feb 2005

22. Details of mail handling
4/16/2017
Details of mail handling
Addresses of the form will always be sent to only one person, since a uid is by definition unique within the directory.;
Addresses of the form abc.efg_hij- will be processed according to the following rules.
Forward to record that matches uid and has address
Forward to record that matches the common name(s)
Forward to record that givename/surname
Forward to a record that contains all the words in the common name(s)
If record does not have address, return phone number
If there are 2 to 5 matches, give more details to sender
If there are more than 5 matches, bounce message
22 DGS
23 Feb 2005

23. 4/16/2017
Mail processing
For a single match, the message is forwarded to that address;
For 2 to 5 matches, the message is bounced back to the sender along with details of the matches. The sender is asked to try again.
For more than 5 matches, the message is bounced back to the sender. The sender is asked to be more specific about the address.
23 DGS
23 Feb 2005

24. Message flow Loop through series of LDAP lookups
4/16/2017
Message flow
Loop through series of LDAP lookups
Zero or more than one matches is failure for ldapm lookup
Perl code alias_bounce handles
no matches
2 to 5 matches
more than 5 matches
No address (snail mail details)
Perl code ldap_one sets new_address and status
24 DGS
23 Feb 2005

25. Exim Global parameters
4/16/2017
Exim Global parameters
ldap_default_servers = “server1 server2:387”
What should be returned: LDAP_URL = ldap:///dc=comany1,dc=com?uid,mail,cn,ou,telephonenumber, o?sub?
Search definitions for different lookups:
MAIL_UID_MATCH = &(mail=*)(uid=${perl{punc_to_dash}{$local_part
MAIL_CN_MATCH = &(mail=*)(cn=${perl{punc_to_spc}{$local_part}})
MAIL_GIVENNAME_SN_MATCH = &(mail=*)(${perl{givenname_sn_match}{$local_part}})
MAIL_CN_WORDS_MATCH = &(mail=*)(${perl{cn_match}{$local_part}})
Perl function that builds up an LDAP filter
Perl routines referenced:
sub punc_to_dash ($) {
my $local_part = shift;
$local_part =~ s/\W+/-/g;
$local_part; }
sub punc_to_spc ($) {
$local_part =~ s/[^-a-z0-9]+/ /gi;
sub first_word ($) {
$local_part =~ /([^\W_]+)/;
$1;
sub last_word ($) {
$local_part =~ /(\w+)\W*$/;
sub cn_match ($) {
my $query;
$query .= "(|(cn=$_)(cn=* $_)(cn=* $_ *)(cn=$_ *))"
for split /[^-a-z0-9]+/, shift;
"(&$query)";
25 DGS
23 Feb 2005

26. LDAP router example Returns mail address when one match company1_user:
4/16/2017
LDAP router example
company1_user:
driver = redirect
allow_defer
allow_fail
condition = "${perl{ldap_who} \
{${lookup ldapm {LDAP_URL(MAIL_UID_MATCH)}{$value} \
{${lookup ldapm {LDAP_URL(MAIL_CN_MATCH)} {$value} \
{${lookup ldapm {LDAP_URL(MAIL_GIVENNAME_SN_MATCH)} {$value} \
{${lookup ldapm {LDAP_URL(MAIL_CN_WORDS_MATCH)} {$value} \
{DUNNO}}}}}}}}}}"
data = ${perl{new_address}}
domains = company1.com
headers_add = "X-LDAP-Alias: V LDAP_ALIAS_VERSION. Sent to resolving to ${perl{new_address}}"
retry_use_local_part
Returns mail address when one match
ldap_who perl function is
sub ldap_who {
my $mail = 0;
(my $addresses = shift) =~ s/\b([a-z;]+=)\s+/$1/ig;
= split /\n/, $addresses, $MAX_ADDRESSES;
$local_part = Exim::expand_string('$local_part');
$domain = Exim::expand_string('$domain');
($new_address) = $addresses[0] =~ /mail=([^,\s]+)/;
$mail = $1;
if (($mail =~ || ($mail =~ {
$result{$local_part} = 'invalid_entry';
$addresses{$local_part} = }
else {
my $naddresses = $addresses ne $DUNNO : 0;
if ($DEBUG) {
warn ">>> returns $naddresses", ($naddresses == 1 ? " ($new_address)" : ""), "\n";
warn "$addresses\n" if $DEBUG > 1;
$result{$local_part} =
$naddresses == 1 ?
($new_address ? 'one' : ($addresses{$local_part} = 'one_no_mail')) :
$naddresses == 0 ? 'none' :
$naddresses >= $MAX_ADDRESSES ? 'too_many' :
($addresses{$local_part} = 'multiple');
$result{$local_part} eq 'one';
26 DGS
23 Feb 2005

27. Bounce router driver = accept retry_use_local_part
4/16/2017
unknownuser:
driver = accept
retry_use_local_part
transport = uid_bounce
no_verify
Associated Perl
my %failure_reason = (
insane => 'invalid address',
none => 'no matches at all',
one_no_mail => 'single match but no address',
multiple => 'few matches',
too_many => 'too many matches',
invalid_entry => 'invalid database entry', );
# failure_reason called by autoreply transport to make X-LDAP-Alias header
sub failure_reason {
if ( !defined $result{Exim::expand_string('$local_part')}
|| !$result{Exim::expand_string('$local_part')} ) {
$failure_reason{'insane'};
} else {
$failure_reason{$result{Exim::expand_string('$local_part')}} }
sub failure_message {
$local_part = Exim::expand_string('$local_part');
$domain = Exim::expand_string('$domain');
if ( !defined $result{$local_part}
|| !$result{$local_part}
&{$failure_sub{'insane'}};
&{$failure_sub{$result{$local_part}}};
sub fail_multiple {
my $header = <<HEADER;
Dear sender,
This message has been automatically generated because I, the
server, found more than one address that could possibly match
My steering philosophy is that mail should be delivered only to the
addressed individual. Since the supplied information is insufficient
to locate a specific individual, your message is being returned.
HEADER
my $help;
if ($result{$local_part} eq 'too_many') {
my $bounce_suggestion = &bounce_suggestion($domain);
$help = <<HELP;
The address given, matches more than
$MAX_ADDRESSES possible entries in our database. In order to make a
delivery you will need to provide an address that is more specific.
$bounce_suggestion
If that fails, please contact who will try to
assist you.
HELP
$help = <<HELP .
To help you locate the correct individual, selected fields from the
possible matches are included below. The alias field is the only one
guaranteed unique within a given community.
return $header . $help . <<SIGNOFF;
$multiple_bounce_footer
SIGNOFF
sub fail_none {
warn does not resolve to any addresses\n" if $DEBUG;
return <<FAIL;
This message has been automatically generated because I, the
server, was unable to find an address that matched
The unique alias <$local_part> does not exist in the directory. It
also did not match any last names or full names in the directory.
FAIL
sub fail_one_no_mail {
warn finds one match but no address\n" if $DEBUG;
my $details =
Dear sender,
This message has been automatically generated because I, the
server, found a single match looking for but
that match contained no forwarding address and was thus
undeliverable. The details of this match are as follows:
$details
$single_bounce_footer
sub fail_entry {
This message has been automatically generated because I, the
server, found a single match for but that match
contained an invalid forwarding address and was thus
undeliverable. The details of this match (including the invalid
address) are as follows:
sub fail_insane {
warn is considered an insane address\n" if $DEBUG;
This message has been automatically generated because the local part
of the address supplied, is not a valid
address. Specifically, the address must comprise only numbers, letters,
underscores, periods or dashes. It must also be a
minimum of three characters in length.
27 DGS
23 Feb 2005

28. Bounce transport uid_bounce: driver = autoreply
4/16/2017
Bounce transport
uid_bounce:
driver = autoreply
from = Comapny1 Mail Server
headers = "X-LDAP-To: bouncing (${perl{failure_reason}})\n\
Mime-Version: 1.0\nContent-Type: multipart/mixed; boundary=\"${perl{mime_boundary}}\""
log = "/var/spool/exim/log/bouncelog"
once = "/var/spool/exim/db/bounce/${local_part}"
once_repeat = 1w
return_message
subject = "Unable to deliver to
text = ${perl{mime_bounce}{${domain}}}
to = $sender_address
transport_filter = "/etc/exim/close_mime ${perl{mime_boundary}}"
exim ]$ /usr/sbin/exim -bt
router = unknownuser, transport = uid_bounce
exim ]$
28 DGS
23 Feb 2005

29. Sample too many matches
4/16/2017
From: Company1 Mail Server
Subject: Unable to deliver to ……
To help you locate the correct individual, selected fields from the possible matches are
included below. The uid field is the only onemguaranteed unique within a given
community.
Name : Andy Few
Uid : AFew1
Organisation : Company1
City : london
Name : Alex Few
Uid : afew2
City : cambridge
Sent
From: Douglas Gray Stephens
To:
Subject: Test message that will bounce as there are too many recipients
Date: Tue, 22 Feb :00:
X-Text-Classification: inbox
This is the body of the message
Douglas.
Received message
From: Company1 Mail Server
To:
Subject: Unable to deliver to
Date: Tue, 22 Feb :44:
Dear sender,
This message has been automatically generated because I, the
server, found more than one address that could possibly match
My steering philosophy is that mail should be delivered only to the
addressed individual. Since the supplied information is insufficient
to locate a specific individual, your message is being returned.
To help you locate the correct individual, selected fields from the
possible matches are included below. The uid field is the only one
guaranteed unique within a given community.
Name : Andy Few
Uid : AFew1
Organisation : Company1
City : london
Name : Alex Few
Uid : afew2
City : cambridge
If you believe that this address should have resolved to a single
recipient or it did so consistently in the past please notify the
Postmaster including as much detail as possible:
at least full name, department, and approximate geographic region
and of course the address you believe was previously correct.
You may reply to this and it will be read by someone who will do
their best to help you.
Sorry I couldn't get your message through this time. Your original
message is attached. If you have been given enough information above
to try again, I would suggest re-sending your original message to
the new address.
Best wishes,
Your humble Company1 server.
Human contact:
mail message [Click mouse-2 to display message]
29 DGS
23 Feb 2005

30. Example with no email address
4/16/2017
Example with no address
From: Company1 Mail Server
Subject: Unable to deliver to
Dear sender,
This message has been automatically generated because I, the server, found a
single match looking for but that match contained no
forwarding address and was thus undeliverable. The details of this match are as
follows:
Name : Dark Ages
Uid : dages1
Organisation : Company1
City : Oxford
Tel :
Returned message
From: Company1 Mail Server
To:
Subject: Unable to deliver to
Date: Tue, 22 Feb :03:
X-Text-Classification: inbox
Dear sender,
This message has been automatically generated because I, the
server, found a single match looking for but
that match contained no forwarding address and was thus
undeliverable. The details of this match are as follows:
Name : Dark Ages
Uid : dages1
Organisation : Company1
City : Oxford
Tel :
You may reply to this and it will be read by someone who will do
their best to help you. You may reply to Postmaster
including as much detail as possible: at least full name, department,
and approximate geographic region and of course the address you
believe was previously correct.
Sorry I couldn't get your message through this time. Your original
message is attached.
Best wishes,
Your humble Company1 server.
Human contact:
mail message [Click mouse-2 to display message]
30 DGS
23 Feb 2005

31. Trouble shooting Test out address resolution
4/16/2017
Trouble shooting
Test out address resolution
exim -bt
<--
router = perimeter_routes, transport = remote_smtp
host mail-relay.slb.com [ ]
host mail-relay.slb.com [ ]
host mail-relay.slb.com [ ]
host mail-relay.slb.com [ ]
31 DGS
23 Feb 2005

32. Trouble shooting (cont)
4/16/2017
Trouble shooting (cont)
Additional debugging
exim -d+lookup -bt Shows details including LDAP calls database lookup required for
……..
perform_ldap_search: ldapm URL = "ldap:///dc=company1,dc=com?uid,mail,cn,ou,telephonenumber,o?sub?(&(mail=*)(uid=dgraystephens))" server=localhost port=389 sizelimit=0 timelimit=0 tcplimit=-1
after ldap_url_parse: host=localhost port=389
ldap_initialize with URL ldap://localhost:389/ ……
ldap_parse_result yielded 0: Success
LDAP search: returning: cn="Douglas Gray Stephens, Douglas Gray-Stephens, Grey Stevens" o="Company1" ou="Core services" uid="dgraystephens" telephoneNumber=" “
Check LDAP server logs for connection details
32 DGS
23 Feb 2005

33. Controlling fuzzy logic or spam
4/16/2017
Controlling fuzzy logic or spam
Fuzzy logic is good when there is no spam
If spam is an issue, then enable users to opt in or out
Add new component to searches, e.g. MAIL_CN_MATCH = &(mail=*)(cn=${perl{punc_to_spc}{$local_part}}) becomes MAIL_CN_MATCH = &(mail=*)(cn=${perl{punc_to_spc}{$local_part}})(!(description=exclud e:cn))
33 DGS
23 Feb 2005