blockhosts.py           http://www.aczoom.com/cms/blockhosts

INSTALLATION
------------

Requirement:
    Python 2.3 or later.
    Will not work with older versions of python, this script uses
    datetime and optparse modules, and also uses the extended print
    statement print >> first seen in python 2.0.

--------------- RPM package install/upgrade/erase --------------------
(using example release 1.0.0-1, change as required):
----------------------------------------------------
For Version 1.0.0, here's what may be installed:
    /etc/blockhosts.cfg
    /usr/bin/blockhosts.py
    /usr/share/doc/BlockHosts-1.0.0/CHANGES
    /usr/share/doc/BlockHosts-1.0.0/INSTALL
    /usr/share/doc/BlockHosts-1.0.0/README
    /usr/share/doc/BlockHosts-1.0.0/blockhosts.html


Install:
    rpm -iv BlockHosts-1.0.0-1.noarch.rpm

Upgrade:
    NOTE: save a copy of /etc/blockhosts.cfg if it was modified, and then
    merge in your changes back after the upgrade.

    rpm -Uv BlockHosts-1.0.0-1.noarch.rpm

Uninstall/Erase:
    rpm -e BlockHosts-1.0.0-1

Check what version is installed, and what files:
    rpm -q BlockHosts
    rpm -ql BlockHosts

----------------------- non-RPM install/upgrade ----------------------
Extract the source package into a local directory, and then follow the
upgrade or install instructions below to install the script and config
file - note that this procedure does not copy over the doc files.

Upgrade:
---------
  If you have an older version, but have not modified any blockhosts files
  locally (such as /etc/blockhosts.cfg), then use this command:

    python setup.py install --force

  If you have locally modified the /etc/blockhosts.cfg file, save a copy,
  run the above command, and then merge your changes into the local file.
  To install without overwriting your local file (this may cause problems
  if the .cfg file format or data fields have changed), run:
    python setup.py install

Fresh install:
-------------

    python setup.py install --force

To see what will be installed without actually installing files, run:

    python setup.py --dry-run install --force


----------------------- First Run ---------------------------------------

After the configuration is as you want it (see next section for
Configuration), then run this program manually, usually as root:
    blockhosts.py --verbose
(use --dry-run if you don't want any output file to be updated).

The first run will scan through the entire system logs, so it will add a
number of hosts to the block list. 

If you run blockhosts.py immediately again, it will most likely report no
updates to the blocked hosts list.

The large number of hosts added will be removed after the "discard"
interval.  By default, this is 12 hours, and from then on,
blockhosts.py will keep track of the new lines seen in the system logs,
and will only add new hosts that are attacking sshd/proftpd.

[The reason a large number of hosts are added on the first run is due to
the way blockhosts.py assigns "time last seen" to each host - to keep
things simple, blockhosts.py does not look at the system log times, but
just uses the current date/time when blockhosts.py was run. This is good
enough for the purpose of determining which host to block.]


----------------------------- Configuration ---------------------------

/etc/blockhost.cfg:
  If needed - edit this file, and change any parameter as required
  for your platform. Note that most changes can be specified on the
  command line, so there may not be any need to edit this file - it
  requires great care to edit this file, see the comments in that file.
  The defaults work for Fedora FC3 platform, using OpenSSH and ProFTPD.
  The LOGFILES line is probably the most important one - names of system
  logs where sshd and proftpd write information may be different on your
  system  from the defaults.

/etc/hosts.allow (or /etc/hosts.deny) - the block file
  Add following sections, in this order:
  -- your permanent whitelist and blacklist of IP addresses
  -- blockhosts marker lines - two lines
  -- execute command to kick off blockhosts.py on connects to services

Example below, you can copy the following lines in entirety to your
/etc/hosts.allow, and edit as needed.
Example applies to either hosts.allow or hosts.deny, best to use a single
file - hosts.allow, and ignore the other file entirely:

# ----
# see "man 5 hosts_access" for details of the format of IP addresses,
#services, allow/deny options. Also see "man hosts_options"
#order of lines in this file is important, first matched IP address line
#is rule applied by hosts_access
#
# permanent whitelist addresses - these should always be allowed access

ALL: 127.0.0.1  : allow
ALL: 192.168.0. : allow

# permanent blacklist addresses - these should always be denied access

ALL: 10.  : deny
ALL: 192. : deny
ALL: 172. : deny

# ----------------------------------------
# next section is the blockhosts section - it will add/delete entries in
# between the two marker lines (#---- BlockHosts Additions)

#---- BlockHosts Additions
#---- BlockHosts Additions

# ----------------------------------------
# finally, the command to execute the blockhosts script, based on
# connection to particular service or services, for example, here's what
# I use:

sshd, proftpd, in.proftpd: ALL: spawn (/usr/bin/blockhosts.py --verbose --echo "%c-%s" >> /var/log/blockhosts.log 2>&1 )& : allow

# --
# See "man hosts.allow" for info on %c and %s identifiers
#----
# for non-verbose, with identification, to syslog only:
#sshd, proftpd, in.proftpd: ALL: spawn /usr/bin/blockhosts.py --echo "%c-%s" & : allow
#----
# minimal logging, to syslog:
#sshd, proftpd, in.proftpd: ALL: spawn /usr/bin/blockhosts.py & : allow
#----
# To test hosts.allow, and to find out exact names of SSH/FTP services,
# add this line to the beginning of hosts.allow, use ssh/ftp to connect
# to your server, and then look at the log (/var/log/messages or
# blockhosts.log) to see the name of the invoked service.
# IMPORTANT: after your test is done, remove this line from hosts.allow!
# Otherwise everyone will always have access.
#ALL : ALL: spawn (/usr/bin/blockhosts.py --verbose --echo "%c-%s" >> /var/log/blockhosts.log 2>&1 )& : allow
# -------------------------------------------------------------------------
