*** Two ways of installing sshdfilter ***

The first thing you need to do is decide on how to install sshdfilter. There are two install routes:
Route 1) As an sshd wrapper where system scripts run sshdfilter instead of sshd. sshdfilter then runs sshd with the -eD options, giving sshdfilter direct access to sshd messages.
Route 2) As a standalone program, reading sshd messages via syslog and a named pipe.

Route 1)
Pros:
1. Efficient 
2. Well tested 
3. Clean.

Cons:
1. Requires changing system startup scripts to run sshdfilter instead of sshd. Some people are nervous about that, especially when installing sshdfilter remotely.
2. sshd and sshdfilter are tied together, restarting sshdfilter has been known to kill all logged in sshd sessions.
3. A bug in sshd with the -eD options makes messages appear multiple times, usually in double. Setting the MaxChances options to exact requirements will need experimentation to make the block events match the policy you had in mind. The debug=1 option helps with this.


Route 2)
Pros:
Isolated from sshd, there is no process relationship between sshd and sshdfilter.
Cons:
Reading the system logs requires more overhead, syslog must log all authpriv (or auth, depending on your system) messages at least twice (to the standard log file and a fifo per sshdfilter), and sshdfilter must parse and identify sshd log messages from all the messages sent to the AUTHPRIV service.


*** General instructions ***

These install instruction start and end with the common elements of both routes.

_Install instructions for sshdfilter_


0. Beta quality install scripts have been written, they are: install_aswrapper.pl and install_standalone.pl.
They automate most of the tasks here, so are well worth trying. They do not attempt firewall configuration.

1. Create an initial configuration file, using the two supplied parts:
# cat etc/sshdfilterrc patterns/<your distro>.partconf > /etc/sshdfilterrc

etc/sshdfilterrc is a simple configuration file that contains some fairly strict defaults. These are similar to the same defaults used by sshdfilter 1.4 and earlier, except that an illegal user doesn't instantly lead to that IP being blocked. There is a selection of commented out examples of what can be done with sshdfilter policies. Namely white/black listed IPs, different numbers of password guesses and block times for different usernames, all specified by regular expressions.

patterns/<your distro>.partconf contains patterns that parse your sshd log messages. A few are supplied, and most distributions have been found to be based on these four. If yours isn't listed, you can look at your old sshd log messages and identify what patterns you need. Email me if you need help. The patterns match to:
 rh7390 - RedHat 7.3, RedHat 9.0, Fedora Core 2.0 or CentOS 4.3
 rhFC30 - RedHat Fedora Core 3.0, Fedora Core 4.0, Red Hat Enterprise Linux ES release 4, or CentOS 3.x
  deb31 - Debian 3.1 (sarge) or Debian (sid, but see README.debian)
su10rc1 - SuSe 10.0 RC 1, Gentoo and Slackware
  dbear - Dropbear, a light weight sshd daemon

ContOS 5 is not currently supported, sshd messages are spread across mutlitple lines so sshdfilter never sees complete reason+ip information per line. This should be fixed in the next version.

2. Edit /etc/sshdfilterrc to suit your needs. Each section deals with either general options to get sshdfilter working (the OPTIONS section and the SSHDLOGS section), or with policy decisions - to block or not block connections and how many chances to give the IP address before blocking that IP. It contains defaults that will problably work for your system but is well worth reading through. See the configuration file for details.


3.
Add the SSHD chain to your iptables firewall setup, typically (/etc/sysconfig/iptables style):
:SSHD - [0:0]
or bash:
$ iptables -N SSHD

Add a jump to SSHD rule with something like (/etc/sysconfig/iptables style):
-A INPUT -p tcp -m tcp --dport 22 -j SSHD
or bash:
$ iptables -I INPUT -p tcp -m tcp --dport 22 -j SSHD

This is only an example, I've no idea how you set up your iptables. Generally you'll have an existing line that ACCEPTS ssh(port 22), and the above should go on the line before. You can look at the current firewall setup with:
iptables -L -vn | less -S
We are only really interested in the INPUT table.

Read INSTALL.ipfw for instructions on installing sshdfilter with ipfw support.

4.
Exceptions to the sshdfilter blocking rules can be made with iptables or the white list in the configuration file. White lists will be useful if you have trusted IP addresses that will never attack your system. A typical example for the 192.168.0.0 network would be (sysconfig style):
-I INPUT -p tcp -m tcp -s 192.168.0.0/16 --dport 22 -j ACCEPT
or bash:
iptables -A INPUT -p tcp -m tcp -s 192.168.0.0/16 --dport 22 -j ACCEPT

5.
copy sshdfilter.pl to /usr/sbin/sshdfilter, or maybe /usr/local/sbin/sshdfilter with:
cp source/sshdfilter.pl /usr/sbin/sshdfilter

6.
Copy the man pages sshdfilter.1 and sshdfilterrc.5 to /usr/share/man/man{1,5} respectively.

7.
If you need to run multiple instances of sshdfilter, say on multiple ports, it 
might be necessary to use multiple sshdfilterrc config files. If the environment
variable SSHDFILTERRC exists, it is read at startup instead of /etc/sshdfilterc.

This means you can start sshdfilter with different options, such as the
port number to block, and have it block IPs independently from other sshdfilter instances. 
Note the jump-to-SSHD-chain rule will need to be duplicated for each port, if
required you can also use a different chain, such as SSHD24.

A line such as:
export SSHDFILTERRC=/etc/sshdfilterrc.p24
in the startup file will achieve this.


Route 1) Steps specific to installing sshdfilter as an sshd wrapper

8a.
Modify the startup script /etc/init.d/sshd to run sshdfilter instead of sshd, examples are in etc/init.d/. Basically, any reference to running the sshd executable should be replaced by sshdfilter.

8b.
Restart sshd via sshdfilter, normally with:
$ /etc/init.d/sshd restart
and check the process tree with:
$ pstree -pul | less -S
(or on some systems $ pstree -pula | less -Sr)
(use the cursor keys to move about, q quits)
This should show sshdfilter, with two children, sshdfilter and sshd. Now ssh logins will appear as children of this sshd - which is how sshd has always worked. Looking at your message logs will show sshdfilter has started.


Route 2) Steps specific to installing sshdfilter standalone.

8a. As root:
Create a named fifo for communication from syslog to sshdfilter:
# mkfifo /var/log/sshd.fifo
# chmod 600 /var/log/sshd.fifo

8b. Edit /etc/syslog.conf and add a line that says:
authpriv.*                                |/var/log/sshd.fifo
or
auth.*                                    |/var/log/sshd.fifo
or for OSX or BSD
auth.*                                    /var/log/sshd.fifo

Notice there is already an authpriv entry, syslog will write to both. If you are installing multiple sshdfilters, each sshdfilter will need its own fifo, fifos don't share their output between multiple readers.

You will need to change the logsource option, in the OPTIONS section of /etc/sshdfilterrc. It defaults to install route 1, for route 2 it should read:
logsource="/var/log/sshd.fifo"

8c. Create/copy+edit an sshdfilter startup file. etc/init.d/sshdfilter is a generic SysV startup files for various distributions:
# cp etc/init.d/sshdfilter /etc/init.d/sshdfilter
OSX uses a different startup method [awaiting details].

and then add it to the startup list with:
# chkconfig --add sshdfilter

If you don't have chkconfig, you can manually add a symbolic link with:
# cd /etc/rc<your run level>.d
# ln -s /etc/init.d/sshdfilter S97sshdfilter
where <your run level> is the number in the result of:
# grep :initdefault: /etc/inittab

If your system isn't SysV (some Slackware?), you can find where your sshd is run with:
# grep -r sshd /etc/rc.d
and place:
/usr/sbin/sshdfilter
after the reference to sshd.

8d.
Start sshdfilter, normally with:
$ /etc/init.d/sshdfilter start
and check the process tree with:
$ pstree -pul | less -S
(use the cursor keys to move about, q quits)
This should show sshdfilter with no children. Looking at your message logs will show sshdfilter has started.

*** Continuing generic install instructions ***

9.
 (!!! LogWatch script not yet written/updated for sshdfilter 1.5 !!!)
If your system uses LogWatch, you can find parsing scripts in etc/log.d/. Note t
hey are setup for a RedHat system that logs sshd (and so sshdfilter) output to /
var/log/secure, your distro probably sends the output to another file, such as /
var/log/auth.log for Debian. You need a recent (7.x) version of LogWatch to us
e these LogWatch scripts. sshd logging works as it used to, sshdfilter always lo
gs sshd output regardless of it triggering sshdfilter to do some action. The Log
Watch scripts consist of two files, you will also need to add 'sshdfilt' to /et
c/log.d/conf/services/secure.conf (or similar, try 'grep -r "sshd " /etc/log.d/conf' 
to find mentions of sshd, sshdfilt should be there too), to tell the other scripts 
about sshdfilter. The line in secure.conf is normally: 
$ignore_services = sshd Pluto stunnel proftpd saslauthd imapd
and needs to be:
$ignore_services = sshd sshdfilt Pluto stunnel proftpd saslauthd imapd
But what it needs to be for you depends on your distribution.

10.
Post Install:
Inform the users of what happens if they try too many password guesses, or type
their login name wrongly. 

For yourself, you could install webmin and webmin-iptables, for non-ssh remote access. So if you lock yourself out of your machine, you have another route in. Of course, this opens up another way into your system for others, so maybe you'd be better off running another sshd on an obscure port.

11.
Testing of sshdfilter can be done by ssh'ing from the same machine. Actually locking yourself out is not necessary but is possible, simply:
ssh somenoneexistantuser@localhost
should lead to sshdfilter messages in the logs stating an illegal user tried to login and how many chances they have before being blocked. Once that IP runs out of chances, an iptables DROP rule is added to the SSHD chain. If you have direct access to the machine, or have ssh'ed in from somewhere else, you will then be able to:
$ iptables -F SSHD
or restart sshdfilter (which will flush the chain and its state table).
Other block triggering commands to try are:
$ ssh existsinguser@localhost
and try this a few times with the wrong password, looking at the logs each time.
And:
$ telnet localhost 22
then press control and ], exit with q. This should trigger the 'No ssh id' message.


Last word.
Thats all, now you can enjoy a much better protected ssh and much less junk in your logs, making them readable again.

