.TH MAIL500 8C "20 August 2000" "OpenLDAP LDVERSION"
.\" $OpenLDAP$
.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
.SH NAME
mail500 \- X.500 capable mailer
.LP
fax500 \- X.500 capable fax delivery agent
.SH SYNOPSIS
.B LIBEXECDIR/mail500 [\-d level] [\-f mailfrom]
.B [\-h hostname] [\-l ldaphost]
.B [\-m address] [\-v vacationhost]
.LP
.B LIBEXECDIR/fax500 [\-d level] [\-f mailfrom]
.B [\-h hostname] [\-l ldaphost]
.B [\-m address]
.SH DESCRIPTION
.B mail500
is an LDAP/X.500-capable mailer, suitable to be invoked from a
mail delivery agent such as
.BR sendmail (8).
It supports mail to both individuals and groups.
.B fax500
is an LDAP/X.500-capable facsimile delivery agent.  It utilizes the
Internet remote-printing experiment (tpc.int).  For more
information on tpc.int, look in
.B /mrose/tpc
on
.BR ftp.ics.uci.edu ,
or send mail to
.BR tpc-faq@town.hall.org .
.SH OPTIONS
.RB \- d level
Turn on debugging as defined by
.I level.
This option directs
.B mail500/fax500
to produce various debugging output via the
.BR syslog (8)
facility at the LOG_ALERT level.
.TP
.BI \-f " mailfrom"
This option tells
.B mail500/fax500
what to set the envelop from address to when (re)invoking sendmail
to deliver mail.
.I mailfrom
should be a valid email address.  Normally, this option is passed
to
.B mail500/fax500
via the sendmail.cf(5) mailer definition, and is set
to something like the $f macro.
.TP
.BI \-l " ldaphost"
Specify an alternate host on which the LDAP server is running.
.TP
.BI \-m " address"
If
.I mail500/fax500
produces a rejection message, this is the
.I address
from which it will com.  Normally, this option is passed to
.I mail500/fax500
via the sendmail.cf(5) mailer definition, and is set to something
like $n@$w (typically, mailer-daemon@hostname).
.TP
.BI \-v " vacationhost"
If the vacation facility is operative, this option specifies the
host to which the mail of users who are on vacation should be sent.
.SH HOW MAIL500 AND FAX500 WORK
When mail500/fax500 gets invoked with one or more names to which to
deliver mail, it searches for each name in X.500.  Where it searches,
and what kind(s) of search(es) it does are compile-time configurable
by changing the
.B base
array in
.BR main.c .
For example, the configuration we use at U-M is like this:
.LP
.nf
Base    base[] =
	{ "ou=People, o=University of Michigan, c=US", 0
		"uid=%s", "cn=%s", NULL,
	  "ou=System Groups, ou=Groups, o=University of Michigan, c=US", 1
		"(&(cn=%s)(associatedDomain=%h))", NULL, NULL,
	  "ou=User Groups, ou=Groups, o=University of Michigan, c=US", 1
		"(&(cn=%s)(associatedDomain=%h))", NULL, NULL,
	  NULL
	};
.fi
.LP
which means that in delivering mail to "name@umich.edu"
.B mail500/fax500would do the
the following searches, stopping if it finds a match at any step:
.LP
.nf
subtree search of "ou=People, o=University of Michigan, c=US"
	for (uid=name)
subtree search of "ou=People, o=University of Michigan, c=US"
	for (cn=name)
subtree search of "ou=System Groups, ou=Groups, o=University of Michigan, c=US"
	for (&(cn=name)(associatedDomain=umich.edu))
subtree search of "ou=User Groups, ou=Groups, o=University of Michigan, c=US"
	for (&(cn=name)(associatedDomain=umich.edu))
.fi
.LP
Notice that when specifying a filter %s is replaced by the name,
or user portion of the address while %h is replaced by whatever is
passed in to
.B mail500/fax500
via the
.RB \- h
option (typically the host portion of the address).
.LP
You can also specify whether you want search results that matched
because the entry's RDN matched the search to be given preference
or not.  At U-M, we only give such preference in the mail group
portion of the searches.  Beware with this option:  the algorithm
used to decide whether an entry's RDN matched the search is very
simple-minded, and may not always be correct.
.LP
There is currently no limit on the number of areas searched (the base
array can be as large as you want), and an arbitrary limit of 2 filters
for each base.  If you want more than that, simply changing the 3 in
the typedef for Base should do the trick.
.SH X.500 SUPPORT
In X.500, there are several new attribute types and one new object
class defined that
.B mail500/fax500
uses.  At its most basic, for normal
entries
.B mail500
will deliver to the value(s) listed in the
.B mail
attribute of the entry, and
.B fax500
will attempt to deliver a fax to the telephone number listed in the
.B facsimileTelephoneNumber
attribute.  For example, at U-M my entry has the attribute
.LP
.nf
	mail= tim@terminator.rs.itd.umich.edu
.fi
.LP
So mail sent to tim@umich.edu will be delivered via
.B mail500
to that
address (assuming the
.BR sendmail.cf (5)
file is set up to call
.B mail500
for mail to somebody@umich.edu - see below).  If there were multiple
values for the mail attribute, multiple copies of the mail would be sent.
.LP
In the case of
.BR fax500 , if my entry has the attribute
.LP
.nf
	facsimileTelephoneNumber= +1 313 764 5140
.fi
.LP
A message sent to tim@fax.umich.edu (assuming the sendmail.cf file
is set up to pass mail @fax.umich.edu to
.BR fax500 \-
see below)
will generate a message to
remote-printer.Timothy_A_Howes@0.4.1.5.4.6.7.3.1.3.1.tpc.int.
.LP
A new object class, rfc822MailGroup, and several new attributes have
been defined to handle email groups/mailing lists.  To use this, you
will need to add this to your local
.BR oidtable.oc :
.LP
.nf
	# object class for representing rfc 822 mailgroups
	rfc822MailGroup:        umichObjectClass.2 : \\
		top : \\
		cn : \\
		rfc822Mailbox, member, memberOfGroup, owner, \\
		errorsTo, rfc822ErrorsTo, requestsTo, rfc822RequestsTo, \\
		joinable, associatedDomain, \\
		description, multiLineDescription, \\
		userPassword, krbName, \\
		telecommunicationAttributeSet, postalAttributeSet
.fi
.LP
And you will need to add these to your local oidtable.at:
.LP
.nf
	# attrs for rfc822mailgroups
	multiLineDescription:   umichAttributeType.2    : CaseIgnoreList
	rfc822ErrorsTo:         umichAttributeType.26   : CaseIgnoreIA5String
	rfc822RequestsTo:       umichAttributeType.27   : CaseIgnoreIA5String
	joinable:               umichAttributeType.28   : Boolean
	memberOfGroup:          umichAttributeType.29   : DN
	errorsTo:               umichAttributeType.30   : DN
	requestsTo:             umichAttributeType.31   : DN
.fi
.LP
The idea was to define a kind of hybrid mail group that could handle
people who were in X.500 or not.  So, for example, members of a group
can be specified via the member attribute (for X.500 members) or the
rfc822MailBox attribute (for non-X.500 members).  Similarly for the
errorsTo and rfc822ErrorsTo, and the requestsTo and rfc822RequestsTo
attributes.
.LP
To create a real mailing list, with a list maintainer, all you have to
do is create an rfc822MailGroup and fill in the errorsTo or
rfc822ErrorsTo attributes (or both).  That will cause any errors
encountered when delivering mail to the group to go to the addresses
listed (or X.500 entry via it's mail attribute).
.LP
If you fill in the requestsTo or rfc822RequestsTo (or both) attributes,
mail sent to groupname-request will be sent to the addresses listed
there.  If you fill in the owner attribute, mail sent to
groupname-owner will be sent to the addresses listed there.  mail500
does this automatically, so you don't have to explicitly add the
groupname-request or groupname-owner aliases to your group.
.LP
To allow users to join a group, there is the joinable flag.  If TRUE,
mail500 will search for entries that have a memberOfGroup attribute
equal to the DN of the group, using the same algorithm it used to find
the group in the first place (i.e. the DNs and filters listed in the
base array).  This allows people to join (or subscribe to) a group
without having to modify the group entry directly.  If joinable is
FALSE, the search is not done.
.SH SENDMAIL CONFIGURATION
The idea is that you might have a rule like this in your sendmail.cf
file somewhere in rule set 0:
.LP
.nf
        R$*<@umich.edu>$*       $#mail500$@umich.edu$:<$1>
        R$*<@fax.umich.edu>$*	$#fax500$@fax.umich.edu$:<$1>
.fi
.LP
These rules say that any address that ends in @umich.edu will cause
the mail500 mailer to be called to deliver the mail, and any address
that ends in @fax.umich.edu will cause the fax500 mailer to
be called.  You probably
also want to do something to prevent addresses like terminator!tim@umich.edu
or tim%terminator.rs.itd.umich.edu@umich.edu from being passed to mail500.
At U-M, we do this by adding rules like this to rule set 9 where we
strip off our local names:
.LP
.nf
	R<@umich.edu>$*:$*                 $>10<@>$1:$2
	R$+%$+<@umich.edu>                 $>10$1%$2<@>
	R$+!$+<@umich.edu>                 $>10$1!$2<@>
.fi
.LP
Of course, you would substitute your domain name for umich.edu in the
above examples.  See the sample sendmail.cf file in the ldap source
directory clients/mail500/ for more details.
.LP
The mail500 and fax500 mailers should be defined similar to this in the
sendmail.cf file:
.LP
.nf
Mmail500, P=LIBEXECDIR/mail500, F=DFMSmnXuh, A=mail500 -f $f -h $h -m $n@$w $u
Mfax500, P=LIBEXECDIR/fax500, F=DFMSmnXuh, A=fax500 -f $f -h $h -m $n@$w $u
.fi
.LP
This defines how mail500/fax500 will be treated by sendmail and what
arguments it will have when it's called.  The various flags specified
by the F=... parameter are explained in your local sendmail book (with
any luck).  The arguments to mail500/fax500 are as defined under OPTIONS
above.  The final argument $u is used to stand for the addresses to which
to deliver the mail.
.SH NOTES
The default values for several #defines that control how mail500 
and fax500 works are configured at compile time in the 
include/ldapconfig.h.edit include file.  You should edit this 
file to suit your site.
.SH BUGS
mail500/fax500 should use the ldap_getfilter(3) facility, instead of 
compiling in the search filters to use.  This is shameful.
.LP
The support for joinable groups (searching to find members who have
set something in their own entry) is really a hack because we did not
have good enough access control to allow people to add and delete
themselves from the group itself.
.LP
At one point, mail500 and fax500 were exactly the same binary, and
would behave appropriately based on how they were invoked.  Unfortunately,
several new features (e.g. vacation support) were added to mail500
but not to fax500.
.SH "SEE ALSO"
.BR ldap(3),
.BR sendmail.cf(5),
.BR sendmail(8),
.SH ACKNOWLEDGEMENTS
.B	OpenLDAP
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
.B	OpenLDAP
is derived from University of Michigan LDAP 3.3 Release.