INSTALL

   1 PRE-REQUISITES
   2
   3  BlockSSHD requires the following CPAN modules:
   4
   5  *) Sys::Syslog - often comes with Perl and may already be installed;
   6  *) Sys::Hostname - often comes with Perl and may already be installed;
   7  *) File::Tail;
   8  *) Tie::File;
   9  *) Net::DNS;
  10  *) Net::Subnets;
  11  *) Getopt::Long;
  12
  13  Please install them prior to running BlockSSHD.
  14
  15 INSTALLATION
  16
  17  1) BlockSSHD can work with iptables on Linux or pf on BSD. Depending on which
  18  you use you will need to add a new chain and/or rule to your iptables or pf
  19  firewall that directs incoming SSH connections to be blocked.
  20
  21  1.1) iptables
  22
  23  For iptables firewalls you can create a new chain like so:
  24
  25  $ iptables -N <chain>
  26
  27  Where <chain> is the same of the iptables chain specified in the configuration
  28  file.
  29
  30  Then you can create the re-direction rule like so:
  31
  32  $ iptables -I INPUT -p tcp -m tcp --dport 22 -j <chain>
  33
  34  If you wish to block FTP logins using ProFTPd then you can add port 21 to the
  35  above rule or add an additional rule.
  36
  37  This rule selects all incoming SSH connections on port 22 and redirects them
  38  to <chain>.  Your blocking rules will be placed in that chain and if the source
  39  IP address of an incoming connection matches a blocking rule in <chain> then
  40  the connection will be dropped.
  41
  42  The rule will need to be placed above any other incoming SSH rules to ensure
  43  all incoming SSH connections are jumped to the blocking chain.  If you use a
  44  distribution like Red Hat and Mandrake that has automated/GUI tools to contruct
  45  your iptables rule base you will need to add this rule using this mechanism.
  46
  47  In both example iptables commands replace <chain> with the name of the
  48  BlockSSHD chain.  The name of this chain also needs to be defined in the
  49  blocksshd.conf configuration file.  BlockSSHD also checks the presence of this
  50  chain each time it is started and will re-create it if it has been deleted.
  51
  52  All blocking rules in the chain will also be flushed each time BlockSSHD is
  53  started.
  54
  55  1.2) pf
  56
  57  For the pf firewall you will need to add a rule to block IP addresses listed
  58  in the target chain like so:
  59
  60  block in on $ext_if proto tcp from <blacklist_sshd> to me port { 21,22 }
  61
  62  The above rule blocks brute force login attacks on both port 21 and 22 and can
  63  prevent brute force attacks using both SSH and ProFTPd.
  64
  65  2) Install the configuration file into the /etc directory and the
  66  script to /usr/sbin (or similar directories in your environment -
  67  however you will need to adjust the script to reflect the new locations of
  68  these files)
  69
  70  This installation can be done using the following command:
  71
  72  # make install
  73
  74  To install a Red Hat-style init script into /etc/rc.d/init.d use:
  75
  76  # make init
  77
  78  3) Adjust the configuration file to suit your environment (see the
  79  CONFIGURATION section).
  80
  81  4) BlockSSHD also logs to syslog.  It uses a program name of blocksshd and a
  82  facility of auth.  You can use this combination to direct the syslog messages
  83  from BlockSSHD to a specific file or location.
  84
  85  5) You're done.
  86
  87 CONFIGURATION
  88
  89  All configuration is held in an external file, blocksshd.conf, this file is
  90  usually located in the /etc/ directory but this can be overridden in
  91  the script.
  92
  93  There are a number of configuration directives located in this file and these
  94  are listed below.
  95
  96  *) os - Specify the operating system BlockSSHd will run under.  Use linux for
  97     Linux and bsd for BSD
  98  *) pid_file - Location of the BlockSSHd PID file
  99  *) send_email - Enable the sending of email notifications
 100  *) email - Email address to send email notifications to
 101  *) chain - Name of the iptables table to hold the rules
 102  *) logfile - Log file to monitor for SSH login failure messages
 103  *) logcheck - Interval to check log file in seconds
 104  *) max_attempts - Maximum number of failures before blocking IP
 105  *) timeout - Time without activity after which IP counts are reset in seconds
 106  *) unblock - Enable unblocking functionality
 107  *) unblock_timeout - Period in seconds since blocking that an IP address is
 108     unblocked
 109  *) restore_blocked - Unable this option to log IP addresses and then re-block
 110     them when BlockSSHd is restarted
 111  *) log_ips - Location of the blocked IP address log file
 112  *) mail - Location of the mail binary used to send emails
 113  *) email_whois_lookup - Enable WHOIS lookup of the blocked IP address to be included in blocking notification
 114  *) whois - Location of the whois binary
 115  *) sed - Location of the sed binary
 116  *) iptables - Location of the iptables binary
 117  *) pfctl - Location of the pfctl binary
 118  *) whitelist - A list of IP addresses that you never want blocked