6 |
@finalout |
@finalout |
7 |
@c %**end of header |
@c %**end of header |
8 |
@include version.texi |
@include version.texi |
9 |
|
@smallbook |
10 |
|
|
11 |
@defcodeindex op |
@defcodeindex op |
12 |
@defcodeindex cm |
@defcodeindex cm |
55 |
|
|
56 |
@menu |
@menu |
57 |
* Overview:: Preliminary information. |
* Overview:: Preliminary information. |
58 |
|
* Glossary:: Frequently Used Terms Explained. |
59 |
* Configuration:: Writing your own configuration files. |
* Configuration:: Writing your own configuration files. |
60 |
* Rule System:: How to use the Rule System. |
* Rule System:: How to use the Rule System. |
61 |
* Invoking Anubis:: How to invoke the GNU @command{anubis}. |
* Invoking Anubis:: How to invoke the GNU @command{anubis}. |
73 |
@end menu |
@end menu |
74 |
|
|
75 |
|
|
76 |
@node Overview, Configuration, Top, Top |
@node Overview, Glossary, Top, Top |
77 |
@chapter Overview |
@chapter Overview |
78 |
@cindex overview |
@cindex overview |
79 |
@cindex Simple Mail Transport Protocol, SMTP |
@cindex Simple Mail Transport Protocol, SMTP |
87 |
@cindex MUA, Mail User Agent |
@cindex MUA, Mail User Agent |
88 |
@cindex MTA, Mail Transport Agent |
@cindex MTA, Mail Transport Agent |
89 |
|
|
90 |
GNU Anubis is an outgoing mail processor. It goes between the MUA (Mail User |
GNU Anubis is an outgoing mail processor. Its purpose is to receive |
91 |
Agent) and the MTA (Mail Transport Agent), and can perform on the fly various |
the outgoing message, perform some manipulations over its contents, |
92 |
sorts of processing and conversion on the outgoing mail in accord with the |
and to forward the altered message to the mail transport agent. |
93 |
sender's specified rules, based on a highly configurable regular expressions |
|
94 |
system. It operates as a proxy server, independently from mail user agents. |
The usual mail sending scheme looks as follows: the user composes |
95 |
GNU Anubis can edit outgoing mail headers, encrypt and/or sign mail with the |
his message using @dfn{mail user agent} (@dfn{MUA} for short). Once |
96 |
GNU Privacy Guard, build secure SMTP tunnels (Simple Mail Transport Protocol) |
the message is composed, the user sends it. When the MUA receives |
97 |
using the TLS/SSL encryption even if your mail user agent doesn't support it, |
the send command it connects to the @dfn{mail transport agent} |
98 |
or tunnel a connection through a SOCKS proxy server. |
(@dfn{MTA} for short) and passes it the message for delivery. The |
99 |
|
figure below illustrates this interaction: |
100 |
@sp 1 |
|
101 |
@smallexample |
@smallexample |
102 |
--------* --------** ------*** |
+-------+ +-------+ |
103 |
| MUA | ---> | Anubis | ---> | MTA | |
| MUA | ---[outmsg]---> | MTA | ... [outmsg] |
104 |
--------- ---------- --------- |
+-------+ +-------+ | |
105 |
|
| |
106 |
@r{* Mail User Agent (client)} |
V |
107 |
@r{** An outgoing mail processor and the SMTP tunnel.} |
+--------------+ |
108 |
@r{*** Mail Transport Agent (server)} |
| Recipient's | |
109 |
@end smallexample |
| Mailbox | |
110 |
|
+--------------+ |
111 |
@sp 1 |
|
112 |
Some quick definitions: |
@end smallexample |
113 |
|
|
114 |
@dfn{Protocol}---any standard for the exchange of information. A protocol |
As shown in this figure, the outgoing message (@dfn{outmsg}), reaches |
115 |
|
the recipient's mailbox unaltered. |
116 |
|
|
117 |
|
However, there are situations where it may be necessary to modify |
118 |
|
the outgoing message before it reaches MTA. As the simplest example, |
119 |
|
the user might wish to sign the outgoing messages with his PGP |
120 |
|
key, but his MUA does not support this operation or supports it |
121 |
|
unconditionally. |
122 |
|
|
123 |
|
In such cases, installing GNU Anubis between the MUA and MTA |
124 |
|
allows the user to perform any additional processing on the |
125 |
|
sent message. The figure below illustrates this concept: |
126 |
|
|
127 |
|
@smallexample |
128 |
|
+-------+ +--------+ +-------+ |
129 |
|
| MUA | ---[outmsg]---> | Anubis | ---[modmsg]---> | MTA | |
130 |
|
+-------+ +--------+ +-------+ |
131 |
|
| |
132 |
|
[modmsg] |
133 |
|
. |
134 |
|
. |
135 |
|
V |
136 |
|
+--------------+ |
137 |
|
| Recipient's | |
138 |
|
| Mailbox | |
139 |
|
+--------------+ |
140 |
|
@end smallexample |
141 |
|
|
142 |
|
The outgoing message is processed by GNU Anubis, and it is |
143 |
|
the resulting message (@dfn{modmsg}) that reaches the MTA. |
144 |
|
|
145 |
|
GNU Anubis is able to perform on messages a wide set of operations, |
146 |
|
such as modifying message headers or body, encrypting or signing |
147 |
|
messages with GPG (GNU Privacy Guard) keys, installing secure tunnels |
148 |
|
to MTA using TLS/SSL encryption, tunneling messages through |
149 |
|
SOCKS proxies, etc. |
150 |
|
|
151 |
|
When the set of built-in operations is not enough, the user can |
152 |
|
define his own operations using Guile, a @dfn{GNU's Ubiquitous |
153 |
|
Intelligent Language for Extensions}. |
154 |
|
|
155 |
|
The message processing is controlled by system-wide and per-user |
156 |
|
configuration files written in a flexible and easy to use |
157 |
|
command scripting language, specially desgined for this |
158 |
|
purpose. |
159 |
|
|
160 |
|
@node Glossary, Configuration, Overview, Top |
161 |
|
@chapter Glossary of Frequently Used Terms |
162 |
|
|
163 |
|
@table @dfn |
164 |
|
@item Protocol |
165 |
|
Any standard for the exchange of information. A protocol |
166 |
defines the specific wording and control flow for communications between |
defines the specific wording and control flow for communications between |
167 |
two or more programs, devices, or systems. |
two or more programs, devices, or systems. |
168 |
|
|
169 |
@dfn{SMTP}---Simpe Mail Tansport Protocol is a common mechanism for exchanging |
@item SMTP |
170 |
|
Simpe Mail Tansport Protocol is a common mechanism for exchanging |
171 |
mail across a network. This protocol is described in the RFC 821 document. |
mail across a network. This protocol is described in the RFC 821 document. |
172 |
|
|
173 |
@dfn{Daemon}---We use a term @dfn{daemon} as a process that runs in the |
@item Daemon |
174 |
|
We use a term @dfn{daemon} to define a process that runs in the |
175 |
background, doing automated processing. |
background, doing automated processing. |
176 |
|
|
177 |
@dfn{Server}---a server provides information or other services for its |
@item Server |
178 |
clients. Most network protocols are client-server based. This term usually |
A server provides information or other services for its |
179 |
|
clients. Most network protocols are client--server based. This term usually |
180 |
refers to an entire machine, but it can refer (and we're doing that) also |
refers to an entire machine, but it can refer (and we're doing that) also |
181 |
to the particular program or process, on that machine, that provides the |
to the particular program or process, on that machine, that provides the |
182 |
service. |
service. |
183 |
|
|
184 |
@dfn{Proxy}---We use a term @dfn{proxy} to define a program, which goes |
@item Proxy |
185 |
|
We use a term @dfn{proxy} to define a program, which goes |
186 |
between the MUA and the MTA (it makes a tunnel). It can be used as a gateway |
between the MUA and the MTA (it makes a tunnel). It can be used as a gateway |
187 |
to an outside world, while using a firewall. The firewalled host sends a data |
to the outside world, while using a firewall. In this case the host |
188 |
to the proxy server, which forwards it to the real server outside, collects |
under the firewall sends data to the proxy server, which in turn |
189 |
|
forwards it to the real server outside, receives |
190 |
the response, and passes it back to the internal host. |
the response, and passes it back to the internal host. |
191 |
|
|
192 |
|
@item Guile |
193 |
|
GNU's Ubiquitous Intelligent Language for Extensions. It provides a |
194 |
|
Scheme interpreter conforming to the R4RS language specification. GNU |
195 |
|
Anubis uses Guile as its extension language. |
196 |
|
For more information about Guile, |
197 |
|
@xref{Top,,Overview,guile,The Guile Reference Manual}. |
198 |
|
|
199 |
|
@item GPG |
200 |
|
GNU Privacy Guard, a tool compatible with the Pretty Good Privacy. |
201 |
|
@end table |
202 |
|
|
203 |
@node Configuration, Rule System, Overview, Top |
@node Configuration, Rule System, Glossary, Top |
204 |
@chapter Configuration |
@chapter Configuration |
205 |
@cindex configuration |
@cindex configuration |
206 |
@cindex settings |
@cindex settings |
214 |
specifies what GNU Anubis should do for a particular user. |
specifies what GNU Anubis should do for a particular user. |
215 |
To protect your passwords in the configuration files, use the 0600 |
To protect your passwords in the configuration files, use the 0600 |
216 |
(u=rw,g=,o=) permissions, otherwise GNU Anubis won't accept them. |
(u=rw,g=,o=) permissions, otherwise GNU Anubis won't accept them. |
217 |
Hash-marked comments (@samp{#}) and white lines in the configuration |
|
218 |
files are ignored. |
@subheading Lexical Structure |
219 |
|
|
220 |
|
Both configuration files use simple line-oriented syntax. Each |
221 |
|
line introduces a single statement. A statement consists of |
222 |
|
@dfn{words}, each word being defined as a contiguous sequence of |
223 |
|
non-whitespace symbols. A word may be composed of alphanumeric |
224 |
|
characters and any of the following punctuation symbols: |
225 |
|
@samp{_}, @samp{.}, @samp{/}, @samp{-}. Any arbitrary sequence |
226 |
|
of characters enclosed in a pair of doublequotes is also recognized |
227 |
|
as a word. |
228 |
|
|
229 |
|
The familiar shell @dfn{here document} syntax may be used to produce |
230 |
|
a word containing several lines of text. The syntax is: |
231 |
|
|
232 |
|
@smallexample |
233 |
|
<<[-]delimiter |
234 |
|
text |
235 |
|
delimiter |
236 |
|
@end smallexample |
237 |
|
|
238 |
|
If ``here document'' starts with @samp{<<-}, then all leading tab |
239 |
|
characters are stripped from input lines and the line containing |
240 |
|
@dfn{delimiter}. This allows to indent here-document in a natural |
241 |
|
fashion. |
242 |
|
|
243 |
|
To summarize all the above, let's consider the example: |
244 |
|
|
245 |
|
@smallexample |
246 |
|
@group |
247 |
|
first-word "second word" <<-EOT |
248 |
|
Third word |
249 |
|
containing several |
250 |
|
lines of text |
251 |
|
EOT |
252 |
|
@end group |
253 |
|
@end smallexample |
254 |
|
|
255 |
@noindent |
@noindent |
256 |
The system configuration file may contain the following sections: |
This line contains three words: @samp{first-word}, @samp{second word} |
257 |
|
and the third one composed of the three lines between the @samp{EOT} |
258 |
|
markers. |
259 |
|
|
260 |
|
If a statement is very long, it may be split among several lines |
261 |
|
of text. To do so, preceede the newline characters with a backslash |
262 |
|
@samp{\}, e.g.: |
263 |
|
|
264 |
@enumerate |
@smallexample |
265 |
@item |
@group |
266 |
@dfn{The CONTROL section}. |
a very long statement\ |
267 |
@* |
occupying several lines\ |
268 |
Required. This specifies the basic GNU Anubis behavior. |
of text |
269 |
@item |
@end group |
270 |
@dfn{The TRANSLATION section}. |
@end smallexample |
271 |
@* |
|
272 |
Optional. This specifies a translation map for remapping |
A @samp{#} in a line starts a @dfn{comment}. It and the rest of |
273 |
remote or local users. |
the line are ignored. Comments may appear on any of the lines in |
274 |
@end enumerate |
the configuration file, except on a commands and within a |
275 |
|
``here-document'' construction. |
276 |
|
A line containing just a comment (with perhaps spaces before it) is |
277 |
|
effectively blank, and is ignored. For example: |
278 |
|
|
279 |
|
@smallexample |
280 |
|
@group |
281 |
|
# This is a comment |
282 |
|
if header[Subject] :re "No.*" # This is also a comment |
283 |
|
guile-process action-name This # is not a comment!!! |
284 |
|
fi |
285 |
|
@end group |
286 |
|
@end smallexample |
287 |
|
|
288 |
|
@subheading Logical Structure |
289 |
|
|
290 |
|
The statements within a configuration file are grouped into |
291 |
|
@dfn{sections}. Each section has its name. A section begins with |
292 |
|
one of the following constructs: |
293 |
|
|
294 |
|
@smallexample |
295 |
|
BEGIN @var{name} |
296 |
|
---BEGIN @var{name}--- |
297 |
|
@end smallexample |
298 |
|
|
299 |
@noindent |
@noindent |
|
The user configuration file may contain the following sections: |
|
300 |
|
|
301 |
@enumerate |
and ends with one of the following constructs: |
302 |
@item |
|
303 |
@dfn{CONTROL section}. |
@smallexample |
304 |
@* |
END |
305 |
Optional. This specifies the basic GNU Anubis behavior. |
---END--- |
306 |
@item |
@end smallexample |
307 |
@dfn{GUILE section}. |
|
308 |
@* |
Notice, that both @samp{BEGIN} and @samp{END} must be uppercase. |
309 |
Optional. |
When using the second form, any amount of whitespace is allowed |
310 |
@item |
between the three dashes and the word. |
311 |
@dfn{The Rule System}. |
|
312 |
@* |
The sections cannot be nested. |
313 |
Optional. Here you can define your own processing rules |
|
314 |
for any particular message (conditional or unconditional |
There are three predefined sections, whose names are uppercase. |
315 |
rules). |
The user may define his own sections, which may then be referred |
316 |
@end enumerate |
to from the @code{RULE} section as subroutines (@pxref{Call Action}). |
317 |
|
|
318 |
|
The predefined section names are: |
319 |
|
|
320 |
|
@table @dfn |
321 |
|
@item CONTROL |
322 |
|
This section specifies the basic GNU Anubis behavior. Its presence |
323 |
|
is required in the system configuration file. It may be used in |
324 |
|
the user configuration file to override the system-wide settings. |
325 |
|
@item TRANSLATION |
326 |
|
This section specifies a translation map for remapping |
327 |
|
remote or local users. It may be used only in the syste-wide |
328 |
|
configuration file. |
329 |
|
@item GUILE |
330 |
|
Contains the settings of the Guile interpreter. The section is |
331 |
|
allowed in both configuration files. |
332 |
|
@item RULE |
333 |
|
Defines the rules that are used to alter the contents of the |
334 |
|
messages. This is the core part of the user configuration file. |
335 |
|
It is not allowed in the system configuration file. |
336 |
|
@end table |
337 |
|
|
338 |
@menu |
@menu |
339 |
* CONTROL Section:: |
* CONTROL Section:: |
343 |
|
|
344 |
|
|
345 |
@node CONTROL Section, TRANSLATION Section, Configuration, Configuration |
@node CONTROL Section, TRANSLATION Section, Configuration, Configuration |
346 |
@section The CONTROL Section |
@section CONTROL Section |
347 |
@cindex CONTROL section, The |
@cindex CONTROL section |
348 |
|
|
349 |
The @samp{CONTROL} section specifies the basic GNU Anubis behavior. |
The @samp{CONTROL} section specifies the basic GNU Anubis behavior. |
350 |
Specified in the system configuration file, it applies to all users on |
Specified in the system configuration file, it applies to all users on |
563 |
|
|
564 |
|
|
565 |
@node TRANSLATION Section, GUILE Section, CONTROL Section, Configuration |
@node TRANSLATION Section, GUILE Section, CONTROL Section, Configuration |
566 |
@section The TRANSLATION Section |
@section TRANSLATION Section |
567 |
@cindex TRANSLATION section, The |
@cindex TRANSLATION section |
568 |
|
|
569 |
The @samp{TRANSLATION} section specifies how to translate remote or local |
The @samp{TRANSLATION} section specifies how to translate remote or local |
570 |
user names, or host names or addresses, to local user names. |
user names, or host names or addresses, to local user names. |
603 |
|
|
604 |
|
|
605 |
@node GUILE Section, , TRANSLATION Section, Configuration |
@node GUILE Section, , TRANSLATION Section, Configuration |
606 |
@section The GUILE Section |
@section GUILE Section |
607 |
@cindex GUILE section, The |
@cindex GUILE section |
608 |
@cindex Guile |
@cindex Guile |
609 |
@cindex extension language |
@cindex extension language |
610 |
@cindex Scheme |
@cindex Scheme |
611 |
|
|
|
The name Guile stands for @dfn{GNU's Ubiquitous Intelligent Language for |
|
|
Extensions}. It provides a Scheme interpreter conforming to the R4RS |
|
|
language specification. GNU Anubis uses Guile as its extension language. |
|
|
|
|
|
This section assumes that the reader is sufficiently familiar with the |
|
|
Scheme language. For information about the language, refer to |
|
|
@ref{Top,,,r4rs,Revised(4) Report on the Algorithmic Language Scheme}. |
|
|
For more information about Guile, |
|
|
@xref{Top,,Overview,guile,The Guile Reference Manual}. |
|
|
|
|
612 |
@deffn Command guile-output @var{file} |
@deffn Command guile-output @var{file} |
613 |
Specifies the name of the file to bind to the Scheme standart error |
Specifies the name of the file to bind to the Scheme standart error |
614 |
and output ports. This option has no effect if GNU Anubis is started |
and output ports. This option has no effect if GNU Anubis is started |
637 |
The rule system is a core part of GNU Anubis. It can be regarded |
The rule system is a core part of GNU Anubis. It can be regarded |
638 |
as a program that is executed for every outgoing message. |
as a program that is executed for every outgoing message. |
639 |
|
|
640 |
Throughout this section, when showing syntax definitions, the |
Throughout this chapter, when showing syntax definitions, the |
641 |
optional parts of these will be enclosed in a pair of square |
optional parts of these will be enclosed in a pair of square |
642 |
brackets, e.g.: |
brackets, e.g.: |
643 |
|
|
644 |
@deffn Syntax keyword [@var{optional-part}] @var{mandatory-part} |
@smallexample |
645 |
@end deffn |
keyword [@var{optional-part}] @var{mandatory-part} |
646 |
|
@end smallexample |
647 |
|
|
648 |
|
@noindent |
649 |
When the square braces are required symbols, they will be marked |
When the square braces are required symbols, they will be marked |
650 |
as such, e.g.: |
as such, e.g.: |
651 |
|
|
652 |
@deffn Syntax |
@smallexample |
653 |
remove @samp{[}@var{key}@samp{]} |
remove @samp{[}@var{key}@samp{]} |
654 |
@end deffn |
@end smallexample |
655 |
|
|
656 |
The rule system is defined in @dfn{RULE} section, which begins with a |
The rule system is defined in @dfn{RULE} section, which begins with a |
657 |
@w{@code{---BEGIN RULE---}} and ends with an @w{@code{---END---}} |
@w{@code{---BEGIN RULE---}} and ends with an @w{@code{---END---}} |
661 |
Each statement is either an @dfn{action} or a @dfn{conditional |
Each statement is either an @dfn{action} or a @dfn{conditional |
662 |
statement}. |
statement}. |
663 |
|
|
664 |
|
@menu |
665 |
|
* Actions:: |
666 |
|
* Conditional Statements:: |
667 |
|
* Triggers:: |
668 |
|
* Boolean Operators:: |
669 |
|
* Regular Expressions:: |
670 |
|
* Action List:: |
671 |
|
* Using Guile Actions:: |
672 |
|
@end menu |
673 |
|
|
674 |
|
@node Actions, Conditional Statements, Rule System, Rule System |
675 |
|
@section Actions |
676 |
|
@cindex actions defined |
677 |
|
|
678 |
An @dfn{action} is a statement defining an operation to be performed |
An @dfn{action} is a statement defining an operation to be performed |
679 |
over the message. Syntactically, each action is |
over the message. Syntactically, each action is |
680 |
|
|
681 |
@deffn Syntax @var{command} [=] @var{right-hand-side} |
@smallexample |
682 |
|
@var{command} [=] @var{right-hand-side} |
683 |
|
@end smallexample |
684 |
|
|
685 |
|
@noindent |
686 |
Where @var{command} specifies a particular operation and |
Where @var{command} specifies a particular operation and |
687 |
@var{right-hand-side} specifies the arguments for it. The equal sign |
@var{right-hand-side} specifies the arguments for it. The equal sign |
688 |
is optional. |
is optional. |
689 |
@end deffn |
|
690 |
|
@node Conditional Statements, Triggers, Actions, Rule System |
691 |
|
@section Conditional Statements |
692 |
|
@cindex Conditional statements |
693 |
|
@cindex @code{if}, conditional statements |
694 |
|
@cindex @code{else}, conditional statements |
695 |
|
@cindex @code{fi}, conditional statements |
696 |
|
|
697 |
A @dfn{conditional statement} defines the control flow in the section. |
A @dfn{conditional statement} defines the control flow in the section. |
698 |
It allows to execute arbitrary actions depending on whether a certain |
It allows to execute arbitrary actions depending on whether a certain |
699 |
condition is met. A conditional statement in its simplest form is: |
condition is met. A conditional statement in its simplest form is: |
700 |
|
|
701 |
@deffn Syntax if @var{part} [@var{pattern-match-flags}] @var{cond-expr} |
@smallexample |
702 |
@deffnx Syntax @var{action-list-1} |
if @var{part} [@var{pattern-match-flags}] @var{cond-expr} |
703 |
@deffnx Syntax fi |
@var{action-list-1} |
704 |
|
fi |
705 |
|
@end smallexample |
706 |
|
|
707 |
The @var{part} specifies which part of the input should be considered |
The @var{part} specifies which part of the input should be considered |
708 |
when evaluating the condition. It is either @samp{command}, meaning |
when evaluating the condition. It is either @samp{command}, meaning |
750 |
The actions represented by @dots{} will be executed only if the |
The actions represented by @dots{} will be executed only if the |
751 |
@samp{Subject:} header of the message starts with @samp{Re:} optionally |
@samp{Subject:} header of the message starts with @samp{Re:} optionally |
752 |
preceeded by any amount of whitespace. |
preceeded by any amount of whitespace. |
|
@end deffn |
|
753 |
|
|
754 |
The more elaborate form of a conditional allows you to choose among |
The more elaborate form of a conditional allows you to choose among |
755 |
the two different action sets depending on a given condition. The |
the two different action sets depending on a given condition. The |
756 |
syntax is: |
syntax is: |
757 |
|
|
758 |
@deffn Syntax if @var{part} [@var{flags}] @var{cond-expr} |
@smallexample |
759 |
@deffnx Syntax @var{action-list-1} |
if @var{part} [@var{flags}] @var{cond-expr} |
760 |
@deffnx Syntax else |
@var{action-list-1} |
761 |
@deffnx Syntax @var{action-list-2} |
else |
762 |
@deffnx Syntax fi |
@var{action-list-2} |
763 |
|
fi |
764 |
|
@end smallexample |
765 |
|
|
766 |
Here, The @var{action-list-1} is executed if the condition |
Here, the @var{action-list-1} is executed if the condition |
767 |
@var{cond-expr} is met. Otherwise, @var{action-list-2} is |
@var{cond-expr} is met. Otherwise, @var{action-list-2} is |
768 |
executed. |
executed. |
769 |
|
|
779 |
@noindent |
@noindent |
780 |
|
|
781 |
Note also, that in the examples above any of the statements |
Note also, that in the examples above any of the statements |
782 |
@var{action-list} may contain conditionals, so that conditinal |
@var{action-list} may contain conditionals, so that the conditional |
783 |
statements may be nested. This allows to create very sophisticated |
statements may be nested. This allows to create very sophisticated |
784 |
rule sets. |
rule sets. |
785 |
|
|
786 |
[FIXME: elaborate on this. Provide an example] |
[FIXME: elaborate on this. Provide an example] |
|
@end deffn |
|
787 |
|
|
788 |
@menu |
@node Triggers, Boolean Operators, Conditional Statements, Rule System |
789 |
* Boolean Operators:: |
@section Triggers |
790 |
* Regular Expressions:: |
@cindex Triggers |
791 |
* Action List:: |
|
792 |
* Triggers:: |
Triggers are conditional statements that use the value of the |
793 |
@end menu |
@samp{Subject} header to alter the control flow. Syntactically, a |
794 |
|
trigger is: |
795 |
|
|
796 |
|
@smallexample |
797 |
|
@group |
798 |
|
rule [@var{flags}] @var{pattern} |
799 |
|
@var{action-list} |
800 |
|
done |
801 |
|
@end group |
802 |
|
@end smallexample |
803 |
|
|
804 |
|
@noindent |
805 |
|
Here, @var{pattern} is the pattern against which the @samp{Subject} |
806 |
|
header is checked, @var{flags} are optional flags controlling the |
807 |
|
type of regular expression used (@pxref{Regular Expressions}). |
808 |
|
|
809 |
|
The triggers act as follows: First, the value of the @samp{Subject} header is |
810 |
|
matched against the pattern @samp{@@@@}@var{pattern}. If it matches, |
811 |
|
then the matched part is removed from the @samp{Subject}, and the |
812 |
|
@var{action-list} is executed. |
813 |
|
|
814 |
|
Basically, putting aside the possibility to use different flavors of |
815 |
|
regular expressions, a trigger is equivalent to the following statement: |
816 |
|
|
817 |
@node Boolean Operators, Regular Expressions, Rule System, Rule System |
@smallexample |
818 |
|
@group |
819 |
|
if header[Subject] :posix "(.*)@@@@@var{pattern}" |
820 |
|
modify header [Subject] "\1" |
821 |
|
@var{action-list} |
822 |
|
fi |
823 |
|
@end group |
824 |
|
@end smallexample |
825 |
|
|
826 |
|
Thus, adding the @samp{@@@@@var{rule-name}} code to the @samp{Subject} |
827 |
|
header of your message, triggers a rule named @var{rule-name}, |
828 |
|
specified in a user configuration file. For example: |
829 |
|
|
830 |
|
@smallexample |
831 |
|
@group |
832 |
|
---BEGIN RULE--- |
833 |
|
rule :basic "^gpg-encrypt-john" |
834 |
|
gpg-encrypt "john's_gpg_key" |
835 |
|
done |
836 |
|
---END--- |
837 |
|
@end group |
838 |
|
@end smallexample |
839 |
|
|
840 |
|
@noindent |
841 |
|
Now you can simply send an email with the following subject: |
842 |
|
@w{@samp{hello John!@@@@gpg-encrypt-john}} to process an outgoing message |
843 |
|
with the rule specified above---encrypt message with a John's public key. |
844 |
|
Moreover, the trigger will remove the @samp{@@@@}, so John will only receive |
845 |
|
a message with a subject @samp{hello John!}. |
846 |
|
|
847 |
|
Another example shows an even more dynamic trigger, that is using |
848 |
|
a substitution and back-references: |
849 |
|
|
850 |
|
@smallexample |
851 |
|
@group |
852 |
|
---BEGIN RULE--- |
853 |
|
rule :extended "^gpg-encrypt:(.*)" |
854 |
|
gpg-encrypt "\1" |
855 |
|
add [X-GPG-Comment] "Encrypted for \1" |
856 |
|
done |
857 |
|
---END--- |
858 |
|
@end group |
859 |
|
@end smallexample |
860 |
|
|
861 |
|
@noindent |
862 |
|
To encrypt a message to user e.g. @samp{John}, simply send an email with |
863 |
|
a subject @w{@samp{hello John!@@@@gpg-encrypt:john's_gpg_key}}. |
864 |
|
This way, you decide at a run time which public key should be used, |
865 |
|
without creating separate rules for each user; thanks to back-references, |
866 |
|
those 3---4 lines are enough. |
867 |
|
|
868 |
|
@node Boolean Operators, Regular Expressions, Triggers, Rule System |
869 |
@section Boolean Operators |
@section Boolean Operators |
870 |
|
|
871 |
The following table lists the three boolean operators that can be used |
The following table lists the three boolean operators that can be used |
902 |
write the following: |
write the following: |
903 |
|
|
904 |
@smallexample |
@smallexample |
905 |
|
@group |
906 |
if (header[X-Mailer] "mutt" or header[X-Mailer] "mail") \ |
if (header[X-Mailer] "mutt" or header[X-Mailer] "mail") \ |
907 |
and not header[Content-Type] "^multipart/mixed;.*" |
and not header[Content-Type] "^multipart/mixed;.*" |
908 |
@var{action} |
@var{action} |
909 |
fi |
fi |
910 |
|
@end group |
911 |
@end smallexample |
@end smallexample |
912 |
@noindent |
@noindent |
913 |
|
|
1010 |
Perl documentation. |
Perl documentation. |
1011 |
|
|
1012 |
|
|
1013 |
@node Action List, Triggers, Regular Expressions, Rule System |
@node Action List, Using Guile Actions, Regular Expressions, Rule System |
1014 |
@section Action List |
@section Action List |
1015 |
@cindex Action List |
@cindex Action List |
1016 |
|
|
1018 |
of an outgoing messages. All action command names are case insensitive, so you |
of an outgoing messages. All action command names are case insensitive, so you |
1019 |
can use for instance: @samp{add} or @samp{ADD} or @samp{AdD}, and so on. |
can use for instance: @samp{add} or @samp{ADD} or @samp{AdD}, and so on. |
1020 |
|
|
|
@c [FIXME] |
|
|
@strong{Caution:} Some action commands below might not be compatible |
|
|
with GNU Anubis > 3.6.2, because this Manual has not been updated for |
|
|
a long time. |
|
|
|
|
1021 |
@menu |
@menu |
1022 |
|
* Stop Action:: Stopping the Processing |
1023 |
|
* Call Action:: Invoking Another Section |
1024 |
* Adding Headers or Text:: How to add a new header or body line(s). |
* Adding Headers or Text:: How to add a new header or body line(s). |
1025 |
* Removing Headers:: How to remove a message header line(s). |
* Removing Headers:: How to remove a message header line(s). |
1026 |
* Modifying Messages:: How to modify a message contents on-the-fly. |
* Modifying Messages:: How to modify a message contents on-the-fly. |
1027 |
* Inserting Files:: How to append text files to an outgoing message. |
* Inserting Files:: How to append text files to an outgoing message. |
1028 |
* Mail Encryption:: How to encrypt a message on-the-fly. |
* Mail Encryption:: How to encrypt a message on-the-fly. |
|
* Remailers:: How to enable the support for Remailers Type-I. |
|
|
* Rot-13:: How to use rot-13 transformation. |
|
1029 |
* External Processor:: How to process a message body using an external tool. |
* External Processor:: How to process a message body using an external tool. |
1030 |
* Quick Example:: A quick example of using an action list. |
* Quick Example:: A quick example of using an action list. |
1031 |
@end menu |
@end menu |
1032 |
|
|
1033 |
|
@node Stop Action, Call Action, Action List, Action List |
1034 |
|
@subsection Stop Action |
1035 |
|
@cindex @code{stop} |
1036 |
|
|
1037 |
|
The @code{stop} command stops immediately the processing of the |
1038 |
|
section. It may be used in the main @code{RULE} section as well as |
1039 |
|
in any user-defined section. For example: |
1040 |
|
|
1041 |
|
@smallexample |
1042 |
|
if not header[Content-Type] "text/plain; .*" |
1043 |
|
stop; |
1044 |
|
fi |
1045 |
|
@end smallexample |
1046 |
|
|
1047 |
|
@node Call Action, Adding Headers or Text, Stop Action, Action List |
1048 |
|
@subsection Call Action |
1049 |
|
@cindex @code{call} |
1050 |
|
|
1051 |
|
The @code{call} command allows to invoke a user-defined section much |
1052 |
|
in the same manner as a subroutine in a programming language. The |
1053 |
|
invoked section continues to execute until its end or the @code{stop} |
1054 |
|
statement is encountered, whichever the first. |
1055 |
|
|
1056 |
|
@smallexample |
1057 |
|
BEGIN myproc |
1058 |
|
if header[Subject] "Re: .*" |
1059 |
|
stop; |
1060 |
|
fi |
1061 |
|
rule "pgp" |
1062 |
|
gpg-encrypt "my_gpg_key" |
1063 |
|
done |
1064 |
|
END |
1065 |
|
|
1066 |
@node Adding Headers or Text, Removing Headers, Action List, Action List |
BEGIN RULE |
1067 |
|
call myproc |
1068 |
|
END |
1069 |
|
@end smallexample |
1070 |
|
|
1071 |
|
@node Adding Headers or Text, Removing Headers, Call Action, Action List |
1072 |
@subsection Adding Headers or Text |
@subsection Adding Headers or Text |
1073 |
@cindex @code{add} |
@cindex @code{add} |
1074 |
|
|
1075 |
The @code{add} command allows you to add arbitrary headers or text |
The @code{add} command allows you to add arbitrary headers or text |
1076 |
to the message. To add a header, use the following syntax: |
to the message. To add a header, use the following syntax: |
1077 |
|
|
1078 |
@deffn Syntax add header @samp{[}@var{name}@samp{]} @var{string} |
@deffn Command add header @samp{[}@var{name}@samp{]} @var{string} |
1079 |
@deffnx Syntax add @samp{[}@var{name}@samp{]} @var{string} |
@deffnx Command add @samp{[}@var{name}@samp{]} @var{string} |
|
|
|
1080 |
For example: |
For example: |
1081 |
|
|
1082 |
@smallexample |
@smallexample |
1085 |
@end smallexample |
@end smallexample |
1086 |
@end deffn |
@end deffn |
1087 |
|
|
1088 |
To add some text, use the following syntax: |
@deffn Command add body @var{text} |
1089 |
|
Adds the @var{text} to the message body. Use of this command with |
1090 |
@deffn Syntax add body @var{text} |
@samp{here document} syntax allows to append multiline text to the |
1091 |
@end deffn |
message, e.g.: |
|
|
|
|
Use of this command with @samp{here document} syntax allows |
|
|
to append multiline text to the message, e.g.: |
|
1092 |
|
|
1093 |
@smallexample |
@smallexample |
1094 |
@group |
@group |
1098 |
EOT |
EOT |
1099 |
@end group |
@end group |
1100 |
@end smallexample |
@end smallexample |
1101 |
|
@end deffn |
1102 |
|
|
1103 |
@node Removing Headers, Modifying Messages, Adding Headers or Text, Action List |
@node Removing Headers, Modifying Messages, Adding Headers or Text, Action List |
1104 |
@subsection Removing Headers |
@subsection Removing Headers |
1107 |
The command @code{remove} removes the specified header from the |
The command @code{remove} removes the specified header from the |
1108 |
message. The syntax is: |
message. The syntax is: |
1109 |
|
|
1110 |
@deffn Syntax remove [@var{flags}] header @samp{[}@var{string}@samp{]} |
@deffn Command remove [@var{flags}] header @samp{[}@var{string}@samp{]} |
1111 |
@deffnx Syntax remove [@var{flags}] @samp{[}@var{string}@samp{]} |
@deffnx Command remove [@var{flags}] @samp{[}@var{string}@samp{]} |
1112 |
|
|
1113 |
The name of the header to delete is given by @var{string} parameter. |
The name of the header to delete is given by @var{string} parameter. |
1114 |
By default only those headers are removed whose names match it exactly. |
By default only those headers are removed whose names match it exactly. |
1115 |
Optional @var{flags} allow to change this behavior. @xref{Regular Expressions}, |
Optional @var{flags} allow to change this behavior. @xref{Regular Expressions}, |
1116 |
for the detailed description of these. |
for the detailed description of these. |
|
@end deffn |
|
1117 |
|
|
1118 |
An example: |
An example: |
1119 |
|
|
1125 |
The first example will remove the @samp{X-Mailer:} header from |
The first example will remove the @samp{X-Mailer:} header from |
1126 |
an outgoing message, and the second one will remove all "X-*" |
an outgoing message, and the second one will remove all "X-*" |
1127 |
headers. |
headers. |
1128 |
|
@end deffn |
1129 |
|
|
1130 |
@node Modifying Messages, Inserting Files, Removing Headers, Action List |
@node Modifying Messages, Inserting Files, Removing Headers, Action List |
1131 |
@subsection Modifying Messages |
@subsection Modifying Messages |
1134 |
The action command @code{modify} allows to alter the headers |
The action command @code{modify} allows to alter the headers |
1135 |
or the body of the message. |
or the body of the message. |
1136 |
|
|
1137 |
@deffn Syntax modify [@var{flags}] header @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]} |
@deffn Command modify [@var{flags}] header @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]} |
1138 |
@deffnx Syntax modify [@var{flags}] @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]} |
@deffnx Command modify [@var{flags}] @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]} |
1139 |
|
|
1140 |
For each header whose name matches @var{key}, replaces its name |
For each header whose name matches @var{key}, replaces its name |
1141 |
with @var{new-key}. If @var{key} is a regular expressions, @var{new-key} |
with @var{new-key}. If @var{key} is a regular expressions, @var{new-key} |
1148 |
@end smallexample |
@end smallexample |
1149 |
@end deffn |
@end deffn |
1150 |
|
|
1151 |
@deffn Syntax modify [@var{flags}] header @samp{[}@var{key}@samp{]} @var{value} |
@deffn Command modify [@var{flags}] header @samp{[}@var{key}@samp{]} @var{value} |
1152 |
@deffnx Syntax modify [@var{flags}] @samp{[}@var{key}@samp{]} @var{value} |
@deffnx Command modify [@var{flags}] @samp{[}@var{key}@samp{]} @var{value} |
1153 |
|
|
1154 |
For each header whose name matches @var{key}, changes its value to |
For each header whose name matches @var{key}, changes its value to |
1155 |
@var{value}. For example: |
@var{value}. For example: |
1162 |
This statement sets the new value to the @code{Subject} header. |
This statement sets the new value to the @code{Subject} header. |
1163 |
@end deffn |
@end deffn |
1164 |
|
|
1165 |
@deffn Syntax modify [@var{flags}] header @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]} @var{value} |
@deffn Command modify [@var{flags}] header @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]} @var{value} |
1166 |
@deffnx Syntax modify [@var{flags}] @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]} @var{value} |
@deffnx Command modify [@var{flags}] @samp{[}@var{key}@samp{]} @samp{[}@var{new-key}@samp{]} @var{value} |
1167 |
|
|
1168 |
Combines the previous two cases, i.e. changes both the header |
Combines the previous two cases, i.e. changes both the header |
1169 |
name and its value, as shown in the following example: |
name and its value, as shown in the following example: |
1173 |
@end smallexample |
@end smallexample |
1174 |
@end deffn |
@end deffn |
1175 |
|
|
1176 |
@deffn Syntax modify [@var{flags}] body @samp{[}@var{key}@samp{]} |
@deffn Command modify [@var{flags}] body @samp{[}@var{key}@samp{]} |
|
|
|
1177 |
Removes all occurrences of @var{key} from the message body. |
Removes all occurrences of @var{key} from the message body. |
1178 |
For example, this statement will remove every occurrence of |
For example, this statement will remove every occurrence of |
1179 |
the word @samp{old}: |
the word @samp{old}: |
1183 |
@end smallexample |
@end smallexample |
1184 |
@end deffn |
@end deffn |
1185 |
|
|
1186 |
@deffn Syntax modify [@var{flags}] body @samp{[}@var{key}@samp{]} @var{string} |
@deffn Command modify [@var{flags}] body @samp{[}@var{key}@samp{]} @var{string} |
|
|
|
1187 |
Replaces all occurences of @var{key} with @var{string}. For example: |
Replaces all occurences of @var{key} with @var{string}. For example: |
1188 |
|
|
1189 |
@smallexample |
@smallexample |
1191 |
@end smallexample |
@end smallexample |
1192 |
@end deffn |
@end deffn |
1193 |
|
|
|
|
|
1194 |
@node Inserting Files, Mail Encryption, Modifying Messages, Action List |
@node Inserting Files, Mail Encryption, Modifying Messages, Action List |
1195 |
@subsection Inserting Files |
@subsection Inserting Files |
1196 |
|
|
1226 |
@end deffn |
@end deffn |
1227 |
|
|
1228 |
|
|
1229 |
@node Mail Encryption, Remailers, Inserting Files, Action List |
@node Mail Encryption, External Processor, Inserting Files, Action List |
1230 |
@subsection Mail Encryption |
@subsection Mail Encryption |
1231 |
@cindex GNU Privacy Guard, GnuPG |
@cindex GNU Privacy Guard, GnuPG |
1232 |
@cindex Pretty Good Privacy, PGP |
@cindex Pretty Good Privacy, PGP |
1283 |
@end deffn |
@end deffn |
1284 |
|
|
1285 |
|
|
1286 |
@node Remailers, Rot-13, Mail Encryption, Action List |
@node External Processor, Quick Example, Mail Encryption, Action List |
1287 |
@subsection Remailers Type-I |
@subsection Using an External Processor |
|
@cindex remailer |
|
1288 |
|
|
1289 |
GNU Anubis supports remailers of type I. The support is written |
@deffn Command external-body-processor @var{program} [@var{args}] |
1290 |
entirely in Scheme. To enable it you need to specify the following |
@cmindex external-body-processor @var{program} [@var{args}] |
1291 |
in the @code{GUILE} section of your configuration file: |
Pipes the message body through @var{program}. @var{program} should |
1292 |
|
be a filter program, that reads the text from the standard input |
1293 |
|
and prints the transformed text on the standard output. The output |
1294 |
|
from the @var{program} replaces the body of the message. |
1295 |
|
@var{args} are any additional arguments the program may require. |
1296 |
|
@end deffn |
1297 |
|
|
1298 |
|
|
1299 |
|
@node Quick Example, , External Processor, Action List |
1300 |
|
@subsection Quick Example |
1301 |
|
|
1302 |
|
Here is a quick example of using an action list: |
1303 |
|
|
1304 |
@smallexample |
@smallexample |
1305 |
@group |
@group |
1306 |
guile-load-program remailer.scm |
---BEGIN RULE--- |
1307 |
|
if header [X-Mailer] :re ".*" |
1308 |
|
remove [X-Mailer] |
1309 |
|
add [X-Comment] "GNU's Not Unix!" |
1310 |
|
gpg-sign "my password" |
1311 |
|
signature-file-append yes |
1312 |
|
fi |
1313 |
|
---END--- |
1314 |
@end group |
@end group |
1315 |
@end smallexample |
@end smallexample |
1316 |
|
|
1317 |
To send the message via a remailer, use the following command |
@noindent |
1318 |
in the @code{RULE} section: |
The example above will remove (on-the-fly) the @samp{X-Mailer:} line from |
1319 |
|
an outgoing message, add an extra header line (@samp{X-Comment:}), sign your |
1320 |
|
message with your private key, and add a simple signature file from your |
1321 |
|
home directory. |
1322 |
|
|
1323 |
@deffn Command guile-process remailer-I @var{keyword-arguments} |
@node Using Guile Actions, , Action List, Rule System |
1324 |
@fnindex remailer-I, Guile function |
@section Using Guile Actions |
1325 |
@cmindex guile-process remailer-I @var{keyword-arguments} |
@cindex Guile |
|
The @var{keyword-arguments} specify the various parameters for |
|
|
the remailer. These are: |
|
1326 |
|
|
1327 |
@table @asis |
The name Guile stands for @dfn{GNU's Ubiquitous Intelligent Language for |
1328 |
@item #:rrt @var{string} |
Extensions}. It provides a Scheme interpreter conforming to the R4RS |
1329 |
This is the only required keyword argument. It sets the value for the |
language specification. GNU Anubis uses Guile as its extension language. |
|
@dfn{Request Remailing To} line. @var{string} should be your actual |
|
|
recipient's email address. |
|
1330 |
|
|
1331 |
@item #:post @var{news-group} |
This section describes how to write GNU Anubis actions in Scheme. |
1332 |
Adds the @samp{Anon-Post-To: @var{news-group}} line, |
It assumes that the reader is sufficiently familiar with the |
1333 |
and prepares the message for sending it to the Usenet |
Scheme language. For information about the language, refer to |
1334 |
via a remailer. Note, that this is only possible with remailers |
@ref{Top,,,r4rs,Revised(4) Report on the Algorithmic Language Scheme}. |
1335 |
that support @samp{Anon-Post-To:} header. |
For more information about Guile, |
1336 |
|
@xref{Top,,Overview,guile,The Guile Reference Manual}. |
1337 |
|
|
1338 |
@item #:latent @var{time} |
@menu |
1339 |
Adds the @samp{Latent-Time:} line, that causes a remailer to keep |
* Defining Guile Actions:: |
1340 |
your message for specified @var{time} before forwarding it. |
* Invoking Guile Actions:: |
1341 |
|
|
1342 |
@item #:random |
Predefined Guile Actions |
1343 |
Adds random suffix to the latent time. |
* Rot-13:: |
1344 |
|
* Remailers:: |
1345 |
|
@end menu |
1346 |
|
|
1347 |
@item #:header @var{string} |
@node Defining Guile Actions, Invoking Guile Actions, Using Guile Actions, Using Guile Actions |
1348 |
Adds an extra header line to the remailed message. |
@subsection Defining Guile Actions |
1349 |
|
@cindex Guile Actions, defining |
1350 |
|
|
1351 |
|
A Guile action is defined as follows: |
1352 |
|
|
1353 |
|
@smalllisp |
1354 |
|
(define (@var{function-name} @var{header} @var{body} . @var{rest}) |
1355 |
|
...) |
1356 |
|
@end smalllisp |
1357 |
|
|
1358 |
|
@noindent |
1359 |
|
Its arguments are: |
1360 |
|
|
1361 |
|
@table @var |
1362 |
|
@item header |
1363 |
|
List of message headers. Each list element is a cons |
1364 |
|
|
1365 |
|
@smallexample |
1366 |
|
(@var{name} . @var{value}) |
1367 |
|
@end smallexample |
1368 |
|
|
1369 |
|
@noindent |
1370 |
|
where @var{name} is the name of the header field, and @var{value} is |
1371 |
|
its value with final CRLF stripped off. Both @var{name} and |
1372 |
|
@var{value} are strings. |
1373 |
|
|
1374 |
|
@item body |
1375 |
|
A string containing the message body. |
1376 |
|
|
1377 |
|
@item rest |
1378 |
|
Any additional arguments passed to the function from the configuration |
1379 |
|
file (@pxref{Invoking Guile Actions}). This argument may be absent if |
1380 |
|
the function is not expected to take optional arguments. |
1381 |
@end table |
@end table |
1382 |
|
|
1383 |
Example: |
The function must return a cons whose car contains the new message |
1384 |
|
headers, and cdr contains the new message body. If the car is |
1385 |
|
@code{#t}, it means that no headers are changed. If the cdr is |
1386 |
|
@code{#t}, it means that the body has not changed. If the cdr is |
1387 |
|
@code{#f}, Anubis will delete the entire message body. |
1388 |
|
|
1389 |
|
As the first example, let's consider a @dfn{no-operation} action, |
1390 |
|
i.e. an action that does not alter the message in any way. It can |
1391 |
|
be written in two ways: |
1392 |
|
|
1393 |
|
@smalllisp |
1394 |
|
(define (noop-1 header body) |
1395 |
|
(cons header body)) |
1396 |
|
|
1397 |
|
(define (noop-2 header body) |
1398 |
|
(cons #t #t)) |
1399 |
|
@end smalllisp |
1400 |
|
|
1401 |
|
The following example is a function that deletes the message body |
1402 |
|
and adds an additional header: |
1403 |
|
|
1404 |
|
@smalllisp |
1405 |
|
(define (proc header body) |
1406 |
|
(cons (append header |
1407 |
|
(cons "X-Body-Deleted" "yes")) |
1408 |
|
#f)) |
1409 |
|
@end smalllisp |
1410 |
|
|
1411 |
|
Let's consider a more constructive example. The following function |
1412 |
|
checks if the @code{Subject} header starts with string @samp{ODP:} |
1413 |
|
(a Polish equivalent to @samp{Re:}), and if it does, the function |
1414 |
|
replaces it with @samp{Re:}. It always adds to the message the header |
1415 |
|
|
1416 |
@smallexample |
@smallexample |
1417 |
@group |
X-Processed-By: GNU Anubis |
|
rule "remail:(.*)/(.*)" |
|
|
guile-process remailer-I #:rrt antonius_block@@helsingor.net \ |
|
|
#:post \1 \ |
|
|
#:latent \2 \ |
|
|
#:header "X-Processed-By: GNU Anubis & Remailer-I" |
|
|
done |
|
|
@end group |
|
1418 |
@end smallexample |
@end smallexample |
1419 |
|
|
1420 |
|
@noindent |
1421 |
|
Additionally, if the optional argument is given, it is appended to |
1422 |
|
the body of the message. |
1423 |
|
|
1424 |
|
@smalllisp |
1425 |
|
(define (fix-subject hdr body . rest) |
1426 |
|
"If the Subject: field starts with characters \"ODP:\", replace |
1427 |
|
them with \"Re:\". |
1428 |
|
If REST is not empty, append its car to BODY" |
1429 |
|
(cons (append |
1430 |
|
(map (lambda (x) |
1431 |
|
(if (and (string-ci=? (car x) "subject") |
1432 |
|
(string-ci=? (substring (cdr x) 0 4) "ODP:")) |
1433 |
|
(cons (car x) |
1434 |
|
(string-append "Re:" |
1435 |
|
(substring (cdr x) 4))) |
1436 |
|
x)) |
1437 |
|
hdr) |
1438 |
|
(list (cons "X-Processed-By" "GNU Anubis"))) |
1439 |
|
(if (null? rest) |
1440 |
|
#t |
1441 |
|
(string-append body "\n" (car rest))))) |
1442 |
|
@end smalllisp |
1443 |
|
|
1444 |
|
@node Invoking Guile Actions, Rot-13, Defining Guile Actions, Using Guile Actions |
1445 |
|
@subsection Invoking Guile Actions |
1446 |
|
@cindex @code{guile-process} |
1447 |
|
|
1448 |
|
The Guile actions are invoked from the @code{RULE} section using the |
1449 |
|
@code{guile-process} command. Its syntax is: |
1450 |
|
|
1451 |
|
@deffn Command guile-process @var{function} @var{args} |
1452 |
|
Arguments: |
1453 |
|
|
1454 |
|
@table @var |
1455 |
|
@item function |
1456 |
|
The name of the Guile function to be invoked. |
1457 |
|
|
1458 |
|
@item args |
1459 |
|
Additional arguments. These are passed to the @var{function} as |
1460 |
|
its third argument (@var{rest}). |
1461 |
|
@end table |
1462 |
@end deffn |
@end deffn |
1463 |
|
|
1464 |
|
To pass keyword arguments to the function, use the usual Scheme |
1465 |
|
notation: @samp{#:key}. |
1466 |
|
|
1467 |
@node Rot-13 |
As an example, let's consider the invocation of the @code{fix-subject} |
1468 |
@subsection Support for ROT-13 |
function, defined in the previous subsection: |
1469 |
|
|
1470 |
|
@smallexample |
1471 |
|
guile-process fix-subject <<-EOT |
1472 |
|
---------- |
1473 |
|
Kind regards, |
1474 |
|
Antonius Block |
1475 |
|
EOT |
1476 |
|
@end smallexample |
1477 |
|
|
1478 |
|
@noindent |
1479 |
|
In this example, the additional argument (a string of three lines) is |
1480 |
|
passed to the function, which will add it to the message of the body. |
1481 |
|
|
1482 |
|
@node Rot-13, Remailers, Invoking Guile Actions, Using Guile Actions |
1483 |
|
@subsection Support for @sc{rot-13} |
1484 |
@cindex rot-13 |
@cindex rot-13 |
1485 |
|
|
1486 |
The ROT-13 transformation is a simple form of encryption where the |
The @sc{rot-13} transformation is a simple form of encryption where the |
1487 |
letters A-M are transposed with the letters L-Z. It is often used in |
letters A-M are transposed with the letters L-Z. It is often used in |
1488 |
Usenet postings/mailing lists to prevent people from accidentally |
Usenet postings/mailing lists to prevent people from accidentally |
1489 |
reading a disturbing message. |
reading a disturbing message. |
1490 |
|
|
1491 |
GNU Anubis supports ROT-13 via a loadable Guile function. To enable |
GNU Anubis supports @sc{rot}-13 via a loadable Guile function. To enable |
1492 |
this support, you will have to add the following to your @code{GUILE} |
this support, you will have to add the following to your @code{GUILE} |
1493 |
section: |
section: |
1494 |
|
|
1502 |
@fnindex rot-13, Guile function |
@fnindex rot-13, Guile function |
1503 |
The command accepts the following @var{keyword-arguments}: |
The command accepts the following @var{keyword-arguments}: |
1504 |
|
|
1505 |
@table @asis |
@table @code |
1506 |
@item #:body |
@item #:body |
1507 |
Encrypt the entire body of the message |
Encrypt the entire body of the message |
1508 |
|
|
1525 |
@end smallexample |
@end smallexample |
1526 |
@end deffn |
@end deffn |
1527 |
|
|
1528 |
|
@node Remailers, , Rot-13, Using Guile Actions |
1529 |
|
@subsection Remailers Type-I |
1530 |
|
@cindex remailer |
1531 |
|
|
1532 |
@node External Processor, Quick Example, Rot-13, Action List |
GNU Anubis supports remailers of type I. The support is written |
1533 |
@subsection Using an External Processor |
entirely in Scheme. To enable it you need to specify the following |
1534 |
|
in the @code{GUILE} section of your configuration file: |
|
@deffn Command external-body-processor @var{program} [@var{args}] |
|
|
@cmindex external-body-processor @var{program} [@var{args}] |
|
|
Pipes the message body through @var{program}. @var{program} should |
|
|
be a filter program, that reads the text from the standard input |
|
|
and prints the transformed text on the standard output. The output |
|
|
from the @var{program} replaces the body of the message. |
|
|
@var{args} are any additional arguments the program may require. |
|
|
@end deffn |
|
|
|
|
|
|
|
|
@node Quick Example, , External Processor, Action List |
|
|
@subsection Quick Example |
|
|
|
|
|
Here is a quick example of using an action list: |
|
1535 |
|
|
1536 |
@smallexample |
@smallexample |
1537 |
@group |
@group |
1538 |
---BEGIN RULE--- |
guile-load-program remailer.scm |
|
if header [X-Mailer] :re ".*" |
|
|
remove [X-Mailer] |
|
|
add [X-Comment] "GNU's Not Unix!" |
|
|
gpg-sign "my password" |
|
|
signature-file-append yes |
|
|
fi |
|
|
---END--- |
|
1539 |
@end group |
@end group |
1540 |
@end smallexample |
@end smallexample |
1541 |
|
|
1542 |
@noindent |
To send the message via a remailer, use the following command |
1543 |
The example above will remove (on-the-fly) the @samp{X-Mailer:} line from |
in the @code{RULE} section: |
|
an outgoing message, add an extra header line (@samp{X-Comment:}), sign your |
|
|
message with your private key, and add a simple signature file from your |
|
|
home directory. |
|
|
|
|
1544 |
|
|
1545 |
@node Triggers, , Action List, Rule System |
@deffn Command guile-process remailer-I @var{keyword-arguments} |
1546 |
@section Triggers |
@fnindex remailer-I, Guile function |
1547 |
@cindex Triggers |
@cmindex guile-process remailer-I @var{keyword-arguments} |
1548 |
Adding the @samp{@@@@@var{rule-name}} code to your message header line, |
The @var{keyword-arguments} specify the various parameters for |
1549 |
e.g. to a @samp{Subject} header line, triggers a rule named @var{rule-name}, |
the remailer. These are: |
|
specified in a user configuration file in the following way: |
|
1550 |
|
|
1551 |
@smallexample |
@table @code |
1552 |
@group |
@item #:rrt @var{string} |
1553 |
rule [@var{flags}] @var{pattern} |
This is the only required keyword argument. It sets the value for the |
1554 |
@var{action-list} |
@dfn{Request Remailing To} line. @var{string} should be your actual |
1555 |
done |
recipient's email address. |
|
@end group |
|
|
@end smallexample |
|
1556 |
|
|
1557 |
@noindent |
@item #:post @var{news-group} |
1558 |
|
Adds the @samp{Anon-Post-To: @var{news-group}} line, |
1559 |
|
and prepares the message for sending it to the Usenet |
1560 |
|
via a remailer. Note, that this is only possible with remailers |
1561 |
|
that support @samp{Anon-Post-To:} header. |
1562 |
|
|
1563 |
An example: |
@item #:latent @var{time} |
1564 |
|
Adds the @samp{Latent-Time:} line, that causes a remailer to keep |
1565 |
|
your message for specified @var{time} before forwarding it. |
1566 |
|
|
1567 |
@smallexample |
@item #:random |
1568 |
@group |
Adds random suffix to the latent time. |
|
---BEGIN RULE--- |
|
|
rule :basic "^gpg-encrypt-john" |
|
|
gpg-encrypt "john's_gpg_key" |
|
|
done |
|
|
---END--- |
|
|
@end group |
|
|
@end smallexample |
|
1569 |
|
|
1570 |
@noindent |
@item #:header @var{string} |
1571 |
Now you can simply send an email with the following subject: |
Adds an extra header line to the remailed message. |
1572 |
@w{@samp{hello John!@@@@gpg-encrypt-john}} to process an outgoing message |
@end table |
|
with the rule specified above---encrypt message with a John's public key. |
|
|
Moreover, the trigger will remove the @samp{@@@@}, so John will only receive |
|
|
a message with a subject @samp{hello John!}. |
|
1573 |
|
|
1574 |
Another example shows even more dynamic trigger, |
Example: |
|
while using a substitution and back-references: |
|
1575 |
|
|
1576 |
@smallexample |
@smallexample |
1577 |
@group |
@group |
1578 |
---BEGIN RULE--- |
rule "remail:(.*)/(.*)" |
1579 |
rule :extended "^gpg-encrypt:(.*)" |
guile-process remailer-I \ |
1580 |
gpg-encrypt "\1" |
#:rrt antonius_block@@helsingor.net \ |
1581 |
add [X-GPG-Comment] "Encrypted for \1" |
#:post \1 \ |
1582 |
|
#:latent \2 \ |
1583 |
|
#:header "X-Processed-By: GNU Anubis & Remailer-I" |
1584 |
done |
done |
|
---END--- |
|
1585 |
@end group |
@end group |
1586 |
@end smallexample |
@end smallexample |
1587 |
|
@end deffn |
|
@noindent |
|
|
To encrypt a message to user e.g. @samp{John}, simply send an email with |
|
|
a subject @w{@samp{hello John!@@@@gpg-encrypt:john's_gpg_key}}. |
|
|
In this case, you decide in a run time which public key should be used, |
|
|
without creating a separate rules for each user; thanks to back-references, |
|
|
those 3---4 lines are enough. |
|
|
|
|
1588 |
|
|
1589 |
@node Invoking Anubis, Sample Beginning, Rule System, Top |
@node Invoking Anubis, Sample Beginning, Rule System, Top |
1590 |
@chapter Invoking GNU Anubis |
@chapter Invoking GNU Anubis |