From 3aeb1a9f4e9094b9882b7f7daddbf687161968f6 Mon Sep 17 00:00:00 2001
From: Daniel Black <grooverdan@users.sourceforge.net>
Date: Sat, 16 Mar 2013 13:57:42 +1100
Subject: [PATCH] ENH: jail.conf man page

---
 man/jail.conf.5 | 145 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 145 insertions(+)
 create mode 100644 man/jail.conf.5

diff --git a/man/jail.conf.5 b/man/jail.conf.5
new file mode 100644
index 00000000..7a841f7d
--- /dev/null
+++ b/man/jail.conf.5
@@ -0,0 +1,145 @@
+.TH JAIL.CONF.5 "fail2ban" "jail.conf(5)"
+.SH NAME
+jail.conf \- configuration for the fail2ban server
+.SH SYNOPSIS
+.B jail.conf / jail.local
+
+.B action.d/*.conf action.d/*.local
+
+.B filter.d/*.conf filter.d/*.local
+.SH DESCRIPTION
+Fail2ban has three configuration file types. Action files are the commands for banning and unbanning IP address,
+Filter files tell fail2ban how authentication failures occur, and Jail configurations that map the two together.
+
+There are *.conf files that are distributed by fail2ban and *.local file that contain user overwritten files. 
+It is recommend that *.conf files are not changed. *.local files are where users overwrite their default settings.
+For instance if you require the default [ssh-iptables-ipset] jail create a jail.local with The jail.conf file is
+ the configuration for the fail2ban server. Only overwride the settings you need to change and the rest come from 
+the default *.conf file.
+
+[ssh-iptables-ipset]
+
+enabled = true
+
+.SH DEFAULT
+The following options are applicable to all jails. Their meaning is in the default jail.conf file.
+.TP
+\fBignoreip\fR 
+.TP
+\fBbantime\fR
+.TP
+\fBfindtime\fR
+.TP
+\fBmaxretry\fR
+.TP
+\fBbackend\fR
+.TP
+\fBusedns\fR
+.TP
+.SH ACTION FILES
+Action files specify which commands are executed to ban an IP address. They are located in /etc/fail2ban/action.d.
+
+Like jail.conf files if you desire local changes create a [actionname].local file in the /etc/fail2ban/action.d directory 
+and override the required settings.
+
+The action files are ini files that have two sections, \fBdefination\fR and \fBinit\fR . 
+
+The [init] section allows for settings relevant to the action. In jail.conf/jail.local these can be overwritten for a particular jail.
+
+The commands are specified in the [defination] section as below..
+
+The commands are executed through a system shell so shell redirection and process control is allowed. The commands should
+return 0 to indicate success which will prevent fail2ban attempting to retry (up to \fBmaxretry\fR times to ban the IP again.
+
+The following action parameters are in the [defination] section.
+.TP
+\fBactionstart\fR
+This is the commands that are executed when the jail starts.
+.TP
+\fBactionstop\fR
+This is the commands that are executed when the jail stops.
+.TP
+\fBactioncheck\fR
+This is the command that is before each other action. It checks to see if the environment is ok.
+.TP
+\fBactionban\fR
+This is the command that bans the IP address.
+.TP
+\fBactionunban\fR
+This is the command that unbans the IP address after \fBbantime\fR.
+
+Tags are in <>. All the elements of [init] are tags that are replaced in all action commands. Tags can be added by the
+\fBfail2ban-client\fR using the setctag command.
+
+More that one command is allowed. Each command needs to be on a new line and indented with whitespace with no blank lines. The following defines
+two commands to be executed.
+
+actionban = iptables -I fail2ban-<name> --source <ip> -j DROP
+
+    echo ip=<ip>, match=<match>, time=<time> >> /var/log/fail2ban.log
+
+The following tags are also substituted in the actionban, actionunban and actioncheck (when called before actionban/actionunban).
+.TP
+\fBip\fR
+An IPv4 ip address to be banned. e.g. 192.168.0.2
+.TP
+.TP
+\fBfailures\fR
+The number of times the failure occurred in the log file. e.g. 3
+.TP
+\fBtime\fR
+The unix time of the ban. e.g. 1357508484
+.TP
+\fBmatches\fR
+The concatinated string of the log file lines of the matches that generated the ban.
+
+.SH FILTER FILES
+
+Filter definations are those in /etc/fail2ban/filter.d/*.conf and filter.d/*.local.
+
+These are used to identify failed authenicate attempts in logs and to extract the host IP address or hostname.
+
+Like action files, filter files are ini files. The main section is the [Definition] section.
+
+There are two filter definations used in the [defination] section, failregex and ignoreregex.
+Other definations are allowed and can be used to substitue into other definations with %(defnname). For example.
+
+baduseragents = IE|wget
+
+failregex = useragent=%(baduseragents)
+
+The \fBfailregex\fR and \fBignoreregex\fR have the following meanings:
+
+.TP
+\fBfailregex\fR
+is the regex that will match failed attempts. The tag <HOST> is used as part of the regex and is itself a regex
+for IPv4 addresses and hostnames. fail2ban will work out which one of these it actually is.
+
+.TP
+\fBignoreregex\fR
+is the regex that will be ignored by fail2ban, even if failregex matches.
+
+.PP
+Filters can also have a section called [INCLUDES]. This is used to read other configuration files.
+
+.TP
+\fBbefore\fR
+indicates that this file is read before the [defination] section.
+
+.TP
+\fBafter\fR
+indicates that this file is read after the [defination] section.
+
+.SH AUTHOR
+Fail2ban Written by Cyril Jaquier <cyril.jaquier@fail2ban.org> with many contributions by Yaroslav O. Halchenko <debian@onerussian.com>.
+Manual page written by Daniel Black.
+.SH "REPORTING BUGS"
+Report bugs to https://github.com/fail2ban/fail2ban/issues
+.SH COPYRIGHT
+Copyright \(co 2013 Daniel Black
+.br
+Copyright of modifications held by their respective authors.
+Licensed under the GNU General Public License v2 (GPL).
+.SH "SEE ALSO"
+.br 
+fail2ban-server(1)