===================
    SSHGUARD
===================

version: 0.91

See http://sshguard.sf.net for information about sshguard, including
technical documentation and licensing.


===================
    INSTALLING
===================

This is how to compile sshguard:

1.  get into the top directory of the source you unpacked from sshguard-ver.tbz

2.  determine what firewall backend you are going to use. There are 3 backends
    supported natively so far: iptables, pf and ipfw. This is the typical
    association with operating systems:

        OS                  FW backend
        ==                  ==========
        MacOS X             ipfw
        Linux               iptables
        OpenBSD             pf
        FreeBSD             pf or ipfw

    if your firewall backend does not appear in this list, please send a
    notification to sshguard-users@lists.sourceforge.net . It could be likely
    become supported with very few effort.

3.  run the following, which compiles sshguard:

        ./configure --with-firewall=__firewall_type_you_chose__
        make

    e.g., for Linux
        ./configure --with-firewall=iptables
        make

4.  run the following as root, which installs sshguard:

        make install

5? The following firewall backends NEED a couple of settings for enabling dynamic
    blocking rules: PF, iptables.

    ## iptables:    do the following as administrator user:
        I.  add a new chain named "sshguard" for holding dynamic rules:
                iptables -N sshguard
        II. pass all SSH traffic to that chain:
                iptables -A INPUT -p tcp --dport 22 -j sshguard

        done :)


    ## PF:          do the following as administrator user:
        I.  add a new table for holding bad guys' addresses; insert this high
            in pf.conf (typically /etc/pf.conf):
            
            table <sshguard> persist

        II. add a rule below that blocks traffic to SSH coming from bad guys:
            
            block in quick on $ext_if from <sshguard> label "ssh bruteforce"

            (if ext_if wasn't defined, replace it with the interface name from
            which SSH untrusted connections come)
        
        III.make PF load the new configuration; do the following as
            administrator user:

                pfctl -f /etc/pf.conf

6.  sshguard monitors SSH activity from the log entries it dumps. These can be
    passed by the system logger, or continuously fetched by the final logfile.

    ##  syslog
        I.  for making syslog feed SSH logs to sshguard edit syslog.conf
            (typically /etc/syslog.conf), and insert:

            auth.info;authpriv.info     |/usr/local/sbin/sshguard

            (if sshguard has been placed somewhere else, mind to adjust this path)
        II. make syslog reload its configuration file; as administrator, do

                killall -HUP syslogd
            

    ## syslog-ng
        I.  for making syslog-ng feed SSH logs to sshguard edit syslog-ng.conf
            (typically /etc/syslog-ng/syslog-ng.conf), and insert:

            filter sshlogs { facility(auth, authpriv) and match(ssh); };
            destination sshguardproc { program("/usr/local/sbin/sshguard"); };
            log { source(src); filter(sshlogs); destination(sshguardproc); };

        II. make syslog-ng reload its configuration file; as administrator, do
            
                killall -HUP syslog-ng

    ## from raw log file
        I.  make tail pass new entries to sshguard as soon as they appear in
            the log file. This is less elegant, but as tail uses kernel
            notification of updates, this takes a minimum to the system.

                tail -n0 -F /var/log/auth.log | /usr/local/sbin/sshguard

            (mind to replace the paths of the log file holding SSH log entries,
            or the path of the sshguard executable, if needed)

7.  for better efficacy, make sure SSH is logging addresses in the IP form and
    not the reverse-name form (PTR). In sshd_config (typically
    /etc/ssh/sshd_config) the following line should be enabled:

        UseDNS no

    if it wasn't enabled, remind to reload sshd (check the correctness of what
    you wrote before restarting, if you operate remotely):

        /usr/sbin/sshd -t
        killall -HUP sshd


This makes it. At the end of it, a process "sshguard" should be running in the
system as soon as the first SSH log entry appears (e.g., after an ssh login
attempt). When sshguard starts, it logs an entry like the following in authlog:

Feb  1 01:01:01 host sshguard[1234]: Started successfully [(a,p,s)=(4, 420, 1200)], now ready to scan.


===================
    DEINSTALL
===================

Just follow the install iter in the opposite versus. Remind to restart the syslog
process if used. Remind to remove the firewall rules/tables if used.