MAN page from PLD anubis-3.4.6-3.i586.rpm

Anubis

Section: Anubis (1)
Updated: Version 3.4.6
Index

NAME

Anubis - an outgoing mail processor and the SMTP tunnel.

SYNOPSIS

anubis[options]

DESCRIPTION

Anubisis an outgoing mail processor. It goes between the MUA (Mail User Agent)and the MTA (Mail Transport Agent), and can perform on the fly various sorts ofprocessing and conversion on the outgoing mail in accord with the sender'sspecified rules, based on a highly configurable regular expressions system.It operates as a proxy server, independently from mail user agents.Anubis can edit outgoing mail headers, encrypt and/or sign mail with theGNU Privacy Guard, build secure SMTP tunnels (Simple Mail Transport Protocol)using the TLS/SSL encryption even if your mail user agent doesn't support it,or tunnel a connection through a SOCKS proxy or WinGate proxy server. Moreover,Anubis supports the remailers (it allows sending mail in an anonymous way).

OPTIONS

-b, --bind [HOST:]PORT: Specify daemon's port number and host name. Default HOST valueis INADDR_ANY, and default PORT number is 25.
-r, --remote-host HOST[:PORT]: Specify a remote SMTP host name or IP address. Default PORT number is 25.
-l, --local-mta FILE: Execute a local SMTP server, which works on standard input and output(inetd-type program). This option excludes the `--remote-mta' option.
-f, --foreground: Foreground mode.
-i, --stdio: Use the SMTP protocol (OMP/Tunnel) as described in RFC 821on standard input and output.Output options:
-s, --silent: Work silently.
-v, --verbose: Work noisily.
-D, --debug: Debug mode (if compiled with `GDEBUG' macro).Misc. options:
--altrc FILE: Specify alternate supervisor's run control file.
--norc: Ignore the run control file.
--version: Print version number and copyright.
--help: It's obvious...

THE RUN CONTROL FILES

The behavior of Anubis is controlled by two run control files.The first one, /etc/anubisrc, is owned by a supervisor, usually root(system configuration file). The second one, ~/.anubisrc,belongs to a client (client/user configuration file).To protect your passwords in the run control files use the 0600(u=rw,g=,o=) permissions, otherwise Anubis won't accept them.

Caution:The run control files have ahigherpriority that command line options, so using the command line optionsis not recommended.

The run control files are divided into several control sections:1) THE CONTROL SECTION2) THE EXTERNAL SECTION3) THE ALL SECTION4) THE RULE SYSTEM (aka THE REGEX SECTION)

The system configuration file may contain only sections No. 1 and 2.The user configuration file may contain only sections No. 1,3,4.

THE CONTROL SECTION

The "CONTROL" section specifies the basic Anubis behavior.Specified by a supervisor, by default, it applies to all users onthe machine, but each user can specify its own "CONTROL" section,to customize own settings. Of course, not all options can be setor change by user. Some options can only be set by a supervisor.The "CONTROL" section starts with the `---BEGIN CONTROL---' line,and the `---END---' line ends it.

Some options are available for both configuration files (/etc/anubisrcand ~/.anubisrc). Those specified in user configuration file,have ahigherpriority that those specified in system configuration file.But there are also options available only for a supervisor, and those cannotbe set or changed in user configuration files. Moreover, there are two optionsavailable only for user configuration files, and these cannot be set or changedby a supervisor.

Caution:All option names are case insensitive, so you can use for instance:bind or BIND or BiNd, and so on.

bind = [HOST:]PORTSpecify daemon's port number and host name. Default HOST value is INADDR_ANY,and default PORT number is 25. This option is available only in the systemconfiguration file (/etc/anubisrc).

remote-mta = HOST[:PORT]Specify a remote SMTP host name or IP address.Default PORT number is 25. This option is available in both configurationfiles (/etc/anubisrc} and ~/.anubisrc).

local-mta = FILE-NAME [ARGS]Execute a local SMTP server, which works on standard input and output(inetd-type program). This option excludes the `REMOTE-MTA' keyword(or `--remote-mta' command line option).

output = NORMAL-VERBOSE-SILENTThis is a logging level for `syslogd' or a terminal (if using the`--foreground' command line option). The `NORMAL' is a default value.The `VERBOSE' makes a more diagnostic output, and the `SILENT' disables an output.If you compile the Anubis with `GDEBUG' macro, then there is another valueavailable, called `DEBUG', e.g. `OUTPUT = DEBUG'. Only in system configurationfile (/etc/anubisrc).

logfile = FILE-NAMEThis option specifies an additional file, where Anubis can log its information,but only those information available for Anubis client. A supervisor cannotset this option (only in user configuration file). For example:

logfile = anubislog

It will log to the ~/anubislog file in a client's home directory.

loglevel = NONE-ERRORS-ALLThis option specifies an output level for an additional file (`LOGFILE').The `ERRORS' is a default value, and it only logs errors.Only in user configuration file.

socks-proxy = HOST[:PORT]This option enables tunneling the connections through a SOCKS proxy server,specified as an argument HOST. The PORT default value is 1080,which is a common port number for SOCKS proxies.

socks-v4 = YES-OR-NOIt specifies a SOCKS protocol version 4. By default it is turned off,and a default mode is SOCKS protocol version 5.

socks-username = USERNAMESpecify a user name, if a SOCKS proxy server requires it.

socks-password = PASSWORDSpecify a password, if a SOCKS proxy server requires it.

wingate1 = HOST[:PORT]This options enables tunneling the connections through a WinGate proxyserver, specified as an argument HOST. The PORT default value is 23,which is a common port number for this service.

wingate2 = HOST[:PORT]Specify a second WinGate proxy server, only if you have alreadyspecified the first one.

ssl = YES-OR-NOThis option enables the TLS/SSL encryption between the MUA (Mail User Agent)and the MTA (Mail Transport Agent). The `NO' is a default value,but using the TLS/SSL encryption is recommended. You should alsospecify a private key and a certificate using the `KEY' and `CERT'keywords (defined below).

oneway-ssl = YES-OR-NOThis option enables the "ONEWAY" encryption. Use this mode,when you want to use the TLS/SSL, but your MUA (Mail User Agent)doesn't provide a support for ESMTP TLS/SSL. Using this optiondoesn't require using the `KEY' and `CERT' keywords.

cert = FILE-NAMESpecify a certificate for the TLS/SSL encryption.The anubis.pem is a default value.

key = FILE-NAMESpecify a private key for the TLS/SSL encryption.The anubis.pem is a default value.

allow-local-mta = YES-OR-NOFor security reasons this option is set to `NO',but the `YES' value enables the `LOCAL-MTA' keyword(or `--local-mta' command line option), so if you want to use a local mailserver, which works on standard input and output, a supervisor must setthis option to `YES'. Only in system configuration file (/etc/anubisrc).

allow-external-processing = YES-OR-NOTo enable processing the "EXTERNAL" section, a supervisor must set thisoption to `YES'. The `NO' is a default value.Only in system configuration file (/etc/anubisrc).

user-notprivileged = USERNAMEFor security reasons, it is recommended to create an unprivileged user,which the server runs as most of the time, when doing unprivileged operations.Only in system configuration file (/etc/anubisrc).For example:

user-notprivileged = anubis

Caution:Create a user account named `anubis' in the /etc/passwd, if necessary.

Summary:

---BEGIN CONTROL---
bind = [HOST:]PORT  (system config only)
remote-mta = HOST[:PORT]
local-mta = FILE-NAME [ARGS]
output = NORMAL-VERBOSE-SILENT  (system config only)
logfile = FILE-NAME  (user config only)
loglevel = NONE-ERRORS-ALL  (user config only)
socks-proxy = HOST[:PORT]
socks-v4 = YES-OR-NO
socks-username = USERNAME
socks-password = PASSWORD
wingate1 = HOST[:PORT]
wingate2 = HOST[:PORT]
ssl = YES-OR-NO
oneway-ssl = YES-OR-NO
cert = FILE-NAME
key = FILE-NAME
allow-local-mta = YES-OR-NO  (system config only)
allow-external-processing = YES-OR-NO  (system config only)
user-notprivileged = USERNAME  (system config only)
---END---

THE EXTERNAL SECTION

The "EXTERNAL" section allows an external clients to usea local run control files, and process outgoing mail.To process this section, a supervisor must set to `YES'the `ALLOW-EXTERNAL-PROCESSING' keyword in the "CONTROL" section.The "EXTERNAL" section is availableONLYin the system configuration file (/etc/anubisrc).The "EXTERNAL" section starts with the `---BEGIN EXTERNAL---' line,and the `---END---' line ends it. Syntax:

---BEGIN EXTERNAL---
external = [user@]address local = username
---END---

An example (/etc/anubisrc):

---BEGIN EXTERNAL---
external = jackAATTsomewhere.net local = john
---END---

The rule above will allow an external user 'jack' at somewhere.net(jackAATTsomewhere.net) to use a local john's run control file.Or you can write: "external = somewhere.net local = john", and thismean that ALL users at somewhere.net are allowed to use a local john'srun control file.

THE ALL SECTION

This section specifies a behavior of an outgoing mail processorin the case of EVERY outgoing message. This section is availableONLYin the user configuration file (~/.anubisrc).The "ALL" section starts with the `---BEGIN ALL---' line,and the `---END---' line ends it. Syntax:

---BEGIN ALL---
ACTION-LIST
---END---

An example (~/.anubisrc):

---BEGIN ALL---
SIGNATURE-FILE-ATTACH = yes
---END---

The example above will add the ~/.signature file to EVERY outgoingmessage!

THE RULE SYSTEM

Anubis' rule system is based, by default, on "regular expressions"(the extended version) or, by user request, on "Perl regular expressions".To enable the "PerlRE", you must recompile the code, specifyingthe './configure --with-pcre'.

According to the GNU's documentation, a "regular expression"(or "regexp", or "pattern") is a text string that describes some(mathematical) set of strings. A regexp R "matches" a string S if Sis in the set of strings described by R. For more information about"regular expressions", read theGNU regular expression library manualand theregex(7).In addition, you can also read theperlre(1).

The rule system is available only for Anubis clients, so it can only beused in the user configuration file. The whole rule system starts withthe `---BEGIN REGEX---' line, and the `---END---' line ends it.

Grammar

IF MODE =REGEX1[!=REGEX2]
ACTION-LIST
FI

The first regular expression (REGEX1) is required.The second one (REGEX2) is optional. Here is a simple rule:

IF MODE =REGEX1
ACTION-LIST
FI

The rule above is true if REGEX1 is TRUE. Another way:

IF MODE =REGEX1!=REGEX2
ACTION-LIST
FI

The rule above is true if REGEX1 is TRUE and REGEX2 is FALSE.The control operator `!=' breaks regular expressions into two pieces:REGEX1 and REGEX2. Please note that there is no SPACE between regularexpressions and the control operators `=' and `!='.

Caution:The MODE means "COMMAND" or "HEADER", for example:

---BEGIN REGEX---
IF COMMAND =REGEX1[!=REGEX2]
ACTION-LIST
FI
IF HEADER =REGEX1[!=REGEX2]
ACTION-LIST
FI
---END---

The "COMMAND" references to the SMTP/ESMTP commands, likehelo, ehlo, mail from, rcpt to, data, quit, etc.

IF COMMAND =^mail from:[ ]*<?johnAATTlocalhost>?
ACTION-LIST
FI

The "HEADER" references to a mail header line, likeFrom:, To:, Subject:, Date:, any header line!

IF HEADER =^Subject: test
ACTION-LIST
FI

Caution:The rule system is case insensitive (except regular expressions),so you can write for instance:

if header =REGEX1[!=REGEX2]
action-list
fi

An example (~/.anubisrc):

---BEGIN REGEX---
if header =^Subject:!=^Subject:[ ]*urgent
signature-file-attach = yes
fi
---END---

The example above will always add the ~/.signature file, exceptan email with the subject "urgent".

ACTION LIST:

Caution:All action command names are case insensitive, so you can use forinstance: add or ADD or AdD, and so on.

add = HEADER LINEThis action command adds the HEADER LINE to an outgoingmessage. For example:

add = X-Comment: GNU's Not Unix

The `ADD' command can be used in the "ALL" section and/orin the "REGEX" section.

remove = HEADER LINE (a regular expression)This action command removes the HEADER LINE from an outgoing message.It have to be a regular expression. For example:

remove =^X-Mailer:

It will remove the `X-Mailer:' line from an outgoing message.This action command can be used in the "ALL" sectionand/or "REGEX" section.

modify = NEW HEADER LINEThis action command can only be used in the "REGEX" section.It modifies a message header line. For example, the following codewill change the `X-Mailer: Pine' line to `X-Mailer: The Big Boss'.

if header =^X-Mailer:[ ]*Pine
modify = X-Mailer: The Big Boss
fi

rot13-subject = YES-OR-NOThis command enables the simple ROT-13 message subject encoding.The `NO' is a default value. The ROT-13 encoding is a simple formof encryption in which the letters A-M are transposed with the letters L-Z.It is often used in Usenet postings/mailing lists to prevent people fromaccidentally reading a disturbing message.

rot13-body = YES-OR-NOThis command enables the simple ROT-13 message body encoding.The `NO' is a default value.

signature-file-attach = YES-OR-NOThis action command adds at the end of a message body the`--<SPC>' line, and includes a client's ~/.signature file.The `NO' is a default value.

body-attach = FILE-NAMEThis action command includes at the end of a message bodya client's FILE-NAME file (a plain text).

body-clear-attach = FILE-NAMESame as above, but wipes out a message (message body + any attachments)before including a message body from a FILE-NAME file.

gpg-passphrase = PASSPHRASESpecify your private key's pass phrase for signing an outgoing messageusing the GNU Privacy Guard (a tool compatible with the Pretty Good Privacy).Of course to protect your passwords in the run control file use the0600 (u=rw,g=,o=) permissions, otherwise Anubis won't accept it.We recommend setting the `GPG-PASSPHRASE' in a one place of yourrun control file, e.g. put it in the "ALL" section.

Caution:Anubis supports the GNU Privacy Guard via the "GnuPG Made Easy" library,available athttp://www.gnupg.org/gpgme.html.

gpg-encrypt = GPG KEYSThis command enables encrypting your outgoing message with the GNU Privacy Guard(Pretty Good Privacy) public key(s). Comma separated list of keys.

gpg-encrypt = John's public key

gpg-sign = PASSPHRASE or `YES' if `GPG-PASSPHRASE' is specified.This command enables signing your outgoing mail with your GNU Privacy Guardprivate key. Specify the PASSPHRASE or set it to `YES' if you have alreadyspecified the `GPG-PASSPHRASE'. For example:

gpg-sign = PASSPHRASE

gpg-passphrase = PASSPHRASE
gpg-sign = yes

rm-rrt = EMAIL-ADDRESSIt enables a support for the remailers (it allows sending mail in an anonymous way),by adding a special lines in a message body. This option specifiesthe "Request Remailing To" (`Anon-To:' line). Set it to a recipient'semail address. Anubis only supports the Type-I remailers (aka Cypherpunks).

rm-post = NEWS-GROUPThis option adds the `Anon-Post-To: NEWS-GROUP' line,and transform an email to a news-mail for sending it to the Usenetvia a remailer. It is only possible with a remailer, which supportsthe `Anon-Post-To:'. For example:

rm-post = alt.unix

rm-gpg = GPG KEYIt makes an outgoing mail encrypted with a remailer's PGP public key,and you must set it, if a remailer requires such an encryption.

rm-header = HEADER LINEThis action command adds an extra header line to a remailed message.

rm-lt = TIMEThe `Latent-Time:' line causes a remailer to keep your messagefor some time before forwarding it. For example (2h):

rm-lt = 2:00

rm-rlt = YES-OR-NOThis command forces the "random Latent-Time" over the `Latent-Time:'and it is a random delay. The `NO' is a default value.

external-body-processor = FILE-NAME [ARGS]This action command enables an external message body processor,which works on standard input and output. It could be an additionalcrypto engine, a spell checker, some text generator, whatever.

Summary:

add = HEADER LINE
remove = HEADER LINE (a regular expression)
modify = NEW HEADER LINE
rot13-subject = YES-OR-NO
rot13-body = YES-OR-NO
signature-file-attach = YES-OR-NO
body-attach = FILE-NAME
body-clear-attach = FILE-NAME
gpg-passphrase = PASSPHRASE
gpg-encrypt = GPG KEY(S)
gpg-sign = PASSPHRASE or `YES' if `GPG-PASSPHRASE' is specified.
rm-rrt = EMAIL-ADDRESS
rm-post = NEWS-GROUP
rm-gpg = GPG KEY
rm-header = HEADER LINE
rm-lt = TIME
rm-rlt = YES-OR-NO
external-body-processor = FILE-NAME [ARGS]

An example (~/.anubisrc):

---BEGIN REGEX---
IF HEADER =^X-Mailer:
    REMOVE =^X-Mailer:
    ADD = X-EXTRA: TEST
    GPG-SIGN = YOUR PASSPHRASE
    SIGNATURE-FILE-ATTACH = yes
FI
---END---

The example above will remove (on-the-fly) the `X-Mailer:' line froman outgoing email, add an extra header line (`X-EXTRA:'), sign your messagewith your private key, and add a simple signature file from your homedirectory.

Dynamic Commands Manipulation system (aka DCM) (part of the rule system)

@@ -> enables the DCM system.

An example (~/.anubisrc):

---BEGIN REGEX---
IF HEADER =^gpg-encrypt-john
GPG-ENCRYPT = john's_gpg_key
FI
---END---

Now you can simply send an email with the following subject:"hello John!@@gpg-encrypt-john" to process an outgoing emailwith the rule above -> encrypt message with a John's private key.Moreover the DCM will remove the `@@', so John will only receivea message with the subject "hello John!".

SAMPLE BEGINNING

Suppose you have a local MTA, listening on port number 25,and you would like to use Anubis. There are two ways to do that.

The first one, you can reconfigure your MTA, and change its daemon'slistening port number to something different than port number 25,e.g. 1111. Next, you can set in Anubis the following options:

BIND = localhost:25
REMOTE-MTA = localhost:1111

The second one, you can disable your local MTA (disable a daemon)with `ntsysv' tool, or similar. Then you can invoke a localMTA as a program, which works on standard input and output.To do that, set the following options:

BIND = localhost:25
LOCAL-MTA = /PATH/TO/YOUR/MTA/MTA-EXECUTABLE -bs

Caution:The `-bs' command line option is a common way to run MTAson standard input and output,but it is not a rule. Read your local MTA's documentation,how to get it working on standard input and output.

Suppose you have a remote MTA at smtpserver.net,which listens on port number 25 (smtpserver.net:25).This is the easiest way for Anubis. Just specify the followingoptions:

BIND = localhost:25
REMOTE-MTA = smtpserver:25

Caution:In the examples above, Anubis is listening on port number 25(which is a default value for the SMTP). Now you must reconfigure your MUA(Mail User Agent) to make it talk to Anubis. All MUAs are normally set upto talk directly to the MTA, so you must change its configuration.You must specify the localhost:25 as the MTA. This makes Anubis to workas an outgoing mail processor between your MUA and the MTA. Read your MUA'sdocumentation, for more information.

Caution:It is required to install the TCP/IP IDENT protocol server (RFC 1413).Without it, an outgoing mail processor will fail.Most modern GNU/Linux (or *BSD) distributions have already installedsuch a server, but if you do not have it, you must install it by your own.For example: pidentd available atftp://ftp.lysator.liu.se/pub/ident/servers/

USING THE TLS/SSL ENCRYPTION

According to the RFC 2246 document, the TLS (Transport Layer Security)protocol provides communications privacy over the Internet. The protocolallows client/server applications to communicate in a way that is designedto prevent eavesdropping, tampering, or message forgery. The primary goalof the TLS Protocol is to provide privacy and data integrity between twocommunicating applications. The TLS protocol itself is based on the SSL 3.0(Secure Socket Layer) protocol specification.

Anubis supports the TLS/SSL (via the OpenSSL, a cryptographic packageavailable at http://www.openssl.org/), but your MTA (Mail Transport Agent)must provide the STARTTLS command first. This can be checked by:

$ telnet your_smtp_server 25
ehlo your_domain_name

The server will response with available commands. If you will seethe STARTTLS, then you can use the TLS/SSL encryption.If your MUA (Mail User Agent) doesn't support the TLS/SSL encryption,but your MTA does, then you should use the `ONEWAY-SSL' keyword in yourrun control file. Before using the TLS/SSL encryption, you must generatea proper private key and a certificate. You can do it simply with:

$ cd anubis-directory
$ ./autogen.sh keygen

It will create the anubis.pem file.For example copy this file to `/usr/share/ssl/certs/'.Next, edit your run control file by adding:

ssl = yes
key = PATH-TO-THE-PRIVATE-KEY
(e.g. key = /usr/share/ssl/certs/anubis.pem)
cert = PATH-TO-THE-CERTIFICATE
(e.g. cert = /usr/share/ssl/certs/anubis.pem)

NOTE: Each client can specify its own private keyand a certificate by adding the `KEY' and `CERT' keywordsin its own user configuration file (~/.anubisrc).

TIPS & HINTS

Using the `LOCAL-MTA' keyword to invoke the local MTA is notthe most efficient method, simply because it requires executing,every time you send mail, a huge program e.g. Sendmail.Sendmail is a popular mail transport agent, available athttp://www.sendmail.org/.Instead of using the `LOCAL-MTA', try to reconfigure your local MTAby forcing it to run on port number different than 25 (e.g. 1111).Next, edit your run control file by adding the following line:

REMOTE-MTA = localhost:1111

instead of:

LOCAL-MTA = /usr/sbin/sendmail -bs

Read your local MTA's documentation about how to change a daemon'slistening port number. In the Sendmail case, specifying the following linein the /etc/mail/sendmail.mc file is good enough:DAEMON_OPTIONS(`Port=1111,Addr=127.0.0.1,Name=MTA')

FILES

/etc/anubisrc- supervisor's run control file
~/.anubisrc- client's run control file

AUTHORS

The Anubis Team (read the AUTHORS file).Anubis Home Page:http://anubis.sourceforge.net/

LICENSE

Anubis is free software; you can redistribute it and/or modifyit under the terms of the GNU General Public License as published bythe Free Software Foundation; either version 2 of the License, or(at your option) any later version.Anubis is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU General Public License for more details.You should have received a copy of the GNU General Public Licensealong with this program; if not, write to the Free SoftwareFoundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USAAnubis is released under the GPL with the additional exemption thatcompiling, linking, and/or using OpenSSL is allowed.

Index

THE RUN CONTROL FILES

THE CONTROL SECTION
THE EXTERNAL SECTION
THE ALL SECTION
THE RULE SYSTEM
Grammar
SAMPLE BEGINNING
USING THE TLS/SSL ENCRYPTION
TIPS & HINTS

This document was created byman2html,using the manual pages.