Deleted content line tracking and badness tracking.
[blocksshd_00z.git] / blocksshd.man
blob5f5e50c4db3547a74d426eeb1058f6c7a903cbaf
1 .TH BLOCKSSHD 1
2 .\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
3 .\" other parms are allowed: see man(7), man(1)
4 .rn SH Sh
5 .de SH
6 .br
7 .ne 11
8 .Sh "\\$1"
9 ..
10 .rn SS Ss
11 .de SS
12 .br
13 .ne 10
14 .Ss "\\$1"
16 .rn TP Tp
17 .de TP
18 .br 
19 .ne 9
20 .Tp \\$1
22 .rn RS Rs
23 .de RS
24 .na
25 .nf
26 .Rs
28 .rn RE Re
29 .de RE
30 .Re
31 .fi
32 .ad
34 .de Sx
35 .PP
36 .ne \\$1
37 .RS
39 .de Ex
40 .RE
41 .PP
43 .SH NAME
44 blocksshd \- Blocks brute force SSH attacks using iptables.
45 .SH SYNOPSIS
46 .B blocksshd
47 .I [\-d \-\-daemon \-\-start] [\-\-stop] [\-h \-\-help] [\-v \-\-version]
48 .SH "DESCRIPTION"
49 This manual page documents the
50 .BR Blocksshd
51 script.
52 .PP
53 .B Blocksshd
54 is a Perl script based on BruteForceBlocker v1.2.3 that dynamically adds IPTables rules for Linux and pf firewall rules for BSD that block SSH brute force attacks. It can also detect ProFTPd login failures.
55 BlockSSHD checks a log file you specify, for example /var/log/secure on a Red 
56 Hat, for SSH login failure messages.  If it detects a failure message it 
57 records the source IP address and starts a counter.  If messages continue to be
58 detected from the same source IP address the counter is incremented for each 
59 message.  When the counter reaches a user-specified threshold then the script
60 will add a firewall rule blocking SSH connections from that source IP address.
61 A user-specified time-out is also defined to trigger a reset of the counter. If
62 the counter is incremented but has not yet reached the blocking threshold and a
63 new login failure message arrives then BlockSSHD checks the time-out.  If the 
64 last increment of the counter occurred earlier than the current time minus the 
65 time-out period then the counter is reset rather than incremented.  The time-out
66 defaults to 600 seconds (10 minutes).
68 The BlockSSHD script can also unblock IP address after a period.  This is 
69 enabled in the blocksshd.conf configuration file using the unblock option and 
70 with the period set using the unblock_timeout option.
72 The BlockSSHD script can also log the IP addresses blocked to a file and 
73 re-apply these blocked IP addresses when the script is re-started.  This allows
74 you to restore previously blocked IP addresses after a restart or when your 
75 firewall rules are flushed.  If you have the unblock function and the re-block
76 function enabled then when the IP address is unblocked it will also be removed
77 from the log file.
79 .SH PRE-REQUISITES
81 BlockSSHD requires the following CPAN modules:
83 .br
84 *) Sys::Syslog - often comes with Perl and may already be installed;
85 .br
86 *) Sys::Hostname - often comes with Perl and may already be installed;
87 .br
88 *) File::Tail;
89 .br
90 *) Net::DNS;
91 .br
92 *) Proc::Daemon;
93 .br
94 *) Proc::PID::File;
95 .br
96 *) Getopt::Long;
98 Please install them prior to running BlockSSHD.
100 .SH OPTIONS
102 .B \-d, \-\-daemon, \-\-start 
103 .IP "Start BlockSSHD in daemon mode"
105 .B \-\-stop 
106 .IP "Stop BlockSSHD"
108 .B \-h, \-\-help 
109 .IP "Print help text"
111 .B \-v, \-\-version
112 .IP "Print the version number"
113 .SH EXAMPLES
114 Start BlockSSHD
115 .Sx 3
116 blocksshd --start
118 Stop BlockSSHD
119 .Sx 3
120 blocksshd --stop
122 .SH Configuration File
123 There a number of configuration directives located in this file and these are listed below.  
125 .br 
126 *) os - Specify the operating system BlockSSHd will run under.  Use linux for Linux and bsd for BSD
128 *) pid_file - Location of the BlockSSHd PID file
130 *) send_email - Enable the sending of email notifications 
132 *) email - Email address to send email notifications to
134 *) chain - Name of the iptables chain to hold the rules
136 *) logfile - Log file to monitor for SSH login failure messages
138 *) logcheck - Interval to check log file in seconds
140 *) max_attempts - Maximum number of failures before blocking IP
142 *) timeout - Time without activity after which IP counts are reset in seconds
144 *) unblock - Enable unblocking functionality
146 *) unblock_timeout - Period in seconds since blocking that an IP address is unblocked 
148 *) restore_blocked - Unable this option to log IP addresses and then re-block them when BlockSSHd is restarted
150 *) log_ips - Location of the blocked IP address log file
152 *) mail - Location of the mail binary used to send emails
154 *) email_whois_lookup - Enable WHOIS lookup of the blocked IP address to be included in blocking notification
156 *) whois - Location of the whois binary
158 *) sed - Location of the sed binary
160 *) iptables - Location of the iptables binary
162 *) pfctl - Location of the pfctl binary
164 *) whitelist - A list of IP addresses that you never want blocked
165 .SH AUTHORS
166 This manual page was written by James Turnbull <james@lovedthanlost.net>