.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$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]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "SSHGUARD-SETUP" "7" "January 1, 2025" "2.5.1" "SSHGuard Manual"
.SH NAME
sshguard-setup \- setting up SSHGuard on your system
.SH DESCRIPTION
.sp
To set up SSHGuard, write \fIsshguard.conf\fP and set up the backend, if
necessary. Configuration options are documented in the sample configuration
file. A good starting point is to copy it and make the necessary changes:
.INDENT 0.0
.IP 1. 3
Set \fBBACKEND\fP\&. You may also need to set it up to work with SSHGuard
(see BACKENDS).
.IP 2. 3
Set \fBFILES\fP, \fBLOGREADER\fP, or both. Alternatively, give \fBsshguard\fP a
list of files to monitor as positional arguments on the command\-line.
.UNINDENT
.sp
Use \fBFILES\fP to specify a space\-separated list of log files to monitor.
Use \fBLOGREADER\fP to specify a shell command to run to obtain logs. Both
settings are ignored if files are given on the command\-line.
.sp
Sample \fBLOGREADER\fP commands for \fBjournalctl(1)\fP and macOS 10.12+ are
available in the sample configuration.
.SH OTHER LOGS
.SS syslog\-ng
.sp
For \fBsyslog\-ng 2.x\fP, add the following lines to \fIsyslog\-ng.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# pass only entries with auth+authpriv facilities from programs other than sshguard
filter sshlogs { facility(auth, authpriv) and not match(\(dqsshguard\(dq); };
# pass to this process with this template (avoids <ID> prefixes)
destination sshguardproc {
program(\(dq/usr/local/sbin/sshguard\(dq
template(\(dq$DATE $FULLHOST $MESSAGE\en\(dq));
};
log { source(src); filter(sshlogs); destination(sshguardproc); };
.EE
.UNINDENT
.UNINDENT
.sp
For \fBsyslog\-ng 3.x\fP, add the following lines to \fIsyslog\-ng.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# enable 3.x mode
@version:3.0

# pass only entries with auth+authpriv facilities from programs other than sshguard
filter f_sshguard { facility(auth, authpriv) and not program(\(dqsshguard\(dq); };
# pass entries built with this format
destination sshguard {
program(\(dq/usr/sbin/sshguard\(dq
template(\(dq$DATE $FULLHOST $MSGHDR$MESSAGE\en\(dq)
);
};
log { source(src); filter(f_sshguard); destination(sshguard); };
.EE
.UNINDENT
.UNINDENT
.sp
After restarting \fBsyslog\-ng\fP, SSHGuard should start as soon as a log entry
with facility \fBauth\fP or \fBauthpriv\fP arrives. If you are monitoring
services other than \fBsshd\fP, add the appropriate log facilities to
\fIsyslog\-ng.conf\fP\&.
.SS metalog
.sp
Add the following lines to \fImetalog.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Stuff to protect from brute force attacks :
    # for ssh
    facility = \(dq*\(dq
    program = \(dqsshd\(dq
    # other services ...
    # log to /var/log/sshguard directory
    logdir = \(dq/var/log/sshguard\(dq
.EE
.UNINDENT
.UNINDENT
.sp
After restarting \fBmetalog\fP, log entries will appear in
\fI/var/log/sshguard\fP\&.  Use \fIlog polling\fP to monitor the \fIcurrent\fP log.
.SH BACKENDS
.sp
SSHGuard can block attackers using one of several firewall backends that is
selected at compile\-time.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Read the documentation for your firewall. Make sure you fully understand each rule or command in the examples below before using them. They may need to be adjusted to suit your particular configuration.
.UNINDENT
.UNINDENT
.SS pf
.sp
SSHGuard adds attackers to table \fI<sshguard>\fP\&. Create the table and block
attackers by adding the following lines to the end of \fIpf.conf\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
table <sshguard> persist
block in proto tcp from <sshguard>
.EE
.UNINDENT
.UNINDENT
.sp
After reloading the \fBpf\fP configuration, you can inspect the contents of
the table using:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# pfctl \-t sshguard \-T show
.EE
.UNINDENT
.UNINDENT
.SS ipfw
.sp
SSHGuard creates and adds attackers to table 22. The table can be used to
block attackers in your ruleset. For example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# ipfw add 5000 reset ip from table\e(22\e) to me
.EE
.UNINDENT
.UNINDENT
.sp
You can inspect the contents of the table using:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# ipfw table 22 list
.EE
.UNINDENT
.UNINDENT
.SS firewalld
.sp
Blocked attackers are added to two ipsets named sshguard4 and sshguard6.
The entries in the ipsets are blocked by default in the default firewall
zone. Additional firewall zones can be configured using:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# firewall\-cmd \-\-zone=zone\-name \-\-permanent \e
    \-\-add\-rich\-rule=\(dqrule source ipset=sshguard4 drop\(dq
# firewall\-cmd \-\-zone=zone\-name \-\-permanent \e
    \-\-add\-rich\-rule=\(dqrule source ipset=sshguard6 drop\(dq
.EE
.UNINDENT
.UNINDENT
.sp
You can inspect the entries in the two ipsets using:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# firewall\-cmd \-\-permanent \-\-info\-ipset=sshguard4
# firewall\-cmd \-\-permanent \-\-info\-ipset=sshguard6
.EE
.UNINDENT
.UNINDENT
.SS ipset
.sp
Blocked attackers are added to two ipsets named sshguard4 and sshguard6.
Nothing is blocked by default, but can used as a source for iptables
and other tools. E.g.:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# iptables  \-I INPUT \-m set \-\-match\-set sshguard4 src \-j DROP
# ip6tables \-I INPUT \-m set \-\-match\-set sshguard6 src \-j DROP
.EE
.UNINDENT
.UNINDENT
.SS netfilter/iptables
.sp
Create a chain for SSHGuard:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# iptables \-N sshguard      # for IPv4
# ip6tables \-N sshguard     # for IPv6
.EE
.UNINDENT
.UNINDENT
.sp
Update the INPUT chain to also pass the traffic to the sshguard chain at the
very end of its processing. Specify in \-\-dport all the ports of services
your sshguard protects. If you want to prevent attackers from doing any
traffic to the host, remove the option completely:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# block any traffic from abusers
iptables \-A INPUT \-j sshguard
ip6tables \-A INPUT \-j sshguard
.EE
.UNINDENT
.UNINDENT
.sp
Or:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# block abusers only for SSH, FTP, POP, IMAP services (use \(dqmultiport\(dq module)
iptables \-A INPUT \-m multiport \-p tcp \-\-destination\-ports 21,22,110,143 \-j sshguard
ip6tables \-A INPUT \-m multiport \-p tcp \-\-destination\-ports 21,22,110,143 \-j sshguard
.EE
.UNINDENT
.UNINDENT
.sp
Verify that you have NOT a default allow rule passing all ssh traffic higher
in the chain. Verify that you have NOT a default deny rule blocking all ssh
traffic in your firewall. In either case, you already have the skill to
adjust your firewall setup.
.sp
Here is a sample ruleset that makes sense:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
iptables \-N sshguard
# block whatever SSHGuard says be bad ...
iptables \-A INPUT \-j sshguard
# enable ssh, dns, http, https
iptables \-A INPUT \-p tcp \-\-dport 22 \-j ACCEPT
iptables \-A INPUT \-p udp \-\-dport 53 \-j ACCEPT
iptables \-A INPUT \-p tcp \-\-dport 80 \-j ACCEPT
iptables \-A INPUT \-p tcp \-\-dport 443 \-j ACCEPT
# and block everything else (default deny)
iptables \-P INPUT DROP
.EE
.UNINDENT
.UNINDENT
.sp
When rebooting, most systems reset the firewall configuration by default. To
preserve your configuration, you usually use the iptables\-save and
iptables\-restore utilities. However, each Linux variant has its own \(dqright
way\(dq.
.SS nftables
.sp
SSHGuard creates tables with a high priority and adds attackers to a set
automatically.
.sp
You can inspect the contents of the sets using:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# nft list set ip sshguard attackers
# nft list set ip6 sshguard attackers
.EE
.UNINDENT
.UNINDENT
.sp
Moreover, you can display sshguard\(aqs tables with:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# nft list table ip sshguard
# nft list table ip6 sshguard
.EE
.UNINDENT
.UNINDENT
.SH TROUBLESHOOTING
.SS Is SSHGuard configured correctly?
.sp
Check that the correct \fBFILES\fP (or \fBLOGREADER\fP) and BACKEND are set in
\fIsshguard.conf\fP\&.
.SS Is SSHGuard running?
.sp
SSHGuard spawns a pipeline of cooperating processes. You can verify that
SSHGuard is started correctly by viewing your process list using \fBps\fP or
\fBtop\fP\&. Shown here are the processes associated with an example
configuration:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
/bin/sh /opt/sshguard/sbin/sshguard
tail \-F \-n 0 /tmp/log.txt
/opt/sshguard/libexec/sshg\-parser
/opt/sshguard/libexec/sshg\-blocker \-a 30 \-p 120 \-s 1800 \-N 128 \-n 32
/bin/sh /usr/local/libexec/sshg\-fw\-null
.EE
.UNINDENT
.UNINDENT
.sp
In order:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
SSHGuard, installed in \fI/opt/sshguard\fP, is being interpreted by \fI/bin/sh\fP\&.
.IP \(bu 2
SSHGuard launched \fBtail \-F \-n 0\fP, which is monitoring \fI/tmp/log.txt\fP\&.
.IP \(bu 2
The default parser \fBsshg\-parser\fP is running.
.IP \(bu 2
The blocker is running with options \fB\-a 30 \-p 120 \-s 1800 \-N 128 \-n 32\fP\&.
.IP \(bu 2
The firewall \fBsshg\-fw\-null\fP is running. The null backend doesn\(aqt actually
block any attacks.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Is SSHGuard recognizing attacks?
.sp
SSHGuard recognizes attacks by parsing log messages. The format of log
messages can occasionally change. If you are using the default, built\-in
attack parser, you can check if SSHGuard recognizes your attacks by running:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ cat /var/log/auth.log | %PREFIX%/libexec/sshg\-parser \-a
.EE
.UNINDENT
.UNINDENT
.sp
Log messages that are recognized as attacks are prefixed with a \(aq*\(aq at the
beginning of each line. If a log message that should be recognized as an
attack is not, consider reporting it.
.SH EXAMPLES
.sp
Ignore \fBFILES\fP and monitor these files instead:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# sshguard /var/log/auth.log /var/log/maillog
.EE
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
sshguard(8)
.\" Generated by docutils manpage writer.
.