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

   1 This is the README file for mail500, a mailer that does X.500 lookups
   2 via LDAP.
   3
   4 If you are planning to run mail500 at your site, there are several
   5 things you will have to tailor in main.c:
   6
   7         LDAPHOST - The host running an LDAP server
   8
   9         base[] - The array telling mail500 where/how to search for
  10                 things.  See the explanation below.
  11
  12 *** WHAT mail500 DOES: ***
  13
  14 mail500 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>$*       $#mail500$@umich.edu$:<$1>
  28
  29 This rule says that any address that ends in @umich.edu will cause
  30 the mail500 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 mail500.
  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 See the sample sendmail.cf in this directory for more details.
  41 For sendmail 8.9 (and later) users can use MAILER(mail500) if
  42 mail500.m4 is placed within sendmail's cf/mailer directory.
  43
  44 The mail500 mailer should be defined similar to this in the
  45 sendmail.cf file:
  46
  47 Mmail500, P=/usr/local/etc/mail500, F=DFMSmnXuh, A=mail500 -f $f -h $h -m $n@$w $u
  48
  49 This defines how mail500 will be treated by sendmail and what
  50 arguments it will have when it's called.  The various flags specified
  51 by the F=... parameter are explained in your local sendmail book (with
  52 any luck).  The arguments to mail500 are as follows:
  53
  54         -f      Who the mail is from.  This will be used as the address
  55                 to which any errors should be sent (unless the address
  56                 specifies a mailing list - see below).  Normally, sendmail
  57                 defines the $f macro to be the sender.
  58
  59         -h      The domain for which the mail is destined.  This is passed
  60                 in to mail500 via the $h macro, which is set by the
  61                 $@ metasymbol in the rule added to rule set 0 above.
  62                 It's normally used when searching for groups.
  63
  64         -m      The mailer-daemon address.  If errors have to be sent,
  65                 this is the address they will come from.  $n is normally
  66                 set to mailer-daemon and $w is normally the local host
  67                 name.
  68
  69 The final argument $u is used to stand for the addresses to which to
  70 deliver the mail.
  71
  72 *** HOW IT WORKS (from the mail500 side): ***
  73
  74 When mail500 gets invoked with one or more names to which to
  75 deliver mail, it searches for each name in X.500.  Where it searches,
  76 and what kind(s) of search(es) it does are compile-time configurable
  77 by changing the base array in main.c.  For example, the configuration
  78 we use at U-M is like this:
  79
  80         Base    base[] =
  81                 { "ou=People, o=University of Michigan, c=US", 0
  82                         "uid=%s", "cn=%s", NULL,
  83                   "ou=System Groups, ou=Groups, o=University of Michigan, c=US", 1
  84                         "(&(cn=%s)(associatedDomain=%h))", NULL, NULL,
  85                   "ou=User Groups, ou=Groups, o=University of Michigan, c=US", 1
  86                         "(&(cn=%s)(associatedDomain=%h))", NULL, NULL,
  87                   NULL
  88                 };
  89
  90 which means that in delivering mail to "name" mail500 would do the
  91 the following searches, stopping if it found anything at any step:
  92
  93         Search (18) [2]: c=US@o=University of Michigan@ou=People
  94         Search subtree (uid=name)
  95         Search (18) [3]: c=US@o=University of Michigan@ou=People
  96         Search subtree (cn=name)
  97
  98         Search (18) [4]: c=US@o=University of Michigan@ou=Groups@ou=System Groups
  99         Search subtree & ((cn=name)(associatedDomain=umich.edu))
 100
 101         Search (18) [5]: c=US@o=University of Michigan@ou=Groups@ou=User Groups
 102         Search subtree & ((cn=name)(associatedDomain=umich.edu))
 103
 104 Notice that when specifying a filter %s is replaced by the name,
 105 or user portion of the address while %h is replaced by whatever is
 106 passed in to mail500 via the -h option (typically the host portion
 107 of the address).
 108
 109 You can also specify whether you want search results that matched
 110 because the entry's RDN matched the search to be given preference
 111 or not.  At U-M, we only give such preference in the mail group
 112 portion of the searches.  Beware with this option:  the algorithm
 113 used to decide whether an entry's RDN matched the search is very
 114 simple-minded, and may not always be correct.
 115
 116 There is currently no limit on the number of areas searched (the base
 117 array can be as large as you want), and an arbitrary limit of 2 filters
 118 for each base.  If you want more than that, simply changing the 3 in
 119 the typedef for Base should do the trick.
 120
 121 *** HOW IT WORKS (from the X.500 side): ***
 122
 123 In X.500, there are several new attribute types and one new object
 124 class defined that mail500 makes use of.  At its most basic, for normal
 125 entries mail500 will deliver to the value(s) listed in the
 126 rfc822Mailbox attribute of the entry.  For example, at U-M my entry has
 127 the attribute
 128
 129         mail= tim@terminator.rs.itd.umich.edu
 130
 131 So mail sent to tim@umich.edu will be delivered via mail500 to that
 132 address.  If there were multiple values for the mail attribute, multiple
 133 copies of the mail would be sent.
 134
 135 A new object class, rfc822MailGroup, and several new attributes have
 136 been defined to handle email groups/mailing lists.  To use this, you
 137 will need to add this to your local oidtable.oc:
 138
 139         # object class for representing rfc 822 mailgroups
 140         rfc822MailGroup:        umichObjectClass.2 : \
 141                 top : \
 142                 cn : \
 143                 rfc822Mailbox, member, memberOfGroup, owner, \
 144                 errorsTo, rfc822ErrorsTo, requestsTo, rfc822RequestsTo,
 145                 joinable, associatedDomain, \
 146                 description, multiLineDescription, \
 147                 userPassword, krbName, \
 148                 telecommunicationAttributeSet, postalAttributeSet
 149
 150 And you will need to add these to your local oidtable.at:
 151
 152         # attrs for rfc822mailgroups
 153         multiLineDescription:   umichAttributeType.2    : CaseIgnoreList
 154         rfc822ErrorsTo:         umichAttributeType.26   : CaseIgnoreIA5String
 155         rfc822RequestsTo:       umichAttributeType.27   : CaseIgnoreIA5String
 156         joinable:               umichAttributeType.28   : Boolean
 157         memberOfGroup:          umichAttributeType.29   : DN
 158         errorsTo:               umichAttributeType.30   : DN
 159         requestsTo:             umichAttributeType.31   : DN
 160
 161 The idea was to define a kind of hybrid mail group that could handle
 162 people who were in X.500 or not.  So, for example, members of a group
 163 can be specified via the member attribute (for X.500 members) or the
 164 rfc822MailBox attribute (for non-X.500 members).  Similarly for the
 165 errorsTo and rfc822ErrorsTo, and the requestsTo and rfc822RequestsTo
 166 attributes.
 167
 168 To create a real mailing list, with a list maintainer, all you have to
 169 do is create an rfc822MailGroup and fill in the errorsTo or
 170 rfc822ErrorsTo attributes (or both).  That will cause any errors
 171 encountered when delivering mail to the group to go to the addresses
 172 listed (or X.500 entry via it's mail attribute).
 173
 174 If you fill in the requestsTo or rfc822RequestsTo (or both) attributes,
 175 mail sent to groupname-request will be sent to the addresses listed
 176 there.  mail500 does this automatically, so you don't have to explicitly
 177 add the groupname-request alias to your group.
 178
 179 To allow users to join a group, there is the joinable flag.  If TRUE,
 180 mail500 will search for entries that have a memberOfGroup attribute
 181 equal to the DN of the group, using the same algorithm it used to find
 182 the group in the first place (i.e. the DNs and filters listed in the
 183 base array).  This allows people to join (or subscribe to) a group
 184 without having to modify the group entry directly.  If joinable is
 185 FALSE, the search is not done.
 186
 187 Finally, keep in mind that this is somewhat experimental at the moment.
 188 We are using it in production at U-M, but your mileage may vary...