README

greyd - greylisting & blacklisting daemon
================================================

[![Build Status](https://travis-ci.org/mikey-austin/greyd.svg?branch=master)](https://travis-ci.org/mikey-austin/greyd)

Project Website
---------------

Check out the project website (http://greyd.org) for more information and documentation.

Overview
--------

**greyd** is derived from OpenBSD's **spamd** spam deferral daemon and supporting programs.
As **spamd** is tightly integrated with the PF firewall, there are no production-ready
ports available for the GNU/Linux world. In addition to providing equivalent features
to **spamd**, **greyd** aims to:

  - Be firewall agnostic, and provide a generic interface for pluggable modules,
    to allow operation with *any* suitable firewall (eg iptables/ipset/netfilter, FreeBSD's
    IPFW, etc.). Currently **greyd** can transparently make use of **PF** and **Netfilter**
    with the appropriate drivers.

  - Provide a generic database interface for pluggable modules to work with a variety
    of different databases (eg Berkeley DB, SQLite, MySQL, Postgres, etc.).

  - Be portable and run on many different systems.

  - Have all of the programs in the **greyd** suite be driven by flexible configuration files,
    in addition to supporting the same command line switches as **spamd** & friends.

  - Have a clean & modularized internal structure, to facilitate unit & regression testing
    (there are currently > 750 tests).

  - Be able to import the same blacklists & whitelists that **spamd** can import.

  - Be able to sync seemlessly with native **spamd**.

Platforms
---------

Greyd runs on **GNU/Linux**, **OpenBSD**, **NetBSD**, **FreeBSD** & **DragonFly BSD**, and they can all sync to each other.

The greyd suite
-----------------

**greyd** provides analogous versions of each of the **spamd** programs, namely:

  * **greyd**       - the main spam deferral daemon
  * **greydb**      - greylisting/greytrapping database management
  * **greyd-setup** - blacklist & whitelist population
  * **greylogd**    - connection tracking & whitelist updating

Development Status
------------------

**greyd** is fully functional and is under active development. All of the features from **spamd**
have been implemented, including synchronization support. Additional features not found in **spamd** have also been implemented, such as **SPF** trapping & optional whitelisting, sync support via greydb and fast blacklist lookup via an internal radix trie.

**greyd** is now fully sync compatible with **spamd**, which would allow, for example, an administrator to add a **greyd** instance into a cluster of existing **spamd** instances.

The following database drivers have been implemented:
  * **Berkeley DB** (4.x onwards), which makes full use of transactions.
  * **Berkeley DB SQL** (5.x onwards).
  * **SQLite 3**
  * **MySQL**
  * **PostgreSQL**

For GNU/Linux, a firewall driver has been implemented for the netfilter ecosystem. This driver makes use of:
  * **libipset** for IP set management
  * **libnetfilter-log** for the tracking and auto-whitelisting of connections
  * **libnetfilter-conntrack** (version >= 1.0.4) for the DNAT original destination lookups

For the BSDs, a **PF** firewall driver has been implemented.

Before the first proper release, there is still the following to be done:
  * <del>autotools build configuration</del>
  * <del>man pages & documentation (install guides, user guides, etc.)</del>
  * <del>sample init scripts for some RHEL-like systems (and Debian)</del>
  * more testing in the wild on different setups

Licensing
---------

All of the source is licensed under the OpenBSD license, with the exception of the netfilter
firewall driver. As this driver links with the libnetfilter userland libraries, it must be licensed
under the GPL (as is my understanding!). This does not conflict with the rest of the code base as all **greyd** drivers are/can be
compiled as shared objects, to be dynamically linked at runtime.