From 980217d29b4d06c69df72c192588a716a70e1415 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Tue, 19 May 2026 12:39:55 +0200 Subject: [PATCH 1/3] 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 --- .../bruteforce_configuration.rst | 27 +++++++++++++++++++ admin_manual/installation/harden_server.rst | 2 ++ 2 files changed, 29 insertions(+) diff --git a/admin_manual/configuration_server/bruteforce_configuration.rst b/admin_manual/configuration_server/bruteforce_configuration.rst index d284c792b64..23316634cf0 100644 --- a/admin_manual/configuration_server/bruteforce_configuration.rst +++ b/admin_manual/configuration_server/bruteforce_configuration.rst @@ -164,3 +164,30 @@ It's possible to exclude IP addresses from the brute force protection. Any excluded IP address can perform authentication attempts without any throttling. It's best to exclude as few IP addresses as you can, or even none at all. + +Brute force protection vs fail2ban +----------------------------------- + +Nextcloud's built-in brute force protection and fail2ban are complementary tools that +operate at different layers of the stack. Using both together is recommended for +production servers. + +**Nextcloud brute force protection** (the ``bruteforcesettings`` app) works at the +**application layer**. It detects suspicious login patterns and adds progressively +longer delays to requests from the offending IP address. It has full context about +Nextcloud-specific endpoints and credentials, and it activates automatically without +any operating system configuration. + +**fail2ban** works at the **OS/network layer**. It watches log files for failed login +entries and instructs the system firewall (e.g. ``iptables`` or ``nftables``) to +block the offending IP outright. Blocked requests are dropped before they reach the +web server, PHP, or the database, saving server resources entirely. + +The two approaches are not mutually exclusive: + +- Nextcloud brute force protection handles application-level throttling transparently, + including for API clients and mobile apps, with no system configuration required. +- fail2ban reduces server load by blocking repeat offenders at the network level + before their requests consume any application resources. + +For setup instructions for fail2ban with Nextcloud, see :ref:`setup_fail2ban`. diff --git a/admin_manual/installation/harden_server.rst b/admin_manual/installation/harden_server.rst index 47d06519590..29a2298f8f5 100644 --- a/admin_manual/installation/harden_server.rst +++ b/admin_manual/installation/harden_server.rst @@ -306,6 +306,8 @@ Depending on your server setup, these are the possible connections: .. _detailed field list: https://github.com/nextcloud/survey_client +.. _setup_fail2ban: + Setup fail2ban -------------- From 4745d84d5dfd119db66561be3fbce68125909461 Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Tue, 19 May 2026 14:44:03 +0200 Subject: [PATCH 2/3] docs(admin): clarify BFP is server-core, not bruteforcesettings app The bruteforcesettings app only provides the admin UI and exclusion settings. The actual brute force protection is implemented in Nextcloud Server core and runs regardless of whether the app is enabled. Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: skjnldsv --- .../configuration_server/bruteforce_configuration.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/admin_manual/configuration_server/bruteforce_configuration.rst b/admin_manual/configuration_server/bruteforce_configuration.rst index 23316634cf0..39f62a2192d 100644 --- a/admin_manual/configuration_server/bruteforce_configuration.rst +++ b/admin_manual/configuration_server/bruteforce_configuration.rst @@ -172,11 +172,12 @@ Nextcloud's built-in brute force protection and fail2ban are complementary tools operate at different layers of the stack. Using both together is recommended for production servers. -**Nextcloud brute force protection** (the ``bruteforcesettings`` app) works at the -**application layer**. It detects suspicious login patterns and adds progressively -longer delays to requests from the offending IP address. It has full context about -Nextcloud-specific endpoints and credentials, and it activates automatically without -any operating system configuration. +**Nextcloud brute force protection** is built into Nextcloud Server itself (the +``bruteforcesettings`` app provides the admin UI and exclusion settings, but the +protection runs regardless). It works at the **application layer**: it detects +suspicious login patterns and adds progressively longer delays to requests from the +offending IP address. It has full context about Nextcloud-specific endpoints and +credentials, and it activates automatically without any operating system configuration. **fail2ban** works at the **OS/network layer**. It watches log files for failed login entries and instructs the system firewall (e.g. ``iptables`` or ``nftables``) to From e4f55ece89a8a66566ea0c3fc6e5314ca06d457a Mon Sep 17 00:00:00 2001 From: skjnldsv Date: Tue, 19 May 2026 14:49:30 +0200 Subject: [PATCH 3/3] docs(admin): warn that disabling bruteforcesettings app does not stop BFP The protection is built into Nextcloud Server core and is always active. Disabling the app only removes the ability to manage brute force settings from the Web interface. Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: skjnldsv --- .../configuration_server/bruteforce_configuration.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/admin_manual/configuration_server/bruteforce_configuration.rst b/admin_manual/configuration_server/bruteforce_configuration.rst index 39f62a2192d..3d8283e7677 100644 --- a/admin_manual/configuration_server/bruteforce_configuration.rst +++ b/admin_manual/configuration_server/bruteforce_configuration.rst @@ -91,8 +91,11 @@ addresses and ranges to exempt from brute force protection. Additional enhancements may be made in the future, within this app and/or in combination with Nextcloud Server for additional monitoring or behavior adjustments related to brute force protection. -.. warning:: Disabling the ``bruteforcesettings`` app does **not** disable brute force protection - - it merely removes your ability to adjust brute force related settings from the Web interface. +.. warning:: + + Disabling the ``bruteforcesettings`` app does **not** disable brute force protection. + The protection is built into Nextcloud Server core and is always active. Disabling the app + only removes the ability to manage brute force settings from the Web interface. .. danger::