Plugins are the heart of qpsmtpd. The core implements only basic SMTP protocol functionality. No useful function can be done by qpsmtpd without loading plugins.

Plugins are loaded on startup where each of them register their interest in various hooks provided by the qpsmtpd core engine.

At least one plugin must allow or deny the RCPT command to enable receiving mail. The check_relay plugin is the standard plugin for this. Other plugins provide extra functionality related to this; for example the require_resolvable_fromhost plugin.

The list of plugins to load are configured in the config/plugins configuration file. One plugin per line, empty lines and lines starting with # are ignored. The order they are loaded is the same as given in this config file. This is also the order the registered hooks are run. The plugins are loaded from the plugins/ directory or from a subdirectory of it. If a plugin should be loaded from such a subdirectory, the directory must also be given, like the virus/clamdscan in the example below. Alternate plugin directories may be given in the config/plugin_dirs config file, one directory per line, these will be searched first before using the builtin fallback of plugins/ relative to the qpsmtpd root directory. It may be necessary, that the config/plugin_dirs must be used (if you're using Apache::Qpsmtpd, for example).

Some plugins may be configured by passing arguments in the plugins config file.

A plugin can be loaded two or more times with different arguments by adding :N to the plugin filename, with N being a number, usually starting at 0.

Another method to load a plugin is to create a valid perl module, drop this module in perl's ”@INC” path and give the name of this module as plugin name. The only restriction to this is, that the module name must contain ::, e.g. “My::Plugin” would be ok, “MyPlugin” not. Appending of :0, :1, … does not work with module plugins.

 check_relay
 virus/clamdscan
 spamassassin reject_threshold 7
 my_rcpt_check example.com
 my_rcpt_check:0 example.org
 My::Plugin

A plugin has at least one method, which inherits from the “Qpsmtpd::Plugin” object. The first argument for this method is always the plugin object itself (and usually called “$self”). The most simple plugin has one method with a predefined name which just returns one constant.

 # plugin temp_disable_connection
 sub hook_connect {
    return(DENYSOFT, "Sorry, server is temporarily unavailable.");
 }

While this is a valid plugin, it is not very useful except for rare circumstances. So let us see what happens when a plugin is loaded.

After the plugin is loaded the “init()” method of the plugin is called, if present. The arguments passed to “init()” are

• $self the current plugin object, usually called “$self”
• $qp the Qpsmtpd object, usually called “$qp”.
• @args the values following the plugin name in the plugins config, split by white space. These arguments can be used to configure the plugin with default and/or static config settings, like database paths, timeouts, …

This is mainly used for inheriting from other plugins, but may be used to do the same as in “register()”.

The next step is to register the hooks the plugin provides. Any method which is named “hook_$hookname” is automagically added.

Plugins should be written using standard named hook subroutines. This allows them to be overloaded and extended easily. Because some of the callback names have characters invalid in subroutine names , they must be translated. The current translation routine is “s/\W/_/g;”. If you choose not to use the default naming convention, you need to register the hooks in your plugin in the “register()” method (see below) with the “register_hook()” call on the plugin object.

  sub register {
    my ($self, $qp, @args) = @_;
    $self->register_hook("mail", "mail_handler");
    $self->register_hook("rcpt", "rcpt_handler");
  }
  sub mail_handler { ... }
  sub rcpt_handler { ... }

The “register()” method is called last. It receives the same arguments as “init()”. There is no restriction, what you can do in “register()”, but creating database connections and reuse them later in the process may not be a good idea. This initialisation happens before any “fork()” is done. Therefore the file handle will be shared by all qpsmtpd processes and the database will probably be confused if several different queries arrive on the same file handle at the same time (and you may get the wrong answer, if any). This is also true for qpsmtpd-async and the pperl flavours, but not for qpsmtpd started by (x)inetd or tcpserver.

In short: don't do it if you want to write portable plugins.

Inheriting methods from other plugins is an advanced topic. You can alter arguments for the underlying plugin, prepare something for the real plugin or skip a hook with this. Instead of modifying ”@ISA” directly in your plugin, use the “isa_plugin()” method from the “init()” subroutine.

  # rcpt_ok_child
  sub init {
    my ($self, $qp, @args) = @_;
    $self->isa_plugin("rcpt_ok");
  }
 
  sub hook_rcpt {
    my ($self, $transaction, $recipient) = @_;
    # do something special here...
    $self->SUPER::hook_rcpt($transaction, $recipient);
  }

See also chapter “Changing return values” and contrib/vetinari/rcpt_ok_maxrelay in SVN.

Most of the existing plugins fetch their configuration data from files in the config/ sub directory. This data is read at runtime and may be changed without restarting qpsmtpd. (: caching?!) The contents of the files can be fetched via

  @lines = $self->qp->config("my_config");

All empty lines and lines starting with ”#” are ignored.

If you don't want to read your data from files, but from a database you can still use this syntax and write another plugin hooking the “config” hook.

Log messages can be written to the log file (or STDERR if you use the logging/warn plugin) with

  $self->qp->log($loglevel, $logmessage);

The log level is one of (from low to high priority)

• LOGDEBUG
• LOGINFO
• LOGNOTICE
• LOGWARN
• LOGERROR
• LOGCRIT
• LOGALERT
• LOGEMERG

While debugging your plugins, you want to set the log level in the logging config file to LOGDEBUG. This will log very much data. To restrict this output just to the plugin you are debugging, you can use the following plugin:

 # logging/debug_plugin - just show LOGDEBUG messages of one plugin
 # Usage: 
 #  logging/debug_plugin my_plugin LOGLEVEL
 #
 #  LOGLEVEL is the log level for all other log messages
 use Qpsmtpd::Constants;
 
 sub register {
   my ($self, $qp, $plugin, $loglevel) = @_;
   die "no plugin name given"
     unless $plugin;
   $loglevel = "LOGWARN"
     unless defined $loglevel;
   $self->{_plugin} = $plugin;
   $self->{_level}  = Qpsmtpd::Constants::log_level($loglevel);
   $self->{_level}  = LOGWARN 
     unless defined $self->{_level};
 }
 
 sub hook_logging {
   my ($self, $transaction, $trace, $hook, $plugin, @log) = @_;
   return(OK) # drop these lines
     if $plugin ne $self->{_plugin} and $trace > $self->{_level};
   return(DECLINED);
 }

The above plugin should be loaded before the default logging plugin, which logs with LOGDEBUG. The plugin name must be the one returned by the “plugin_name()” method of the debugged plugin. This is probably not the same as the name of the plugin (i.e. not the same you write in the plugins config file). In doubt: take a look in the log file for lines like “queue::qmail_2dqueue hooking queue” (here: queue/qmail-queue ⇒ queue::qmail_2dqueue).

Each plugin inherits the public methods from “Qpsmtpd::Plugin”.

• plugin_name() Returns the name of the currently running plugin
• hook_name() Returns the name of the running hook
• auth_user() Returns the name of the user the client is authed as (if authentication is used, of course)
• auth_mechanism() Returns the auth mechanism if authentication is used
• connection() Returns the “Qpsmtpd::Connection” object associated with the current connection
• transaction() Returns the “Qpsmtpd::Transaction” object associated with the current transaction

The temporary file and directory functions can be used for plugin specific workfiles and will automatically be deleted at the end of the current transaction.

• temp_file() Returns a unique name of a file located in the default spool directory, but does not open that file (i.e. it is the name not a file handle).
• temp_dir() Returns the name of a unique directory located in the default spool directory, after creating the directory with 0700 rights. If you need a directory with different rights (say for an antivirus daemon), you will need to use the base function “$self→qp→temp_dir()”, which takes a single parameter for the permissions requested (see mkdir for details). A directory created like this will not be deleted when the transaction is ended.
• spool_dir() Returns the configured system-wide spool directory.

Both may be used to share notes across plugins and/or hooks. The only real difference is their life time. The connection notes start when a new connection is made and end, when the connection ends. This can, for example, be used to count the number of none SMTP commands. The plugin which uses this is the count_unrecognized_commands plugin from the qpsmtpd core distribution.

The transaction note starts after the MAIL FROM: command and are just valid for the current transaction, see below in the reset_transaction hook when the transaction ends.

Each plugin must return an allowed constant for the hook and (usually) optionally a “message” for the client. Generally all plugins for a hook are processed until one returns something other than DECLINED.

Plugins are run in the order they are listed in the plugins configuration file.

The return constants are defined in “Qpsmtpd::Constants” and have the following meanings:

• DECLINED Plugin declined work; proceed as usual. This return code is always allowed unless noted otherwise.
• OK Action allowed.
• DENY Action denied.
• DENYSOFT Action denied; return a temporary rejection code (say 450 instead of 550).
• DENY_DISCONNECT Action denied; return a permanent rejection code and disconnect the client. Use this for “rude” clients. Note that you're not supposed to do this according to the SMTP specs, but bad clients don't listen sometimes.
• DENYSOFT_DISCONNECT Action denied; return a temporary rejection code and disconnect the client. See note above about SMTP specs.
• DONE Finishing processing of the request. Usually used when the plugin sent the response to the client.

The YIELD constant is not mentioned here, because it is not used by plugins directly.

This section covers the hooks, which are run in a normal SMTP connection. The order of these hooks is like you will (probably) see them, while a mail is received.

Every hook receives a “Qpsmtpd::Plugin” object of the currently running plugin as the first argument. A “Qpsmtpd::Transaction” object is the second argument of the current transaction in the most hooks, exceptions are noted in the description of the hook. If you need examples how the hook can be used, see the source of the plugins, which are given as example plugins.

NOTE: for some hooks (post-fork, post-connection, disconnect, deny, ok) the return values are ignored. This does not mean you can return anything you want. It just means the return value is discarded and you can not disconnect a client with DENY_DISCONNECT. The rule to return DECLINED to run the next plugin for this hook (or return OK / DONE to stop processing) still applies.

Called by a controlling process (e.g. forkserver or prefork) after accepting the remote server, but before beginning a new instance (or handing the connection to the worker process).

Useful for load-management and rereading large config files at some frequency less than once per session.

This hook is available in the qpsmtpd-forkserver, qpsmtpd-prefork and qpsmtpd-async flavours.

NOTE: You should not use this hook to do major work and / or use lookup methods which (may) take some time, like DNS lookups. This will slow down all incoming connections, no other connection will be accepted while this hook is running!

Arguments this hook receives are (NOTE: currently no ”%args” for qpsmtpd-async):

  my ($self,$transaction,%args) = @_;
  # %args is:
  # %args = ( remote_ip    => inet_ntoa($iaddr),
  #           remote_port  => $port,
  #           local_ip     => inet_ntoa($laddr),
  #           local_port   => $lport,
  #           max_conn_ip  => $MAXCONNIP,
  #           child_addrs  => [values %childstatus],
  #         );

NOTE: the “$transaction” is of course “undef” at this time.

Allowed return codes are

• DENY / DENY_DISCONNECT returns a 550 to the client and ends the connection
• DENYSOFT / DENYSOFT_DISCONNECT returns a 451 to the client and ends the connection

Anything else is ignored.

Example plugins are hosts_allow and connection_time.

It is called at the start of a connection before the greeting is sent to the connecting client.

Arguments for this hook are

  my $self = shift;

NOTE: in fact you get passed two more arguments, which are “undef” at this early stage of the connection, so ignore them.

Allowed return codes are

• OK Stop processing plugins, give the default response
• DECLINED Process the next plugin
• DONE Stop processing plugins and dont give the default response, i.e. the plugin gave the response
• DENY Return hard failure code and disconnect
• DENYSOFT Return soft failure code and disconnect

Example plugin for this hook is the check_relay plugin.

It is called after the client sent EHLO (hook_ehlo) or HELO (hook_helo) Allowed return codes are

• DENY Return a 550 code
• DENYSOFT Return a 450 code
• DENY_DISCONNECT / DENYSOFT_DISCONNECT as above but with disconnect
• DONE Qpsmtpd wont do anything, the plugin sent the message
• DECLINED Qpsmtpd will send the standard EHLO/HELO answer, of course only if all plugins hooking helo/ehlo return DECLINED.

Arguments of this hook are

  my ($self, $transaction, $host) = @_;
  # $host: the name the client sent in the 
  # (EH|HE)LO line

NOTE: “$transaction” is “undef” at this point.

After the MAIL FROM: line sent by the client is broken into pieces by the “hook_mail_parse()”, this hook recieves the results. This hook may be used to pre-accept adresses without the surrounding <> (by adding them) or addresses like <user@example.com.> or <user@example.com > by removing the trailing ”.” / ”” ””.

Expected return values are OK and an address which must be parseable by “Qpsmtpd::Address→parse()” on success or any other constant to indicate failure.

Arguments are

  my ($self, $transaction, $addr) = @_;

Called right after the envelope sender line is parsed (the MAIL FROM: command). The plugin gets passed a “Qpsmtpd::Address” object, which means the parsing and verifying the syntax of the address (and just the syntax, no other checks) is already done. Default is to allow the sender address. The remaining arguments are the extensions defined in RFC 1869 (if sent by the client).

NOTE: According to the SMTP protocol, you can not reject an invalid sender until after the RCPT stage (except for protocol errors, i.e. syntax errors in address). So store it in an “$transaction→note()” and process it later in an rcpt hook.

Allowed return codes are

• OK sender allowed
• DENY Return a hard failure code
• DENYSOFT Return a soft failure code
• DENY_DISCONNECT / DENYSOFT_DISCONNECT as above but with disconnect
• DECLINED next plugin (if any)
• DONE skip further processing, plugin sent response

Arguments for this hook are

  my ($self,$transaction, $sender, %args) = @_;
  # $sender: an Qpsmtpd::Address object for 
  # sender of the message

Example plugins for the “hook_mail” are require_resolvable_fromhost and check_badmailfrom.

See “hook_mail_pre”, s/MAIL FROM:/RCPT TO:/.

This hook is called after the client sent an RCPT TO: command (after parsing the line). The given argument is parsed by “Qpsmtpd::Address”, then this hook is called. Default is to deny the mail with a soft error code. The remaining arguments are the extensions defined in RFC 1869 (if sent by the client).

Allowed return codes

• OK recipient allowed
• DENY Return a hard failure code, for example for an User does not exist here message.
• DENYSOFT Return a soft failure code, for example if the connect to a user lookup database failed
• DENY_DISCONNECT / DENYSOFT_DISCONNECT as above but with disconnect
• DONE skip further processing, plugin sent response

Arguments are

  my ($self, $transaction, $recipient, %args) = @_;
  # $rcpt = Qpsmtpd::Address object with 
  # the given recipient address

Example plugin is rcpt_ok.

After the client sent the DATA command, before any data of the message was sent, this hook is called.

NOTE: This hook, like EHLO, VRFY, QUIT, NOOP, is an endpoint of a pipelined command group (see RFC 1854) and may be used to detect “early talkers”. Since svn revision 758 the check_earlytalker plugin may be configured to check at this hook for “early talkers”.

Allowed return codes are

• DENY Return a hard failure code
• DENYSOFT Return a soft failure code
• DENY_DISCONNECT / DENYSOFT_DISCONNECT as above but with disconnect
• DONE Plugin took care of receiving data and calling the queue (not recommended)

NOTE: The only real use for DONE is implementing other ways of receiving the message, than the default… for example the CHUNKING SMTP extension (RFC 1869, 1830/3030) … a plugin for this exists at http://svn.perl.org/qpsmtpd/contrib/vetinari/experimental/chunking, but it was never tested “in the wild”.

Arguments:

  my ($self, $transaction) = @_;

Example plugin is greylisting.

If you wish to provide your own Received header line, do it here. You can use or discard any of the given arguments (see below).

Allowed return codes:

• OK, $string use this string for the Received header.
• anything else use the default Received header

Arguments are

 my ($self, $transaction, $smtp, $auth, $sslinfo) = @_;
 # $smtp - the SMTP type used (e.g. "SMTP" or "ESMTP").
 # $auth - the Auth header additionals.
 # $sslinfo - information about SSL for the header.

The “data_post” hook is called after the client sent the final ”.\r\n” of a message, before the mail is sent to the queue.

Allowed return codes are

• DENY Return a hard failure code
• DENYSOFT Return a soft failure code
• DENY_DISCONNECT / DENYSOFT_DISCONNECT as above but with disconnect
• DONE skip further processing (message will not be queued), plugin gave the response.

NOTE: just returning OK from a special queue plugin does (nearly) the same (i.e. dropping the mail to /dev/null) and you don't have to send the response on your own. If you want the mail to be queued, you have to queue it manually!

Arguments:

  my ($self, $transaction) = @_;

Example plugins: spamassassin, virus/clamdscan

This hook is run, just before the mail is queued to the “backend”. You may modify the in-process transaction object (e.g. adding headers) or add something like a footer to the mail (the latter is not recommended).

Allowed return codes are

• DONE no queuing is done
• OK / DECLINED queue the mail

When all “data_post” hooks accepted the message, this hook is called. It is used to queue the message to the “backend”.

Allowed return codes:

• DONE skip further processing (plugin gave response code)
• OK Return success message, i.e. tell the client the message was queued (this may be used to drop the message silently).
• DENY Return hard failure code
• DENYSOFT Return soft failure code, i.e. if disk full or other temporary queuing problems

Arguments:

  my ($self, $transaction) = @_;

Example plugins: all queue/* plugins

This hook is called always after “hook_queue”. If the return code is not OK, a message (all remaining return values) with level LOGERROR is written to the log. Arguments are

 my $self = shift;
 

NOTE: “$transaction” is not valid at this point, therefore not mentioned.

This hook will be called several times. At the beginning of a transaction (i.e. when the client sends a MAIL FROM: command the first time), after queueing the mail and every time a client sends a RSET command. Arguments are

 my ($self, $transaction) = @_;

NOTE: don't rely on “$transaction” being valid at this point.

After the client sent a QUIT command, this hook is called (before the “hook_disconnect”).

Allowed return codes

• DONE plugin sent response
• DECLINED next plugin and / or qpsmtpd sends response

Arguments: the only argument is “$self”

Expample plugin is the quit_fortune plugin.

This hook will be called from several places: After a plugin returned DENY(|SOFT)_DISCONNECT, before connection is disconnected or after the client sent the QUIT command, AFTER the quit hook and ONLY if no plugin hooking “hook_quit” returned DONE.

All return values are ignored, arguments are just “$self”

Example plugin is logging/file

This is the counter part of the “pre-connection” hook, it is called directly before the connection is finished, for example, just before the qpsmtpd-forkserver instance exits or if the client drops the connection without notice (without a QUIT). This hook is not called if the qpsmtpd instance is killed.

The only argument is “$self” and all return codes are ignored, it would be too late anyway .

Example: connection_time

Before the line from the client is parsed by “Qpsmtpd::Command→parse()” with the built in parser, these hooks are called. They can be used to supply a parsing function for the line, which will be used instead of the built in parser.

The hook must return two arguments, the first is (currently) ignored, the second argument must be a (CODE) reference to a sub routine. This sub routine receives three arguments:

• $self the plugin object
• $cmd the command (i.e. the first word of the line) sent by the client
• $line the line sent by the client without the first word

Expected return values from this sub are DENY and a reason which is sent to the client or OK and the “$line” broken into pieces according to the syntax rules for the command.

NOTE: ignore the example from “Qpsmtpd::Command”, the “unrecognized_command_parse” hook was never implemented,…

The provided sub routine must return two or more values. The first is discarded, the second is the hostname (sent by the client as argument to the HELO / EHLO command). All other values are passed to the helo / ehlo hook. This hook may be used to change the hostname the client sent… not recommended, but if your local policy says only to accept HELO hosts with FQDNs and you have a legal client which can not be changed to send his FQDN, this is the right place.

The provided sub routine must return two or more values. The first is either OK to indicate that parsing of the line was successfull or anything else to bail out with 501 Syntax error in command. In case of failure the second argument is used as the error message for the client.

If parsing was successfull, the second argument is the sender's / recipient's address (this may be without the surrounding < and >, don't add them here, use the “hook_mail_pre()” / “hook_rcpt_pre()” methods for this). All other arguments are sent to the “mail / rcpt” hook as MAIL / RCPT parameters (see RFC 1869 SMTP Service Extensions for more info). Note that the mail and rcpt hooks expect a list of key/value pairs as the last arguments.

…

Now some special hooks follow. Some of these hooks are some internal hooks, which may be used to alter the logging or retrieving config values from other sources (other than flat files) like SQL databases.

This hook is called when a log message is written, for example in a plugin it fires if someone calls “$self→log($level, $msg);”. Allowed return codes are

• DECLINED next logging plugin
• OK (not DONE, as some might expect!) ok, plugin logged the message

Arguments are

  my ($self, $transaction, $trace, $hook, $plugin, @log) = @_;
  # $trace: level of message, for example 
  #          LOGWARN, LOGDEBUG, ...
  # $hook:  the hook in/for which this logging 
  #          was called
  # $plugin: the plugin calling this hook
  # @log:   the log message

NOTE: “$transaction” may be “undef”, depending when / where this hook is called. It's probably best not to try acessing it.

All logging/* plugins can be used as example plugins.

This hook is called after a plugin returned DENY, DENYSOFT, DENY_DISCONNECT or DENYSOFT_DISCONNECT. All return codes are ignored, arguments are

  my ($self, $transaction, $prev_hook, $return, $return_text) = @_;

NOTE: “$transaction” may be “undef”, depending when / where this hook is called. It's probably best not to try acessing it.

Example plugin for this hook is logging/adaptive.

The counter part of “hook_deny”, it is called after a plugin did not return DENY, DENYSOFT, DENY_DISCONNECT or DENYSOFT_DISCONNECT. All return codes are ignored, arguments are

  my ( $self, $transaction, $prev_hook, $return, $return_text ) = @_;

NOTE: “$transaction” may be “undef”, depending when / where this hook is called. It's probably best not to try acessing it.

Called when a config file is requested, for example in a plugin it fires if someone calls “my @cfg = $self→qp→config($cfg_name);”. Allowed return codes are

• DECLINED plugin didn't find the requested value
• OK requested values as ”@list”, example:

  return (OK, @{$config{$value}}) 
    if exists $config{$value};
  return (DECLINED);

Arguments:

  my ($self,$transaction,$value) = @_; 
  # $value: the requested config item(s)

NOTE: “$transaction” may be “undef”, depending when / where this hook is called. It's probably best not to try acessing it.

Example plugin is http_config from the qpsmtpd distribution.

This is called if the client sent a command unknown to the core of qpsmtpd. This can be used to implement new SMTP commands or just count the number of unknown commands from the client, see below for examples. Allowed return codes:

• DENY_DISCONNECT Return 521 and disconnect the client
• DENY Return 500
• DONE Qpsmtpd wont do anything; the plugin responded, this is what you want to return, if you are implementing new commands
• Anything else… Return 500 Unrecognized command

Arguments:

  my ($self, $transaction, $cmd, @args) = @_;
  # $cmd  = the first "word" of the line 
  #         sent by the client
  # @args = all the other "words" of the 
  #         line sent by the client
  #         "word(s)": white space split() line

NOTE: “$transaction” may be “undef”, depending when / where this hook is called. It's probably best not to try acessing it.

Example plugin is tls.

This hook triggers if a client sends the HELP command, allowed return codes are:

• DONE Plugin gave the answer.
• DENY The client will get a “syntax error” message, probably not what you want, better use

  $self->qp->respond(502, "Not implemented.");
  return DONE;

Anything else will be send as help answer.

Arguments are my ($self, $transaction, @args) = @_;

with ”@args” being the arguments from the client's command.

If the client sents the VRFY command, this hook is called. Default is to return a message telling the user to just try sending the message. Allowed return codes:

• OK Recipient Exists
• DENY Return a hard failure code
• DONE Return nothing and move on
• Anything Else… Return a 252

Arguments are:

 my ($self) = shift;

If the client sents the NOOP command, this hook is called. Default is to return “250 OK”.

Allowed return codes are:

• DONE Plugin gave the answer
• DENY_DISCONNECT Return error code and disconnect client
• DENY Return error code.
• Anything Else… Give the default answer of 250 OK.

Arguments are

  my ($self,$transaction,@args) = @_;

NOTE: This hook is only available in qpsmtpd-async.

It is called while starting qpsmtpd-async. You can run more than one instance of qpsmtpd-async (one per CPU probably). This hook is called after forking one instance.

Arguments:

 my $self = shift;

The return values of this hook are discarded.

See README.authentication in the qpsmtpd base dir.

This is a walk through a new queue plugin, which queues the mail to a (remote) QMQP-Server.

First step is to pull in the necessary modules

 use IO::Socket;
 use Text::Netstring qw( netstring_encode 
                         netstring_decode 
                         netstring_verify 
                         netstring_read );

We know, we need a server to send the mails to. This will be the same for every mail, so we can use arguments to the plugin to configure this server (and port).

Inserting this static config is done in “register()”:

  sub register {
    my ($self, $qp, @args) = @_;
 
    die "No QMQP server specified in qmqp-forward config"
      unless @args;
 
    $self->{_qmqp_timeout} = 120;
 
    if ($args[0] =~ /^([\.\w_-]+)$/) {
      $self->{_qmqp_server} = $1;
    }
    else {
      die "Bad data in qmqp server: $args[0]";
    }
 
    $self->{_qmqp_port} = 628;
    if (@args > 1 and $args[1] =~ /^(\d+)$/) {
      $self->{_qmqp_port} = $1;
    }
 
    $self->log(LOGWARN, "WARNING: Ignoring additional arguments.") 
      if (@args > 2);
  }

We're going to write a queue plugin, so we need to hook to the queue hook.

  sub hook_queue {
    my ($self, $transaction) = @_;
 
    $self->log(LOGINFO, "forwarding to $self->{_qmqp_server}:"
                       ."$self->{_qmqp_port}");

The first step is to open a connection to the remote server.

   my $sock = IO::Socket::INET->new(
                 PeerAddr => $self->{_qmqp_server},
                 PeerPort => $self->{_qmqp_port},
                 Timeout  => $self->{_qmqp_timeout},
                 Proto    => 'tcp')
      or $self->log(LOGERROR, "Failed to connect to "
                      ."$self->{_qmqp_server}:"
                      ."$self->{_qmqp_port}: $!"),
        return(DECLINED);
    $sock->autoflush(1);

• The client starts with a safe 8-bit text message. It encodes the message as the byte string “firstline\012secondline\012 … \012lastline”. (The last line is usually, but not necessarily, empty.) The client then encodes this byte string as a netstring. The client also encodes the envelope sender address as a netstring, and encodes each envelope recipient address as a netstring.

The client concatenates all these netstrings, encodes the concatenation as a netstring, and sends the result.

(from http://cr.yp.to/proto/qmqp.html)

The first idea is to build the package we send, in the order described in the paragraph above:

  my $message = $transaction->header->as_string;
  $transaction->body_resetpos;
  while (my $line = $transaction->body_getline) {
    $message .= $line;
  }
  $message  = netstring_encode($message);
  $message .= netstring_encode($transaction->sender->address);
  for ($transaction->recipients) {
    push @rcpt, $_->address;
  }
  $message .= join "", netstring_encode(@rcpt);
  print $sock netstring_encode($message)
    or do {
      my $err = $!;
      $self->_disconnect($sock);
      return(DECLINED, "Failed to print to socket: $err");
    };

This would mean, we have to hold the full message in memory… Not good for large messages, and probably even slower (for large messages).

Luckily it's easy to build a netstring without the help of the “Text::Netstring” module if you know the size of the string (for more info about netstrings see http://cr.yp.to/proto/netstrings.txt).

We start with the sender and recipient addresses:

  my ($addrs, $headers, @rcpt);
  $addrs = netstring_encode($transaction->sender->address);
  for ($transaction->recipients) {
    push @rcpt, $_->address;
  }
  $addrs .= join "", netstring_encode(@rcpt);

Ok, we got the sender and the recipients, now let's see what size the message is.

  $headers   = $transaction->header->as_string;
  my $msglen = length($headers) + $transaction->body_length;

We've got everything we need. Now build the netstrings for the full package and the message.

First the beginning of the netstring of the full package

  # (+ 2: the ":" and "," of the message's netstring)
  print $sock ($msglen + length($msglen) + 2 + length($addrs))
               .":"
               ."$msglen:$headers" ### beginning of messages netstring
    or do { 
      my $err = $!;
      $self->_disconnect($sock);
      return(DECLINED, 
             "Failed to print to socket: $err");
    };

Go to beginning of the body

  $transaction->body_resetpos;

If the message is spooled to disk, read the message in blocks and write them to the server

  if ($transaction->body_fh) {
    my $buff;
    my $size = read $transaction->body_fh, $buff, 4096;
    unless (defined $size) {
      my $err = $!;
      $self->_disconnect($sock);
      return(DECLINED, "Failed to read from body_fh: $err");
    }
    while ($size) {
      print $sock $buff
        or do { 
          my $err = $!;
          $self->_disconnect($sock);
          return(DECLINED, "Failed to print to socket: $err");
        };
 
      $size = read $transaction->body_fh, $buff, 4096;
      unless (defined $size) {
        my $err = $!;
        $self->_disconnect($sock);
        return(DECLINED, 
               "Failed to read from body_fh: $err");
      }
    }
  }

Else we have to read it line by line …

  else { 
    while (my $line = $transaction->body_getline) {
      print $sock $line
        or do { 
          my $err = $!;
          $self->_disconnect($sock);
          return(DECLINED, "Failed to print to socket: $err");
        };
    }
  }

Message is at the server, now finish the package.

  print $sock ","    # end of messages netstring
             .$addrs # sender + recpients
             .","    # end of netstring of 
                     #   the full package
    or do { 
      my $err = $!;
      $self->_disconnect($sock);
      return(DECLINED, 
             "Failed to print to socket: $err");
    };

We're done. Now let's see what the remote qmqpd says…

• (continued from http://cr.yp.to/proto/qmqp.html:)

The server's response is a nonempty string of 8-bit bytes, encoded as a netstring.

The first byte of the string is either K, Z, or D. K means that the message has been accepted for delivery to all envelope recipients. This is morally equivalent to the 250 response to DATA in SMTP; it is subject to the reliability requirements of RFC 1123, section 5.3.3. Z means temporary failure; the client should try again later. D means permanent failure.

Note that there is only one response for the entire message; the server cannot accept some recipients while rejecting others.

    my $answer = netstring_read($sock);
    $self->_disconnect($sock);
 
    if (defined $answer and netstring_verify($answer)) {
      $answer = netstring_decode($answer);
 
      $answer =~ s/^K// and return(OK,
                                 "Queued! $answer");
      $answer =~ s/^Z// and return(DENYSOFT, 
                                 "Deferred: $answer");
      $answer =~ s/^D// and return(DENY,
                                 "Denied: $answer");
    }

If this is the only queue/* plugin, the client will get a 451 temp error:

    return(DECLINED, "Protocol error");
  }
 
  sub _disconnect {
    my ($self,$sock) = @_;
    if (defined $sock) {
      eval { close $sock; };
      undef $sock;
    }
  }

If you want to make the client think a message has been regularily accepted, but in real you delete it or send it to /dev/null, …, use something like the following plugin and load it before your default queue plugin.

  sub hook_queue {
    my ($self, $transaction) = @_;
    if ($transaction->notes('discard_mail')) {
      my $msg_id = $transaction->header->get('Message-Id') || '';
      $msg_id =~ s/[\r\n].*//s;
      return(OK, "Queued! $msg_id");
    }
    return(DECLINED);
  }

This is an example how to use the “isa_plugin” method.

The rcpt_ok_maxrelay plugin wraps the rcpt_ok plugin. The rcpt_ok plugin checks the rcpthosts and morercpthosts config files for domains, which we accept mail for. If not found it tells the client that relaying is not allowed. Clients which are marked as “relay clients” are excluded from this rule. This plugin counts the number of unsuccessfull relaying attempts and drops the connection if too many were made.

The optional parameter MAX_RELAY_ATTEMPTS configures this plugin to drop the connection after MAX_RELAY_ATTEMPTS unsuccessful relaying attempts. Set to “0” to disable, default is “5”.

Note: Do not load both (rcpt_ok and rcpt_ok_maxrelay). This plugin should be configured to run last, like rcpt_ok.

 use Qpsmtpd::DSN;
 
 sub init {
   my ($self, $qp, @args) = @_;
   die "too many arguments"
     if @args > 1;
   $self->{_count_relay_max} = defined $args[0] ? $args[0] : 5;
   $self->isa_plugin("rcpt_ok");
 }
 
 sub hook_rcpt {
   my ($self, $transaction, $recipient) = @_;
   my ($rc, @msg) = $self->SUPER::hook_rcpt($transaction, $recipient);
 
   return ($rc, @msg)
      unless (($rc == DENY) and $self->{_count_relay_max});
 
   my $count = 
     ($self->qp->connection->notes('count_relay_attempts') || 0) + 1;
   $self->qp->connection->notes('count_relay_attempts', $count);
 
   return ($rc, @msg) unless ($count > $self->{_count_relay_max});
   return Qpsmtpd::DSN->relaying_denied(DENY_DISCONNECT, 
           "Too many relaying attempts"); 
 }