Cyril, One point in this reply of particular relevance to you is a possible feature request, marked with a *** below. I'm hoping it's only a documentation issue.
Thanks for your work on fail2ban. Ross Boylan On Sat, Nov 25, 2006 at 08:56:47PM -0500, Yaroslav Halchenko wrote: > 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 ;-) Yes. Thanks for passing this on; I was hoping it would help. > > 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? I thought /etc/fail2ban/ was read by the server, but the site you mentioned further down in your response says it is read only by the client. So I guess the client can do all configuration. For automatic persistence, you need to edit the conf files, I assume. When I thought these files were done by the server, I thought the server might respond to client commands by writing stuff into /etc/. > > > 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 *** One "detail" that is important is what types of file names are read in the split config. Many programs that use such a scheme ignore certain file names (e.g., they read "foo" but not "foo~"). If fail2ban reads all files, it would be nice if it didn't! If it doesn't skip editor backup files, for example, the result will likely be obscure bugs. > 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 I meant "how does it interact" in a different sense, although the sense used in your reply is important too. I meant it more in the sense "if you're using fail2ban, is it also safe to use x (e.g., some firewall frontend) at the same time? In particular, is it safe to be making modifications through that other channel? As a limiting case, I expect that if a user manually clears iptables then fail2ban's settings will be lost, and it might encounter errors when it can't find chains. My speculation may be inaccurate; the point is that definitive guidance on these topics would be helpful. Another housekeeping issue is the level of reloading that is required if you change the configuration files. Some of this may be debian-specific, because of the init.d scripts. > > > 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 Yikes! There seem to be a lot of apache sections. For debian, it might be worth modifying these for apache2, since that's what ships (e.g. /var/log/apache2). > ,---------------------------------[ /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. Well, what does the line "Option: fwstart" add to the description? I have a feeling these fwxxx options are themselves customizable somewhere. > > > 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 comment in the excerpt above says Debian's python-gamin doesn't work, but your remark after seems to indicate it will be used. What does this mean? Is the yoh comment wrong? Are the both true, so that if the module is available it will be used, but the results will be unexpected? > > > 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 -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
