]> git.wincent.com - bansshee.git/blob - README
Initial import
[bansshee.git] / README
1 $Id$
2
3 CONTENTS
4
5   * Overview
6   * Donations
7   * Requirements
8   * Configuration
9   * Starting Bansshee
10   * Stopping Bansshee
11   * Bansshee Website
12   * Obtaining Bansshee
13   * Contributing Code
14   * Author
15
16
17 OVERVIEW
18
19 Bansshee is a Perl script that runs as a daemon watching for SSH dictionary attacks. On detecting an attack it uses the firewall to temporarily prevent further access attempts. Many aspects of Bansshee are configurable, including the number of failed access attempts that may be generated by a given IP before they are considered an attack, how long an IP will remain on the blocklist before being removed and what the grace period should be between attempts before the internal counters are reset.
20
21
22 DONATIONS
23
24 Bansshee is provided free of charge under the GPL (see the LICENSE file for details) so it is both free "as in beer" and free "libre". Although it is free you can encourage further development by making a donation and you are encouraged to do so if you find it to be useful. Donations can be sent via PayPal to author at win@wincent.org or via the website:
25
26   http://bansshee.org/donate/
27
28
29 REQUIREMENTS
30
31 Perl
32 ====
33
34 Bansshee requires a recent version of Perl compiled with multithreading support. Specifically it requires the newer "ithreads" (interpreter threads) implementation available in Perl 5.6.0 and later. This version of Bansshee was built and tested using Perl v5.8.0 (built for "i386-linux-thread-multi"). You can check the version of Perl installed on your system and whether it supports multi-threading by passing the -v or -V switch to Perl on the command line (more information on this below).
35
36 Perl modules
37 ============
38
39 Bansshee relies on a number of Perl modules. More information about any of the modules can be found by going to http://search.cpan.org/ and performing a search for the module name. You can determine if a module is present on your system by using Perl's "-c" command line switch to check the syntax of the "bansshee" script; it will report any required modules missing from your system:
40
41   perl -c bansshee
42
43 To install any missing modules you can use Perl's CPAN module. For example, to install the "File::Tail" module you could use:
44
45   sudo perl -MCPAN -e 'install File::Tail'
46
47 Here follows a list of the modules used by Bansshee:
48
49 * threads
50
51 Bansshee is written to use the newer "ithreads" (interpreter threads) model introduced in Perl 5.6.0. To confirm that your version of Perl is compatible examine the output of "perl -V" and look for the following:
52
53   usethreads=define use5005threads=undef useithreads=define
54
55 Note that "use5005threads" (the old thread model) is set to "undef" and the new thread implementation ("useithreads") is set to "define".
56
57 * Sys::Syslog
58
59 A Perl interface to the UNIX syslog(3) calls. To my knowledge this module is included with the Perl base install.
60
61 * sigtrap
62
63 A Perl pragma to enable simple signal handling. Again I believe this is included with the Perl base install.
64
65 * Proc::Daemon
66
67 A module for running a Perl program as a daemon (background) process.
68
69 * File::Tail
70
71 A Perl extension for efficiently reading from continously updated files.
72
73 iptables
74 ========
75
76 Bansshee uses the iptables administration tool to control the tables of the IP packet filter rules in the kernel.
77
78 General
79 =======
80
81 Bansshee must be run with root privileges so as to be able to make modifications to the firewall using iptables, and also to monitor the log file (which may be owned by root and not world-readable).
82
83
84 CONFIGURATION
85
86 Bansshee has a number of customizable settings that can be used to modify its behaviour. The settings appear near the top of the "bansshee" script itself under the 
87 heading "Default Settings". You may either edit the settings directly in the file itself, or place your customized settings in the "/etc/bansshee.conf" file. Settings in 
88 the conf file will override settings in the script. By using the conf file you can upgrade the Bansshee script without having to re-apply your customizations to the 
89 script each time.
90
91 * permitted_illegal_user
92
93 This is the number of attempts to log in using an illegal (unknown) username that will be permitted from a single IP address before that IP address gets blocked. Defaults to 5 attempts.
94
95 * permitted_incorrect_pass
96
97 This is the number of attempts to log in using a legal (known) username but supplying an invalid password that will be permitted from a single IP address before that IP address gets blocked. Defaults to 5 attempts.
98
99 * unban_wait
100
101 This is the minimum number of seconds that a blocked IP address must wait before it gets automatically removed from the blocklist. Defaults to 3600 seconds (1 hour).
102
103 * grace_period
104
105 This is the number of seconds that must pass before prior illegal user or incorrect password attempts from a given IP address are disregarded. Defaults to 3600 seconds (1 hour).
106
107 * unblocking_interval
108
109 This is the number of seconds that Bansshee waits before checking the blocklist and removing any IP addresses which have been in the blocklist for more than "unban_wait" seconds. Defaults to 300 (5 minutes).
110
111
112 STARTING BANSSHEE
113
114 For information on installing Bansshee see the INSTALL file.
115
116 For automatic startup at boot time see the platform-specific files in the support directory. If Bansshee has been set up to 
117 start automatically at boot time then it should always be started (and stopped) using the same control script. For example, 
118 on Red Had Enterprise Linux the following command would be used:
119
120   sudo service bansshee start
121
122 For manual startup, working from the directory containing the bansshee script:
123
124   sudo ./bansshee
125
126
127 STOPPING BANSSHEE
128
129 To manually stop Bansshee find its PID and kill it. For example, on a system like Red Hat Enterprise Linux which comes with a "pidof" command the following command can be used to stop Bansshee:
130
131   sudo kill $(pidof -x bansshee)
132
133 Bansshee will catch the kill signal, perform clean-up and then exit.
134
135 If Bansshee has been set up to start automatically at boot time then it should be stopped using the same control script that was used to start it. For example, on Red Hat Enterprise Linux the following command would be used:
136
137   sudo service bansshee stop
138
139 Unlike some other anti-dictionary attack tools currently available, Bansshee makes no attempt to save its state between sessions. This is because most attacks are transitory in nature anyway (the attacker tries and then moves on) and there is little benefit to trying to maintain state information between sessions. As a result the Bansshee code base is cleaner and less likely to contain bugs. It sets up its own IP tables rules on launch and cleans up after itself on exit. The need for a persistent store is also minimized by the fact that Bansshee is solid and stable enough to run for long periods without being restarted. At the time of writing my current Bansshee install has been up and running without interruption for an entire month without any problems.
140
141
142 BANSSHEE WEBSITE
143
144   http://bansshee.org/
145   http://wincent.com/a/products/bansshee/
146
147
148 OBTAINING BANSSHEE
149
150 The latest released version of Bansshee can be downloaded from the website (link appears above).
151
152 The latest development version of Bansshee can be checked out via Subversion:
153
154   svn co svn://svn.wincent.com/bansshee/trunk
155
156 To check out a specific version, use the appropriate tag:
157
158   svn co svn://svn.wincent.com/bansshee/tags/1.0-RELEASE
159
160 Example tags: 1.0-RELEASE
161
162 To check out the latest release in a specific branch, specify the branch:
163
164   svn co svn://svn.wincent.com/bansshee/branches/1.0
165
166 Example branches: 1.0
167
168 Note that at the time of writing there are no special branches; all development occurs on the main trunk.
169
170 To update an existing working copy:
171
172   svn up
173
174 For more information on using Subversion please see the official Subversion website:
175
176   http://subversion.tigris.org/
177
178 Or the Subversion book:
179
180   http://svnbook.red-bean.com/
181
182
183 CONTRIBUTING CODE
184
185 To submit changes against a copy of Bansshee checked out using Subversion (see OBTAINING BANSSHEE) simply perform an "svn 
186 diff" in your working copy and send your diff to the author (contact details below).
187
188
189 AUTHOR
190
191 Bansshee is written and maintained by Wincent Colaiuta. Wincent's company website is:
192
193   http://wincent.com/ 
194
195 His personal weblog can be found at:
196
197   http://colaiuta.net/
198