Merge pull request #4141 from caronc/apprise-tag-support

Improved Apprise integration (support tagging)

ChangeLog

@@ -98,6 +98,7 @@ ver. 1.1.1-dev-1 (20??/??/??) - development nightly edition
   by first ban (and automatically reloaded by update after small latency to avoid expensive stats check on every compare);
   the entries inside the file can be separated by comma, space or new line with optional comments (text following chars
   `#` or `;` after space or newline would be ignored up to next newline)
+* `action.d/apprise.conf` - updated to support tagging and other command line args (gh-4141)
 * `action.d/*-ipset.conf`:
   - parameter `ipsettype` to set type of ipset, e. g. hash:ip, hash:net, etc (gh-3760)
 * `action.d/iptables.conf` - action and few derivatives of it extended to handle multiple chains,

config/action.d/apprise.conf

@@ -2,8 +2,66 @@
 #
 # Author: Chris Caron <lead2gold@gmail.com>
 #
+# ban & send a notification to one or more of the 120+ services supported by
+# Apprise.
+#  - See https://appriseit.com/services/ for details on what is supported.
+#  - See https://appriseit.com/getting-started/configuration/ for information
+#    on how to prepare an Apprise configuration file.
 #
-
+#    This plugin requires that Apprise is installed on your system:
+#
+#       pip install apprise
+#
+#    Breakdown:
+#       config   provide a path to an Apprise Config file
+#                The default is /etc/fail2ban/apprise.conf if not provided.
+#                Both YAML and TEXT formats are supported.
+#                You can even point your configuration to an Apprise API
+#                endpoint.
+#
+#       args     Provide additional arguments to support the Apprise CLI.
+#                See https://appriseit.com/cli/usage/ for additional options.
+#                the --tag (-g) is incredibly useful for integrating with
+#                fail2ban as you can exclusively have it target specific
+#                notifications this way.
+#
+#    Config Example #1: Simple
+#      1. Create a /etc/fail2ban/apprise.conf
+#         ```
+#         # /etc/fail2ban/apprise.conf
+#         fail2ban=mailto://user:pass@example.com
+#         ```
+#      2  In /etc/fail2ban/jail.conf
+#         ```
+#         # ...
+#         action = %(action_)s
+#                  apprise[args='--tag fail2ban']
+#         # ...
+#         ```
+#
+#    Config Example #2: YAML an Custom path
+#      1. Create a /etc/fail2ban/apprise.conf
+#         ```
+#         # /etc/fail2ban/apprise.yaml
+#         urls:
+#           - mailto://user:pass@example.com:
+#              tags: f2b
+#         ```
+#      2. In /etc/fail2ban/jail.conf
+#         ```
+#         # ...
+#         action = %(action_)s
+#                  apprise[config='/etc/fail2ban/apprise.yaml',args='--tag f2b']
+#         # ...
+#         ```
+#
+#    Config Example #3: Apprise API
+#     1. in /etc/fail2ban/jail.conf
+#         ```
+#         # ...
+#         action = %(action_)s
+#                  apprise[config='http://apprise.example.ca/get/mykey',args='-g f2b']
+#         # ...
 [Definition]
 
 # Option:  actionstart
@@ -45,5 +103,9 @@ actionunban =
 # Define location of the default apprise configuration file to use
 #
 config = /etc/fail2ban/apprise.conf
+
+# Support passing in arguments for example: "-g fail2ban"
 #
-apprise = apprise -c "<config>"
+args =
+#
+apprise = apprise -c "<config>" <args>

config/jail.conf

@@ -227,14 +227,11 @@ action_mwl = %(action_)s
 action_xarf = %(action_)s
              xarf-login-attack[service=%(__name__)s, sender="%(sender)s", logpath="%(logpath)s", port="%(port)s"]
 
-# ban & send a notification to one or more of the 50+ services supported by Apprise.
-# See https://github.com/caronc/apprise/wiki for details on what is supported.
-#
-# You may optionally over-ride the default configuration line (containing the Apprise URLs)
-# by using 'apprise[config="/alternate/path/to/apprise.cfg"]' otherwise
-# /etc/fail2ban/apprise.conf is sourced for your supported notification configuration.
+# ban & send a notification to one or more of the 120+ services supported by Apprise.
 # action = %(action_)s
-#          apprise
+#          apprise[config="/alternate/path/to/apprise.yaml", args='--tag fail2ban']
+# See https://github.com/caronc/apprise/wiki for details on what is supported.
+# Or action.d/apprise.conf for more details how to configure or customize it.
 
 # ban IP on CloudFlare & send an e-mail with whois report and relevant log lines
 # to the destemail.