OS4X Fail2Ban integration

Since OS4X 2026-05-06, OS4X offers a capability to write a logfile compatible to Fail2Ban. This system helps you to prevent attacks from externally.

Installation

On Debian based systems, it is very easy to install Fail2Ban:

apt update && apt -y install fail2ban

Configuration

Several configuration files and options must be set up for a working Fail2Ban environment.

OS4X Configuration

In Configuration -> Logging, define a path in Absolute path to Fail2ban logfile. This file must be writable by the OS4X daemon running user.

Then create the file and optionalle change permissions, otherwise Fail2Ban will fail to start due to a missing log file to be analyzed:

touch /opt/os4x/tmp/fail2ban.log
chmod 666 /opt/os4x/tmp/fail2ban.log

Fail2Ban filter

Create the following file:

/etc/fail2ban/filter.d/os4x.conf

with the following content:

[Definition]
failregex = 
    ^TLS error .+ during connect try from <HOST>: .*$
    ^TLS error .+ during connect try from <HOST> (.+): .*$
ignoreregex =

Fail2Ban jail

Create the following file:

/etc/fail2ban/jail.d/os4x.conf

with the following content:

[os4x]
enabled = true
port = 6619
filter = os4x
logpath = /opt/os4x/tmp/fail2ban.log
maxretry = 3
findtime = 600
bantime = 3600
action = %(action_mwl)s

Keep an eye on the following parameters:

• port: Change the TCP port 6619 to your configured TLS listener port if necessary.
• logpath: This must be the same path as configured in OS4X.

In this default configuration, after three unsuccessful connections within ten minutes ("findtime = 600") the IP is being blocked on the given port for one hour ("bantime = 3600").

Restart Fail2Ban service

systemctl reload fail2ban

Test

With the TLS server configured to check the TLS client certificate, connect from an external host to your TLS listener port without a TLS client certificate:

openssl s_client -connect 192.168.40.24:6619 -tls1_2

(with "tls1_2" for TLS 1.2, adopt to another version if required).

The configured Fail2Ban log file should state something like this:

TLS error 167772359 during connect try from 10.10.14.7: peer did not return a certificate

Retry this three times within ten minutes, succeeding connection tries must fail with a "connection refused" error from client side.

Unban

Easy allowing new connections from a client:

fail2ban-client set os4x unbanip 10.10.14.7