qpsmtpd/docs/hooks.md

SMTP hooks

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.

hook_pre_connection

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 qpsmtpd-forkserver and qpsmtpd-prefork flavors.

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:

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.

hook_connect

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.

hook_helo / hook_ehlo

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.

hook_mail_pre

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) = @_;

hook_mail

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 resolvable_fromhost and badmailfrom.

hook_rcpt_pre

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

hook_rcpt

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.

hook_data

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 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.

hook_received_line

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.

data_headers_end

This hook fires after all header lines of the message data has been received. Defaults to doing nothing, just continue processing. At this step, the sender is not waiting for a reply, but we can try and prevent him from sending the entire message by disconnecting immediately. (Although it is likely the packets are already in flight due to buffering and pipelining).

NOTE: BE CAREFUL! If you drop the connection legal MTAs will retry again and again, spammers will probably not. This is not RFC compliant and can lead to an unpredictable mess. Use with caution.

Why this hook may be useful for you, see http://www.nntp.perl.org/group/perl.qpsmtpd/2009/02/msg8502.html, ff.

Allowed return codes:

• DENY_DISCONNECT

  Return 554 Message denied and disconnect

• DENYSOFT_DISCONNECT

  Return 421 Message denied temporarily and disconnect

• DECLINED

  Do nothing

Arguments:

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

FIXME: check arguments

hook_data_post_headers

The data_post_headers hook is called after the client sends the final .\r\n of a message and before the message is processed by data_post. This hook is used by plugins that insert new headers (ex: Received-SPF) and/or modify headers such as appending to Authentication-Results (SPF, DKIM, DMARC).

When it is desirable to have these header modifications evaluated by filtering software (spamassassin, dspam, etc.) running on data_post, this hook should be used instead of data_post.

Note that you cannot reject in this hook, use the data_post hook instead

Allowed return codes are

• DECLINED

  Do nothing

hook_data_post

The data_post hook is called after all headers has been added in data_post_headers above. This is meant for plugins that expect complete messages, such as content analyzing spam filters. Plugins can still add headers in this hook, however it is recommended only informational headers are added here.

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, dspam

hook_queue_pre

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

hook_queue

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

hook_queue_post

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.

hook_reset_transaction

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.

hook_quit

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.

hook_disconnect

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

hook_post_connection

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

Parsing Hooks

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,...

hook_helo_parse / hook_ehlo_parse

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.

hook_mail_parse / hook_rcpt_parse

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.

hook_auth_parse

FIXME...

Special hooks

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.

hook_logging

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.

hook_deny

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_plugin, $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.

hook_ok

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_plugin, $return, $return_text ) = @_;

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

hook_config

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, @values

  requested values as @list, example:

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

Arguments:

my ($self,$transaction,@keys) = @_;
# @keys: 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.

hook_user_config

Called when a per-user configuration directive is requested, for example if someone calls my @cfg = $rcpt->config($cfg_name);. Allowed return codes are

• DECLINED

  plugin didn't find the requested value

• OK, @values

  requested values as @list, example:

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

Arguments:

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

Example plugin is user_config from the qpsmtpd distribution.

hook_unrecognized_command

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.

hook_help

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.

hook_vrfy

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;

hook_noop

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) = @_;

Authentication hooks

See docs/authentication.pod.