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 DESCRIPTION
   8 Umpf is a program that reads an e-mail from stdin and according to the config
   9 file decides, what to do with it. It is possible to forward the e-mail,
  10 filter it through external program and, of course, deliver it to the local
  11 mailbox.  IMAP support is planned, but not ready yet.
  12 .SH OPTIONS
  13 .TP
  14 .B \-c "\|file\^"
  15 Set an alternative location of the config file.
  16 .TP
  17 .B \-m "\|file\^"
  18 Set an alternative location of the default mailbox.
  19 .SH CONFIGURATION
  20 The program reads a config file (default location is
  21 .I ~/.umpf
  22 ) and according
  23 to the rules provided it decides, what to do with it. If no rule is matched,
  24 or some action fails, or the config file cannot be parsed, e-mail is
  25 delivered to the default mailbox (default location is
  26 .I /var/mail/login
  27 , program needs setgid to be able to use it).
  28 .SS VARIABLES
  29 Variables can be specified in the config file. Their identifiers must start
  30 with the letter
  31 .B "$"
  32 , 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 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 .B Lvalue = Rvalue ;
  61 .P
  62 Lvalue is a variable identifier. Rvalue can be variable, a constant (constant
  63 must be given in double quotes) or an expression consisting of variables,
  64 constants and binary operations
  65 .B .
  66 ,
  67 .B +
  68 ,
  69 .B -
  70 ,
  71 .B *
  72 and
  73 .B /
  74 , operation
  75 .B .
  76 stands for string contatenations, the rest of them are arithmetic operations.
  77 Doing arithemtic operations makes sense only on integers. Precedence of the
  78 operations can be specified using parentheses.
  79 .SS ACTIONS
  80 Actions are specified with an arrow operator. Plain
  81 .TP
  82 .B -> ;
  83 means "deliver the e-mail to the default mailbox and exit".
  84 .TP
  85 .B -> expression ;
  86 means "deliver the e-mail the mailbox specified behind arrow and exit"
  87 .TP
  88 .B -> pipe expression ;
  89 means "pipe the e-mail to the external program specified behind pipe
  90 keyword". Output of the program is stored in
  91 .B $LAST_OUTPUT
  92 variable, its exit code is stored in
  93 .B $LAST_EXIT_CODE
  94 variable.
  95 .TP
  96 .B -> filter expression
  97 means "pipe the e-mail to the external program and replace it with output of the program". All the headers variables,
  98 .B $MAIL_LEN
  99 and
 100 .B $LAST_EXIT_CODE
 101 are set accordingly.
 102 .TP
 103 .B -> discard ;
 104 means just "discard the email and exit".
 105 .TP
 106 .B -> mail expression ;
 107 means "forward the e-mail to the address specifed behind the mail keyword and exit"
 108 .TP -1
 109 If action fails, the e-mail is delivered to the default mailbox.
 110 .P
 111 Some of the actions (delivery or forwarding an e-mail) can have keyword copy
 112 in front of the arrow, ie.
 113 .P
 114 .B copy -> "mailbox";
 115 .P
 116 When copy is specified, the program does not exit after doing an action but
 117 continues reading the rules. It also does not deliver to default mailbox if
 118 action fails.
 119 .SS CONDITIONS
 120 Conditional execution of commands can be specified in a following way:
 121 .P
 122 .B if (condition) { ... }
 123 .P
 124 .B if (condtion) { ... } else { ... }
 125 .P
 126 .B if (condition) { ... } else if { ... } [ else { ... } ]
 127 .P
 128 where the condition can be a constant, a variable or an expression consisting
 129 of following operations:
 130 .TP
 131 .B &
 132 is binary boolean and
 133 .TP
 134 .B |
 135 is binary boolean or
 136 .TP
 137 .B ^
 138 is binary boolean xor
 139 .TP
 140 .B !
 141 is unary boolean not
 142 .TP -1
 143 A variable or a constant has a boolean value 0, if its value is either "" or
 144 "0" and 1 otherwise.
 145 .P
 146 Expressions can be compared using following binary relations.
 147 .P
 148 String comparisons:
 149 .P
 150 .TP
 151 .B ~~
 152 means "matches" (left operand should be string, right one can be a perl compatible regular expression)
 153 .TP
 154 .B !~
 155 means "does not match"
 156 .TP -1
 157 Integer comparisons (does not make sense on strings):
 158 .TP
 159 .B ==
 160 means "is equal to"
 161 .TP
 162 .B !=
 163 means "is not equal to"
 164 .TP
 165 .B <
 166 means "is lesser than"
 167 .TP
 168 .B >
 169 means "is greater than"
 170 .TP
 171 .B <=
 172 means "is lesser or equal than"
 173 .TP
 174 .B >=
 175 means "is greater or equal than"
 176 .TP -1
 177 Parentheses can be used to specify a precedence. Boolean operations have greater priority than relation operations.
 178 .SS COMMENTS
 179 All the text behind a hash character up to the end of the line is ignored.
 180 .SH EXIT STATUS
 181 .TP
 182 .B 0
 183 Success
 184 .TP
 185 .B 1
 186 Failure
 187 .TP
 188 .B EX_TEMPFAIL
 189 Temporary OS failure
 190 .SH BUGS
 191 Aer prsenet.
 192 .SH TODO
 193 IMAP support.
 194 .SH AUTHOR
 195 Anicka <anicka@anicka.net>
 196 .SH RESOURCES
 197 Current version of the program can be downloaded at
 198 .B http://www.anicka.net/umpf
 199 .SH COPYING
 200 The program can be used according to the terms of GPL, version 2.