1SSHGUARD-SETUP(7)               SSHGuard Manual              SSHGUARD-SETUP(7)
2
3
4

NAME

6       sshguard-setup - setting up SSHGuard on your system
7

DESCRIPTION

9       To set up SSHGuard, write sshguard.conf and set up the backend, if nec‐
10       essary. Configuration options are documented in the  sample  configura‐
11       tion  file.  A good starting point is to copy it and make the necessary
12       changes:
13
14       1. Set BACKEND. You may also need to set it up to  work  with  SSHGuard
15          (see BACKENDS).
16
17       2. Set  FILES,  LOGREADER, or both. Alternatively, give sshguard a list
18          of files to monitor as positional arguments on the command-line.
19
20       Use FILES to specify a space-separated list of log  files  to  monitor.
21       Use  LOGREADER  to  specify a shell command to run to obtain logs. Both
22       settings are ignored if files are given on the command-line.
23
24       Sample LOGREADER commands for journalctl(1) and macOS 10.12+ are avail‐
25       able in the sample configuration.
26

OTHER LOGS

28   syslog-ng
29       For syslog-ng 2.x, add the following lines to syslog-ng.conf:
30
31          # pass only entries with auth+authpriv facilities from programs other than sshguard
32          filter sshlogs { facility(auth, authpriv) and not match("sshguard"); };
33          # pass to this process with this template (avoids <ID> prefixes)
34          destination sshguardproc {
35          program("/usr/local/sbin/sshguard"
36          template("$DATE $FULLHOST $MESSAGE\n"));
37          };
38          log { source(src); filter(sshlogs); destination(sshguardproc); };
39
40       For syslog-ng 3.x, add the following lines to syslog-ng.conf:
41
42          # enable 3.x mode
43          @version:3.0
44
45          # pass only entries with auth+authpriv facilities from programs other than sshguard
46          filter f_sshguard { facility(auth, authpriv) and not program("sshguard"); };
47          # pass entries built with this format
48          destination sshguard {
49          program("/usr/sbin/sshguard"
50          template("$DATE $FULLHOST $MSGHDR$MESSAGE\n")
51          );
52          };
53          log { source(src); filter(f_sshguard); destination(sshguard); };
54
55       After  restarting syslog-ng, SSHGuard should start as soon as a log en‐
56       try with facility auth or authpriv arrives. If you are monitoring  ser‐
57       vices  other  than  sshd,  add  the  appropriate log facilities to sys‐
58       log-ng.conf.
59
60   metalog
61       Add the following lines to metalog.conf:
62
63          Stuff to protect from brute force attacks :
64              # for ssh
65              facility = "*"
66              program = "sshd"
67              # other services ...
68              # log to /var/log/sshguard directory
69              logdir = "/var/log/sshguard"
70
71       After restarting metalog, log entries will appear in /var/log/sshguard.
72       Use log polling to monitor the current log.
73

BACKENDS

75       SSHGuard  can  block  attackers  using one of several firewall backends
76       that is selected at compile-time.
77
78       WARNING:
79          Read the documentation for your firewall. Make sure you fully under‐
80          stand  each rule or command in the examples below before using them.
81          They may need to be adjusted to suit your particular configuration.
82
83   pf
84       SSHGuard adds attackers to table <sshguard>. Create the table and block
85       attackers by adding the following lines to the end of pf.conf:
86
87          table <sshguard> persist
88          block in proto tcp from <sshguard>
89
90       After  reloading  the pf configuration, you can inspect the contents of
91       the table using:
92
93          # pfctl -t sshguard -T show
94
95   ipfw
96       SSHGuard creates and adds attackers to table 22. The table can be  used
97       to block attackers in your ruleset. For example:
98
99          # ipfw add 5000 reset ip from table\(22\) to me
100
101       You can inspect the contents of the table using:
102
103          # ipfw table 22 list
104
105   firewalld
106       Blocked  attackers  are  added  to  two ipsets named sshguard4 and ssh‐
107       guard6.  The entries in the ipsets are blocked by default  in  the  de‐
108       fault firewall zone. Additional firewall zones can be configured using:
109
110          # firewall-cmd --zone=zone-name --permanent \
111              --add-rich-rule="rule source ipset=sshguard4 drop"
112          # firewall-cmd --zone=zone-name --permanent \
113              --add-rich-rule="rule source ipset=sshguard6 drop"
114
115       You can inspect the entries in the two ipsets using:
116
117          # firewall-cmd --permanent --info-ipset=sshguard4
118          # firewall-cmd --permanent --info-ipset=sshguard6
119
120   ipset
121       Blocked  attackers  are  added  to  two ipsets named sshguard4 and ssh‐
122       guard6.  Nothing is blocked by default, but can used as  a  source  for
123       iptables and other tools. E.g.:
124
125          # iptables  -I INPUT -m set --match-set sshguard4 src -j DROP
126          # ip6tables -I INPUT -m set --match-set sshguard6 src -j DROP
127
128   netfilter/iptables
129       Create a chain for SSHGuard:
130
131          # iptables -N sshguard      # for IPv4
132          # ip6tables -N sshguard     # for IPv6
133
134       Update  the  INPUT chain to also pass the traffic to the sshguard chain
135       at the very end of its processing. Specify in --dport all the ports  of
136       services  your sshguard protects. If you want to prevent attackers from
137       doing any traffic to the host, remove the option completely:
138
139          # block any traffic from abusers
140          iptables -A INPUT -j sshguard
141          ip6tables -A INPUT -j sshguard
142
143       Or:
144
145          # block abusers only for SSH, FTP, POP, IMAP services (use "multiport" module)
146          iptables -A INPUT -m multiport -p tcp --destination-ports 21,22,110,143 -j sshguard
147          ip6tables -A INPUT -m multiport -p tcp --destination-ports 21,22,110,143 -j sshguard
148
149       Verify that you have NOT a default allow rule passing all  ssh  traffic
150       higher  in  the  chain.  Verify  that  you have NOT a default deny rule
151       blocking all ssh traffic in your firewall. In either case, you  already
152       have the skill to adjust your firewall setup.
153
154       Here is a sample ruleset that makes sense:
155
156          iptables -N sshguard
157          # block whatever SSHGuard says be bad ...
158          iptables -A INPUT -j sshguard
159          # enable ssh, dns, http, https
160          iptables -A INPUT -p tcp --dport 22 -j ACCEPT
161          iptables -A INPUT -p udp --dport 53 -j ACCEPT
162          iptables -A INPUT -p tcp --dport 80 -j ACCEPT
163          iptables -A INPUT -p tcp --dport 443 -j ACCEPT
164          # and block everything else (default deny)
165          iptables -P INPUT DROP
166
167       When  rebooting,  most  systems reset the firewall configuration by de‐
168       fault. To preserve  your  configuration,  you  usually  use  the  ipta‐
169       bles-save  and  iptables-restore utilities. However, each Linux variant
170       has its own "right way".
171
172   nftables
173       SSHGuard creates tables with a high priority and adds  attackers  to  a
174       set automatically.
175
176       You can inspect the contents of the sets using:
177
178          # nft list set ip sshguard attackers
179          # nft list set ip6 sshguard attackers
180
181       Moreover, you can display sshguard's tables with:
182
183          # nft list table ip sshguard
184          # nft list table ip6 sshguard
185

TROUBLESHOOTING

187   Is SSHGuard configured correctly?
188       Check that the correct FILES (or LOGREADER) and BACKEND are set in ssh‐
189       guard.conf.
190
191   Is SSHGuard running?
192       SSHGuard spawns a pipeline of cooperating  processes.  You  can  verify
193       that  SSHGuard  is started correctly by viewing your process list using
194       ps or top. Shown here are the processes associated with an example con‐
195       figuration:
196
197          /bin/sh /opt/sshguard/sbin/sshguard
198          tail -F -n 0 /tmp/log.txt
199          /opt/sshguard/libexec/sshg-parser
200          /opt/sshguard/libexec/sshg-blocker -a 30 -p 120 -s 1800 -N 128 -n 32
201          /bin/sh /usr/local/libexec/sshg-fw-null
202
203       In order:
204
205          • SSHGuard,  installed  in  /opt/sshguard,  is  being interpreted by
206            /bin/sh.
207
208          • SSHGuard launched tail -F -n 0, which is monitoring /tmp/log.txt.
209
210          • The default parser sshg-parser is running.
211
212          • The blocker is running with options -a 30 -p 120 -s 1800 -N 128 -n
213            32.
214
215          • The firewall sshg-fw-null is running. The null backend doesn't ac‐
216            tually block any attacks.
217
218   Is SSHGuard recognizing attacks?
219       SSHGuard recognizes attacks by parsing log messages. The format of  log
220       messages  can  occasionally  change.  If  you  are  using  the default,
221       built-in attack parser, you can check if SSHGuard recognizes  your  at‐
222       tacks by running:
223
224          $ cat /var/log/auth.log | %PREFIX%/libexec/sshg-parser -a
225
226       Log  messages that are recognized as attacks are prefixed with a '*' at
227       the beginning of each line. If a log message that should be  recognized
228       as an attack is not, consider reporting it.
229

EXAMPLES

231       Ignore FILES and monitor these files instead:
232
233          # sshguard /var/log/auth.log /var/log/maillog
234

SEE ALSO

236       sshguard(8)
237
238
239
240
2412.4                             August 27, 2020              SSHGUARD-SETUP(7)
Impressum