]> mj.ucw.cz Git - umpf.git/blob - umpf.1
more fixes for manpage
[umpf.git] / 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.