maddy

 1# System command filter
 2
 3This module executes an arbitrary system command during a specified stage of
 4checks execution.
 5
 6```
 7command executable_name arg0 arg1 ... {
 8	run_on body
 9
10	code 1 reject
11	code 2 quarantine
12}
13```
14
15## Arguments
16
17The module arguments specify the command to run. If the first argument is not
18an absolute path, it is looked up in the Libexec Directory (/usr/lib/maddy on
19Linux) and in $PATH (in that ordering). Note that no additional handling
20of arguments is done, especially, the command is executed directly, not via the
21system shell.
22
23There is a set of special strings that are replaced with the corresponding
24message-specific values:
25
26- `{source_ip}` – IPv4/IPv6 address of the sending MTA.
27- `{source_host}` – Hostname of the sending MTA, from the HELO/EHLO command.
28- `{source_rdns}` – PTR record of the sending MTA IP address.
29- `{msg_id}` – Internal message identifier. Unique for each delivery.
30- `{auth_user}` – Client username, if authenticated using SASL PLAIN
31- `{sender}` – Message sender address, as specified in the MAIL FROM SMTP command.
32- `{rcpts}` – List of accepted recipient addresses, including the currently handled
33  one.
34- `{address}` – Currently handled address. This is a recipient address if the command
35  is called during RCPT TO command handling (`run_on rcpt`) or a sender
36  address if the command is called during MAIL FROM command handling (`run_on
37  sender`).
38
39If value is undefined (e.g. `{source_ip}` for a message accepted over a Unix
40socket) or unavailable (the command is executed too early), the placeholder
41is replaced with an empty string. Note that it can not remove the argument.
42E.g. `-i {source_ip}` will not become just `-i`, it will be `-i ""`
43
44Undefined placeholders are not replaced.
45
46## Command stdout
47
48The command stdout must be either empty or contain a valid RFC 5322 header.
49If it contains a byte stream that does not look a valid header, the message
50will be rejected with a temporary error.
51
52The header from stdout will be **prepended** to the message header.
53
54## Configuration directives
55
56### run_on `conn` | `sender` | `rcpt` | `body`
57Default: `body`
58
59When to run the command. This directive also affects the information visible
60for the message.
61
62- `conn`<br>
63    Run before the sender address (MAIL FROM) is handled.<br>
64    **Stdin**: Empty <br>
65    **Available placeholders**: {source_ip}, {source_host}, {msg_id}, {auth_user}.
66
67- `sender`<br>
68    Run during sender address (MAIL FROM) handling.<br>
69    **Stdin**: Empty <br>
70    **Available placeholders**: conn placeholders + {sender}, {address}.
71    The {address} placeholder contains the MAIL FROM address.
72
73- `rcpt`<br>
74    Run during recipient address (RCPT TO) handling. The command is executed
75    once for each RCPT TO command, even if the same recipient is specified
76    multiple times.<br>
77    **Stdin**: Empty <br>
78    **Available placeholders**: sender placeholders + {rcpts}.
79    The {address} placeholder contains the recipient address.
80
81- `body`<br>
82    Run during message body handling.<br>
83    **Stdin**: The message header + body <br>
84    **Available placeholders**: all except for {address}.
85
86---
87
88### code _integer_ ignore <br>code _integer_ quarantine <br>code _integer_ reject _smtp-code_ _smtp-enhanced-code_ _smtp-message_
89
90This directive specifies the mapping from the command exit code _integer_ to
91the message pipeline action.
92
93Two codes are defined implicitly, exit code 1 causes the message to be rejected
94with a permanent error, exit code 2 causes the message to be quarantined. Both
95actions can be overridden using the 'code' directive.
96