1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/src/tmail/tmail.1	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,205 @@
     1.4 +.ig
     1.5 + * ========================================================================
     1.6 + * Copyright 1988-2007 University of Washington
     1.7 + *
     1.8 + * Licensed under the Apache License, Version 2.0 (the "License");
     1.9 + * you may not use this file except in compliance with the License.
    1.10 + * You may obtain a copy of the License at
    1.11 + *
    1.12 + *     http://www.apache.org/licenses/LICENSE-2.0
    1.13 + *
    1.14 + * 
    1.15 + * ========================================================================
    1.16 +..
    1.17 +.TH TMAIL 1 "September 27, 2007"
    1.18 +.SH NAME
    1.19 +tmail \- Mail Delivery Module
    1.20 +.nh
    1.21 +.SH SYNOPSIS
    1.22 +.B tmail
    1.23 +.I [-b format] [\-D] [-f from_name] [\-I inbox_specifier] user[+folder] ...
    1.24 +.SH DESCRIPTION
    1.25 +.I tmail
    1.26 +delivers mail to a user's INBOX or a designated folder.
    1.27 +.I tmail
    1.28 +may be configured as a drop-in replacement for
    1.29 +.IR binmail (1),
    1.30 +.IR mail.local (1)
    1.31 +or any program intended for use for mail delivery by a mail delivery program
    1.32 +such as
    1.33 +.IR sendmail (8).
    1.34 +.PP
    1.35 +.I tmail
    1.36 +is intended to be used for direct delivery by the mailer daemon;
    1.37 +.IR dmail (1)
    1.38 +is the preferred tool for user applications, e.g. a mail delivery
    1.39 +filter such as
    1.40 +.IR procmail (1) .
    1.41 +If
    1.42 +.I tmail
    1.43 +is used for a user application,
    1.44 +then the calling program must be aware of the restrictions noted below.
    1.45 +.PP
    1.46 +When
    1.47 +.I tmail
    1.48 +exits, it returns exit status values to enable the mail delivery program
    1.49 +to determine whether a message was delivered successfully or had a
    1.50 +temporary (requeue for later delivery) or permanent (return to sender)
    1.51 +failure.
    1.52 +.PP
    1.53 +If the 
    1.54 +.I +folder
    1.55 +extension is included in the user argument, 
    1.56 +.I tmail
    1.57 +will attempt to deliver to the designated folder.  If the folder does not 
    1.58 +exist or the extension is not included, the message is delivered to the 
    1.59 +user's INBOX.
    1.60 +If delivery is to INBOX and no INBOX currently exists,
    1.61 +.I tmail
    1.62 +will create a new INBOX, using the \fB-I\fR or \fB-b\fR flag if specified.
    1.63 +.I tmail
    1.64 +recognizes the format of an existing INBOX or folder, and appends the new
    1.65 +message in that format.
    1.66 +.PP
    1.67 +The \fB-b\fR flag specifies a format to create INBOX if INBOX does not
    1.68 +already exist.  This flag requires privileges, and can not be used with
    1.69 +\fB-I\fR.  The argument is
    1.70 +a format name such as mix, mbx, etc.
    1.71 +.PP
    1.72 +The \fB-D\fR flag specifies debugging; this enables additional message
    1.73 +telemetry.
    1.74 +.PP
    1.75 +The \fB-f\fR or \fB-r\fR flag is used by
    1.76 +the mail delivery program to specify a Return-Path.  The header
    1.77 +.br
    1.78 +   Return-Path: <\fIfrom_name\fR> 
    1.79 +.br 
    1.80 +is prepended to the message before delivery.  
    1.81 +.PP
    1.82 +The \fB-I\fR flag is used by the mail delivery program
    1.83 +to specify an alternative INBOX name.  This flag requires privileges,
    1.84 +and can not be used with \fB-b\fR.  This affects the location and format
    1.85 +of INBOX.  If specified, it should be in one of three forms:
    1.86 +.sp
    1.87 +The first form of argument to \fB-I\fR is the string "INBOX", which
    1.88 +means to write to the system default inbox using the system default
    1.89 +mailbox format.  These system defaults are defined when the c-client
    1.90 +library is built.
    1.91 +.sp
    1.92 +The second form of argument to \fB-I\fR is a delivery specification,
    1.93 +consisting of "#driver.", a c-client mailbox format driver name, "/",
    1.94 +and a file name.  This will write to the specified file in the
    1.95 +specified format.  For example, #driver.mbx/INBOX will write to file
    1.96 +"INBOX" in the home directory in mbx format; and
    1.97 +#driver.unix/mail/incoming will write to file "incoming" in the
    1.98 +user's "mail" subdirectory in unix (default UNIX) format.
    1.99 +.sp
   1.100 +The third form of argument to \fB-I\fR is any other name.  Normally,
   1.101 +this will write to the specified file on the user's home directory in
   1.102 +the specified format.  However, certain names are special.  These are:
   1.103 +.PP
   1.104 +.nf
   1.105 +  value       equivalant to
   1.106 +  -----       -------------
   1.107 +  INBOX.MTX   #driver.mtx/INBOX.MTX
   1.108 +  mbox        #driver.unix/mbox
   1.109 +  mail.txt    #driver.tenex/mail.txt
   1.110 +.fi
   1.111 +.PP
   1.112 +If \fB-I\fR is not specified, the default action is \fB-I INBOX\fR.
   1.113 +.PP
   1.114 +If multiple recipients are specified on the command line,
   1.115 +.I tmail
   1.116 +spawns one child process per recipient to perform actual delivery.  This
   1.117 +way of calling
   1.118 +.I tmail
   1.119 +is not recommended; see below under
   1.120 +.IR RESTRICTIONS .
   1.121 +.SH INSTALLATION
   1.122 +If 
   1.123 +.I tmail
   1.124 +is to be used for mail delivery from the mail delivery program, it 
   1.125 +.I must
   1.126 +be installed setuid root.
   1.127 +.sp
   1.128 +If sendmail is the mail delivery program,
   1.129 +.I tmail
   1.130 +is invoked from sendmail.cf.  Look for the "Mlocal" line, and substitute
   1.131 +the path name for the
   1.132 +.I tmail
   1.133 +binary in place of /bin/mail, /usr/lib/mail.local, etc.  You should also
   1.134 +add the flag to invoke
   1.135 +.I tmail
   1.136 +with CRLF style newlines; this is usually done with E=\\r\\n in the Mlocal
   1.137 +line.
   1.138 +.sp
   1.139 +Here is an example of an Mlocal line in sendmail version 8:
   1.140 +.sp
   1.141 +.nf
   1.142 +Mlocal, P=/usr/local/etc/tmail, F=lsDFMAw5:/|@qPrn+,
   1.143 +  S=10/30, R=20/40, E=\\r\\n, T=DNS/RFC822/X-Unix,
   1.144 +  A=tmail $u
   1.145 +.fi
   1.146 +.PP
   1.147 +If
   1.148 +.I tmail
   1.149 +is to be called with the \fB-I\fR flag, it must be invoked with both
   1.150 +real and effective UID root.  Many sendmail configurations invoke the
   1.151 +local mailer as the sending user when that user is local, which
   1.152 +will prevent \fB-b\fR or \fB-I\fR from working.
   1.153 +.SH SECURITY CONSIDERATIONS
   1.154 +If
   1.155 +.I tmail
   1.156 +is invoked by an ordinary user, the Received: header line will
   1.157 +indicate the name or UID of the user that invoked it.
   1.158 +.PP
   1.159 +Ordinary users are not permitted to use the \fB-b\fR or \fB-I\fR flag since
   1.160 +otherwise a user could create any file on another user's directory.
   1.161 +.PP
   1.162 +.I tmail
   1.163 +can deliver mail to home directories.  In addition,
   1.164 +.I tmail
   1.165 +can be used to deliver mail to other mail folders in a home directory
   1.166 +or an inferior directory of a home directory.
   1.167 +.SH RESTRICTIONS
   1.168 +The calling program should invoke
   1.169 +.I tmail
   1.170 +with CRLF newlines, otherwise
   1.171 +.I tmail
   1.172 +will complain in syslog.
   1.173 +.PP
   1.174 +Absolute pathnames and 
   1.175 +.I ~user
   1.176 +specifications are not permitted in
   1.177 +.I +folder
   1.178 +extensions.
   1.179 +.PP
   1.180 +Ordinary users are not permitted to use the \fB-I\fR flag.
   1.181 +.PP
   1.182 +IMAP4 namespace names are not yet supported in 
   1.183 +.I +folder
   1.184 +extensions.
   1.185 +.PP
   1.186 +It is not possible to use
   1.187 +.I tmail
   1.188 +to deliver to
   1.189 +.IR mh (1)
   1.190 +format mailboxes.
   1.191 +.PP
   1.192 +If delivery to multiple users is specified and delivery to any single user
   1.193 +fails, the entire delivery will be reported as having failed, even though
   1.194 +delivery to other users may have succeeded.  If
   1.195 +.I tmail
   1.196 +is used for mail delivery from
   1.197 +.IR sendmail (8),
   1.198 +a separate tmail invocation should be done for each user.  Otherwise a
   1.199 +delivery failure for a single user in a message going to multiple users
   1.200 +will cause multiple deliveries to all the other users every time
   1.201 +.IR sendmail (8),
   1.202 +retries.
   1.203 +.SH AUTHOR
   1.204 +Mark Crispin, MRC@CAC.Washington.EDU
   1.205 +.SH "SEE ALSO"
   1.206 +binmail(1)
   1.207 +.br
   1.208 +sendmail(8)