2 *** WARNING: Preliminary ***
4 This is the README file for maildap, a mailer that does X.500 lookups
5 via LDAP. It is based on mail500.
7 If you are planning to run maildap at your site, you need to create a
8 configuration file. Previous versions required modifying the source
9 code for configuration. This is no longer necessary.
12 *** WHAT maildap DOES: ***
14 maildap is designed to be invoked as a mailer (e.g., from sendmail),
15 similar to the way /bin/mail works. It takes a few required arguments
16 and then a list of addresses to deliver to. It expects to find the
17 message to deliver on its standard input. It looks up the addresses in
18 X.500 to figure out where to route the mail, and then execs sendmail to
19 do the actual delivery. It supports simple aliases, groups, and
20 mailing lists, the details of which are given below.
22 *** HOW IT WORKS (from the sendmail side): ***
24 The idea is that you might have a rule like this in your sendmail.cf
25 file somewhere in rule set 0:
27 R$*<@umich.edu>$* $#maildap$@umich.edu$:<$1>
29 This rule says that any address that ends in @umich.edu will cause
30 the maildap mailer to be called to deliver the mail. You probably
31 also want to do something to prevent addresses like terminator!tim@umich.edu
32 or tim%terminator.rs.itd.umich.edu@umich.edu from being passed to maildap.
33 At U-M, we do this by adding rules like this to rule set 9 where we
34 strip off our local names:
36 R<@umich.edu>$*:$* $>10<@>$1:$2
37 R$+%$+<@umich.edu> $>10$1%$2<@>
38 R$+!$+<@umich.edu> $>10$1!$2<@>
40 You can also feed complete FQDN addresses to maildap. For instance,
41 you could define a class containing the list of domains you want to
44 FQ/etc/mail/maildapdomains
46 and then use a rule in rule set 0 like this:
48 R$*<$=Q>$* $#maildap $@$2 $:<$1@$2>
50 See the sample sendmail.cf in this directory for more details.
51 For sendmail 8.9 (and later) users can use MAILER(maildap) if
52 maildap.m4 is placed within sendmail's cf/mailer directory.
54 The maildap mailer should be defined similar to this in the
57 Mmaildap, P=/usr/local/etc/maildap, F=DFMSmnXuh, A=maildap -f $f -h $h -m $n@$w $u
59 This defines how maildap will be treated by sendmail and what
60 arguments it will have when it's called. The various flags specified
61 by the F=... parameter are explained in your local sendmail book (with
62 any luck). The arguments to maildap are as follows:
64 -f Who the mail is from. This will be used as the address
65 to which any errors should be sent (unless the address
66 specifies a mailing list - see below). Normally, sendmail
67 defines the $f macro to be the sender.
69 -h The domain for which the mail is destined. This is passed
70 in to maildap via the $h macro, which is set by the
71 $@ metasymbol in the rule added to rule set 0 above.
72 It's normally used when searching for groups.
74 -m The mailer-daemon address. If errors have to be sent,
75 this is the address they will come from. $n is normally
76 set to mailer-daemon and $w is normally the local host
79 The final argument $u is used to stand for the addresses to which to
82 *** HOW IT WORKS (from the maildap side): ***
84 When maildap gets invoked with one or more names to which to deliver
85 mail, it searches for each name in X.500. Where it searches, and what
86 kind(s) of search(es) is controlled by a configuration file. There
87 are a number of different approaches to handling mail and no general
88 rules can be given. We will however present some examples of what you
89 can do. The new maildap is designed to be flexible and able to
90 accommodate most scenarios.
92 For instance, if you are following the mail distribution model that
93 the old maildap used, you need lines in the configuration file like
96 search ldap:///ou=People, dc=OpenLDAP, dc=org??sub?\
97 (|(uid=%25l)(cn==%25l))
99 search ldap:///ou=System Groups, ou=Groups, dc=OpenLDAP, dc=org??sub?\
100 (&(cn=%25l)(associatedDomain==%25h))
102 search ldap:///ou=User Groups, ou=Groups, dc=OpenLDAP, dc=org??sub?\
103 (&(cn=%25l)(associatedDomain==%25h))
105 As you can see, searches are described by using LDAP URLs. You can
106 have as many searches as you want, but the first search that succeeds
107 completes the processing for a recipient address. You can provide an
108 attribute list in the URL and it will be honored. Otherwise, the
109 attribute list will default as explained below.
111 Filters can contain substitutions. Actually, they *should* contain
112 substitutions or the search result would not change with the recipient
113 address. Since the usual substitution character is % and it has
114 special meaning in URLs, you have to represent it according to the URL
115 syntax, that is, %25, 25 being the hex code of %. The filter can be
116 as complex as you want and you may make as many substitutions as you
117 want. Known substitutions at this time are:
119 %m The recipient address we are considering now, maybe fully
121 %h The host, that is, the value of the -h argument to
123 %l The local part from %m
124 %d The domain part from %m
126 So, in the above example, if the recipient address were
127 name@OpenLDAP.org, maildap would do the the following searches,
128 stopping if it found anything at any step:
130 Search (18) [2]: dc=org@dc=OpenLDAP@ou=People
131 Search subtree (uid=name)
132 Search (18) [3]: dc=org@dc=OpenLDAP@ou=People
133 Search subtree (cn=name)
135 Search (18) [4]: dc=org@dc=OpenLDAP@ou=Groups@ou=System Groups
136 Search subtree & ((cn=name)(associatedDomain=OpenLDAP.org))
138 Search (18) [5]: dc=org@dc=OpenLDAP@ou=Groups@ou=User Groups
139 Search subtree & ((cn=name)(associatedDomain=OpenLDAP.org))
141 [Beware: Currently unimplemented]
142 You can also specify whether you want search results that matched
143 because the entry's RDN matched the search to be given preference
144 or not. At U-M, we only give such preference in the mail group
145 portion of the searches. Beware with this option: the algorithm
146 used to decide whether an entry's RDN matched the search is very
147 simple-minded, and may not always be correct.
149 *** HOW IT WORKS (from the X.500 side): ***
151 First you need to decide what attributes you will search for and what
152 attributes will be used to deliver the message. In the classical
153 maildap, we would search by uid or cn and deliver to the mail
154 attribute. Another model is to search by the mail attribute and
155 deliver to something else, such as the uid if determined that the user
158 *** THE CONFIGURATION FILE
160 The configuration file is composed of lines that prescribe the
161 operation of maildap. Blank lines are ignored and lines beginning
162 with # are considered comments and ignored. Outside comments, the
163 sequence '\', newline, whitespace is ignored so that long lines can be
164 split for readability.
166 Attribute Definitions
168 Lines starting with 'attribute' define the semantics of an attribute.
169 Notice that attributes will be considered in the order they are
170 defined in the configuration file. This means that the presence of
171 some can preempt processing of other attributes and that attributes
172 that simply collect needed information must be defined before others
173 that use that information. The format is:
175 attribute name [multivalued] [final] [multiple-entries] [<syntax>] [<kind>]
177 If the attribute is "multivalued", all values will be considered. If
178 it is not and several values are found the entry is declared in error.
180 If the attribute is "final", its presence in an entry prevents further
181 analysis of the entry.
183 If the attribute is "multiple-entries" and it is of an appropriate
184 syntax that can point to other entries, all such entries are
185 considered, otherwise the entry is in error.
189 recipient The value(s) of this attribute should be
190 used as the address(es) to deliver the message
191 to if they are in an appropriate syntax. If
192 they otherwise point at other entries, they
193 should be retrieved and expanded as necessary
194 to complete the resolution of this entry. The
195 process is recursive and all.
197 errors The value(s) of this attribute represent the
198 entities that should receive error messages
199 for mail messages directed to this entry.
200 The presence of an attribute of this kind
201 force a change in the envelope sender address
204 The known syntaxes are:
206 local-native-mailbox An unqualified mailbox name
207 rfc822 A fully qualified RFC822 mail address
208 rfc822-extended Currently identical to rfc822
209 dn The Distinguished Name of some other entry
210 url A URL either of the mailto: or ldap: styles,
211 others styles, notably file:, could be added.
212 No substitutions are supported currently.
213 search-with-filter=<filter> Do a search on all known search bases
214 with the give filter. The only currenty
215 substitution available is %D, the DN of the
218 The default attributes to search
220 A line starting with "default-attributes" contains a comma-separated
221 list of attributes to use in searches everytime a specific list is not
226 As shown in the example above, lines starting with "search" provide
227 the search bases to use to initially try to resolve each entry or when
228 using attributes of syntax "search-with-filter".
232 A configuration file that approximates the operation of the old
233 maildap runs as follows:
235 attribute errorsTo errors dn
236 attribute rfc822ErrorsTo errors rfc822
237 attribute requestsTo request dn
238 attribute rfc822RequestsTo request rfc822
239 attribute owner owner dn
240 attribute mail multivalued recipient rfc822
241 attribute member multivalued recipient dn
242 attribute joinable multiple-entries recipient \
243 search-with-filter=(memberOfGroup=%D)
245 default-attributes objectClass,title,postaladdress,telephoneNumber,\
246 mail,description,owner,errorsTo,rfc822ErrorsTo,requestsTo,\
247 rfc822RequestsTo,joinable,cn,member,moderator,onVacation,uid,\
250 # Objectclasses that, when present, identify an entry as a group
251 group-classes mailGroup
253 search ldap:///ou=People, dc=OpenLDAP, dc=org??sub?\
254 (|(uid=%25l)(cn==%25l))
256 search ldap:///ou=System Groups, ou=Groups, dc=OpenLDAP, dc=org??sub?\
257 (&(cn=%25l)(associatedDomain==%25h))
259 search ldap:///ou=User Groups, ou=Groups, dc=OpenLDAP, dc=org??sub?\
260 (&(cn=%25l)(associatedDomain==%25h))
262 A configuration that approximates the semantics of the mailRecipient
263 and mailGroup classes used by Netscape:
265 attribute mgrpErrorsTo errors url
266 attribute rfc822ErrorsTo errors rfc822
267 attribute mailRoutingAddress final recipient rfc822
268 attribute mailHost final host forward-to-host
269 attribute uid final recipient local-native-mailbox
270 attribute uniqueMember multivalued recipient dn
271 attribute mgrpRFC822MailMember multivalued recipient rfc822-extended
272 attribute mgrpDeliverTo multivalued multiple-entries recipient url
274 default-attributes objetcClass,mailRoutingAddress,mailHost,uid,uniqueMember,\
275 mgrpRFC822MailMember,mgrpErrorsTo,rfc822ErrorsTo
277 # Objectclasses that, when present, identify an entry as a group
278 group-classes mailGroup
280 search ldap://localhost/dc=OpenLDAP,dc=org?\
281 objectClass,mailRoutingAddress,mailHost,uid?\
283 (&(|(mail=%25m)(mailAlternateAddress=%25m))(objectClass=mailRecipient))
285 search ldap://localhost/dc=OpenLDAP,dc=org?\
286 objectClass,uniqueMember,mgrpRFC822MailMember,mgrpErrorsTo,mgrpDeliverTo,rfc822ErrorsTo?\
288 (&(|(mail=%25m)(mailAlternateAddress=%25m))(objectClass=mailGroup))
290 [ The rest is from the original README and I did not rewrite it yet ]
292 In X.500, there are several new attribute types and one new object
293 class defined that maildap makes use of. At its most basic, for normal
294 entries maildap will deliver to the value(s) listed in the
295 rfc822Mailbox attribute of the entry. For example, at U-M my entry has
298 mail= tim@terminator.rs.itd.umich.edu
300 So mail sent to tim@umich.edu will be delivered via maildap to that
301 address. If there were multiple values for the mail attribute, multiple
302 copies of the mail would be sent.
304 A new object class, rfc822MailGroup, and several new attributes have
305 been defined to handle email groups/mailing lists. To use this, you
306 will need to add this to your local oidtable.oc:
308 # object class for representing rfc 822 mailgroups
309 rfc822MailGroup: umichObjectClass.2 : \
312 rfc822Mailbox, member, memberOfGroup, owner, \
313 errorsTo, rfc822ErrorsTo, requestsTo, rfc822RequestsTo,
314 joinable, associatedDomain, \
315 description, multiLineDescription, \
316 userPassword, krbName, \
317 telecommunicationAttributeSet, postalAttributeSet
319 And you will need to add these to your local oidtable.at:
321 # attrs for rfc822mailgroups
322 multiLineDescription: umichAttributeType.2 : CaseIgnoreList
323 rfc822ErrorsTo: umichAttributeType.26 : CaseIgnoreIA5String
324 rfc822RequestsTo: umichAttributeType.27 : CaseIgnoreIA5String
325 joinable: umichAttributeType.28 : Boolean
326 memberOfGroup: umichAttributeType.29 : DN
327 errorsTo: umichAttributeType.30 : DN
328 requestsTo: umichAttributeType.31 : DN
330 The idea was to define a kind of hybrid mail group that could handle
331 people who were in X.500 or not. So, for example, members of a group
332 can be specified via the member attribute (for X.500 members) or the
333 rfc822MailBox attribute (for non-X.500 members). Similarly for the
334 errorsTo and rfc822ErrorsTo, and the requestsTo and rfc822RequestsTo
337 To create a real mailing list, with a list maintainer, all you have to
338 do is create an rfc822MailGroup and fill in the errorsTo or
339 rfc822ErrorsTo attributes (or both). That will cause any errors
340 encountered when delivering mail to the group to go to the addresses
341 listed (or X.500 entry via it's mail attribute).
343 If you fill in the requestsTo or rfc822RequestsTo (or both) attributes,
344 mail sent to groupname-request will be sent to the addresses listed
345 there. maildap does this automatically, so you don't have to explicitly
346 add the groupname-request alias to your group.
348 To allow users to join a group, there is the joinable flag. If TRUE,
349 maildap will search for entries that have a memberOfGroup attribute
350 equal to the DN of the group, using the same algorithm it used to find
351 the group in the first place (i.e. the DNs and filters listed in the
352 base array). This allows people to join (or subscribe to) a group
353 without having to modify the group entry directly. If joinable is
354 FALSE, the search is not done.
356 Finally, keep in mind that this is somewhat experimental at the moment.
357 We are using it in production at U-M, but your mileage may vary...