1. history

qmail-spp - qmail SMTP plugin patch

1. What's that?

  qmail-spp adds plugin support to qmail's SMTP daemon (qmail-smtpd).  It's
  written entirely in C using native qmail libraries, so it does not create any

2. Why it has been written / Why use it?

  qmail-spp has been written because currently there is no common way of
  enhancing qmail-smtpd's functionality apart of patches which usually are not
  compatible one with other and require recompilation. In addition, qmail-spp
  gives you possibility of enhancing your mail server in any language, so you
  can easily integrate it with anything you want.

3. How does it work?

  Plugins are external programs which are executed after processing SMTP
  command, but just before accepting it by qmail - this lets you to add extra
  checks on commands' arguments before accepting it - for instance you can check
  envelope recipient address against your "black list".

  Plugins can be written in any language, because they are independent programs.

    - should not read anything from standard input,
    - should not exit with error code 120,
    - should print all errors to standard error (they are logged),
    - can print commands on standard output.

  All required data (as HELO host, last RCPT address, etc.) can be retrieved
  from environmental variables.

4. Which SMTP commands can be enhanced this way?

  HELO/EHLO, MAIL, RCPT, DATA and (if supported) AUTH. There is also one
  pseudo-event triggered just after client connection.

5. What environmental variables are set by qmail-spp?

  SMTPHELOHOST     - argument of 'HELO/EHLO' command
  SMTPMAILFROM     - argument of 'MAIL' command
  SMTPRCPTTO       - argument of last 'RCPT' command
  SMTPRCPTCOUNT    - how many times have 'RCPT' command been accepted
  SMTPRCPTCOUNTALL - as above, but counts rejected 'RCPT' commands too
  SMTPRCPTHOSTSOK  - rcpthosts check was successful (1) or not (0)

  If supported:
  SMTPAUTHUSER    - user name of authorized SMTP client
  SMTPAUTHMETHOD  - used SMTP authorization method

  You should probably also take a look at if you use tcpserver (from
  ucspi-tcp package).

6. What environmental variables can I use to control qmail-spp?

  NOSPP       - if set, qmail-spp won't run in this session
  SPPCONFFILE - if set, specifies alternative configuration file
                (instead of standard "control/smtpplugins")

7. What plugin commands are supported and how to use them?

  A            - Accept mail - turn off qmail-spp in this session
  N            - Next - accept current SMTP command (do not execute
                 remaining plugins for this command)
  O            - Ok - like N, but omits qmail checks in MAIL and RCPT
  Emsg         - Error - do not accept this SMTP command and immediately
                 send 'msg' to the client
  LMmsg        - Later, Mail - like E, but shows error after MAIL command
  LRmsg        - Later, Rcpt - like E, but shows error after RCPT command
  LDmsg        - Later, Data - like E, but shows error after DATA command
  Rmsg         - Reject mail - send 'msg' to the client and drop connection
  D            - Drop connection immediately, without printing anything
  Svar=value   - Set environmental variable 'var' to 'value'
  Uvar         - Unset 'var' variable
  Hcontent     - Header - add header 'content' (eg. 'X-Spam-Flag: YES') - Change last address provided by the client to ''
                 (MAIL FROM or RCPT TO address)
  Pmsg         - Print - send 'msg' to the client

  Plugins should simply print commands on standard output, one per line,
  eg. RCPT plugin which prints
    HX-Spam-Flag: YES

    and print "redirected spam from <$SMTPMAILFROM>" to standard error


    change last RCPT TO address to ''
    add 'X-Spam-Flag: YES' header
    set $spam to 1
    accept mail (turn off qmail-spp for this session)

    and log 'redirected spam from <>' message (where
    <> is envelope sender address)


    * each plugin command must end with a new line

    * valid SMTP response codes are not added automatically to messages
    generated by plugins

    * A, N, O, E, R and D should be used as the last command

8. Installation

  Simply cd into the qmail source dir, patch it and install in usual way.

  Following patches are bundled with qmail-spp:

    * qmail-spp.diff - patch against stock qmail 1.03

    * netqmail-spp.diff - patch against netqmail 1.05 -

    * qmail-spp-smtpauth.diff - patch against qmail patched with
    Krzysztof Dabrowski's SMTP AUTH patch -

    * qmail-spp-smtpauth-eh.diff - patch against qmail patched with
    Erwin Hoffman's SMTP AUTH patch v. 0.4.3 -

    * qmail-spp-smtpauth-tls-20060105.diff - patch against netqmail 1.05
    patched with Bill Shupp's smtpauth/tls combo patch v. 20060105, contributed
    by Jason 'XenoPhage' Frisvold (friz /at/ godshell \dot\ com)

    original Shupp's patch at:

  Remember to create configuration file (see below) - you can also use sample
  smtpplugins file bundled in samples/ directory.

9. Configuration

  The main standard configuration file of qmail-spp is


  (assuming that /var/qmail is your qmail home dir).

  It consist of few sections, one for each command:

    connection - for plugins run just after client connection
    helo - for HELO/EHLO
    mail - for MAIL
    rcpt - for RCPT
    data - for DATA
    auth - for AUTH (if supported)

  Section names are marked using square brackets ('[' and ']'). After section
  name there are plugins to execute for this command - one per line.


    # smtpplugins sample file
    :plugins/rbl -r




    :plugins/tarpit --start-after=5 --wait=3


  Paths are relative to the qmail home dir.

  If you want your plugin to be executed by system shell, add ':' just before
  plugin path. This might be useful for debugging or passing arguments to your
  program, but note that this is slightly slower than normal mode.

10. More information

  More information can be found on qmail-spp home page:

11.  Legal notes

  Copyright (c)  2004-2006  Pawel Foremski <>

  Permission is granted to copy, distribute and/or modify this document under
  the terms of the GNU Free Documentation License, Version 1.2 or any later
  version published by the Free Software Foundation; with no Invariant Sections,
  no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be
  found at

# vim: textwidth=80 tabstop=2 expandtab

1. history

CategoryDns CategoryWatch CategoryTemplate

MoinQ: VPS/ConoHa/netqmail/qmail-spp/README (last edited 2023-05-25 11:11:32 by ToshinoriMaeno)