git.sur5r.net Git - openldap/blob - clients/maildap/README

   1
   2 *** WARNING:  Preliminary ***
   3
   4 This is the README file for maildap, a mailer that does X.500 lookups
   5 via LDAP.  It is based on mail500.
   6
   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.
  10 there are several
  11
  12 *** WHAT maildap DOES: ***
  13
  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.
  21
  22 *** HOW IT WORKS (from the sendmail side): ***
  23
  24 The idea is that you might have a rule like this in your sendmail.cf
  25 file somewhere in rule set 0:
  26
  27 R$*<@umich.edu>$*       $#maildap$@umich.edu$:<$1>
  28
  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:
  35
  36 R<@umich.edu>$*:$*                 $>10<@>$1:$2
  37 R$+%$+<@umich.edu>                 $>10$1%$2<@>
  38 R$+!$+<@umich.edu>                 $>10$1!$2<@>
  39
  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
  42 serve like this:
  43
  44 FQ/etc/mail/maildapdomains
  45
  46 and then use a rule in rule set 0 like this:
  47
  48 R$*<$=Q>$*              $#maildap $@$2 $:<$1@$2>
  49
  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.
  53
  54 The maildap mailer should be defined similar to this in the
  55 sendmail.cf file:
  56
  57 Mmaildap, P=/usr/local/etc/maildap, F=DFMSmnXuh, A=maildap -f $f -h $h -m $n@$w $u
  58
  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:
  63
  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.
  68
  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.
  73
  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
  77                 name.
  78
  79 The final argument $u is used to stand for the addresses to which to
  80 deliver the mail.
  81
  82 *** HOW IT WORKS (from the maildap side): ***
  83
  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.
  91
  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
  94 these:
  95
  96 search  ldap:///ou=People, dc=OpenLDAP, dc=org??sub?\
  97         (|(uid=%25l)(cn==%25l))
  98
  99 search  ldap:///ou=System Groups, ou=Groups, dc=OpenLDAP, dc=org??sub?\
 100         (&(cn=%25l)(associatedDomain==%25h))
 101
 102 search  ldap:///ou=User Groups, ou=Groups, dc=OpenLDAP, dc=org??sub?\
 103         (&(cn=%25l)(associatedDomain==%25h))
 104
 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.
 110
 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:
 118
 119         %m   The recipient address we are considering now, maybe fully
 120              qualified
 121         %h   The host, that is, the value of the -h argument to
 122              maildap
 123         %l   The local part from %m
 124         %d   The domain part from %m
 125
 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:
 129
 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)
 134
 135         Search (18) [4]: dc=org@dc=OpenLDAP@ou=Groups@ou=System Groups
 136         Search subtree & ((cn=name)(associatedDomain=OpenLDAP.org))
 137
 138         Search (18) [5]: dc=org@dc=OpenLDAP@ou=Groups@ou=User Groups
 139         Search subtree & ((cn=name)(associatedDomain=OpenLDAP.org))
 140
 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.
 148
 149 *** HOW IT WORKS (from the X.500 side): ***
 150
 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
 156 has a local account.
 157
 158 *** THE CONFIGURATION FILE
 159
 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.
 165
 166 Attribute Definitions
 167
 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:
 174
 175 attribute name [multivalued] [final] [multiple-entries] [<syntax>] [<kind>]
 176
 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.
 179
 180 If the attribute is "final", its presence in an entry prevents further
 181 analysis of the entry.
 182
 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.
 186
 187 The known kinds are:
 188
 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.
 196
 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
 202                         of the message.
 203
 204 The known syntaxes are:
 205
 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
 216                         current entry.
 217
 218 The default attributes to search
 219
 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
 222 known.
 223
 224 Search bases
 225
 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".
 229
 230 *** EXAMPLES
 231
 232 A configuration file that approximates the operation of the old
 233 maildap runs as follows:
 234
 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)
 244
 245 default-attributes objectClass,title,postaladdress,telephoneNumber,\
 246         mail,description,owner,errorsTo,rfc822ErrorsTo,requestsTo,\
 247         rfc822RequestsTo,joinable,cn,member,moderator,onVacation,uid,\
 248         suppressNoEmailError
 249
 250 # Objectclasses that, when present, identify an entry as a group
 251 group-classes mailGroup
 252
 253 search  ldap:///ou=People, dc=OpenLDAP, dc=org??sub?\
 254         (|(uid=%25l)(cn==%25l))
 255
 256 search  ldap:///ou=System Groups, ou=Groups, dc=OpenLDAP, dc=org??sub?\
 257         (&(cn=%25l)(associatedDomain==%25h))
 258
 259 search  ldap:///ou=User Groups, ou=Groups, dc=OpenLDAP, dc=org??sub?\
 260         (&(cn=%25l)(associatedDomain==%25h))
 261
 262 A configuration that approximates the semantics of the mailRecipient
 263 and mailGroup classes used by Netscape:
 264
 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
 273
 274 default-attributes objetcClass,mailRoutingAddress,mailHost,uid,uniqueMember,\
 275         mgrpRFC822MailMember,mgrpErrorsTo,rfc822ErrorsTo
 276
 277 # Objectclasses that, when present, identify an entry as a group
 278 group-classes mailGroup
 279
 280 search  ldap://localhost/dc=OpenLDAP,dc=org?\
 281         objectClass,mailRoutingAddress,mailHost,uid?\
 282         sub?\
 283         (&(|(mail=%25m)(mailAlternateAddress=%25m))(objectClass=mailRecipient))
 284
 285 search  ldap://localhost/dc=OpenLDAP,dc=org?\
 286         objectClass,uniqueMember,mgrpRFC822MailMember,mgrpErrorsTo,mgrpDeliverTo,rfc822ErrorsTo?\
 287         sub?\
 288         (&(|(mail=%25m)(mailAlternateAddress=%25m))(objectClass=mailGroup))
 289
 290 [ The rest is from the original README and I did not rewrite it yet ]
 291
 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
 296 the attribute
 297
 298         mail= tim@terminator.rs.itd.umich.edu
 299
 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.
 303
 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:
 307
 308         # object class for representing rfc 822 mailgroups
 309         rfc822MailGroup:        umichObjectClass.2 : \
 310                 top : \
 311                 cn : \
 312                 rfc822Mailbox, member, memberOfGroup, owner, \
 313                 errorsTo, rfc822ErrorsTo, requestsTo, rfc822RequestsTo,
 314                 joinable, associatedDomain, \
 315                 description, multiLineDescription, \
 316                 userPassword, krbName, \
 317                 telecommunicationAttributeSet, postalAttributeSet
 318
 319 And you will need to add these to your local oidtable.at:
 320
 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
 329
 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
 335 attributes.
 336
 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).
 342
 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.
 347
 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.
 355
 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...