1knockd(1)                                                            knockd(1)
2
3
4

NAME

6       knockd - port-knock server
7

SYNOPSIS

9       knockd [options]
10

DESCRIPTION

12       knockd  is a port-knock server.  It listens to all traffic on an ether‐
13       net (or PPP) interface, looking for special "knock" sequences of  port-
14       hits.   A client makes these port-hits by sending a TCP (or UDP) packet
15       to a port on the server.  This port need not be open  --  since  knockd
16       listens  at the link-layer level, it sees all traffic even if it's des‐
17       tined for a closed port.  When the server detects a  specific  sequence
18       of  port-hits,  it  runs  a  command defined in its configuration file.
19       This can be used to open up holes in a firewall for quick access.
20

COMMANDLINE OPTIONS

22       -i, --interface <int>
23              Specify an interface to listen on.  The default is eth0.
24
25       -d, --daemon
26              Become a daemon.  This is usually desired for normal server-like
27              operation.
28
29       -c, --config <file>
30              Specify  an  alternate location for the config file.  Default is
31              /etc/knockd.conf.
32
33       -D, --debug
34              Output debugging messages.
35
36       -l, --lookup
37              Lookup DNS names for log entries. This may be a  security  risk!
38              See section SECURITY NOTES.
39
40       -4, --only-ip-v4
41              Ignore packets from IPv6 and handle only IPv4.
42
43       -v, --verbose
44              Output verbose status messages.
45
46       -V, --version
47              Display the version.
48
49       -h, --help
50              Syntax help.
51

CONFIGURATION

53       knockd  reads  all  knock/event  sets  from a configuration file.  Each
54       knock/event begins with a title marker, in the form [name], where  name
55       is  the  name  of  the  event  that  will appear in the log.  A special
56       marker, [options], is used to define global options.
57
58
59       Example #1:
60              This example uses two knocks.  The first will allow the  knocker
61              to access port 22 (SSH), and the second will close the port when
62              the knocker is complete.  As you can see, this could  be  useful
63              if  you  run a very restrictive (DENY policy) firewall and would
64              like to access it discreetly.
65
66              [options]
67                   logfile = /var/log/knockd.log
68
69              [openSSH]
70                   sequence    = 7000,8000,9000
71                   seq_timeout = 10
72                   tcpflags    = syn
73                   command     = /usr/sbin/iptables -A INPUT -s %IP% --dport 22 -j ACCEPT
74
75              [closeSSH]
76                   sequence    = 9000,8000,7000
77                   seq_timeout = 10
78                   tcpflags    = syn
79                   command     = /usr/sbin/iptables -D INPUT -s %IP% --dport 22 -j ACCEPT
80
81
82
83       Example #2:
84              This example uses a single knock to control access  to  port  22
85              (SSH).   After receiving a successful knock, the daemon will run
86              the start_command, wait for the time specified  in  cmd_timeout,
87              then  execute the stop_command.  This is useful to automatically
88              close the door behind a knocker.  The knock sequence  uses  both
89              UDP and TCP ports.
90
91              [options]
92                   logfile = /var/log/knockd.log
93
94              [opencloseSSH]
95                   sequence      = 2222:udp,3333:tcp,4444:udp
96                   seq_timeout   = 15
97                   tcpflags      = syn,ack
98                   start_command = /usr/sbin/iptables -A INPUT -s %IP% -p tcp --syn -j ACCEPT
99                   cmd_timeout   = 5
100                   stop_command  = /usr/sbin/iptables -D INPUT -s %IP% -p tcp --syn -j ACCEPT
101
102
103
104       Example #3:
105              This example doesn't use a single, fixed knock sequence to trig‐
106              ger an event, but a set of sequences taken from a sequence  file
107              (one time sequences), specified by the one_time_sequences direc‐
108              tive.  After each successful knock, the used  sequence  will  be
109              invalidated  and the next sequence from the sequence file has to
110              be used for a successful knock.  This prevents an attacker  from
111              doing  a  replay  attack after having discovered a sequence (eg,
112              while sniffing the network).
113
114              [options]
115                   logfile = /var/log/knockd.log
116
117              [opencloseSMTP]
118                   one_time_sequences = /etc/knockd/smtp_sequences
119                   seq_timeout        = 15
120                   tcpflags           = fin,!ack
121                   start_command      = /usr/sbin/iptables -A INPUT -s %IP% -p tcp --dport 25 -j ACCEPT
122                   cmd_timeout        = 5
123                   stop_command       = /usr/sbin/iptables -D INPUT -s %IP% -p tcp --dport 25 -j ACCEPT
124
125
126
127       Example #4:
128              Example to support IPv4 and IPv6. You can  provide  a  dedicated
129              command for each of the two protocols.
130
131              [options]
132                   logfile = /var/log/knockd.log
133
134              [opencloseSMTP]
135                   one_time_sequences = /etc/knockd/smtp_sequences
136                   seq_timeout        = 15
137                   tcpflags           = fin,!ack
138                   start_command      = /usr/sbin/iptables -A INPUT -s %IP% -p tcp --dport 25 -j ACCEPT
139                   start_command_6    = /usr/sbin/ip6tables -A INPUT -s %IP% -p tcp --dport 25 -j ACCEPT
140                   cmd_timeout        = 5
141                   stop_command       = /usr/sbin/iptables -D INPUT -s %IP% -p tcp --dport 25 -j ACCEPT
142                   stop_command_6     = /usr/sbin/ip6tables -D INPUT -s %IP% -p tcp --dport 25 -j ACCEPT
143
144

CONFIGURATION: GLOBAL DIRECTIVES

146       UseSyslog
147              Log  action messages through syslog().  This will insert log en‐
148              tries into your /var/log/messages or equivalent.
149
150       LogFile = /path/to/file
151              Log actions directly to a file, usually /var/log/knockd.log.
152
153       PidFile = /path/to/file
154              Pidfile   to    use    when    in    daemon    mode,    default:
155              /var/run/knockd.pid.
156
157       Interface = <interface_name>
158              Network  interface  to listen on. Only its name has to be given,
159              not the path to the device (eg, "eth0" and not "/dev/eth0"). De‐
160              fault: eth0.
161

CONFIGURATION: KNOCK/EVENT DIRECTIVES

163       Sequence = <port1>[:<tcp|udp>],<port2>[:<tcp|udp>][,<port3>[:<tcp|udp>]
164       ...]
165              Specify the sequence of ports in the special knock. If  a  wrong
166              port  with  the  same flags is received, the knock is discarded.
167              Optionally, you can define the protocol to be used on a per-port
168              basis (default is TCP).
169
170       One_Time_Sequences = /path/to/one_time_sequences_file
171              File  containing  the one time sequences to be used.  Instead of
172              using a fixed sequence, knockd will read the sequence to be used
173              from  that  file.   After each successful knock attempt this se‐
174              quence will be disabled by writing a '#' character at the  first
175              position  of  the  line containing the used sequence.  That used
176              sequence will then be replaced by the next valid  sequence  from
177              the file.
178
179              Because  the  first character is replaced by a '#', it is recom‐
180              mended that you leave a space at the  beginning  of  each  line.
181              Otherwise  the  first digit in your knock sequence will be over‐
182              written with a '#' after it has been used.
183
184              Each line in the one time sequences file  contains  exactly  one
185              sequence and has the same format as the one for the Sequence di‐
186              rective.  Lines beginning with a '#' character will be ignored.
187
188              Note: Do not edit the file while knockd is running!
189
190       Seq_Timeout = <timeout>
191              Time to wait for a sequence to complete in seconds. If the  time
192              elapses before the knock is complete, it is discarded.
193
194       TCPFlags = fin|syn|rst|psh|ack|urg
195              Only pay attention to packets that have this flag set.  When us‐
196              ing TCP flags, knockd will IGNORE tcp packets that  don't  match
197              the flags.  This is different than the normal behavior, where an
198              incorrect packet would invalidate the entire knock, forcing  the
199              client  to  start over.  Using "TCPFlags = syn" is useful if you
200              are testing over an SSH connection, as the SSH traffic will usu‐
201              ally interfere with (and thus invalidate) the knock.
202
203              Separate   multiple   flags   with   commas   (eg,   TCPFlags  =
204              syn,ack,urg).  Flags can be explicitly excluded by  a  "!"  (eg,
205              TCPFlags = syn,!ack).
206
207       Target = <ip-address>
208              Use  the  specified IP address instead of the address determined
209              for the Interface when matching the Sequence.  This is useful if
210              knockd  is  running  on a router and you want to do something in
211              response to an actual connection attempt  to  a  routed  host  -
212              e.g., invoking etherwake to send the host a WOL packet.
213
214       Start_Command = <command>
215              Specify  the command to be executed when a client makes the cor‐
216              rect port-knock with IPv4.  All instances of %IP%  will  be  re‐
217              placed  with the knocker's IP address.  The Command directive is
218              an alias for Start_Command.
219
220       Start_Command_6 = <command>
221              Specify the command to be executed when a client makes the  cor‐
222              rect  port-knock  with  IPv6.  All instances of %IP% will be re‐
223              placed with the knocker's IP address.  The  Command_6  directive
224              is an alias for Start_Command_6. If not present it will automat‐
225              ically fallback onto the same IPV4 Start_Command value. You  can
226              use empty value to force doing nothing.
227
228       Cmd_Timeout = <timeout>
229              Time  to  wait  (in seconds) between Start_Command and Stop_Com‐
230              mand.  This directive is optional, only required if Stop_Command
231              is used.
232
233       Stop_Command = <command>
234              Specify the command to be executed when Cmd_Timeout seconds have
235              passed since Start_Command has been executed.  All instances  of
236              %IP%  will  be replaced with the knocker's IP address.  This di‐
237              rective is optional.
238
239       Stop_Command_6 = <command>
240              Specify the command to be executed when Cmd_Timeout seconds have
241              passed  since  Start_Command_6 has been executed.  All instances
242              of %IP% will be replaced with the knocker's  IP  address.   This
243              directive  is  optional.   If  not present it will automatically
244              fallback onto the same IPV4  Stop_Command  value.  You  can  use
245              empty value to force doing nothing.
246

SECURITY NOTES

248       Using  the  -l  or --lookup commandline option to resolve DNS names for
249       log entries may be a security risk!  An attacker may find out the first
250       port  of  a sequence if he can monitor the DNS traffic of the host run‐
251       ning knockd.  Also a host supposed to be stealth (eg, dropping  packets
252       to  closed  TCP  ports  instead of replying with an ACK+RST packet) may
253       give itself away by resolving a DNS name if an attacker manages to  hit
254       the first (unknown) port of a sequence.
255

SEE ALSO

257       knock  is  the  accompanying port-knock client, though telnet or netcat
258       could be used for simple TCP knocks instead.  For more advanced knocks,
259       see hping, sendip or packit.
260

AUTHOR

262       Judd Vinet <jvinet@zeroflux.org>
263
264
265
266knockd 0.8                      April 22, 2021                       knockd(1)
Impressum