To begin with you need a sqlgrey user :
- groupadd sqlgrey
- adduser -g sqlgrey sqlgrey

#####################
## Database choice ##
#####################

SQLite: quick and dirty way. The database is integrated with sqlgrey.
MySQL: lightweight RDBMS, quite fast but not as stable and standard
	 compliant as PostgreSQL.
PostgreSQL: full-fledge, very mature RDBMS.

###########
## SQLite 

# Dependancies:
you need the DBD::SQLite perl module (and libsqlite of course).

# Howto:
Setup /etc/sqlgrey/sqlgrey.conf with
db_type = SQLite
db_name = <whatever_you_want_as_name>

# Note:
sqlgrey will create the file storing database data in the working
directory: launch sqlgrey in its home directory.

##########
## MySQL

# Dependancies:
you need the DBD::MySQL perl module and a working MySQL server.

# Howto:
Launch the 'mysql' command-line utility with admin rights.
Create a sqlgrey database:
- For MySQL < 5.0
  > CREATE DATABASE sqlgrey;
- For MYSQL >= 5.0
  > CREATE DATABASE sqlgrey CHARACTER SET latin1;

Then set up access rights:
> GRANT ALL ON sqlgrey.* TO sqlgrey@localhost;

Setup /etc/sqlgrey/sqlgrey.conf with
db_type = mysql
db_name = sqlgrey

# Note:
MySQL is really fast. I'd recommend it if you don't want to host critical
databases with high access concurrency.

###############
## PostgreSQL

# Dependancies:
you need the DBD::Pg perl module and a working PostgreSQL server.

# Howto:
1/ Create a sqlgrey database and a PostgreSQL sqlgrey user:
as postgres user (su - postgres):

-bash-2.05b$ createuser sqlgrey
Shall the new user be allowed to create databases? (y/n) y
Shall the new user be allowed to create more new users? (y/n) n
CREATE USER
-bash-2.05b$

You'll have to check your pg_hba.conf file if you're not sure about
the access control configuration. For the next step, you need to be
able to connect as sqlgrey.

-bash-2.05b$ createdb -U sqlgrey sqlgrey
CREATE DATABASE
-bash-2.05b$

Pay attention to the access controls: as Unix user sqlgrey, you must
be able to connect to the sqlgrey database as sqlgrey PostgreSQL user...
Look into pg_hba.conf and if needed set a password for the PostgreSQL
sqlgrey user.
sqlgrey will use the TCP/IP socket to connect, please make sure that
"tcpip_socket = true"
is in your 'postgresql.conf' file.

This is my personnal recommendation, really robust, can scale up and
down when properly configured.

###########################
## Postfix configuration ##
###########################

Start by adding check_policy_service after reject_unauth_destination in
/etc/postfix/main.cf:

 smtpd_recipient_restrictions =
               ...
               reject_unauth_destination
               check_policy_service inet:127.0.0.1:2501

This assumes sqlgrey will listen on the TCP 2501 port (default) and is
on the same host.

## Example:
A complete example for a site that uses SASL authentication and various
anti-SPAM rules, all in smtpd_recipient_restrictions:

smtpd_recipient_restrictions =
# -----------------
# -- Our clients --
# -----------------
# our networks are welcomed
        permit_mynetworks
# SASL clients (SMTP auth) are ok too
        permit_sasl_authenticated
# ------------
# -- Others --
##------------
# 3 quick checks on senders/recipients
        reject_unknown_sender_domain
        reject_non_fqdn_sender
        reject_non_fqdn_recipient
# helo/ehlo syntax check
        reject_invalid_hostname
# Seen false positives, but really efficient on UCE
# forbid <name> helos and enforces <fqdn> helos
#       reject_non_fqdn_hostname
# at this stage we must be the destination
        reject_unauth_destination
# check for obvious helo fakes
        check_helo_access hash:/etc/postfix/smtp_helo_blacklist
# RCPT TO not in our maps (reject early instead of bouncing messages)
        reject_unlisted_recipient
# SQLgrey is called here
        check_policy_service inet:127.0.0.1:2501
# RBL checks
        reject_rbl_client sbl-xbl.spamhaus.org
        reject_rbl_client list.dsbl.org

Note: smtp_helo_blacklist looks like that:

[xxx.xxx.xxx.xxx]       554 Liar: This is one of our IPs
[yyy.yyy.yyy.yyy]       554 Liar: This is one of our IPs
my.hostname.tld         554 Liar: That's my hostname
mydomain.tld            554 Liar: That's my domain
.mydomain.tld           554 Liar: You aren't part of my domain
mydomain2.tld           554 Liar: That's my domain
.mydomain2.tld          554 Liar: You aren't part of my domain

*Important* note about RBLs:
As using a rbl imply handing the decision to reject mail to
outsiders, you are strongly advised to review and understand
one RBL's listing policy *before* adding it to your
configuration.

##################
## Whitelisting ##
##################

Some MTAs don't play well with greylisting (often because they don't
respect the RFCs). To work around this problem (that your users won't
fail to report to you when it will happen):
- don't disable sqlgrey logs (by default it will log what you need).
- ask your user for the e-mail of the person that unsuccesfully tried
 to send mail to her/him and when the unsuccessfull attempt occured.
- in the meantime, if the transmission failure occured recently (less than
max_connect_age in sqlgrey.conf, by default 24 hours) advise your user to
contact the sender and politely ask her to re-send the message, there are
good chances that the second attempt will get through (SQLgrey will probably
find a match: the first attempt).
- grep your mail logs for the address, you'll find a line like this
<timestamp> <system> sqlgrey: grey: new: <id>(www.xxx.yyy.zzz): <sender_address> -> <your_user>
by default, one day later you'll find this line:
<timestamp> <system> sqlgrey: spam: <id>: <sender_address> -> <your_user> at <timestamp>

What matters to you is the IP address (or the class C network) and
the domain name it is associated with. If Postfix could find a reliable
domain name (the reverse lookup must itself point to the IP address),
you'll find it in one of the lines in your log before the first
sqlgrey log line.

If you can get a reliable domain name, put it in
/etc/sqlgrey/clients_fqdn_whitelist.local
do *not* touch the /etc/sqlgrey/clients_fqdn_whitelist file as it will
be overwritten by a future sqlgrey installation or update_sqlgrey_config
The top of /etc/sqlgrey/clients_fqdn_whitelist explains the expected
formats.
You don't need to restart sqlgrey as it monitors the ".local" files
and reload them as soon as they change or when they are created for
the first time.

If you can't get a reliable domain name, just put the IP address in
the /etc/sqlgrey/clients_ip_whitelist.local file. If you need to,
you can add a whole class C network by putting a line with only the
three first bytes of the IP addresses.
IPv6 addresses are also supported in this file.

As it's quite important I repeat: only look for the installed
clients_*_whitelist files for reference and put your own entries
in the corresponding *.local files.

You are advised to subscribe to the sqlgrey-users mailing-list
(see http://lists.sourceforge.net/lists/listinfo/sqlgrey-users)
and submit the IP addresses and domain names you have to add to
your .local files to make your users happy and the reason why
you did so (see comments on why the existing systems are added).

As of 1.4.3, SQLgrey's whitelists can be updated from a central
repository with the update_sqlgrey_config script.
update_sqlgrey_config outputs modified entries on STDOUT.
Running it from cron once a day (updates are scarcely needed and
the average interval between updates is roughly one month) is a
great way to be warned of new whitelist entries or old entries
being cleaned up.

#####################
# Warnings by email #
#####################

SQLgrey can send emails when it detects anomalies. You need to:
- make sure the user SQLgrey runs as (should be sqlgrey) can send emails
with the 'mail' command. use
echo "test" | mail -s "SQLgrey test" <mailbox@a-domain.tld>
and check that the message made it through.
- put the following line (replace with your email address):
admin_mail = <postmaster@yourdomain>
in /etc/sqlgrey/sqlgrey.conf

That's all. SQLgrey will make sure it doesn't flood your mailbox by
rate-limiting the emails it sends.

##################
# OPTIN / OPTOUT #
##################

See README.OPTINOUT

#################
# RPM Packaging #
#################

Some of the steps required to install SQLgrey are covered by a RPM
package built with the included spec file:
- creates a sqlgrey user,
- installs a /etc/init.d/sqlgrey SysV init file,
- installs a /etc/sqlgrey/sqlgrey.conf config file
- installs /etc/sqlgrey/clients_*_whitelist files

What's left to you is the Postfix and Database setup.

#################
# Gentoo ebuild #
#################

The sourceforge site (http://sqlgrey.sourceforge.net/) points to the
latest ebuild available. See http://linuxreviews.org/gentoo/ebuilds/
for how to use it.

If you use the ebuild and haven't done so yet, please fill a comment on
http://bugs.gentoo.org/show_bug.cgi?id=71535

#####################
# Reloading SQLgrey #
#####################

If you change the sqlgrey.conf file you must restart SQLgrey to re-read it.
If you change distributed whitelists (not local ones, they are automatically
reloaded) or want to force a database reconnection you can force a reload by
sending SIGUSR1 to the sqlgrey process.