Skip to content

Commit 192fc10

Browse files
committed
docs(admin): explain bruteforcesettings vs fail2ban relationship
Admins frequently ask whether to use Nextcloud's built-in brute force protection or fail2ban, and whether both are needed. Added a new section to bruteforce_configuration.rst that explains the layer each operates on (application vs OS/network) and why they are complementary rather than mutually exclusive. Also added a missing RST reference label to the fail2ban section in harden_server.rst so it can be cross-referenced. Fixes #11425 Signed-off-by: skjnldsv <skjnldsv@protonmail.com>
1 parent e793142 commit 192fc10

2 files changed

Lines changed: 29 additions & 0 deletions

File tree

admin_manual/configuration_server/bruteforce_configuration.rst

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -164,3 +164,30 @@ It's possible to exclude IP addresses from the brute force protection.
164164

165165
Any excluded IP address can perform authentication attempts without any throttling.
166166
It's best to exclude as few IP addresses as you can, or even none at all.
167+
168+
Brute force protection vs fail2ban
169+
-----------------------------------
170+
171+
Nextcloud's built-in brute force protection and fail2ban are complementary tools that
172+
operate at different layers of the stack. Using both together is recommended for
173+
production servers.
174+
175+
**Nextcloud brute force protection** (the ``bruteforcesettings`` app) works at the
176+
**application layer**. It detects suspicious login patterns and adds progressively
177+
longer delays to requests from the offending IP address. It has full context about
178+
Nextcloud-specific endpoints and credentials, and it activates automatically without
179+
any operating system configuration.
180+
181+
**fail2ban** works at the **OS/network layer**. It watches log files for failed login
182+
entries and instructs the system firewall (e.g. ``iptables`` or ``nftables``) to
183+
block the offending IP outright. Blocked requests are dropped before they reach the
184+
web server, PHP, or the database, saving server resources entirely.
185+
186+
The two approaches are not mutually exclusive:
187+
188+
- Nextcloud brute force protection handles application-level throttling transparently,
189+
including for API clients and mobile apps, with no system configuration required.
190+
- fail2ban reduces server load by blocking repeat offenders at the network level
191+
before their requests consume any application resources.
192+
193+
For setup instructions for fail2ban with Nextcloud, see :ref:`setup_fail2ban`.

admin_manual/installation/harden_server.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -306,6 +306,8 @@ Depending on your server setup, these are the possible connections:
306306
.. _detailed field list: https://github.com/nextcloud/survey_client
307307

308308

309+
.. _setup_fail2ban:
310+
309311
Setup fail2ban
310312
--------------
311313

0 commit comments

Comments
 (0)