[BR]: INCLUDES sections are poorly documented and failed inclusions are not reported #4076
Description
Environment:
- Fail2Ban version : 1.1.0-8
- OS, including release name/version : Debian 13 "Trixie"
- Fail2Ban installed via OS/distribution mechanisms
- You have not applied any additional foreign patches to the codebase
- Some customizations were done to the configuration (provide details below is so)
The issue:
I've noticed some people having great trouble getting the INCLUDES section to work.
Firstly, it is not clear, nor documented in the jail.conf manpage, how to define multiple files for inclusion. No example is given.
Secondly, fail2ban doesn't fail or even warn you, if any included file does not exist.
Steps to reproduce
Enter something like this in config:
[INCLUDES]
before = file1.conf, file2.conf
or even just this:
[INCLUDES]
before = file1.conf
when file1.conf is in a different directory
Expected behavior
fail2ban should warn, e.g.
# fail2ban-client --test
2025-09-28 01:23:45,678 fail2ban.configparserinc[420]: WARNING File 'file1.conf, file2.conf' included by '/etc/fail2ban/jail.conf' doesn't exist
Observed behavior
fail2ban does not warn on this config error, nor does it document how to use it in the manpage.
Any additional information
My suggested change for the manpage:
--- jail.conf.5.orig 2025-09-28 01:14:36.679351925 +0100
+++ jail.conf.5 2025-09-28 02:10:52.709529223 +0100
@@ -83,10 +83,27 @@
.TP
.B before
-indicates that the specified file is to be parsed before the current file.
+indicates that the specified file(s) are to be parsed before the current file.
+Filenames should be given one per line, and can either be absolute paths, or
+relative to the file doing the including.
.TP
.B after
-indicates that the specified file is to be parsed after the current file.
+indicates that the specified file(s) are to be parsed after the current file
+and included in its definition. One use-case for this is to designate another
+file as the official location to make edits that extend or override a filter.
+Files listed here do not need to exist.
+.RE
+
+Example of usage:
+.RS
+.nf
+[INCLUDES]
+before = ../shared/common.conf
+ common.conf
+ /usr/local/etc/fail2ban/common.conf
+
+after = common.local
+.fi
.RE
Using Python "string interpolation" mechanisms, other definitions are allowed and can later be used within other definitions as %(name)s.My suggested change for the includes parser:
--- configparserinc.py.orig 2025-09-28 02:17:07.543218022 +0100
+++ configparserinc.py 2025-09-28 02:51:01.041413411 +0100
@@ -278,6 +278,8 @@
if option_name in parser.options(SCPWI.SECTION_NAME):
newResources = parser.get(SCPWI.SECTION_NAME, option_name)
for newResource in newResources.split('\n'):
+ if option_name == 'before' and not os.path.exists(newResource):
+ logSys.warning("File '%s' included by '%s' doesn't exist" % (newResource, resource))
if os.path.isabs(newResource):
r = newResource
else: