gld for Debian
==============

gld stands for GreyList Daemon.

gld is a standalone policy delegation server for postfix that implements the
greylist algorithm as defined at

http://www.greylisting.org

It's written in C and uses MySQL for the database stuff.


Requirements:
------------

postfix >= 2.1
mysql-server

It is possible to have postfix, mysql-server and this daemon all
running on different machines, so this package does not have a Depends
on postfix or mysql-server (only a Suggests). For simplicity, this
document assumes they are all on the same machine.


Configuration:
-------------

* Make sure mysql-server starts on boot. Otherwise gld will not start,
and postfix will not receive any mail. In doubt:

dpkg-reconfigure mysql-server-5.5

* Make sure mysql-server has a priority of 18 or lower in the boot scripts.
The default is 20, which is the same as postfix. gld has 19, so
you will have to lower the priority of mysql-server to 18 at least:

update-rc.d -f mysql remove
update-rc.d mysql defaults 18

Note: The priority-based boot process in wheezy should make this
step not required at all.

* Choose a user, a password and a database name and put them in the
/etc/gld.conf file at the very end.

* Create the database with the chosen name, then create a user
to access the database and give it the password in the previous step.
Assuming that you only changed the password in /etc/gld.conf, you
can easily do this from a mysql shell by doing this:

CREATE DATABASE gld;
GRANT ALL PRIVILEGES ON gld.* TO gld@localhost IDENTIFIED BY 'passwordforgld';
USE gld;
source /usr/share/gld/tables.mysql
source /usr/share/gld/table-whitelist.sql

* Edit /etc/default/gld so that it reads:

ENABLED=1

Then gld will start automatically on boot.

* Start gld and see if there are errors:

invoke-rc.d gld start

You should see something like this:

Starting GreyListing Daemon: gld.

* If everything was ok until this point, postfix will be ready to use gld.
Edit /etc/postfix/main.cf and add a line like this:

check_policy_service inet:127.0.0.1:2525

to the smtpd_recipient_restrictions variable, or any other variable
which is appropriate for this. By default, the Debian postfix package
does not define any variable which is suitable for this, so it is
possible that you will have to add the definition yourself (not just
"add" the check_policy_service line). In such case, you may copy the
following example verbatim:

smtpd_recipient_restrictions = reject_unauth_destination,
  check_policy_service inet:127.0.0.1:2525

It is very important that you have reject_unauth_destination first.
In doubt, install the postfix-doc package and read the Postfix manual,
for which this README.Debian is not meant to be a replacement.

* After changing /etc/postfix/main.cf, reload postfix:

postfix reload


Database cleanup:
----------------

You might want to perform some cleanup of old entries automatically
using a cron job (so that the database do not become polluted by spammers).
Options -c and -k may help here. For example:

#!/bin/sh
set -e
(
gld -c 90
gld -k 7
) | egrep -v 'Cleaned [[:digit:]]+ entries older than [[:digit:]]+ days'


That would clean all database entries not updated in three months and
entries with only one hit not updated in a week.


Bugs:
----

start-stop-daemon is unable to start or kill gld appropriately.
For this reason /etc/init.d/gld does not use start-stop-daemon.
Help will be appreciated to debug this.

Features:
--------

Some people have reported that postfix sometimes has timeout problems
when talking with the gld daemon, the logs from postfix/smtpd are like
this:

warning: timeout on 127.0.0.1:2525 while reading input attribute name
warning: problem talking to server 127.0.0.1:2525: Connection timed out

This may be fixed by increasing the value of smtpd_policy_service_timeout
in /etc/postfix/main.cf. The default value is 100s, so you might want
to try something like this:

smtpd_policy_service_timeout = 240s

Security warnings:
-----------------

* Make sure you have secured your MySQL installation. I usually do this
just after installing mysql-server:

use mysql;
delete from user where user='';
delete from user where host != 'localhost';
update user set password=PASSWORD('somepassword') where user='root';
flush privileges;

then create a file named $HOME/.my.cnf with mode 600 containing this:

[mysql]
user     = root
password = somepassword

* By default, /etc/gld.conf is mode 644, which means every local user
will have access to the gld database. If you don't like this, change
the password and do chmod 640 /etc/gld.conf.

* The default /etc/gld.conf says LOOPBACKONLY=1, which means gld will
only accept connections from localhost. Use LOOPBACKONLY=0 only if you
really need it, i.e. if your greylisting daemon is going to be used by
a Postfix installed in another machine. Make sure the greylisting
daemon may only be accessed by the machine running Postfix.

IPv6
----

In previous releases, the default size for ip field in
/usr/share/gld/tables.mysql was 16 bytes, which is not enough
for IPv6 addresses.

This would be a possible way to convert the database:

invoke-rc.d gld stop
gld-dump > gld.sql
gld-restore < gld.sql
invoke-rc.d gld start

where gld-dump is a script like this:

#!/bin/sh
set -e
eval `grep ^SQL /etc/gld.conf`
mysqldump="mysqldump --add-drop-table --skip-extended-insert --skip-comments"
$mysqldump -h ${SQLHOST} -p ${SQLDB} -u ${SQLUSER} --password=${SQLPASSWD} |\
 sed -e 's/`ip` char(16) NOT NULL DEFAULT/`ip` char(45) NOT NULL DEFAULT/'

and gld-restore is a script like this:

#!/bin/sh
set -e
eval `grep ^SQL /etc/gld.conf`
mysql="mysql"
$mysql -h ${SQLHOST} -p ${SQLDB} -u ${SQLUSER} --password=${SQLPASSWD}