<about>SQLgrey is a postfix policy service implementing a grey-listing policy.[br]
SQLgrey is written in Perl and uses DBI to access an SQL database.[br]
Its goal is reducing the SPAM reaching user mailboxes</about>

<enable_sqlgrey>Enable SQLGrey Policy server</enable_sqlgrey>
<enable_sqlgrey_text>If enabled, artica will add the policy server into it's confugration in order to force postfix asking what he do when receiving mails</enable_sqlgrey_text>

<reconnect_delay>reconnect delay</reconnect_delay>
<reconnect_delay_text>don't allow a reconnection before x minutes</reconnect_delay_text>
<max_connect_age>max connect age</max_connect_age>
<max_connect_age_text>don't allow a reconnection after x hours</max_connect_age_text>
<connect_src_throttle>Throttling too many new entries from new host</connect_src_throttle>
<connect_src_throttle_text>
 Setting this optional parameter will refuse an excessive number of new entries in the connect table from the same host, in the following manner:
 [ul]
[li]If there are already "connect_src_throttle" entries in the connect table from the same host (e-mails which have not been retried yet)[/li]
[li]And there is NO entry for this host in domain awl[/li]
[li]And there are LESS than "connect_src_throttle" entries in the from awl table for this host[/li]
[li]THEN further incoming connections from this host will be (temporarily)refused without new entries being created in the connect table (until some already waiting entries have been successfully retried).[/li]
[/ul]
This feature may prevent the connect table from growing too big and being polluted by spambots, viruses, zombie machines and the like.[br]
If set to "0" (default), this feature won't be used.[br]
</connect_src_throttle_text>

<awl_age>Auto White List age</awl_age>
<awl_age_text>Set in day the maximum days to live in auto white list age.[br]
For bigger sites you may want a smaller Auto White List age and a bigger group domain level
</awl_age_text>

<group_domain_level>Group domain level</group_domain_level>
<group_domain_level_text>wait for X validated adresses to add a whole domain in Auto White List</group_domain_level_text>

<full>greylist by IP address</full>
<classc>greylist by class C network</classc>
<smart>Smart</smart>

<greymethod>Greylisting method</greymethod>
<greymethod_text>[ul]
[li]full   : greylist by IP address[/li]
[li]classc : greylist by class C network. eg: 2.3.4.6 connection accepted if 2.3.4.145 did connect earlier[/li]
[li]smart  : greylist by class C network unless there is no reverse lookup or it looks like a home-user address[/li]
[/ul]
</greymethod_text>

<optmethod>Optin/Optout</optmethod>
<optmethod_text>
SQLgrey behaviour depends on the 'optmethod' configuration variable in sqlgrey.conf
By default Optin/Optout is set to 'none'.[br]
SQLgrey will apply greylisting (with the default whitelisting and auto-whitelisting described in the HOWTO) to every message.
[br]

If Optin/Optout is set to either 'optin' or 'optout', SQLgrey will check four tables to decide if the greylisting must be used.[br]
These four tables are:
[ul]
[li]optin_domain[/li]
[li]optin_email[/li]
[li]optout_domain[/li]
[li]optout_email[/li]
[/ul]

They each have only one column with either a domain name or a full email address (stored as a VARCHAR(255)).
[br]
[br][i][b]the content of each of these table *MUST* be *lowercased*.[br] SQLgrey always use lowercased address internally and for
performance reasons won't ask the database to check for different cases.[/b][/i]
[br]
If 'optin' is used, SQLgrey will only greylist in two cases:
[ul]
[li]the domain is in optin_domain AND the address isn't in optout_email,[/li]
[li]the address is in optin_email.[/li]
[/ul]
[br]
If 'optout' is used, SQLgrey won't greylist in two cases:
[ul]
[li]the domain is in optout_domain AND the address isn't in optin_email,[/li]
[li]the address is in optout_email.[/li]
[/ul]
[br]
[b][i]
SQLgrey doesn't check if the 4 tables' content is consistent. [br]
For example you should make sure that an address isn't both in optin_email and optout_email which doesn't make sense (SQLgrey won't crash but its
behaviour can change between versions).[/i]
[/b]
[br][br]
[H5]Performance guidelines[/H5]
For maximum performance, you should use the method which will use the least table entries.[br]
If nearly all your users want greylisting, you'll have better performance with 'optout'. If all of them want it without exception, use 'none'.[br]

If the needs of your users change between domains, use one of the optin/out_domain tables to set defaults (depending on the optmethod) by domain and add exceptions in the optin/out_email tables. This will
lower the number of entries in the database and help with performance.
[br]
[br][H5]Long email addresses[/H5]

For portability, addresses are limited to 255 characters. If you have users with addresses of more than 255 characters,
you'll have to trim the addresses the same way SQLgrey does: simply take the 255 first characters of the address leaving the rest out.[br]
If you have several users with the same 255 first characters, then it won't work properly (obviously the last user modified will set the
behaviour for the group beginning with the same characters).[br] As addresses of this size are pretty uncommon, the risk of collisions is probably only theoric though.
</optmethod_text>


<discrimination>Discriminating Greylisting</discrimination>
<discrimination_text>

Discrimination behaviour is enabled by the 'discrimination' configuration variable in sqlgrey.conf
[br]
[H5]Default[/H5]

By default discrimination is set to 'off'. [br]
SQLgrey will apply greylisting (with the default whitelisting and auto-whitelisting described in the HOWTO) to every message.[br]
By default 'discrimination add rule number' is 'off'.[br]
If set to on, the greylist reply to the client will have the rule number added to the end  of the rejection text. (eg. 'Greylisted for 5 minutes (2)').
[br]
[H5]Discrimination[/H5]
Discrimination based greylisting is only usefull if you DO NOT want to greylist everybody.
[br]There may be several reasons for this.[br]
For example it can be used as a soft transistion to start greylisting, slowly  over time  making it more and more restrictive. [br]
Or it can help you convince management to allow you to do greylisting by explaining that you'd only greylist "anything suspicous" and thus, not your own  customers.
[br]

[H5]Discrimination - what is it?[/H5]

This feature was pretty hard to find a name for, but discrimination describes pretty well what it does. It discriminates ;).

I think of it as "the airport principle".[br] Everybody is let onto the plane UNLESS they find you suspicous.
You might have long hair,wear a turban, have dark skin or simply wearing a t-shirt saying  "explosive" or "GNU rocks".
[br]Then you will, by discrimination, be held back for further analysis. (im not saying it fair, its just a very good example)
[br]
The same principle applies here.
[br]Everyone is whitelisted UNLESS they look suspicous.[br]
If so, they have to go through greylisting.[br]
What is suspicous is defined in the discrimination.regexp file.[br]
In here one defines regular expression that will be used to check different attributes.[br]
[br][br]
Example:[br]
sender =~ @microsoft.com$
[br][br]
This line simply defines, that if the senders address ends on microsoft.com, its suspicous and thus will be greylisted.[br]
[br][br]
Another example:[br]
sender !~ ^(god|allah|jesus)@heaven.com$[br]
[br][br]
Note the !~ which means "anything that does NOT match, is suspicous".[br]
In this particular example we say: "We trust god, allah or jesus sending from heaven.com, but EVERYONE else will be greylisted."[br]

[br]
[H5]Rule Details[/H5]
The rules in /discrimination.regexp are defines by the following triplet:
[br]
[br]attribute comparison-operator regex[br]
[br]Valid comparison operators are:[br]
[br]=~ 	Equal to
[br]!~	Not Equal to
[br]
Valid attributes are anyhing sent from postfix to the policy deamon,but the ill explain the most common (and usefull) here:
[ul]
[li]sender		= the From address (from MAIL FROM:)[/li]
[li]recipient	= the recipients mail address (from RCPT TO:)[/li]
[li]client_address	= IP address of the client[/li]
[li]client_name	= Reverse-dns name of the client[/li]
[li]helo_name	= The text entered as "helo text"[/li]
[/ul]
[br]
Valid regular expression are simply perl compatable regular expressions.[br]
(without the "/" in beginning and end).[br]
[br]
[H5]Configuration directive: discrimination add rule number[/H5]

enable adds the rule number of the rule that caused the greylisting to the end of the rejection text, like this:[br]
 [i]Greylisted for 5 minutes (2)[/i][br]
In this case, 2 means the second (valid) regular expression in the file,caused the greylisting.[br]
This feature is to allow the support department to help customers figure out why, if their mail gets greylisted.[br]

[br]
[H5]Rule tips[/H5]
Its hard to define what is worthy of another look, and its definently not a 100% solution. [br]
If you have the guts and/or oppotunity, you should go with normal greylisting.[br]
I look often at our maillog and by doing so, start to see patterns to what spam looks like.
[br]You should do the same to find out whats good for greylisting, but some general tips are:[br]
[ul]
[li]missing reverse-dns[/li]
[li]mails from microsoft, fbi, paypal, ebay and the likes[/li]
[li]NULL senders. (blank sender address)[/li]
[li]mailaddresses with special chars (eg. $ or *)[/li]
[/ul][br]
The first one takes alot of the trash. So does NULL senders, but be advised that NULL senders are also legaly used in bounce mails.[br]
[br]
[H5]Performance guidelines[/H5]

It doesnt take much to do this check if you keep your list of expressions within reasonable limits.
[br]Actually this feature should be a performance saver, as it takes away a bunch of sql load, depending on how much you discriminate.[br]
[br]
This function is being used in a real-life scenario with ~100.000 accounts being checked by 10 regular expressions.[br]
There is no measurable perfomance loss.[br]
</discrimination_text>

<discrimination_add_rulenr>discrimination add rule number</discrimination_add_rulenr>
<discrimination_add_rulenr_text>Add discrimination rule number in logs</discrimination_add_rulenr_text>


<reject_first_attempt>Reject first attempt</reject_first_attempt>
<reject_first_attempt_text>
SQLgrey can tell Postfix to:[br]
[ul]
[li]immediately reject a message with a temporary reject code[/li]
[li]only do so if following rules would allow the message to pass [br]
[/ul][br]
The first choice will prevent Postfix from spending time evaluating potentially expensive rules.[br]
In some cases you may want following rules to be aware of the connection this.[br]

[br]We can specify a different rejection strategy for the first connection attempt, and for early reconnections.
[br]'immed' chooses immediate rejection 'delay' choose delayed rejection
</reject_first_attempt_text>

<reject_early_reconnect>Reject early reconnect</reject_early_reconnect>
<reject_early_reconnect_text>Default for early reconnection is the value affected to 'Reject first attempt' </reject_early_reconnect_text>

<whitelists_host>whitelists host</whitelists_host>
<whitelists_host_text>where to get updates for whitelists</whitelists_host_text>

<admin_mail>Administrator email address</admin_mail>
<admin_mail_text>who gets urgent notifications (DB is down for example) empty: don't send mail notifications</admin_mail_text>

<main_settings>Main settings</main_settings>
<fqdn_white_list>FQDN white list</fqdn_white_list>

<fqdn_white_list_text>
SQLgrey expects the following expressions:[br][br]
[b]hostname.domain.com[/b] whole system name (least CPU intensive)[br]
[b]*.domain.com[/b] whitelist any fqdn in the domain 'domain.com'[br]
[b]/regexp/[/b] whitelist any fqdn matching the regexp (by far most CPU intensive)[br]
[br]
[i]Note you need the following two lines to allow both <lots of mtas>.example.com and example.com [b]*.example.com example.com[/b][/i]
</fqdn_white_list_text>

<add_white_list>Add a white listed server</add_white_list>
<ip_white_list>IP white list</ip_white_list>
<ip_white_list_text>Add here only IP address of server that will be exclude from SQLGrey process</ip_white_list_text>
