--- fail2ban-0.8.6.orig/doc/run-rootless.txt +++ fail2ban-0.8.6/doc/run-rootless.txt @@ -0,0 +1,92 @@ +Fail2ban normally requires root priviledges to insert iptables rules +through calls to /sbin/iptables and also to read the logfiles. +Fail2ban can run as an unpriviledged user provided that those two +capabilites are preserved. The idea is to run fail2ban as a normal +user (e.g. fail2ban) who belongs to a group which is allowed to read +logfiles. The user should also be allowed to write to +/proc/net/xt_recent/fail2ban- (name is specified in the iptables +rule). + +/proc/net/xt_recent/* is created by the xt_recent kernel module when +an iptables rule with '-m limit' is inserted. This file contains a +dynamic list of IP addresses which can than be used in iptables rules. +Addresses can be matched against this list, with an optional timeout. +One way to use xt_recent is to insert IPs into this list from an +iptables rule, e.g. after connecting to the SSH port three times in a +minute. This is the standard usage described in iptables(3). + +Another way to use xt_recent is by inserting the rules by writing to +/proc/net/xt_recent/fail2ban-. This can be performed by a fail2ban +action. Files in /proc/net/xt_recent/ are protected by normal +filesystem rules, so can be chown'ed and chmod'ed to be writable by a +certain user. After the necessary iptables rules are inserted (which +requires root priviledges), blacklisting can be perfomed by an +unpriviledged user. + +Using fail2ban with xt_recent allows smarter filtering than normal +iptables rules with the xt_recent module can provide. + +The disadvantage is that fail2ban cannot perform the setup by itself, +which would require the priviledge to call /sbin/iptables, and it must +be done through other means. + +The primary advantage is obvious: it's generally better to run +services not as root. This setup is more robust, because xt_recent has +it's own memory management and should behave smartly in case a very +large amount of IPs is blocked. Also in case the fail2ban process dies +the rules expire automatically. In case of a large amount of blocked +IPs, traversing rules linearly for each SYN packet as fail2ban +normally inserts them will be slow, but xt_recent with the same number +of IPs would be much faster. (Didn't test this, so this is pure +handwaving, but it should really be this way ;)) From the +administrators point of view, a setup with xt_recent might also be +easier, because it's very simple to modify the permissions on +/proc/net/xt_recent/fail2ban- to be readable or writable by +some user and thus allow delisting IPs by helper administrators +without the ability to mess up other iptables rules. + +The xt_recent-echo jail can be used under the root user without +further configuration. To run not as root, futher setup is necessary: + +- Create user: + + - set FAIL2BAN_USER in /etc/default/fail2ban. + + This probably should be fail2ban. + + - add user fail2ban who can read /var/log/auth.log and other + necessary log files. Log files are owned by group 'adm', so + it is enough if this user belongs to this group. + + The user can be created e.g. with + + useradd --system --no-create-home --home-dir / --groups adm fail2ban + +- Statically initialize chains firewall: + + - put a rule to check the xt_recent list in the static firewall initialization + script, with names like fail2ban-ssh (action uses separate chains per each + jail, so define here the ones you need 1-per-jail) + + Sample invocation might be + + iptables -I INPUT -m recent --update --seconds 3600 --name fail2ban- -j DROP + + with suitably replaced. + + - suppress actionstart for iptables-xt_recent-echo action by creating an override file + iptables-xt_recent-echo.local to accompany iptables-xt_recent-echo.conf with + + [Definition] + actionstart = + +- Permissions: + + make sure that configuration files under /etc/fail2ban are readable by + fail2ban user. Make sure that logfiles of fail2ban itself are writable + by the fail2ban user. /etc/init.d/fail2ban will change the ownership at + startup, but it is also necessary to modify /etc/logrotate.d/fail2ban. + + The simplest way is to replace '# create ...' with the following + # create 640 fail2ban adm + --- fail2ban-0.8.6.orig/config/action.d/iptables-xt_recent-echo.conf +++ fail2ban-0.8.6/config/action.d/iptables-xt_recent-echo.conf @@ -0,0 +1,76 @@ +# Fail2Ban configuration file +# +# Author: Zbigniew Jędrzejewski-Szmek +# +# $Revision: 1 $ +# + +[Definition] + +# Option: actionstart +# Notes.: command executed once at the start of Fail2Ban. +# Values: CMD +# +# Changing iptables rules requires root priviledges. If fail2ban is +# configured to run as root, firewall setup can be performed by +# fail2ban automatically. However, if fail2ban is configured to run as +# a normal user, the configuration must be done by some other means +# (e.g. using static firewall configuration with the +# iptables-persistent package). +# +# Explanation of the rule below: +# Check if any packets coming from an IP on the fail2ban- +# list have been seen in the last 3600 seconds. If yes, update the +# timestamp for this IP and drop the packet. If not, let the packet +# through. +# +# Fail2ban inserts blacklisted hosts into the fail2ban- list +# and removes them from the list after some time, according to its +# own rules. The 3600 second timeout is independent and acts as a +# safeguard in case the fail2ban process dies unexpectedly. The +# shorter of the two timeouts actually matters. +actionstart = iptables -I INPUT -m recent --update --seconds 3600 --name fail2ban- -j DROP + +# Option: actionstop +# Notes.: command executed once at the end of Fail2Ban +# Values: CMD +# +actionstop = echo / > /proc/net/xt_recent/fail2ban- + +# Option: actioncheck +# Notes.: command executed once before each actionban command +# Values: CMD +# +actioncheck = test -e /proc/net/xt_recent/fail2ban- + +# Option: actionban +# Notes.: command executed when banning an IP. Take care that the +# command is executed with Fail2Ban user rights. +# Tags: IP address +# number of failures +#