[email protected]
[Top] [All Lists]

Bug#400416: marked as forwarded (fail2ban: Better Documentation)

Subject: Bug#400416: marked as forwarded fail2ban: Better Documentation
From: Debian Bug Tracking System
Date: Sat, 25 Nov 2006 18:33:12 -0800
Your message dated Sat, 25 Nov 2006 20:56:47 -0500
with message-id <[email protected]>
has caused the Debian Bug report #400416,
regarding fail2ban: Better Documentation
to be marked as having been forwarded to the upstream software
author(s) Cyril Jaquier <[email protected]>.

(NB: If you are a system administrator and have no idea what I am
talking about this indicates a serious mail system misconfiguration
somewhere.  Please contact me immediately.)

Debian bug tracking system administrator
(administrator, Debian Bugs database)

--- Begin Message ---
Subject: Re: Bug#400416: fail2ban: Better Documentation
From: Yaroslav Halchenko
Date: Sat, 25 Nov 2006 20:56:47 -0500
Hi Ross,

Thank you for the detailed list of concerns which arise due to missing
parts of documentation. I am forwarding this bug upstream, thus I will
keep all the text you wrote + providing some quick answers so you could
start using it.
Also I believe the intent was to have better documentation within the
next release ;-)

On Sat, 25 Nov 2006, Ross Boylan wrote:

> Package: fail2ban
> Version: 0.7.4-3
> Severity: wishlist

> I'm tempted to give this higher severity.  It's very hard to figure
> out how to use this package, or at least to customize it, with current
> documentation.  Even after reading the provided docs (both man and
> /usr/share/doc) and visiting the web site, I'm pretty baffled.  And
> I've been using earlier versions of the program!

> One can make informed guesses, but it shouldn't be necessary to guess.

> More overall orientation is needed.  The docs do provide the overall
> purpose of the program, but the next level of detail down is missing.

> What are the parts of the system (client, server, entries in iptables,
> apparently--some of this becomes apparent on the man pages)?  Some of
> the documentation seems to imply local customization can be done
> entirely from the client.  Is that true?  Is that preferred?

> What are the basic concepts of the system?  What's a jail?  What is
> the difference between the configuration subdirectories (some help on
> http://fail2ban.sourceforge.net/wiki/index.php/MANUAL_0_8)?
Please have a look at
http://fail2ban.sourceforge.net/wiki/index.php/FEATURE_Split_config
It might answer some questions
Cyril - I've made some adjustments on that page. I hope that they are ok
and might be useful somewhere in the documentation.

> What is the syntax of the configuration file?  There is clearly some
> template system at work--what is it?  It also looks as if there are
> some global options that may be overriddent for the monitoring of a
> particular application.

> What are the keywords and what do they mean?

> How does fail2ban interact with other systems (e.g. firewall front
> ends) or administrators who might mess around with the iptables?  For
> example, are such combinations a no-no?  Do they risk blowing away
> fail2ban's settings?
actions.d/* define the set of possible actions to be taken. I think
those are the only ways fail2ban can/should interact with the system

> How do the overrides work?  I first had the impression that to
> override foo.conf you copied it to foo.conf.local and then modified
> it--foo.conf would not be read at all.  However, comments in
> jail.conf,
> --------------------------------------------------
> # Default action to take: ban & send an e-mail with whois report
> # to the destemail. Copy/paste+uncomment next 2 lines into jail.local
> # to activate
> #action = iptables[name=%(__name__)s, port=%(port)s]
> #               mail-whois[name=%(__name__)s, dest=%(destemail)s].
> -----------------------------------------------------
> indicate 1) the correct file name is foo.local,
> 2) that file supplements foo.conf;
> 3) apparently foo.local overrides variable definitions without needing
> to comment out the original.
yes - I made those comments ;-) 

> The advice in that comment is also wrong.
:-(

> I followed it and got
> ConfigParser.MissingSectionHeaderError: File contains no section headers.
> file: /etc/fail2ban/jail.local, line: 1
> 'action = iptables[name=%(__name__)s, port=%(port)s]\n'
>  failed!
> when I tried to restart.  Adding a [DEFAULT] header got it going,
> though I'm a little unsure whether I should have copied the other
> entries over as well.
indeed. forgotten to mention the section name. Thanks! you need to copy
only entries you would like to have different or additional. Thus mine
jail.local looks like
,---------------------------------[ /etc/fail2ban/jail.local 
]------------------------
| [DEFAULT]
|
| bantime  = 3600
| maxretry = 3
|
| # Destination email address used solely for the interpolations in
| # jail.{conf,local} configuration files.
| destemail = [email protected]
|
| # Default action to take: ban & send an e-mail with whois report
| # to the destemail
| action = shorewall[name=%(__name__)s, port=%(port)s]
|
| #                mail-whois[name=%(__name__)s, dest=%(destemail)s]
|
| [apache]
| enabled = true
| logpath = /home/vservers/www/var/log/apache2/*error.log
| maxretry = 4
|
|
| [apache-noscript]
| enabled = true
| port    = http
| filter  = apache-noscript
| #logpath = /var/log/apache*/*error.log
| logpath = /home/vservers/www/var/log/apache2/*error.log
| maxretry = 6
|
| [apache-attacks]
| enabled = true
| port    = http
| filter  = apache-attacks
| #logpath = /var/log/apache*/*access.log
| logpath = /home/vservers/www/var/log/apache2/*access.log
| maxretry = 1
|
| [apache-attacks-gb]
| enabled = true
| port    = http
| filter  = apache-attacks-gb
| logpath = /home/vservers/www/var/log/apache2/*www.onerussian.com*access.log
| maxretry = 1
| bantime  = 36000
|
| [exim4-abuse]
| enabled = true
| port    = smtp
| filter  = exim4-abuse
| logpath = /var/log/exim4/mainlog
| maxretry = 4
| bantime  = 3600
|
| [sasl]
| enabled  = true
|
`-------------------------------------------------------------------------------

> The comments in the configuration files are cryptic:
> ----------------------------------------
> # Option:  fwstart
> # Notes.:  command executed once at the start of Fail2Ban.
> # Values:  CMD

> actionstart = touch <tmpfile>
> -------------------------------------------------
> Huh?  What's fwstart?  And again, what's the syntax.
hm... fwstart is the "command executed once at the start of Fail2Ban" if
that action is used for some jail.

> The man page, among other places, uses syntax like <JAIL>.  Is that a
> number?  A string?
I bet you could name them by numbers, or it can be plain string as it is
now -- ssh, apache, apache-attacks, etc

> The Debian package suggests python-gamin, and the web site mentions
> gamin as well.  Neither provide much indication of how it's used.  I
> guess from the Debian packaging it's not required, and I guess from
> the gamin site that fail2ban can monitor more efficiently if the
> package is present.
from jail.conf:
,---------------------------[ jail.conf          ]------------------------
| # "backend" specifies the backend used to get files modification. Available
| # options are "gamin", "polling" and "auto".
| # yoh: For some reason Debian shipped python-gamin didn't work as
| # expected
| #      This issue left ToDo, so polling is default backend for now
| backend = polling
`-------------------------------------------------------------------------
if no backend specified, then if gamin is available - it gets used (ie
auto mode is assumed)

> The web site is a mixed blessing.  For example,
> http://fail2ban.sourceforge.net/wiki/index.php/FAQ_english#Configuration
> says "There is only one configuration file, where Fail2ban can be
> whole configurated, this file is located at: /etc/fail2ban.conf".  Not
> true any more (or is that just a Debian thing?).
nope - it is 0.7. thing... I bet, Cyril (upstream) would be very
thankful for help with documentation and site reorganization (it is wiki
after all)

> As a specific example, I doubt I would have found where to customize
> the email notification without your specific guidance (from a
> different bug).

> BTW, TODO.Debian includes moving to a split config; it's probably time
> to remove that item :)
;) indeed ;-) done - will be in next debian release

Thanks once again
> -- System Information:
> Debian Release: 4.0
>   APT prefers testing
>   APT policy: (990, 'testing'), (990, 'stable'), (50, 'unstable')
> Architecture: i386 (i686)
> Shell:  /bin/sh linked to /bin/bash
> Kernel: Linux 2.4.27advncdfs
> Locale: LANG=en_US, LC_CTYPE=en_US (charmap=ISO-8859-1)

> Versions of packages fail2ban depends on:
> ii  iptables                1.3.6.0debian1-3 administration tools for packet 
> fi
> ii  lsb-base                3.1-15           Linux Standard Base 3.1 init 
> scrip
> ii  python                  2.4.3-11         An interactive high-level 
> object-o
> ii  python-central          0.5.10           register and build utility for 
> Pyt
> ii  python2.4               2.4.3-8          An interactive high-level 
> object-o

> fail2ban recommends no packages.

> -- no debconf information



-- 
                                  .-.
=------------------------------   /v\  ----------------------------=
Keep in touch                    // \\     ([email protected]|www.)onerussian.com
Yaroslav Halchenko              /(   )\               ICQ#: 60653192
                   Linux User    ^^-^^    [175555]



--- End Message ---
<Prev in Thread] Current Thread [Next in Thread>
  • Bug#400416: marked as forwarded (fail2ban: Better Documentation), Debian Bug Tracking System <=