From 6eb262fea684359709e985920d1879556ca47918 Mon Sep 17 00:00:00 2001 From: Yaroslav Halchenko Date: Sun, 24 Mar 2013 22:12:52 -0400 Subject: [PATCH] My improvements to manpages --- man/fail2ban.1 | 30 ++++++++++------ man/jail.conf.5 | 93 ++++++++++++++++++++++++------------------------- 2 files changed, 65 insertions(+), 58 deletions(-) diff --git a/man/fail2ban.1 b/man/fail2ban.1 index 1198c07c..9af9ec54 100644 --- a/man/fail2ban.1 +++ b/man/fail2ban.1 @@ -2,25 +2,33 @@ .SH NAME fail2ban \- a set of server and client programs to limit brute force authentication attempts. .SH DESCRIPTION -Fail2Ban consists of a client, server and some configuration files to achieve limiting -brute force of authenitcation attempts. +Fail2Ban consists of a client, server and configuration files to limit +brute force authentication attempts. -The server program is \fBfail2ban-server\fR which is configured from the configuration files. The -fail2ban-server can also be configured using the \fBfail2ban-client\fR. +The server program \fBfail2ban-server\fR is responsible for monitoring +log files and issuing ban/unban commands. It gets configured through +a simple protocol by \fBfail2ban-client\fR, which can also read +configuration files and issue corresponding configuration commands to +the server. -For details on the configuration of fail2ban see the jail.conf(5) manual page. +For details on the configuration of fail2ban see the jail.conf(5) +manual page. A jail (as specified in jail.conf) couples filters and +actions definitions for any given list of files to get monitored. -For details on the configuration of fail2ban-server see the fail2ban-server(1) manual page. +For details on the command-line options of fail2ban-server see the +fail2ban-server(1) manual page. -For details on the configuration of fail2ban-client see the fail2ban-client(1) manual page. +For details on the command-line options and commands for configuring +the server via fail2ban-client see the fail2ban-client(1) manual page. -For testing regular expressions assocated with filter using the fail2ban-regex program may be of -use and its manual page is fail2ban-regex(1). +For testing regular expressions specified in a filter using the +fail2ban-regex program may be of use and its manual page is +fail2ban-regex(1). .SH FILES \fI/etc/fail2ban/*\fR .SH AUTHOR -Manual page written by Daniel Black +Manual page written by Daniel Black and Yaroslav Halchenko .SH "REPORTING BUGS" Report bugs to https://github.com/fail2ban/fail2ban/issues .SH COPYRIGHT @@ -32,5 +40,5 @@ Licensed under the GNU General Public License v2 (GPL). .br fail2ban-server(1) fail2ban-client(1) -jail.conf(5) fail2ban-regex(1) +jail.conf(5) diff --git a/man/jail.conf.5 b/man/jail.conf.5 index 38c29bbf..8f38c14b 100644 --- a/man/jail.conf.5 +++ b/man/jail.conf.5 @@ -8,13 +8,13 @@ jail.conf \- configuration for the fail2ban server .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. +Fail2ban has three configuration file types. Action files are the commands for banning and unbanning of IP address, +Filter files tell fail2ban how to detect authentication failures, and Jail configurations combine filters with actions into jails. -There are *.conf files that are distributed by fail2ban and *.local file that contain user overwritten files. -It is recommended 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 to extend jail.conf ( -the configuration for the fail2ban server). The jail.local file will be the following if you only need to enable +There are *.conf files that are distributed by fail2ban and *.local file that contain user customizations. +It is recommended that *.conf files should remain unchanged. If needed, customizations should be provided in *.local files. +For instance, if you would like to customize the [ssh-iptables-ipset] jail, create a jail.local to extend jail.conf +(the configuration for the fail2ban server). The jail.local file will be the following if you only need to enable it: .TP @@ -22,13 +22,13 @@ it: [ssh-iptables-ipset] enabled = true -.TP -Only overwride the settings you need to change and the rest of the configuration comes from the corresponding +.PP +Override only the settings you need to change and the rest of the configuration will come from the corresponding *.conf file. .SH DEFAULT -The following options are applicable to all jails. Their meaning is in the default jail.conf file. +The following options are applicable to all jails. Their meaning is described in the default jail.conf file. .TP \fBignoreip\fR .TP @@ -41,55 +41,53 @@ The following options are applicable to all jails. Their meaning is in the defau \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, \fBDefinition\fR and \fBInit\fR . +.SH "ACTION FILES" +Action files specify which commands are executed to ban and unban an IP address. They are located under /etc/fail2ban/action.d. -The [Init] section allows for settings relevant to the action. In jail.conf/jail.local these can be overwritten for a particular jail. +Like with jail.conf files, if you desire local changes create an [actionname].local file in the /etc/fail2ban/action.d directory +and override the required settings. -The commands are specified in the [Definition] section as below.. +Action files are ini files that have two sections, \fBDefinition\fR and \fBInit\fR . -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 [Init] section allows for action-specific settings. In jail.conf/jail.local these can be overwritten for a particular jail as options to the jail. -The following action parameters are in the [Definition] section. +The following commands can be present in the [Definition] section. .TP \fBactionstart\fR -This is the commands that are executed when the jail starts. +command(s) executed when the jail starts. .TP \fBactionstop\fR -This is the commands that are executed when the jail stops. +command(s) 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. +the command ran before any other action. It aims to verify if the environment is still ok. .TP \fBactionban\fR -This is the command that bans the IP address. +command(s) that bans the IP address after \fBmaxretry\fR log lines matches within last \fBfindtime\fR seconds. .TP \fBactionunban\fR -This is the command that unbans the IP address after \fBbantime\fR. +command(s) that unbans the IP address after \fBbantime\fR. + +Commands specified in the [Definition] section are executed through a system shell so shell redirection and process control is allowed. The commands should +return 0, otherwise error would be logged. Moreover if \fBactioncheck\fR exits with non-0 status, it is taken as indication that firewall status has changed and fail2ban needs to reinitialize itself (i.e. issue \fBactionstop\fR and \fBactionstart\fR commands). -Tags are in <>. All the elements of [Init] are tags that are replaced in all action commands. Tags can be added by the +Tags are enclosed 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 +More than a single command is allowed to be specified. Each command needs to be on a separate line and indented with whitespaces without blank lines. The following example defines two commands to be executed. -actionban = iptables -I fail2ban- --source -j DROP + actionban = iptables -I fail2ban- --source -j DROP + echo ip=, match=, time=