X-Git-Url: http://git.marmaro.de/?a=blobdiff_plain;f=man%2Fslocal.man1;fp=man%2Fslocal.man1;h=cc822f0e3a20e80854422b3880d85b5a428c8167;hb=5aaedc4256d58afe2481d667afdcb5162a914ba9;hp=0000000000000000000000000000000000000000;hpb=2676fdf95667cfa0fec45372dbb956c8645c1119;p=mmh diff --git a/man/slocal.man1 b/man/slocal.man1 new file mode 100644 index 0000000..cc822f0 --- /dev/null +++ b/man/slocal.man1 @@ -0,0 +1,434 @@ +.\" +.\" %nmhwarning% +.\" +.TH SLOCAL %manext1% "%nmhdate%" MH.6.8 [%nmhversion%] +.SH NAME +slocal \- asynchronously filter and deliver new mail +.SH SYNOPSIS +.HP 5 +.na +.B %libdir%/slocal +[address\ info\ sender] +.RB [ \-addr +.IR address ] +.RB [ \-info +.IR data ] +.RB [ \-sender +.IR sender ] +.RB [ \-user +.IR username ] +.RB [ \-mailbox +.IR mbox ] +.\" \%[\-home\ homedir] +.RB [ \-file +.IR file ] +.RB [ \-maildelivery +.IR deliveryfile ] +.RB [ \-verbose " | " \-noverbose ] +.RB [ \-suppressdup " | " \-nosuppressdup ] +.RB [ \-debug ] +.RB [ \-version ] +.RB [ \-help ] +.ad +.SH DESCRIPTION +.B Slocal +is a program designed to allow you to have your inbound +mail processed according to a complex set of selection criteria. +You do not normally invoke +.B slocal +yourself, rather +.B slocal +is invoked on your behalf by your system's Message Transfer Agent +(such as +.BR sendmail ) +when the message arrives. +.PP +The message selection criteria used by +.B slocal is specified +in the file +.RI \*(lq \&.maildelivery \*(rq +in the user's home directory. +You can specify an alternate file with the +.B \-maildelivery +.I file +option. The syntax of this file is specified below. +.PP +The message delivery address and message sender are determined from +the Message Transfer Agent envelope information, if possible. +Under +.BR sendmail , +the sender will obtained from the UUCP +\*(lqFrom:\*(rq line, if present. The user may override these +values with command line arguments, or arguments to the +.B \-addr +and +.B \-sender +switches. +.PP +The message is normally read from the standard input. The +.B \-file +switch sets the name of the file from which the message should be +read, instead of reading stdin. This is useful when debugging a +.RI \*(lq \&.maildelivery \*(rq +file. +.PP +The +.B \-user +switch tells +.B slocal +the name of the user for +whom it is delivering mail. The +.B \-mailbox +switch tells +.B slocal +the name of the user's maildrop file. +.PP +.B slocal +is able to detect and suppress duplicate messages. +To enable this, use the option +.BR \-suppressdup . +.B slocal +will +keep a database containing the Message-ID's of incoming messages, +in order to detect duplicates. Depending on your configuration, +this database will be in either ndbm or Berkeley db format. +.PP +The +.B \-info +switch may be used to pass an arbitrary argument to +sub-processes which +.B slocal +may invoke on your behalf. +.PP +The +.B \-verbose +switch causes +.B slocal +to give information on +stdout about its progress. The +.B \-debug +switch produces more +verbose debugging output on stderr. These flags are useful when +creating and debugging your +.RI \*(lq \&.maildelivery \*(rq +file, as they +allow you to see the decisions and actions that +.B slocal +is taking, as well as check for syntax errors in your +.RI \*(lq \&.maildelivery \*(rq +file. + +.SS "Message Transfer Agents" +Most modern MTAs including +.BR sendmail , +.BR postfix +and +.BR exim +support a \&.forward file for directing incoming mail. +You should include the line +.PP +.RS 5 +\*(lq|\ %libdir%/slocal\ \-user\ username\*(rq +.RE +.PP +in your \&.forward file in your home directory. This will cause +your MTA to invoke +.B slocal +on your behalf when a message arrives. + +.SS "The Maildelivery File" +The +.RI \*(lq \&.maildelivery \*(rq +file controls how +.B slocal +filters and delivers +incoming mail. Each line of this file consists of five fields, separated +by white-space or comma. Since double-quotes are honored, these +characters may be included in a single argument by enclosing the entire +argument in double-quotes. A double-quote can be included by preceding it +with a backslash. Lines beginning with `#' and blank lines are ignored. +.PP +The format of each line in the +.RI \*(lq \&.maildelivery \*(rq +file is: +.PP +.RS 5 +.B header pattern action result string +.RE +.PP +.BR header : +.RS 5 +The name of a header field (such as To, Cc, or From) that is to +be searched for a pattern. This is any field in the headers of +the message that might be present. +.PP +The following special fields are also defined: +.TP \w'defaultrrr'u +.I source +the out-of-band sender information +.TP \w'defaultrrr'u +.I addr +the address that was used to cause delivery to the recipient +.TP \w'defaultrrr'u +.I default +this matches +.B only +if the message hasn't been delivered yet +.TP \w'defaultrrr'u +.I * +this always matches +.RE +.PP +.BR pattern : +.RS 5 +The sequence of characters to match in the specified header field. +Matching is case-insensitive, but does not use regular expressions. +.RE +.PP +.BR action : +.RS 5 +The action to take to deliver the message. When a message is delivered, +a \*(lqDelivery\-Date:\ date\*(rq header is added which indicates the date +and time that message was delivered. +.TP 4 +.I destroy +This action always succeeds. +.TP 4 +.IR file ", " mbox ", or " > +Append the message to the file named by +.IR string . +The message is +appended to the file in mbox (uucp) format. This is the format used by most +other mail clients (such as mailx, elm). If the message can be appended to +the file, then this action succeeds. +.TP 4 +.I mmdf +Identical to +.IR file , +but always appends the message using the MMDF mailbox format. +.TP 4 +.IR pipe " or " | +Pipe the message as the standard input to the command named by +.IR string , +using the Bourne shell +.B sh +to interpret the string. +Prior to giving the string to the shell, it is expanded with the following +built-in variables: +.RS +.TP \w'zzreplyztozaaa'u +$(sender) +the out-of-band sender information +.TP \w'zzreplyztozaaa'u +$(address) +the address that was used to cause delivery to the recipient +.TP \w'zzreplyztozaaa'u +$(size) +the size of the message in bytes +.TP \w'zzreplyztozaaa'u +$(reply\-to) +either the \*(lqReply\-To:\*(rq or \*(lqFrom:\*(rq field of the message +.TP \w'zzreplyztozaaa'u +$(info) +the out-of-band information specified +.RE +.TP 4 +.IR qpipe " or " ^ +Similar to +.IR pipe , +but executes the command +directly, after built-in variable expansion, without assistance from +the shell. This action can be used to avoid quoting special characters +which your shell might interpret. +.TP 4 +.IR folder " or " + +Store the message in the +.B nmh +folder named by +.IR string . +Currently this is handled by piping the message to the +.B nmh +program +.BR rcvstore , +although this may change in the future. +.RE +.PP +.BR result : +.RS 5 +Indicates how the action should be performed: +.TP \w'Azzz'u +.I A +Perform the action. If the action succeeds, then the message +is considered delivered. +.TP \w'Azzz'u +.I R +Perform the action. Regardless of the outcome of the action, +the message is not considered delivered. +.TP \w'Azzz'u +.I ? +Perform the action only if the message has not been delivered. +If the action succeeds, then the message is considered delivered. +.TP \w'Azzz'u +.I N +Perform the action only if the message has not been delivered +and the previous action succeeded. If this action succeeds, then the +message is considered delivered. +.PP +The delivery file is always read completely, so that several matches +can be made and several actions can be taken. +.RE + +.SS "Security of Delivery Files" +In order to prevent security problems, the +.RI \*(lq \&.maildelivery \*(rq +file must be owned either by the user or by root, and must be +writable only by the owner. If this is not the case, the file is +not read. +.PP +If the +.RI \*(lq \&.maildelivery \*(rq +file cannot be found, or does not +perform an action which delivers the message, then +.B slocal +will check for a global delivery file at +.IR %etcdir%/maildelivery . +This file is read according to the same rules. This file must be +owned by the root and must be writable only by the root. +.PP +If a global delivery file cannot be found or does not perform an +action which delivers the message, then standard delivery to the +user's maildrop is performed. + +.SS "Example Delivery File" +To summarize, here's an example delivery file: +.PP +.nf +.ta \w'default 'u +\w'mh-workersxx 'uC +\w'destroy 'uC +\w'result 'u +# +# .maildelivery file for nmh's slocal +# +# Blank lines and lines beginning with a '#' are ignored +# +# FIELD PATTERN ACTION RESULT STRING +# + +# File mail with foobar in the \*(lqTo:\*(rq line into file foobar.log +To foobar file A foobar.log + +# Pipe messages from coleman to the program message-archive +From coleman pipe A /bin/message-archive + +# Anything to the \*(lqnmh-workers\*(rq mailing list is put in +# its own folder, if not filed already +To nmh-workers folder ? nmh-workers + +# Anything with Unix in the subject is put into +# the file unix-mail +Subject unix file A unix-mail + +# I don't want to read mail from Steve, so destroy it +From steve destroy A \- + +# Put anything not matched yet into mailbox +default \- file ? mailbox + +# always run rcvtty +* \- pipe R %libdir%/rcvtty +.fi + +.SS "Sub-process environment" +When a process is invoked, its environment is: the user/group-ids are +set to recipient's ids; the working directory is the recipient's home +directory; the umask is 0077; the process has no /dev/tty; the standard +input is set to the message; the standard output and diagnostic output are +set to /dev/null; all other file-descriptors are closed; the environment +variables +.BR $USER , +.BR $HOME , +.B $SHELL +are set appropriately, and no other environment variables exist. +.PP +The process is given a certain amount of time to execute. If the process +does not exit within this limit, the process will be terminated with +extreme prejudice. The amount of time is calculated as ((size / 60) + +300) seconds, where size is the number of bytes in the message (with +30 minutes the maximum time allowed). +.PP +The exit status of the process is consulted in determining the success +of the action. An exit status of zero means that the action succeeded. +Any other exit status (or abnormal termination) means that the action +failed. +.PP +In order to avoid any time limitations, you might implement a process +that began by +.BR fork ()-ing. +The parent would return the appropriate +value immediately, and the child could continue on, doing whatever it +wanted for as long as it wanted. This approach is somewhat risky if +the parent is going to return an exit status of zero. If the parent is +going to return a non-zero exit status, then this approach can lead to +quicker delivery into your maildrop. + +.SH FILES +.fc ^ ~ +.nf +.ta \w'%etcdir%/ExtraBigFileName 'u +^%etcdir%/mts.conf~^nmh mts configuration file +^$HOME/\&.maildelivery~^The file controlling local delivery +^%etcdir%/maildelivery~^Rather than the standard file +^%mailspool%/$USER~^The default maildrop +.fi + +.SH "SEE ALSO" +rcvdist(1), rcvpack(1), rcvstore(1), rcvtty(1), mh\-format(5) + +.SH DEFAULTS +.nf +.RB ` \-noverbose ' +.RB ` \-nosuppressdup ' +.RB ` \-maildelivery "' defaults to $HOME/\&.maildelivery" +.RB ` \-mailbox "' deaults to %mailspool%/$USER" +.RB ` \-file "' defaults to stdin" +.RB ` \-user "' defaults to the current user" +.fi + +.SH CONTEXT +None + +.SH HISTORY +.B Slocal +was originally designed to be backward-compatible with +the +.B maildelivery +facility provided by +.BR MMDF-II . +Thus, the +.RI \*(lq \&.maildelivery \*(rq +file syntax is somewhat limited. But +.B slocal +has been modified and extended, so that is it no longer compatible with +.BR MMDF-II . +.PP +In addition to an exit status of zero, the +.B MMDF +values +.B RP_MOK +(32) and +.B RP_OK +(9) mean that the message has been fully delivered. +Any other non-zero exit status, including abnormal termination, is +interpreted as the +.B MMDF +value +.B RP_MECH +(200), which means +\*(lquse an alternate route\*(rq (deliver the message to the maildrop). + +.SH BUGS +Only two return codes are meaningful, others should be. +.PP +.B Slocal +was originally designed to be backwards-compatible with the +.B maildelivery +functionality provided by +.BR MMDF-II .