umpf.1

   1 .TH "umpf" 1
   2 .SH NAME
   3 umpf \- universal mail processing filter
   4 .SH SYNOPSIS
   5 .B umpf
   6 [-c config_file] [-m default_mailbox]
   7 .SH AVAILABILITY
   8 Linux only.
   9 .SH DESCRIPTION
  10 Umpf is a program that reads an e-mail from stdin and according to the config
  11 file decides, what to do with it. It is possible to forward the e-mail,
  12 filter it through external program and, of course, deliver it to the local
  13 mailbox.  IMAP support is planned, but not ready yet.
  14 .SH OPTIONS
  15 .TP
  16 .B \-c "\|file\^"
  17 Set an alternative location of the config file.
  18 .TP
  19 .B \-m "\|file\^"
  20 Set an alternative location of the default mailbox.
  21 .SH CONFIGURATION
  22 The program reads a config file (default location is
  23 .I ~/.umpf
  24 ) and according
  25 to the rules provided it decides, what to do with it. If no rule is matched,
  26 or some action fails, or the config file cannot be parsed, e-mail is
  27 delivered to the default mailbox (default location is
  28 .I /var/mail/login
  29 , program needs setgid to be able to use it).
  30 .SS VARIABLES
  31 Variables can be specified in the config file. Their identifiers must start
  32 with the letter \fB$\fP, variables have three types that are distinguisghed according to the case of
  33 the identifiers. Upper case identifiers are reserved for automatic variables
  34 like message size, it is possible to modify them but it is not encouraged.
  35 Variables with identifiers starting with an upper-case letter but mixed case
  36 otherwise correspond to values of e-mail headers, assigning to them will
  37 change the headers. Variables with identifiers starting with a lower case
  38 letter are intended for general use. Otherwise, variable identifiers are
  39 case-insensitive, ie. $abc refers to the same variable as $aBc, but not the
  40 same as $Abc and all of these variables differ from $ABC.
  41 .SS AUTOMATIC VARIABLES
  42 Config file recognizes these automatic variables:
  43 .TP
  44 .B $MAIL_LEN
  45 refers to the length of the e-mail, including headers
  46 .TP
  47 .B $LAST_EXIT_CODE
  48 refers to the exit code of last external program executed (actions filter or
  49 pipe can be used to do it)
  50 .TP
  51 .B $LAST_OUTPUT
  52 refers to the output of last external program executed by action pipe
  53 .SS COMMANDS
  54 A command is either an action specification or an assignment. All the
  55 commands must end with semicolon. Commands can be grouped in blocks bounded by
  56 braces.
  57 .SS ASSIGNMENTS
  58 Assignment is specified in a following way:
  59 .P
  60 \fILvalue\fB = \fIRvalue\fB ;\fP
  61 .P
  62 Lvalue is a variable identifier. Rvalue can be variable, a constant (either a
  63 string constant that must be given in double quotes or an integer) or an
  64 expression consisting of variables, constants and binary operations
  65 \fB.\fP, \fB+\fP, \fB\-\fP, \fB*\fP and \fB/\fP, operation \fB.\fP stands for string
  66 contatenations, the rest of them are arithmetic operations.  Doing arithmetic
  67 operations makes sense only on integers. Precedence of the operations can be
  68 specified using parentheses, arithmetic operators have a usual priority,
  69 string concatenations has the lowest priority.
  70 .SS ACTIONS
  71 Actions are specified with an arrow operator.
  72 .TP
  73 .B "-> ;"
  74 means "deliver the e-mail to the default mailbox and exit".
  75 .TP
  76 \fB-> \fIexpression\fB ;\fP
  77 means "deliver the e-mail the mailbox specified behind arrow and exit"
  78 .TP
  79 \fB-> pipe \fIexpression\fB ;\fP
  80 means "pipe the e-mail to the external program specified behind pipe
  81 keyword". Output of the program is stored in
  82 .B $LAST_OUTPUT
  83 variable, its exit code is stored in
  84 .B $LAST_EXIT_CODE
  85 variable.
  86 .TP
  87 \fB-> filter \fIexpression\fB ;\fP
  88 means "pipe the e-mail to the external program and replace it with output of the program". All the header variables,
  89 .B $MAIL_LEN
  90 and
  91 .B $LAST_EXIT_CODE
  92 are set accordingly.
  93 .TP
  94 \fB-> discard ;\fP
  95 means just "discard the email and exit".
  96 .TP
  97 \fB-> mail \fIexpression\fB ;\fP
  98 means "forward the e-mail to the address specifed behind the mail keyword and exit"
  99 .TP -1
 100 If action fails, the e-mail is delivered to the default mailbox.
 101 .P
 102 Some of the actions (delivery or forwarding an e-mail) can have keyword copy
 103 in front of the arrow, ie.
 104 .P
 105 \fBcopy -> $mailbox ;\fP
 106 .P
 107 When copy is specified, the program does not exit after doing an action but
 108 continues reading the rules. It also does not deliver to the default mailbox if
 109 action fails.
 110 .SS CONDITIONS
 111 Conditional execution of commands can be specified in a following way:
 112 .P
 113 \fBif (\fIcondition\fB) { \fI...\fB }
 114 .P
 115 \fBif (\fIcondition\fB) { \fI...\fB } else { \fI...\fB }
 116 .P
 117 \fBif (\fIcondition\fB) { \fI...\fB } Ielse if { \fI...\fB } \fI[\fB else { \fI...\fB } \fI]\fP
 118 .P
 119 where the condition can be a constant, a variable or an expression consisting
 120 of following operations:
 121 .TP
 122 .B "&"
 123 is boolean and
 124 .TP
 125 .B "|"
 126 is boolean or
 127 .TP
 128 .B "^"
 129 is boolean xor
 130 .TP
 131 .B "!"
 132 is boolean not
 133 .TP -1
 134 A variable or a constant has a boolean value 0, if its value is either "" or
 135 "0" and 1 otherwise.
 136 .P
 137 Expressions can be compared using following binary relations.
 138 .P
 139 String comparisons:
 140 .TP 5
 141 .B ~~
 142 means "matches" (left operand should be string, right one can be a perl compatible regular expression)
 143 .TP
 144 .B !~
 145 means "does not match"
 146 .TP -1
 147 Integer comparisons (does not make sense on strings):
 148 .TP 5
 149 .B ==
 150 means "is equal to"
 151 .TP
 152 .B !=
 153 means "is not equal to"
 154 .TP
 155 .B <
 156 means "is less than"
 157 .TP
 158 .B >
 159 means "is greater than"
 160 .TP
 161 .B <=
 162 means "is less or equal than"
 163 .TP
 164 .B >=
 165 means "is greater or equal than"
 166 .TP -1
 167 Parentheses can be used to specify a precedence. Boolean operations have greater priority than relation operations.
 168 .SS COMMENTS
 169 All the text behind a hash character up to the end of the line is ignored.
 170 .SH EXIT STATUS
 171 .TP
 172 .B 0
 173 Success
 174 .TP
 175 .B 1
 176 Failure
 177 .TP
 178 .B EX_TEMPFAIL
 179 Temporary OS failure
 180 .SH BUGS
 181 Aer prsenet.
 182 .SH TODO
 183 IMAP support.
 184 .SH AUTHOR
 185 Anicka <anicka@anicka.net>
 186 .SH RESOURCES
 187 Current version of the program can be downloaded at
 188 .B http://www.anicka.net/umpf
 189 .SH COPYING
 190 The program can be used according to the terms of GPL, version 2.