NAME

       hapolicy - policy delegation high availability script

SYNOPSIS

       hapolicy [OPTIONS] --service=SERVICE1 [--service=SERVICE2 ...]

               Services:
               -s, --service <name>=<address>:<port>[:<prio>:<weight>:<timeout>]

               Options:
               -d, --default <action>  returns <action> if no service was available (default: 'dunno')
               -l, --logging           log requests
               -v, --verbose           increase logging verbosity
               -L, --stdout            log to stdout, for debugging, do NOT use with postfix

DESCRIPTION

   INTRODUCTION
       hapolicy enables high availability, weighted loadbalancing and a fallback action for
       postfix policy delegation services. Invoked via postfix spawn it acts as a wrapper that
       queries other policy servers via tcp connection. The order of the service queries can be
       influenced by assigning a specific priority and weight to each service. A service is
       considered 'failing', if the connection is refused or the specified service timeout is
       reached. If all of the configured policy services were failing, hapolicy returns a default
       action (e.g. dunno) to postfix.

       With version 1.00 hapolicy has less than 200 lines of perl code using only standard perl
       modules. It does not require any disk access nor configuration files and runs under an
       unpriviledged user account. This should allow fast and reliable operation.

   CONFIGURATION
       A service has the following attributes

           "servicename"           => {
                      ip              => '127.0.0.1',         # ip address
                      port            => '10040',             # tcp port
                      prio            => '10',                # optional, lower wins
                      weight          => '1',                 # optional, for items with same prio (weighted round-robin), higher is better
                      timeout         => '30',                # optional, query timeout in seconds
           },

       You may define multiple services at the command line. Which means that

               hapolicy -s "grey1=10.0.0.1:10031:10" -s "grey2=10.0.0.2:10031:20"

       will always try first service grey1 at ip 10.0.0.1 port 10031 and if that service is not
       available or does not answer within the default of 30 seconds the next service grey2 at ip
       10.0.0.2 port 10031 will be queried.

       If you want to load balance connections you may define

               hapolicy -s "polw1=10.0.0.1:12525:10:2" -s "polw2=10.0.0.2:12525:10:1"

       which queries service polw1 at ip 10.0.0.1 twice as much as service polw2 at ip 10.0.0.2.
       Note that this setup also ensures high availability for both services. If polw1 is not
       available or does not answer within the default of 30 seconds polw2 will be queried and
       vice versa. There is no reason to define a service twice.

   INTEGRATION
       Enter the following at the bottom of your postfix master.cf (usually located at
       /etc/postfix):

               # service description, note the leading blanks at the second line
               127.0.0.1:10060 inet    n       n       n       -       0       spawn
                 user=nobody argv=/usr/local/bin/hapolicy -l -s GREY1=10.0.0.1:10031:10 -s GREY2=10.0.0.2:10031:10

       save the file and open postfix main.cf. Modify it as follows:

               127.0.0.1:10060_time_limit   = 3600

               smtpd_recipient_restrictions =
                   permit_mynetworks,
                   ... other authed permits ...
                   reject_unauth_destination,
                   ... other restrictions ...
                   check_policy_service inet:127.0.0.1:10060   # <- hapolicy query

       Now issue 'postfix reload' at the command line. Of course you can have more enhanced
       setups using postfix restriction classes. Please see "LINKS" for further options.

LINKS

       [1] Postfix SMTP Access Policy Delegation
       <http://www.postfix.org/SMTPD_POLICY_README.html>

       [2] Postfix Per-Client/User/etc. Access Control
       <http://www.postfix.org/RESTRICTION_CLASS_README.html>

LICENSE

       hapolicy is free software and released under BSD license, which basically means that you
       can do what you want as long as you keep the copyright notice:

       Copyright (c) 2008, Jan Peter Kessler All rights reserved.

       Redistribution and use in source and binary forms, with or without modification, are
       permitted provided that the following conditions are met:

        * Redistributions of source code must retain the above copyright
          notice, this list of conditions and the following disclaimer.
        * Redistributions in binary form must reproduce the above copyright
          notice, this list of conditions and the following disclaimer in
          the documentation and/or other materials provided with the
          distribution.
        * Neither the name of the authors nor the names of his contributors
          may be used to endorse or promote products derived from this
          software without specific prior written permission.

       THIS SOFTWARE IS PROVIDED BY ME ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
       INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
       PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, INDIRECT,
       INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
       PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
       INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
       LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
       OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

AUTHOR

       Jan Peter Kessler <info (AT) postfwd (DOT) org>. Let me know, if you have any suggestions.