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:

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