The short version is: it receives log messages, it detects when a networked service has been abused based on them, and blocks the address of who abused it; after some time, it releases the blocking.

The full version is: sshguard runs on a machine as a small daemon, and receives log messages (in a number of ways, e.g. from syslog). When it determines that address X did something bad to service Y, it fires a rule in the machine's firewall (one of the many supported) for blocking X.

Sshguard keeps X blocked for some time, then releases it automatically.

You kiddin'? :)

Several people wrote and released some scripts for blocking brute force attacks against SSH. Sshguard was started to have something closer to the traditional UNIX daemon: a small application written in C. As a collateral service, it is appealing to have something running standalone, consuming as little memory and computational resources as possible, and not sensitive to the dependencies and the versioning incompatibilities of script interpreters.

Sshguard was then progressively extended with more features. Today, some additional differentials from other tools include log validation, sophisticated whitelisting, touchiness, and automatic blacklisting.

On the top of this, sshguard strives for ease of use and quality of documentation, and the team tries to be as responsive as possible to users.

No. With these systems, you open up your firewall for control by the public. Collaborative blocking works when it can be assumed that no malicious collaborators exist.

Yes. The 'hosts' backend ('sshg-fw-hosts') adds TCP Wrapper rules to /etc/hosts.allow.

Yes. FreeBSD jails are particular because "root" access to them is a phony administrator to the host system, and thus cannot tweak the host's kernel knobs, including the firewall. Still, SSHGuard works fine inside a jail, see the SSHGuard without firewall FAQ. If you control the host system as well, you can run a single SSHGuard from it and let it monitor the log files of all jails. SSHGuard will monitor the activity of the jails, but operate the firewall from the host.

Firewalls such as PF or Netfilter, today, are very powerful. Some enthusiastic people believe that they can be effectively used in place of sshguard in stopping attacks. The solutions advocated are typically based on throttling handshakes to certain services, or limiting the rate of connections that the same address can generate to a service. These solutions are both insufficient and harmful. They are insufficient because attackers are home free as long as they keep attacks just above the minimal rate enforced by the firewall; logs keep spoiled with huge volumes of irrelevant entries; no backlog is available for responding to exceptionally insisting attackers. They are harmful because they degrade the quality of service for legitimate users, who have to withstand the same restrictive policies meant to thwart attackers. For example, performing many frequent SSH connections is common when using SSH as a tunnel for transferring or synchronizing files, and the hiccup is even bigger with services like imap or http, where multiple parallel connections are ordinary. Sshguard wants to stop attacks securely, while being transparent to legitimate users.

Imagine you forget your email password, would you like to be cut out from your mail server permanently?

Imagine you're connected in a network with dynamic IP addressing. If one user abuses a server now, and this afternoon you're assigned his IP address. Would you like to be prevented accessing the server for his fault?

We observed many people set the pardon time option to huge values to mimic blacklisting at first sight. Consider carefully what you're doing there.

Sshguard already does what we believe is the right way to tackle what you want, with touchiness. Attackers are blocked for exponentially longer times (eg 10, 20, 40, 80, ... minutes) when they insist on a host. You can enable automatic blacklisting: after a number of attacks, an address will be automatically stored in a blacklist and never released anymore. Combined with touchiness, this guarantees more stability. Still, use wisely.

Sshguard runs on many Operating Systems, so it's not possible to answer clean in one shot. In general, a script going like the following will work:

#! /bin/sh
# this is a concept, elaborate to your taste
case $1 in
start)
    /usr/local/sbin/sshguard -l /var/log/auth.log &
    ;;
stop)
    killall sshguard
    ;;
*)
    echo "Use start or stop"
    exit 1
    ;;
esac

Under Linux, you want to place this in /etc/init.d/sshguard (and then link it to /etc/rc*.d/ as appropriate depending on your distribution); you won't need start/killdaemon() machinery, as you'll ever run one instance of sshguard at a time and there's no reloads. Under BSD, you put it under /usr/local/etc/rc.d/sshguard (FreeBSD) or /etc/rc.d (OpenBSD) for the RC bootstrap system; you won't need dependency definitions as sshguard has no dependencies. If any maintainer will provide boot scripts I'll be happy to review them and publish on the website.

You have one of these problems:

• sshguard is not given logs correctly
• sshguard cannot run the commands for blocking

Let's debug. How do you pass logs to sshguard?

• syslog: kill all sshguard instances on your system (killall sshguard), then try to make sshd log something (e.g. try a login via ssh) and check if syslog has raised a new instance for it. If no new instance appears you have misconfigured syslog.
• tail: check that the log file you're polling from is receiving sshd log entries.

Next, go on with the firewall. Check the paths first: where is iptables, or pfctl, or ipfw? You may need to specify their path explicitly from ./configure if they are not in standard paths nor in system's PATH. Then, are you running sshguard with sufficient credentials to change firewall rules? Administrator permissions are typically needed.

Sshguard debug messages are very useful for understanding problems. See later in this FAQ for how to access them.

If you seek deeper tweaking, be inspired by this thread recounting a debug session.

You don't. Sshguard enables monitoring for all supported services straight out of the box.

If you think attacks for some supported services are not blocked, make sure sshguard is actually being given their log messages (tee is your friend).

In versions ≥ 1.4, sshguard offers an interactive mode for convenient inspection of what can be going wrong on a system. To enable this mode, set the SSHGUARD_DEBUG environment variable, e.g.:

env SSHGUARD_DEBUG=foo /usr/local/sbin/sshguard

Paste any valid attack message (such as "Invalid user foo from 1.3.4.8") on its console, and hit enter. Sshguard will parse any string issued, and print to the console a message such as "Matched address 1.2.3.4:4 attacking service 100, dangerousness 10." confirming recognition — or nothing otherwise. When the pattern is pasted enough times, sshguard will attempt to block the attacker, and print a message like "First abuse of '1.3.4.8', adding to offenders list." followed by the (blocking backend-dependant) details of the process. When the pardon time elapses, release details are similarly printed.

Support for IP Filter is included since version 1.1.

In recent versions, you need to enable richer logging from sshd for SSHGuard to have enough evidence to spot attackers: in /etc/ssh/sshd_config change the log level setting to LogLevel verbose, and restart sshd. This setting is still largely suitable for production use.