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