Fail2ban - Revision history

Britter: Use inclusive language

2026-01-28T08:34:00Z

Use inclusive language

← Older revision		Revision as of 08:34, 28 January 2026
Line 22:		Line 22:

	* The <syntaxhighlight lang="nix" inline>maxretry</syntaxhighlight> option allows you to specify how many failures are required for an IP address to be blocked.		* The <syntaxhighlight lang="nix" inline>maxretry</syntaxhighlight> option allows you to specify how many failures are required for an IP address to be blocked.
	* To prevent being locked out accidentally, use <syntaxhighlight lang="nix" inline>ignoreIP</syntaxhighlight> to ~~whitelist IPs~~ or IP ranges to be never ~~cheked~~. In the example below, common LAN IP address ranges as well as the specific IP '8.8.8.8' and the address associated with the hostname "wiki.nixos.org" are excluded from any bans. Note that the loopback addresses "127.0.0.0/8" and "::1" are added by default.		* To prevent being locked out accidentally, use <syntaxhighlight lang="nix" inline>ignoreIP</syntaxhighlight> to define IP allow lists or IP ranges to be never checked. In the example below, common LAN IP address ranges as well as the specific IP '8.8.8.8' and the address associated with the hostname "wiki.nixos.org" are excluded from any bans. Note that the loopback addresses "127.0.0.0/8" and "::1" are added by default.
	* <syntaxhighlight lang="nix" inline>bantime</syntaxhighlight> specifies for how much time an IP address is blocked after reaching the maximum number of failures. Note that the bantime can be increased for every violation by setting <syntaxhighlight lang="nix" inline>bantime-increment.enable = true;</syntaxhighlight>. The bantime increment can then be customized by specifying a formula (in Python) like <syntaxhighlight lang="python" inline>ban.Time * math.exp(float(ban.Count+1)banFactor)/math.exp(1banFactor)</syntaxhighlight> with <syntaxhighlight lang="nix" inline>bantime-increment.formula</syntaxhighlight>, the multipliers with <syntaxhighlight lang="nix" inline>bantime-increment.multipliers</syntaxhighlight>, the maximum bantime with <syntaxhighlight lang="nix" inline>bantime-increment.maxtime</syntaxhighlight> and the indication to consider the bans issued throughout multiple jails with <syntaxhighlight lang="nix" inline>bantime-increment.overalljails</syntaxhighlight>		* <syntaxhighlight lang="nix" inline>bantime</syntaxhighlight> specifies for how much time an IP address is blocked after reaching the maximum number of failures. Note that the bantime can be increased for every violation by setting <syntaxhighlight lang="nix" inline>bantime-increment.enable = true;</syntaxhighlight>. The bantime increment can then be customized by specifying a formula (in Python) like <syntaxhighlight lang="python" inline>ban.Time * math.exp(float(ban.Count+1)banFactor)/math.exp(1banFactor)</syntaxhighlight> with <syntaxhighlight lang="nix" inline>bantime-increment.formula</syntaxhighlight>, the multipliers with <syntaxhighlight lang="nix" inline>bantime-increment.multipliers</syntaxhighlight>, the maximum bantime with <syntaxhighlight lang="nix" inline>bantime-increment.maxtime</syntaxhighlight> and the indication to consider the bans issued throughout multiple jails with <syntaxhighlight lang="nix" inline>bantime-increment.overalljails</syntaxhighlight>
	* <syntaxhighlight lang="nix" inline>banaction</syntaxhighlight> specifies which of the actions in <syntaxhighlight lang="nix" inline>/etc/fail2ban/action.d</syntaxhighlight> should be the default ban action (e.g., iptables, iptables-new, iptables-multiport, iptables-ipset-proto6-allports, shorewall, etc.)		* <syntaxhighlight lang="nix" inline>banaction</syntaxhighlight> specifies which of the actions in <syntaxhighlight lang="nix" inline>/etc/fail2ban/action.d</syntaxhighlight> should be the default ban action (e.g., iptables, iptables-new, iptables-multiport, iptables-ipset-proto6-allports, shorewall, etc.)
Line 28:		Line 28:


	<~~syntaxHighlight~~ lang=nix>		<syntaxhighlight lang="nix">
	services.fail2ban = {		services.fail2ban = {
	enable = true;		enable = true;
Line 34:		Line 34:
	maxretry = 5;		maxretry = 5;
	ignoreIP = [		ignoreIP = [
	# ~~Whitelist~~ some subnets		# Allow list for some subnets
	"10.0.0.0/8" "172.16.0.0/12" "192.168.0.0/16"		"10.0.0.0/8" "172.16.0.0/12" "192.168.0.0/16"
	"8.8.8.8" # ~~whitelist~~ a specific IP		"8.8.8.8" # allow a specific IP
	"wiki.nixos.org" # resolve the IP via DNS		"wiki.nixos.org" # resolve the IP via DNS
	];		];
Line 62:		Line 62:
	};		};
	};		};
	</~~syntaxHighlight~~>		</syntaxhighlight>

	These settings are written to <code>/etc/fail2ban/jail.local</code>, where fail2ban will read them.		These settings are written to <code>/etc/fail2ban/jail.local</code>, where fail2ban will read them.

Pigs: /* Basic Usage */ Add links to module options and ssh page

2025-05-13T17:09:42Z

Basic Usage: Add links to module options and ssh page

← Older revision		Revision as of 17:09, 13 May 2025
Line 4:		Line 4:

	== Basic Usage ==		== Basic Usage ==

	Enable Fail2ban [[NixOS modules\|NixOS module]] with the expression:		Enable Fail2ban [[NixOS modules\|NixOS module]] with the expression:
	<~~syntaxHighlight lang=nix~~>
			{{file\|/etc/nixos/configuration.nix\|nix\|
			<nowiki>
	services.fail2ban.enable = true;		services.fail2ban.enable = true;
	</~~syntaxHighlight~~>		</nowiki>
	NixOS comes with a pre-configured SSH jail which will observe errors in the SSH daemon and ban offending IPs. If all you need is basic rate-limiting and only have the SSH port exposed, you don't have to setup anything else.		}}

			NixOS comes with a pre-configured SSH jail which will observe errors in the [[SSH#OpenSSH Server\|SSH daemon]] and ban offending IPs. If all you need is basic rate-limiting and only have the SSH port exposed, you don't have to setup anything else.

			For additional configuration options, see the{{nixos:option\|services.fail2ban}} module documentation.

	== Advanced Usage ==		== Advanced Usage ==

Klinger: added Category:Server Category:Networking

2024-09-26T20:21:36Z

added Category:Server Category:Networking

← Older revision		Revision as of 20:21, 26 September 2024
Line 109:		Line 109:

	[[Category:Applications]]		[[Category:Applications]]
			[[Category:Server]]
			[[Category:Networking]]

RTUnreal: /* Extending Fail2ban */ Fix typo

2024-09-24T23:11:29Z

Extending Fail2ban: Fix typo

← Older revision		Revision as of 23:11, 24 September 2024
Line 83:		Line 83:
	The defined filters and actions can then be used in a new jail (created as seen above):		The defined filters and actions can then be used in a new jail (created as seen above):

	<~~syntaxHighlight~~ lang=nix>		<syntaxhighlight lang="nix">
	services.fail2ban = {		services.fail2ban = {
	# --- snip ---		# --- snip ---
	jails = {		jails = {
	~~ngnix~~-url-probe.settings = {		nginx-url-probe.settings = {
	enabled = true;		enabled = true;
	filter = "nginx-url-probe";		filter = "nginx-url-probe";
Line 99:		Line 99:
	};		};
	};		};
	</~~syntaxHighlight~~>		</syntaxhighlight>

	For more details on how to develop Fail2ban filters please see [https://fail2ban.readthedocs.io/en/latest/filters.html the official documentation].		For more details on how to develop Fail2ban filters please see [https://fail2ban.readthedocs.io/en/latest/filters.html the official documentation].

Samueldr: fixed deprecated syntax

2024-04-05T01:36:13Z

fixed deprecated syntax

← Older revision		Revision as of 01:36, 5 April 2024
Line 1:		Line 1:
	[https://www.fail2ban.org Fail2ban] is an intrusion prevention software. It scans through log files to find signs of malicious intent. In general, Fail2ban will update the firewall rules to reject the offending IP address for a set amount of time.		[https://www.fail2ban.org Fail2ban] is an intrusion prevention software. It scans through log files to find signs of malicious intent. In general, Fail2ban will update the firewall rules to reject the offending IP address for a set amount of time.

	Fail2Ban uses the concept of a "jail" to modularize its configuration. A jail consists of an action (such as blocking a port using iptables) that is triggered when a filter (regular expression) applied to a log file triggers/matches more than a certain number of times in a certain time period. Actions that ship with Fail2Ban are defined in <~~source~~ lang="nix" inline>/etc/fail2ban/action.d</~~source~~>, while filters are defined in <~~source~~ lang="nix" inline>/etc/fail2ban/filter.d</~~source~~>.		Fail2Ban uses the concept of a "jail" to modularize its configuration. A jail consists of an action (such as blocking a port using iptables) that is triggered when a filter (regular expression) applied to a log file triggers/matches more than a certain number of times in a certain time period. Actions that ship with Fail2Ban are defined in <syntaxhighlight lang="nix" inline>/etc/fail2ban/action.d</syntaxhighlight>, while filters are defined in <syntaxhighlight lang="nix" inline>/etc/fail2ban/filter.d</syntaxhighlight>.

	== Basic Usage ==		== Basic Usage ==
Line 12:		Line 12:
	== Advanced Usage ==		== Advanced Usage ==

	The Fail2ban NixOS module exposes various parameters for adjusting the configuration. In the following, all options mentioned are implicitly prefixed with <~~source~~ lang="nix" inline>services.fail2ban</~~source~~> , unless specified otherwise.		The Fail2ban NixOS module exposes various parameters for adjusting the configuration. In the following, all options mentioned are implicitly prefixed with <syntaxhighlight lang="nix" inline>services.fail2ban</syntaxhighlight> , unless specified otherwise.

	* The <~~source~~ lang="nix" inline>maxretry</~~source~~> option allows you to specify how many failures are required for an IP address to be blocked.		* The <syntaxhighlight lang="nix" inline>maxretry</syntaxhighlight> option allows you to specify how many failures are required for an IP address to be blocked.
	* To prevent being locked out accidentally, use <~~source~~ lang="nix" inline>ignoreIP</~~source~~> to whitelist IPs or IP ranges to be never cheked. In the example below, common LAN IP address ranges as well as the specific IP '8.8.8.8' and the address associated with the hostname "wiki.nixos.org" are excluded from any bans. Note that the loopback addresses "127.0.0.0/8" and "::1" are added by default.		* To prevent being locked out accidentally, use <syntaxhighlight lang="nix" inline>ignoreIP</syntaxhighlight> to whitelist IPs or IP ranges to be never cheked. In the example below, common LAN IP address ranges as well as the specific IP '8.8.8.8' and the address associated with the hostname "wiki.nixos.org" are excluded from any bans. Note that the loopback addresses "127.0.0.0/8" and "::1" are added by default.
	* <~~source~~ lang="nix" inline>bantime</~~source~~> specifies for how much time an IP address is blocked after reaching the maximum number of failures. Note that the bantime can be increased for every violation by setting <~~source~~ lang="nix" inline>bantime-increment.enable = true;</~~source~~>. The bantime increment can then be customized by specifying a formula (in Python) like <~~source~~ lang="python" inline>ban.Time * math.exp(float(ban.Count+1)banFactor)/math.exp(1banFactor)</~~source~~> with <~~source~~ lang="nix" inline>bantime-increment.formula</~~source~~>, the multipliers with <~~source~~ lang="nix" inline>bantime-increment.multipliers</~~source~~>, the maximum bantime with <~~source~~ lang="nix" inline>bantime-increment.maxtime</~~source~~> and the indication to consider the bans issued throughout multiple jails with <~~source~~ lang="nix" inline>bantime-increment.overalljails</~~source~~>		* <syntaxhighlight lang="nix" inline>bantime</syntaxhighlight> specifies for how much time an IP address is blocked after reaching the maximum number of failures. Note that the bantime can be increased for every violation by setting <syntaxhighlight lang="nix" inline>bantime-increment.enable = true;</syntaxhighlight>. The bantime increment can then be customized by specifying a formula (in Python) like <syntaxhighlight lang="python" inline>ban.Time * math.exp(float(ban.Count+1)banFactor)/math.exp(1banFactor)</syntaxhighlight> with <syntaxhighlight lang="nix" inline>bantime-increment.formula</syntaxhighlight>, the multipliers with <syntaxhighlight lang="nix" inline>bantime-increment.multipliers</syntaxhighlight>, the maximum bantime with <syntaxhighlight lang="nix" inline>bantime-increment.maxtime</syntaxhighlight> and the indication to consider the bans issued throughout multiple jails with <syntaxhighlight lang="nix" inline>bantime-increment.overalljails</syntaxhighlight>
	* <~~source~~ lang="nix" inline>banaction</~~source~~> specifies which of the actions in <~~source~~ lang="nix" inline>/etc/fail2ban/action.d</~~source~~> should be the default ban action (e.g., iptables, iptables-new, iptables-multiport, iptables-ipset-proto6-allports, shorewall, etc.)		* <syntaxhighlight lang="nix" inline>banaction</syntaxhighlight> specifies which of the actions in <syntaxhighlight lang="nix" inline>/etc/fail2ban/action.d</syntaxhighlight> should be the default ban action (e.g., iptables, iptables-new, iptables-multiport, iptables-ipset-proto6-allports, shorewall, etc.)
	* <~~source~~ lang="nix" inline>extraPackages</~~source~~> contains a list of derivations whose outputs are needed by Fail2ban actions		* <syntaxhighlight lang="nix" inline>extraPackages</syntaxhighlight> contains a list of derivations whose outputs are needed by Fail2ban actions


Line 61:		Line 61:
	== Extending Fail2ban ==		== Extending Fail2ban ==

	Fail2ban capabilities can be freely extended by adding new jails, filters, and actions; the first ones of them are already covered in the "Basic usage" section, while the other two need dedicated config files to be created in the <~~source~~ lang="nix" inline>/etc/fail2ban/filter.d</~~source~~> and <~~source~~ lang="nix" inline>/etc/fail2ban/action.d</~~source~~> folders.		Fail2ban capabilities can be freely extended by adding new jails, filters, and actions; the first ones of them are already covered in the "Basic usage" section, while the other two need dedicated config files to be created in the <syntaxhighlight lang="nix" inline>/etc/fail2ban/filter.d</syntaxhighlight> and <syntaxhighlight lang="nix" inline>/etc/fail2ban/action.d</syntaxhighlight> folders.

	In order to do this, you'll have to add a <~~source~~ lang="nix" inline>environment.etc</~~source~~> section to your NixOS config file and specify there the contents of your custom actions and filters:		In order to do this, you'll have to add a <syntaxhighlight lang="nix" inline>environment.etc</syntaxhighlight> section to your NixOS config file and specify there the contents of your custom actions and filters:

	<syntaxHighlight lang=nix>		<syntaxHighlight lang=nix>

Samueldr: fixed deprecated syntax

2024-04-05T01:32:02Z

fixed deprecated syntax

← Older revision		Revision as of 01:32, 5 April 2024
Line 1:		Line 1:
	[https://www.fail2ban.org Fail2ban] is an intrusion prevention software. It scans through log files to find signs of malicious intent. In general, Fail2ban will update the firewall rules to reject the offending IP address for a set amount of time.		[https://www.fail2ban.org Fail2ban] is an intrusion prevention software. It scans through log files to find signs of malicious intent. In general, Fail2ban will update the firewall rules to reject the offending IP address for a set amount of time.

	Fail2Ban uses the concept of a "jail" to modularize its configuration. A jail consists of an action (such as blocking a port using iptables) that is triggered when a filter (regular expression) applied to a log file triggers/matches more than a certain number of times in a certain time period. Actions that ship with Fail2Ban are defined in <source lang="nix" ~~enclose="none"~~>/etc/fail2ban/action.d</source>, while filters are defined in <source lang="nix" ~~enclose="none"~~>/etc/fail2ban/filter.d</source>.		Fail2Ban uses the concept of a "jail" to modularize its configuration. A jail consists of an action (such as blocking a port using iptables) that is triggered when a filter (regular expression) applied to a log file triggers/matches more than a certain number of times in a certain time period. Actions that ship with Fail2Ban are defined in <source lang="nix" inline>/etc/fail2ban/action.d</source>, while filters are defined in <source lang="nix" inline>/etc/fail2ban/filter.d</source>.

	== Basic Usage ==		== Basic Usage ==
Line 12:		Line 12:
	== Advanced Usage ==		== Advanced Usage ==

	The Fail2ban NixOS module exposes various parameters for adjusting the configuration. In the following, all options mentioned are implicitly prefixed with <source lang="nix" ~~enclose="none"~~>services.fail2ban</source> , unless specified otherwise.		The Fail2ban NixOS module exposes various parameters for adjusting the configuration. In the following, all options mentioned are implicitly prefixed with <source lang="nix" inline>services.fail2ban</source> , unless specified otherwise.

	* The <source lang="nix" ~~enclose="none"~~>maxretry</source> option allows you to specify how many failures are required for an IP address to be blocked.		* The <source lang="nix" inline>maxretry</source> option allows you to specify how many failures are required for an IP address to be blocked.
	* To prevent being locked out accidentally, use <source lang="nix" ~~enclose="none"~~>ignoreIP</source> to whitelist IPs or IP ranges to be never cheked. In the example below, common LAN IP address ranges as well as the specific IP '8.8.8.8' and the address associated with the hostname "wiki.nixos.org" are excluded from any bans. Note that the loopback addresses "127.0.0.0/8" and "::1" are added by default.		* To prevent being locked out accidentally, use <source lang="nix" inline>ignoreIP</source> to whitelist IPs or IP ranges to be never cheked. In the example below, common LAN IP address ranges as well as the specific IP '8.8.8.8' and the address associated with the hostname "wiki.nixos.org" are excluded from any bans. Note that the loopback addresses "127.0.0.0/8" and "::1" are added by default.
	* <source lang="nix" ~~enclose="none"~~>bantime</source> specifies for how much time an IP address is blocked after reaching the maximum number of failures. Note that the bantime can be increased for every violation by setting <source lang="nix" ~~enclose="none"~~>bantime-increment.enable = true;</source>. The bantime increment can then be customized by specifying a formula (in Python) like <source lang="python" ~~enclose="none"~~>ban.Time * math.exp(float(ban.Count+1)banFactor)/math.exp(1banFactor)</source> with <source lang="nix" ~~enclose="none"~~>bantime-increment.formula</source>, the multipliers with <source lang="nix" ~~enclose="none"~~>bantime-increment.multipliers</source>, the maximum bantime with <source lang="nix" ~~enclose="none"~~>bantime-increment.maxtime</source> and the indication to consider the bans issued throughout multiple jails with <source lang="nix" ~~enclose="none"~~>bantime-increment.overalljails</source>		* <source lang="nix" inline>bantime</source> specifies for how much time an IP address is blocked after reaching the maximum number of failures. Note that the bantime can be increased for every violation by setting <source lang="nix" inline>bantime-increment.enable = true;</source>. The bantime increment can then be customized by specifying a formula (in Python) like <source lang="python" inline>ban.Time * math.exp(float(ban.Count+1)banFactor)/math.exp(1banFactor)</source> with <source lang="nix" inline>bantime-increment.formula</source>, the multipliers with <source lang="nix" inline>bantime-increment.multipliers</source>, the maximum bantime with <source lang="nix" inline>bantime-increment.maxtime</source> and the indication to consider the bans issued throughout multiple jails with <source lang="nix" inline>bantime-increment.overalljails</source>
	* <source lang="nix" ~~enclose="none"~~>banaction</source> specifies which of the actions in <source lang="nix" ~~enclose="none"~~>/etc/fail2ban/action.d</source> should be the default ban action (e.g., iptables, iptables-new, iptables-multiport, iptables-ipset-proto6-allports, shorewall, etc.)		* <source lang="nix" inline>banaction</source> specifies which of the actions in <source lang="nix" inline>/etc/fail2ban/action.d</source> should be the default ban action (e.g., iptables, iptables-new, iptables-multiport, iptables-ipset-proto6-allports, shorewall, etc.)
	* <source lang="nix" ~~enclose="none"~~>extraPackages</source> contains a list of derivations whose outputs are needed by Fail2ban actions		* <source lang="nix" inline>extraPackages</source> contains a list of derivations whose outputs are needed by Fail2ban actions


Line 61:		Line 61:
	== Extending Fail2ban ==		== Extending Fail2ban ==

	Fail2ban capabilities can be freely extended by adding new jails, filters, and actions; the first ones of them are already covered in the "Basic usage" section, while the other two need dedicated config files to be created in the <source lang="nix" ~~enclose="none"~~>/etc/fail2ban/filter.d</source> and <source lang="nix" ~~enclose="none"~~>/etc/fail2ban/action.d</source> folders.		Fail2ban capabilities can be freely extended by adding new jails, filters, and actions; the first ones of them are already covered in the "Basic usage" section, while the other two need dedicated config files to be created in the <source lang="nix" inline>/etc/fail2ban/filter.d</source> and <source lang="nix" inline>/etc/fail2ban/action.d</source> folders.

	In order to do this, you'll have to add a <source lang="nix" ~~enclose="none"~~>environment.etc</source> section to your NixOS config file and specify there the contents of your custom actions and filters:		In order to do this, you'll have to add a <source lang="nix" inline>environment.etc</source> section to your NixOS config file and specify there the contents of your custom actions and filters:

	<syntaxHighlight lang=nix>		<syntaxHighlight lang=nix>

Mic92 at 13:43, 1 April 2024

2024-04-01T13:43:33Z

← Older revision		Revision as of 13:43, 1 April 2024
Line 15:		Line 15:

	* The <source lang="nix" enclose="none">maxretry</source> option allows you to specify how many failures are required for an IP address to be blocked.		* The <source lang="nix" enclose="none">maxretry</source> option allows you to specify how many failures are required for an IP address to be blocked.
	* To prevent being locked out accidentally, use <source lang="nix" enclose="none">ignoreIP</source> to whitelist IPs or IP ranges to be never cheked. In the example below, common LAN IP address ranges as well as the specific IP '8.8.8.8' and the address associated with the hostname "nixos.~~wiki~~" are excluded from any bans. Note that the loopback addresses "127.0.0.0/8" and "::1" are added by default.		* To prevent being locked out accidentally, use <source lang="nix" enclose="none">ignoreIP</source> to whitelist IPs or IP ranges to be never cheked. In the example below, common LAN IP address ranges as well as the specific IP '8.8.8.8' and the address associated with the hostname "wiki.nixos.org" are excluded from any bans. Note that the loopback addresses "127.0.0.0/8" and "::1" are added by default.
	* <source lang="nix" enclose="none">bantime</source> specifies for how much time an IP address is blocked after reaching the maximum number of failures. Note that the bantime can be increased for every violation by setting <source lang="nix" enclose="none">bantime-increment.enable = true;</source>. The bantime increment can then be customized by specifying a formula (in Python) like <source lang="python" enclose="none">ban.Time * math.exp(float(ban.Count+1)banFactor)/math.exp(1banFactor)</source> with <source lang="nix" enclose="none">bantime-increment.formula</source>, the multipliers with <source lang="nix" enclose="none">bantime-increment.multipliers</source>, the maximum bantime with <source lang="nix" enclose="none">bantime-increment.maxtime</source> and the indication to consider the bans issued throughout multiple jails with <source lang="nix" enclose="none">bantime-increment.overalljails</source>		* <source lang="nix" enclose="none">bantime</source> specifies for how much time an IP address is blocked after reaching the maximum number of failures. Note that the bantime can be increased for every violation by setting <source lang="nix" enclose="none">bantime-increment.enable = true;</source>. The bantime increment can then be customized by specifying a formula (in Python) like <source lang="python" enclose="none">ban.Time * math.exp(float(ban.Count+1)banFactor)/math.exp(1banFactor)</source> with <source lang="nix" enclose="none">bantime-increment.formula</source>, the multipliers with <source lang="nix" enclose="none">bantime-increment.multipliers</source>, the maximum bantime with <source lang="nix" enclose="none">bantime-increment.maxtime</source> and the indication to consider the bans issued throughout multiple jails with <source lang="nix" enclose="none">bantime-increment.overalljails</source>
	* <source lang="nix" enclose="none">banaction</source> specifies which of the actions in <source lang="nix" enclose="none">/etc/fail2ban/action.d</source> should be the default ban action (e.g., iptables, iptables-new, iptables-multiport, iptables-ipset-proto6-allports, shorewall, etc.)		* <source lang="nix" enclose="none">banaction</source> specifies which of the actions in <source lang="nix" enclose="none">/etc/fail2ban/action.d</source> should be the default ban action (e.g., iptables, iptables-new, iptables-multiport, iptables-ipset-proto6-allports, shorewall, etc.)
Line 30:		Line 30:
	"10.0.0.0/8" "172.16.0.0/12" "192.168.0.0/16"		"10.0.0.0/8" "172.16.0.0/12" "192.168.0.0/16"
	"8.8.8.8" # whitelist a specific IP		"8.8.8.8" # whitelist a specific IP
	"nixos.~~wiki~~" # resolve the IP via DNS		"wiki.nixos.org" # resolve the IP via DNS
	];		];
	bantime = "24h"; # Ban IPs for one day on the first ban		bantime = "24h"; # Ban IPs for one day on the first ban

imported>Rollin rob at 09:39, 24 March 2024

2024-03-24T09:39:18Z

← Older revision		Revision as of 09:39, 24 March 2024
Line 8:		Line 8:
	services.fail2ban.enable = true;		services.fail2ban.enable = true;
	</syntaxHighlight>		</syntaxHighlight>
	NixOS comes with a pre-configured SSH jail which will observe errors in the SSH daemon and ban offending IPs. If ~~you~~ all you need is basic rate-limiting and only have the SSH port exposed, you don't have to setup anything else.		NixOS comes with a pre-configured SSH jail which will observe errors in the SSH daemon and ban offending IPs. If all you need is basic rate-limiting and only have the SSH port exposed, you don't have to setup anything else.

	== Advanced Usage ==		== Advanced Usage ==

imported>Writer: Streamline text and adapt to 23.11 where new expressions are possible and one was removed

2023-12-10T12:07:25Z

Streamline text and adapt to 23.11 where new expressions are possible and one was removed

← Older revision		Revision as of 12:07, 10 December 2023
Line 1:		Line 1:
	[https://www.fail2ban.org Fail2ban] is an intrusion prevention software. It scans through log files to find signs of malicious intent. In general, Fail2ban will update the firewall rules to reject the offending IP address for a set amount of time.		[https://www.fail2ban.org Fail2ban] is an intrusion prevention software. It scans through log files to find signs of malicious intent. In general, Fail2ban will update the firewall rules to reject the offending IP address for a set amount of time.

			Fail2Ban uses the concept of a "jail" to modularize its configuration. A jail consists of an action (such as blocking a port using iptables) that is triggered when a filter (regular expression) applied to a log file triggers/matches more than a certain number of times in a certain time period. Actions that ship with Fail2Ban are defined in <source lang="nix" enclose="none">/etc/fail2ban/action.d</source>, while filters are defined in <source lang="nix" enclose="none">/etc/fail2ban/filter.d</source>.

	== Basic Usage ==		== Basic Usage ==
	~~The~~ Fail2ban [[NixOS modules\|NixOS module]] ~~can be found under <source lang="nix" enclose="none">services.fail2ban</source>; from now on (unless differently specified), all options described are prefixed with this namespace.~~		Enable Fail2ban [[NixOS modules\|NixOS module]] with the expression:

	~~The service can be enabled~~ with the expression:
	<syntaxHighlight lang=nix>		<syntaxHighlight lang=nix>
	services.fail2ban.enable = true;		services.fail2ban.enable = true;
	</syntaxHighlight>		</syntaxHighlight>
	~~This will also enable~~ a jail ~~for sshd~~, ~~which comes with NixOS~~.		NixOS comes with a pre-configured SSH jail which will observe errors in the SSH daemon and ban offending IPs. If you all you need is basic rate-limiting and only have the SSH port exposed, you don't have to setup anything else.

	==~~= Configuration =~~==		== Advanced Usage ==

	The Fail2ban NixOS module exposes ~~different~~ parameters for adjusting the configuration:		The Fail2ban NixOS module exposes various parameters for adjusting the configuration. In the following, all options mentioned are implicitly prefixed with <source lang="nix" enclose="none">services.fail2ban</source> , unless specified otherwise.

	* The <source lang="nix" enclose="none">maxretry</source> option allows you to specify how many failures are required for an IP address to be blocked.		* The <source lang="nix" enclose="none">maxretry</source> option allows you to specify how many failures are required for an IP address to be blocked.
	* To prevent being locked out accidentally, ~~the '~~ignoreIP~~' option can be used~~ to ~~prevent IP addresses and~~ IP ranges ~~from being blocked~~. In the example below, common LAN IP address ranges as well as the specific IP '8.8.8.8' and the address associated with the hostname "nixos.wiki" ~~(note~~ that the loopback addresses "127.0.0.0/8" and "::1" are added by default).		* To prevent being locked out accidentally, use <source lang="nix" enclose="none">ignoreIP</source> to whitelist IPs or IP ranges to be never cheked. In the example below, common LAN IP address ranges as well as the specific IP '8.8.8.8' and the address associated with the hostname "nixos.wiki" are excluded from any bans. Note that the loopback addresses "127.0.0.0/8" and "::1" are added by default.
	* <source lang="nix" enclose="none">bantime</source> specifies for how much time an IP address is blocked after reaching the maximum number of ~~tries~~. Note that the bantime can be increased for every violation by setting <source lang="nix" enclose="none">bantime-increment.enable~~</source> to <source lang~~=~~"nix" enclose="none">~~true</source>~~; the~~ bantime increment can then be customized by specifying a formula (in Python) like <source lang="python" enclose="none">ban.Time * math.exp(float(ban.Count+1)banFactor)/math.exp(1banFactor)</source> with <source lang="nix" enclose="none">bantime-increment.formula</source>, the multipliers with <source lang="nix" enclose="none">bantime-increment.multipliers</source>, the maximum bantime with <source lang="nix" enclose="none">bantime-increment.maxtime</source> and the indication to consider the bans issued throughout multiple jails with <source lang="nix" enclose="none">bantime-increment.overalljails</source>		* <source lang="nix" enclose="none">bantime</source> specifies for how much time an IP address is blocked after reaching the maximum number of failures. Note that the bantime can be increased for every violation by setting <source lang="nix" enclose="none">bantime-increment.enable = true;</source>. The bantime increment can then be customized by specifying a formula (in Python) like <source lang="python" enclose="none">ban.Time * math.exp(float(ban.Count+1)banFactor)/math.exp(1banFactor)</source> with <source lang="nix" enclose="none">bantime-increment.formula</source>, the multipliers with <source lang="nix" enclose="none">bantime-increment.multipliers</source>, the maximum bantime with <source lang="nix" enclose="none">bantime-increment.maxtime</source> and the indication to consider the bans issued throughout multiple jails with <source lang="nix" enclose="none">bantime-increment.overalljails</source>
	* <source lang="nix" enclose="none">banaction</source> specifies which ~~one among~~ the actions ~~contained~~ in <source lang="nix" enclose="none">/etc/fail2ban/action.d</source> should be the default ~~banning~~ action (e.g., iptables, iptables-new, iptables-multiport, iptables-ipset-proto6-allports, shorewall, etc.)		* <source lang="nix" enclose="none">banaction</source> specifies which of the actions in <source lang="nix" enclose="none">/etc/fail2ban/action.d</source> should be the default ban action (e.g., iptables, iptables-new, iptables-multiport, iptables-ipset-proto6-allports, shorewall, etc.)
	* <source lang="nix" enclose="none">extraPackages</source> ~~can receive~~ a list of derivations whose outputs are needed by Fail2ban actions		* <source lang="nix" enclose="none">extraPackages</source> contains a list of derivations whose outputs are needed by Fail2ban actions
	* <source lang="nix" enclose="none">jails</source> contains the configuration of each Fail2ban “jail”. A jail consists of an action (such as blocking a port using iptables) that is triggered when a filter applied to a log file triggers more than a certain number of times in a certain time period. Actions are defined in <source lang="nix" enclose="none">/etc/fail2ban/action.d</source>, while filters are defined in <source lang="nix" enclose="none">/etc/fail2ban/filter.d</source>.
	* <source lang="nix" enclose="none">extraSettings</source> can contain parameters that are automatically applied to every jail config (i.e., in the <source lang="ini" enclose="none">[DEFAULT]</source> section)

	<syntaxHighlight lang=nix>		<syntaxHighlight lang=nix>
	services.fail2ban = {		services.fail2ban = {
	enable = true;		enable = true;
	maxretry = 5; ~~# Observe 5 violations before banning an IP~~		# Ban IP after 5 failures
			maxretry = 5;
	ignoreIP = [		ignoreIP = [
	# ~~Whitelisting~~ some subnets:		# Whitelist some subnets
	"10.0.0.0/8" "172.16.0.0/12" "192.168.0.0/16"		"10.0.0.0/8" "172.16.0.0/12" "192.168.0.0/16"
	"8.8.8.8" # ~~Whitelists~~ a specific IP		"8.8.8.8" # whitelist a specific IP
	"nixos.wiki" # ~~Resolves~~ the IP via DNS		"nixos.wiki" # resolve the IP via DNS
	];		];
	bantime = "24h"; # ~~Set bantime to~~ one day		bantime = "24h"; # Ban IPs for one day on the first ban
	bantime-increment = {		bantime-increment = {
	enable = true; # Enable increment of bantime after each violation		enable = true; # Enable increment of bantime after each violation
Line 41:		Line 41:
	};		};
	jails = {		jails = {
	apache-nohome-iptables = ''		apache-nohome-iptables.settings = {
	# Block an IP address if it accesses a non-existent		# Block an IP address if it accesses a non-existent
	# home directory more than 5 times in 10 minutes,		# home directory more than 5 times in 10 minutes,
	# since that indicates that it's scanning.		# since that indicates that it's scanning.
	filter = apache-nohome		filter = "apache-nohome";
	action = iptables-multiport[name=HTTP, port="http,https"]		action = ''iptables-multiport[name=HTTP, port="http,https"]'';
	logpath = /var/log/httpd/error_log*		logpath = "/var/log/httpd/error_log*";
	backend = auto		backend = "auto";
	findtime = 600		findtime = 600;
	bantime = 600		bantime = 600;
	maxretry = 5		maxretry = 5;
	'';		};
	};		};
	};		};
	</syntaxHighlight>		</syntaxHighlight>

	These settings are written to <code>/etc/fail2ban/jail.local</code>, where fail2ban will ~~use~~ them.		These settings are written to <code>/etc/fail2ban/jail.local</code>, where fail2ban will read them.

	== Extending Fail2ban ==		== Extending Fail2ban ==
Line 87:		Line 87:
	# --- snip ---		# --- snip ---
	jails = {		jails = {
	ngnix-url-probe = ''		ngnix-url-probe.settings = {
	enabled = true		enabled = true;
	filter = nginx-url-probe		filter = "nginx-url-probe";
	logpath = /var/log/nginx/access.log		logpath = "/var/log/nginx/access.log";
	action = %(action_)s[blocktype=DROP]		action = ''%(action_)s[blocktype=DROP]
	ntfy		ntfy'';
	backend = auto # Do not forget to specify this if your jail uses a log file		backend = "auto"; # Do not forget to specify this if your jail uses a log file
	maxretry = 5		maxretry = 5;
	findtime = 600		findtime = 600;
	'';		};
	};		};
	};		};

imported>Writer: Reduce redudant desciptions and add new information.

2023-11-26T22:08:06Z

Reduce redudant desciptions and add new information.

← Older revision		Revision as of 22:08, 26 November 2023
Line 4:		Line 4:
	The Fail2ban [[NixOS modules\|NixOS module]] can be found under <source lang="nix" enclose="none">services.fail2ban</source>; from now on (unless differently specified), all options described are prefixed with this namespace.		The Fail2ban [[NixOS modules\|NixOS module]] can be found under <source lang="nix" enclose="none">services.fail2ban</source>; from now on (unless differently specified), all options described are prefixed with this namespace.

	The service can be enabled ~~by setting <source lang="nix" enclose="none">enable</source> to <source lang="nix" enclose="none">true</source>~~:		The service can be enabled with the expression:
	<syntaxHighlight lang=nix>		<syntaxHighlight lang=nix>
	services.fail2ban.enable = true; ~~# Enables Fail2ban~~		services.fail2ban.enable = true;
	</syntaxHighlight>		</syntaxHighlight>
			This will also enable a jail for sshd, which comes with NixOS.

	=== Configuration ===		=== Configuration ===
	The Fail2ban NixOS module exposes different parameters ~~needed to adjust~~ the configuration:
			The Fail2ban NixOS module exposes different parameters for adjusting the configuration:

	* The <source lang="nix" enclose="none">maxretry</source> option allows you to specify how many failures are required for an IP address to be blocked.		* The <source lang="nix" enclose="none">maxretry</source> option allows you to specify how many failures are required for an IP address to be blocked.
Line 54:		Line 56:
	};		};
	</syntaxHighlight>		</syntaxHighlight>

			These settings are written to <code>/etc/fail2ban/jail.local</code>, where fail2ban will use them.

	== Extending Fail2ban ==		== Extending Fail2ban ==