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