blocksshd.man

   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"
  15 ..
  16 .rn TP Tp
  17 .de TP
  18 .br
  19 .ne 9
  20 .Tp \\$1
  21 ..
  22 .rn RS Rs
  23 .de RS
  24 .na
  25 .nf
  26 .Rs
  27 ..
  28 .rn RE Re
  29 .de RE
  30 .Re
  31 .fi
  32 .ad
  33 ..
  34 .de Sx
  35 .PP
  36 .ne \\$1
  37 .RS
  38 ..
  39 .de Ex
  40 .RE
  41 .PP
  42 ..
  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).
  67
  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.
  71
  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.
  78
  79 .SH PRE-REQUISITES
  80
  81 BlockSSHD requires the following CPAN modules:
  82
  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;
  97
  98 Please install them prior to running BlockSSHD.
  99
 100 .SH OPTIONS
 101 .TP
 102 .B \-d, \-\-daemon, \-\-start
 103 .IP "Start BlockSSHD in daemon mode"
 104 .TP
 105 .B \-\-stop
 106 .IP "Stop BlockSSHD"
 107 .TP
 108 .B \-h, \-\-help
 109 .IP "Print help text"
 110 .TP
 111 .B \-v, \-\-version
 112 .IP "Print the version number"
 113 .SH EXAMPLES
 114 Start BlockSSHD
 115 .Sx 3
 116 blocksshd --start
 117 .Ex
 118 Stop BlockSSHD
 119 .Sx 3
 120 blocksshd --stop
 121 .Ex
 122 .SH Configuration File
 123 There a number of configuration directives located in this file and these are listed below.
 124
 125 .br
 126 *) os - Specify the operating system BlockSSHd will run under.  Use linux for Linux and bsd for BSD
 127 .br
 128 *) pid_file - Location of the BlockSSHd PID file
 129 .br
 130 *) send_email - Enable the sending of email notifications
 131 .br
 132 *) email - Email address to send email notifications to
 133 .br
 134 *) chain - Name of the iptables chain to hold the rules
 135 .br
 136 *) logfile - Log file to monitor for SSH login failure messages
 137 .br
 138 *) logcheck - Interval to check log file in seconds
 139 .br
 140 *) max_attempts - Maximum number of failures before blocking IP
 141 .br
 142 *) timeout - Time without activity after which IP counts are reset in seconds
 143 .br
 144 *) unblock - Enable unblocking functionality
 145 .br
 146 *) unblock_timeout - Period in seconds since blocking that an IP address is unblocked
 147 .br
 148 *) restore_blocked - Unable this option to log IP addresses and then re-block them when BlockSSHd is restarted
 149 .br
 150 *) log_ips - Location of the blocked IP address log file
 151 .br
 152 *) mail - Location of the mail binary used to send emails
 153 .br
 154 *) email_whois_lookup - Enable WHOIS lookup of the blocked IP address to be included in blocking notification
 155 .br
 156 *) whois - Location of the whois binary
 157 .br
 158 *) sed - Location of the sed binary
 159 .br
 160 *) iptables - Location of the iptables binary
 161 .br
 162 *) pfctl - Location of the pfctl binary
 163 .br
 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>
 167