Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  SSHGUARD (8)


sshguard - block brute-force attacks by aggregating system logs \$1 \n[an-margin] level \n[rst2man-indent-level] level margin: \n[rst2man-indent\n[rst2man-indent-level]] - \n[rst2man-indent0] \n[rst2man-indent1] \n[rst2man-indent2]


External Programs
Log Validation
See Also


sshguard [-v] [-a thresh] [-b thresh:file] [-e script] [-f service:pidfile] [-l source] [-p interval] [-s interval] [-w address | file]


sshguard protects hosts from brute-force attacks against SSH and other services. It aggregates system logs and blocks repeat offenders using one of several firewall backends, including iptables, ipfw, and pf.

sshguard can read log messages from standard input (suitable for piping from syslog) or monitor one or more log files. Log messages are parsed, line-by-line, for recognized patterns. If an attack, such as several login failures within a few seconds, is detected, the offending IP is blocked. Offenders are unblocked after a set interval, but can be semi-permanently banned using the blacklist option.

See for setup instructions.

Other features, attack signatures, and additional documentation can be found at


-a thresh (default 40)
  Block an attacker when its dangerousness exceeds thresh. Each attack pattern that is matched contributes a fixed dangerousness of 10.
-b thresh:file
  Blacklist an attacker when its dangerousness exceeds thresh. Blacklisted addresses are added to file so they can be read at the next startup. Blacklisted addresses are never automatically unblocked, but it is good practice to periodically clean out stale blacklist entries.
-e script
  Execute an external program when an event is triggered. See EXTERNAL PROGRAMS below.
-f service:pidfile
-l source
  Monitor source for log messages. By default, sshguard reads log messages from standard input. Give this option once for every source to monitor instead. sshguard transparently handles log rotations. When using this option, standard input is ignored, but can be re-added by giving \(aq-l -\(aq.
-p interval (default 420 secs, or 7 minutes)
  Wait at least interval seconds before releasing a blocked address. Repeat attackers are blocked for 1.5 times longer after each attack. Because sshguard unblocks attackers only at infrequent intervals, this parameter is inexact (actual blocks will be longer).
-s interval (default 1200 secs, or 20 minutes)
  Forget about an attacker interval seconds after its last attempt. Its dangerousness will be reset to zero.
-w address | file
  Whitelist the given address, hostname, or address block. Alternatively, read whitelist entires from file. This option can be given multiple times. See WHITELISTING below for details.
-v Print version information and exit.


  Enable additional debugging information.


sshguard can be instructed to execute an external program whenever an event relevant to the firewall is triggered.

The logic and capabilities of external programs are similar to those of a database trigger. When an event is triggered, the external program can:
o add behavior to the firewall action (e.g. custom notifications)
o change behavior of the firewall action (e.g. block different address)
o cancel the firewall action (e.g. custom whitelisting)

External programs are run on all firewall events. Every external program has these responsibilities:
o to define the behavior associated with every event (action), and especially to not behave on events of disinterest.
o to run the final firewall intended firewall action (or not).
o to exit with a relevant status for success (0) or failure (non-0).

The action that the external process is called to carry out determines the information passed to it. All information passed from sshguard to external programs is via environment variables:
  (all actions) The name of the trigger event: one value amongst:
o init
o fin
o block (*)
o block_list (*)
o release (*)
o flush
  (all actions) The PID of the sshguard process running the program.
  (all actions) The firewall command that sshguard intended to run if no extra program were given. The external program shall run this within a shell.
  (marked actions) The address, or the comma-separated list of addresses, to operate.
  (marked actions) The type of the address(es) to operate: \(aq4\(aq for IPv4, \(aq6\(aq for IPv6.
  (marked actions) The service target of the event, expressed as service code. See


sshguard supports address whitelisting. Whitelisted addresses are not blocked even if they appear to generate attacks. This is useful for protecting lame LAN users (or external friendly users) from being incidentally blocked.

Whitelist addresses are controlled through the -w command-line option. This option can add explicit addresses, host names and address blocks:
  specify the numeric IPv4 or IPv6 address directly, like:


or in multiple occurrences:

-w -w 2001:0db8:85a3:0000:0000:8a2e:0370:7334

host names
  specify the host name directly, like:


or in multiple occurrences:

-w -w

All IPv4 and IPv6 addresses that the host resolves to are whitelisted. Hosts are resolved to addresses once, when sshguard starts up.
address blocks
  specify the IPv4 or IPv6 address block in the usual CIDR notation:

-w 2002:836b:4179::836b:0000/126

or in multiple occurrences:

-w -w

file When longer lists are needed for whitelisting, they can be wrapped into a plain text file, one address/hostname/block per line, with the same syntax given above.

sshguard can take whitelists from files when the -w option argument begins with a \(aq.\(aq (dot) or \(aq/\(aq (slash).

This is a sample whitelist file (say /etc/friends):

# comment line (a \(aq#\(aq as very first character)
#   a single IPv4 and IPv6 address
#   address blocks in CIDR notation
#   hostnames

And this is how sshguard is told to make a whitelist up from the /etc/friends file:

sshguard -w /etc/friends

The -w option can be used only once for files. For addresses, host names and address blocks it can be used with any multiplicity, even with mixes of them.


Syslog and syslog-ng typically insert a PID of the generating process in every log message. This can be checked for authenticating the source of the message and avoid false attacks to be detected because malicious local users inject crafted log messages. This way sshguard can be safely used even on hosts where this assumption does not hold.

Log validation is only needed when sshguard is fed log messages from syslog or from syslog-ng. When a process logs directly to a raw file and sshguard is configured for polling logs directly from it, you only need to adjust the log file permissions so that only root can write on it.

For enabling log validation on a given service the -f option is used as follows:

-f 100:/var/run/

which associates the given pidfile to the ssh service (code 100). A list of well-known service codes is available at

The -f option can be used multiple times for associating different services with their pidfile:

sshguard -f 100:/var/run/ -f 123:/var/run/

Services that are not configured for log validation follow a default-allow policy (all of their log messages are accepted by default).

PIDs are checked with the following policy:
1. the logging service is searched in the list of services configured for validation. If not found, the entry is accepted.
2. the logged PID is compared with the pidfile. If it matches, the entry is accepted
3. the PID is checked for being a direct child of the authoritative process. If it is, the entry is accepted.
4. the entry is ignored.

Low I/O load is committed to the operating system because of an internal caching mechanism. Changes in the pidfile value are handled transparently.


syslog(1), syslog.conf(5), hosts_access(5)




Michele Mazzucchi <>, Kevin Zheng <>

Search for    or go to Top of page |  Section 8 |  Main Index

1.6.3 SSHGUARD (8) December 11, 2015

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.