postfwd/doc/hapolicy.txt

128 lines
5.8 KiB
Plaintext
Raw Permalink Normal View History

2013-11-05 16:33:44 +00:00
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.