HAPOLICY(1)

📦
version 1.35 · 4 versions
, in debian bookworm, ubuntu noble

🌸 NAME 🌸

hapolicy — policy delegation high availability script 💅

(this page is HAPOLICY(1) from the User Contributed Perl Documentation, in case you were wondering where you wandered into, bestie 🫶)

✨ 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

so like. you got services, you got options. let's break it down 🎀

services:

  • -s, --service <name>=<address>:<port>[:<prio>:<weight>:<timeout>] — the actual policy servers you're pointing at. that's the whole point of this girl 🦋

options:

  • -d, --default <action> — if literally no service was available, this is what she returns instead. default is 'dunno' 💜
  • -l, --logging — log the requests, queen ✨
  • -v, --verbose — crank the logging verbosity up, one step at a time 📈
  • -L, --stdout — send logs to stdout instead, for debugging. do NOT use this with postfix, that's not a vibe 💀

🦋 DESCRIPTION 🦋

🌈 INTRODUCTION 🌈

okay so hapolicy gives you high availability, weighted loadbalancing and a fallback action for postfix policy delegation services. iconic. when postfix spawns it, it acts as a little wrapper that goes and queries other policy servers over a tcp connection. 🌸

the order those service queries happen in? you can influence it by assigning a specific priority and weight to each service. and a service counts as 'failing' if the connection is refused or if the specified service timeout is reached. no cap. and if all the configured policy services were failing, hapolicy returns a default action (like dunno) to postfix. the safety net 💅

as of version 1.00, hapolicy has less than 200 lines of perl code and uses only standard perl modules. it needs no disk access, no configuration files, and it runs under an unprivileged user account. all of that is on purpose — it should allow fast and reliable operation. she's low-maintenance and she ate 🔥

💖 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 doesn't answer within the default of 30 seconds, the next service grey2 at ip 10.0.0.2 port 10031 will be queried. so it's giving backup-plan energy 🧚

and 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 doesn't answer within the default of 30 seconds, polw2 will be queried and vice versa. mutual backup, we love to see it 💞

there is no reason to define a service twice. literally don't do it bestie 🙈

⭐ 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. slay 💅

🎀 LICENSE 🎀

hapolicy is free software and released under the 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.

like, it's free free. just keep the notice and we're good 🫶

💜 AUTHOR 💜

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

that's the whole page bestie!! brought to you by perl v5.36.0, dated 2023-01-23 — go configure something, mwah 💋✨

📦 where this page comes from