<commit_before>POSTFIX INTEGRATION

Please follow the instructions in the README for building DSPAM. Once DSPAM
has been built, the following instructions may be used to integrate it with
Postfix.


INTEGRATING DSPAM AS A CONTENT FILTER

The most seamless way to integrate DSPAM into Postfix is as a content filter.
This requires very little work, and allows the two to communicate seamlessly.
You may want to first read Postfix's FILTER_README from the Postfix source tree
or online at http://www.postfix.org/FILTER_README.html to familiarize yourself
with what we're doing. In a nutshell, Postfix sends all mail to the content
filter instead of delivering it. It's the content filter's job to then pass
the [modified] message back into Postfix (called reinjection) or do something
else with the message. By default, DSPAM will quarantine what it believes is
spam, but it can be configured to tag it instead. We will use DSPAM's LMTP and
SMTP functionality to integrate the two seamlessly together like so:

[Postfix] (LMTP) -> [DSPAM]                     [Postfix] -> { Delivery }
                       |___ (SMTP Reinjection) ____|

Step 1: Configure DSPAM as a server daemon

  The first step is to configure DSPAM to listen as an LMTP server on a local
  UNIX socket. This is what Postfix will connect to when it sends messages to
  DSPAM. Be sure you have configured DSPAM with the --enable-daemon option.
  You will need to use an MT-safe storage driver, such as MySQL or PostgreSQL.
  Once you have DSPAM installed, make the following changes in dspam.conf:

ServerMode		auto
ServerParameters	"--deliver=innocent"
ServerIdent		"localhost.localdomain"
ServerPID		/var/run/dspam.pid
ServerDomainSocketPath	"/tmp/dspam.sock"

  This will tell DSPAM to listen on /tmp/dspam.sock using the options above.

  You'll also need to configure DSPAM to pass the good mail back into Postfix.
  Comment out any "TrustedDeliveryAgent" option in dspam.conf and replace it
  with the options below. We'll use local TCP port 10026 in our example.

DeliveryHost		127.0.0.1
DeliveryPort		10026
DeliveryIdent		localhost
DeliveryProto		SMTP

  This tells DSPAM to deliver using SMTP to port 10026 on the local machine.
  We'll configure Postfix to listen on this port for reinjection.

  Finally, you'll want to use DSPAM's ParseToHeader option. This option tells
  DSPAM to automatically train when it sees a spam- or notspam- address in
  the To: header. Depending on how you have configured DSPAM to manage users,
  your settings may be slightly different. On a typical setup, where the
  entire email address is the user's DSPAM username, you would use something
  like this:

ParseToHeaders		on
ChangeModeOnParse	on
ChangeUserOnParse	full

  This means if a user forwards their spam to <EMAIL>, the
  username will be set to <EMAIL> and the training mode will be set to
  "learn spam".

  You can then start DSPAM:  dspam --daemon &

Step 2: Configure Postfix to use a content filter

  The next step is to configure Postfix to use DSPAM as a content filter.
  This is relatively simple and requires only a minor change to your
  master.cf file:

  Change:

smtp      inet  n       -       n       -       -        smtpd

  To:

smtp      inet  n       -       n       -       -        smtpd
  -o content_filter=lmtp:unix:/tmp/dspam.sock

  This tells Postfix to send all mail to DSPAM for content filtering.

Step 3: Configure a reinjection port

  You'll also need to configure Postfix to listen on a local port for
  reinjection. This is where DSPAM sends back the "good" mail (or alternatively,
  tagged mail also). Add this to your master.cf:

localhost:10026 inet  n -       n       -       -        smtpd
  -o content_filter=
  -o receive_override_options=no_unknown_recipient_checks,no_header_body_checks
  -o smtpd_helo_restrictions=
  -o smtpd_client_restrictions=
  -o smtpd_sender_restrictions=
  -o smtpd_recipient_restrictions=permit_mynetworks,reject
  -o mynetworks=127.0.0.0/8
  -o smtpd_authorized_xforward_hosts=127.0.0.0/8

  Any mail sent to localhost:10026 will be delivered in whatever way you
  have configured Postfix, without being passed through DSPAM again. This is
  also where DSPAM will deliver false positives to when they are retrained by
  the user.

You're now good to go! Turn on Postfix and do a little testing. Send a message
to yourself on port 25. It should have X-DSPAM headers. Send a message to
yourself on port 10026. It should not.

If you are deadset against running DSPAM as a server daemon, this design can
be changed to call DSPAM via commandline, and have DSPAM reinject by calling
Postfix's sendmail function. I wouldn't recommend this, but here's how.
Instead of configuring DSPAM's DeliveryHost and Server options, you'll want to
configure DSPAM to call sendmail to deliver mail:
<commit_msg>Add notes about: - chrooted postfix setup - a method to only filter incoming mail (when the SMTP server is also used as a relay).<commit_after>POSTFIX INTEGRATION

Please follow the instructions in the README for building DSPAM. Once DSPAM
has been built, the following instructions may be used to integrate it with
Postfix.


INTEGRATING DSPAM AS A CONTENT FILTER

The most seamless way to integrate DSPAM into Postfix is as a content filter.
This requires very little work, and allows the two to communicate seamlessly.
You may want to first read Postfix's FILTER_README from the Postfix source tree
or online at http://www.postfix.org/FILTER_README.html to familiarize yourself
with what we're doing. In a nutshell, Postfix sends all mail to the content
filter instead of delivering it. It's the content filter's job to then pass
the [modified] message back into Postfix (called reinjection) or do something
else with the message. By default, DSPAM will quarantine what it believes is
spam, but it can be configured to tag it instead. We will use DSPAM's LMTP and
SMTP functionality to integrate the two seamlessly together like so:

[Postfix] (LMTP) -> [DSPAM]                     [Postfix] -> { Delivery }
                       |___ (SMTP Reinjection) ____|

Step 1: Configure DSPAM as a server daemon

  The first step is to configure DSPAM to listen as an LMTP server on a local
  UNIX socket. This is what Postfix will connect to when it sends messages to
  DSPAM. Be sure you have configured DSPAM with the --enable-daemon option.
  You will need to use an MT-safe storage driver, such as MySQL or PostgreSQL.
  Once you have DSPAM installed, make the following changes in dspam.conf:

ServerMode		auto
ServerParameters	"--deliver=innocent"
ServerIdent		"localhost.localdomain"
ServerPID		/var/run/dspam.pid
ServerDomainSocketPath	"/tmp/dspam.sock"

  This will tell DSPAM to listen on /tmp/dspam.sock using the options above.

  You'll also need to configure DSPAM to pass the good mail back into Postfix.
  Comment out any "TrustedDeliveryAgent" option in dspam.conf and replace it
  with the options below. We'll use local TCP port 10026 in our example.

DeliveryHost		127.0.0.1
DeliveryPort		10026
DeliveryIdent		localhost
DeliveryProto		SMTP

  This tells DSPAM to deliver using SMTP to port 10026 on the local machine.
  We'll configure Postfix to listen on this port for reinjection.

  Finally, you'll want to use DSPAM's ParseToHeader option. This option tells
  DSPAM to automatically train when it sees a spam- or notspam- address in
  the To: header. Depending on how you have configured DSPAM to manage users,
  your settings may be slightly different. On a typical setup, where the
  entire email address is the user's DSPAM username, you would use something
  like this:

ParseToHeaders		on
ChangeModeOnParse	on
ChangeUserOnParse	full

  This means if a user forwards their spam to <EMAIL>, the
  username will be set to <EMAIL> and the training mode will be set to
  "learn spam".

  You can then start DSPAM:  dspam --daemon &

Step 2: Configure Postfix to use a content filter

  The next step is to configure Postfix to use DSPAM as a content filter.
  This is relatively simple and requires only a minor change to your
  master.cf file:

  Change:

smtp      inet  n       -       n       -       -        smtpd

  To:

smtp      inet  n       -       n       -       -        smtpd
  -o content_filter=lmtp:unix:/tmp/dspam.sock

  This tells Postfix to send all mail to DSPAM for content filtering.

  If your Postfix installation is chrooted (as eg. the default Postfix 
  configuration in Debian GNU/Linux), make sure the socket is located 
  within the chroot (eg. /var/spool/postfix/var/run/dspam/dspam.sock).

  Make sure the user under which dspam runs has write access to the
  socket directory.

  You can also change Postfix configuration so that it does not run
  chrooted (both smtp and lmtp services should be modified as follows:

smtp      inet  n       -       n       -       -        smtpd
  -o content_filter=lmtp:unix:/var/run/dspam/dspam.sock
lmtp      inet  n       -       n       -       -        smtpd

  The 3rd dash specifies if the process will run chrooted or not.


 If your SMTP server is also used as a relay, and you want DSPAM to
 only inspect incoming mail, you can use the following as an alternative
 to the pure content filtering method:

 You will need Postfix support for PCRE maps (perl compatible regular
 expression).
 
 In Postfix main.cf, add the following to your smtpd_recipient_restrictions:

smtpd_recipient_restrictions = 
  [...]
  check_recipient_access pcre:/etc/postfix/dspam_filter_access

 where dspam_filter_access contains:

/./ FILTER dspam:dspam

  Run postmap /etc/postfix/dspam_filter_access

 Add he following service at the end of master.cf:

dspam                 unix    -       n       n       -       -    pipe
  flags=Ru user=dspam argv=/usr/bin/dspam --client --deliver=innocent,spam --user ${recipient} --mail-from=${sender}

 You will also have to add the following line in main.cf:
dspam_destination_recipient_limit = 1


Step 3: Configure a reinjection port

  You'll also need to configure Postfix to listen on a local port for
  reinjection. This is where DSPAM sends back the "good" mail (or alternatively,
  tagged mail also). Add this to your master.cf:

localhost:10026 inet  n -       n       -       -        smtpd
  -o content_filter=
  -o receive_override_options=no_unknown_recipient_checks,no_header_body_checks
  -o smtpd_helo_restrictions=
  -o smtpd_client_restrictions=
  -o smtpd_sender_restrictions=
  -o smtpd_recipient_restrictions=permit_mynetworks,reject
  -o mynetworks=127.0.0.0/8
  -o smtpd_authorized_xforward_hosts=127.0.0.0/8

  Any mail sent to localhost:10026 will be delivered in whatever way you
  have configured Postfix, without being passed through DSPAM again. This is
  also where DSPAM will deliver false positives to when they are retrained by
  the user.

You're now good to go! Turn on Postfix and do a little testing. Send a message
to yourself on port 25. It should have X-DSPAM headers. Send a message to
yourself on port 10026. It should not.

If you are deadset against running DSPAM as a server daemon, this design can
be changed to call DSPAM via commandline, and have DSPAM reinject by calling
Postfix's sendmail function. I wouldn't recommend this, but here's how.
Instead of configuring DSPAM's DeliveryHost and Server options, you'll want to
configure DSPAM to call sendmail to deliver mail:

{'fraction_non_alphanumeric': 0.04575794835763218, 'fraction_numerical': 0.009836641489548568, 'mean_word_length': 3.376249039200615, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 6, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 9, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6028696', 'n_tokens_mistral': 3542, 'n_tokens_neox': 3305, 'n_words': 1582}