
AuthBackupChecker C++ filter for Communigate Pro
2010 Niversoft Ides Logicielles


The AuthBackupChecker C++ filter is intended to act as an external
authenticator in Communigate Pro and process unknown names to route some of
them to external servers for which the current host acts as backup.

In short, the filter validates the unknown name against its internal tables,
then contacts the target host to verify if the target account is valid.
Finally, it tells CGP to route the message to the target account/host.

Function detail:

The sqlite database contains a list of domains that has to be relayed,
including IPs, port and the desired order if there is many IPs for one domain.
The database also contains a domain alias table to avoid repeating entries.

The filter works as an external authenticator. When it receives a request, it
first rejects anything which is not [MAIL], doesn't have a fully qualified
email address, or for which the domain part does not match an entry in the
alias or the domain table. In that case, CGP will process the unknown name
normally, either passing it to another authenticator or rejecting it.

If the domain is found is the table, the filter then retrieves the connection
data for this domain, including a previously opened socket if any, as the
filter caches previous connections for as long as it can. It checks in its
account_cache database for the presence of a previous positive or negative
result that is not yet expired, to avoid querying the target server for things
it already knows. If found, it returns the answer to CGP, whether or not this
is a known account.

If nothing is found in the cache or entries are expired, the filter tries an
SMTP connection, reusing the previous connection if any, and issues a simple
MAIL FROM <>, RCPT TO: <target email>, to see if the target server would
accept the email.

This is compatible with most SMTP servers, providing it is configured to give
an immediate valid answer to this query to the backup server.

The filter finally caches the information and returns the final positive or
negative answer to CGP. The cached entries are set to expire after a
configurable delay, by default one week for positive values, one day for
negative ones.

In the event the filter is unable to connect to any of the IPs provided for a
target host, or if the target host returns a 4xx answer (temp failure), the
filter returns a positive answer to CGP, but does not cache it. It will return
negative only when it receives a definitive negative answer from the target
host (5xx, account does not exist).

Usage:

In CGP, if not already done, create the domains you backup. These are usually
empty domains. In these domains settings, make sure the "Consult External for
Unknown" setting is set to Yes.

Add the filter to the External Authentication section of the CGP Helpers page
(Webadmin: Settings / General / Helpers)
Set the Log Level to All Info.

The domains you setup in the filter should not be included in your Router
table

Command-line switches
--help, -h:       Display Help.
--uncache, -u:    Remove all previously cached addresses
                     from the database on startup.
--verbose, -v:    Log all the SMTP transactions
--expire, -e:     Specify the expire delay, in hours,
                     for positive cached entries.
--nexpire, -n:    Specify the expire delay, in hours,
                     for negative cached entries.

To setup the domain list, you need to add them to the sqlite database using
the sqlite3 command-line tool available in many linux distributions and other
supported OS, or another sqlite database manager such as the SQLite Manager
extension for Firefox. You can connect and modify the database while the
filter is running. The database is automatically created and populated with
the correct tables the first time the filter is ran.

You will need to edit the "domain_ips" table and the "domain_aliases" table.

In the domain_ips table, enter the "main" name for each backuped server, its
IP and port (you can leave the column to NULL for the default port). The
filter does not perform DNS operations, it is unlikely to work if the backuped
server has a dynamic IP, unless you use another tool to update the database
automatically. If the target server has several IPs and you would like each
one to be tested, create one row per IP. You can set the order you wish the
IPs to be tested on.

domain_ips
domain(VARCHAR), ip(VARCHAR), port(INTEGER), order(INTEGER)

In the domain_aliases, enter each domain name that points to the servers
entered in domain_ips. If one host hosts several domains, each of them,
including each possible alias has to be entered in the domain_aliases table so
the filter knows it has to check them.

domain_aliases
alias(VARCHAR), domain(VARCHAR)

The value in the domain colum has to exist in the domain_ips table. If it
doesn't, the filter will issue a temporary internal error (failure) for each
request involving the affected aliases.

The filter is available for Linux (x86, x64), Mac OSX (Intel, PPC),
FreeBSD 6+ (x86, x64), Windows (Win32, x64), Solaris (SPARC, i386), and
requires glibc 2.5 and up except on Windows.

For more information please contact Niversoft at info@niversoft.com
