1knockd(1) knockd(1)
2
6 knockd - port-knock server
7
9 knockd [options]
10
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
22 -i, --interface <int>
23 Specify an interface to listen on. The default is eth0.
24 -d, --daemon
26 Become a daemon. This is usually desired for normal server-like
27 operation.
28 -c, --config <file>
30 Specify an alternate location for the config file. Default is
31 /etc/knockd.conf.
32 -D, --debug
34 Output debugging messages.
35 -l, --lookup
37 Lookup DNS names for log entries. This may be a security risk!
38 See section SECURITY NOTES.
39 -4, --only-ip-v4
41 Ignore packets from IPv6 and handle only IPv4.
42 -v, --verbose
44 Output verbose status messages.
45 -V, --version
47 Display the version.
48 -h, --help
50 Syntax help.
51
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 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 [options]
67 logfile = /var/log/knockd.log
68 [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 [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 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 [options]
92 logfile = /var/log/knockd.log
93 [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 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 [options]
115 logfile = /var/log/knockd.log
116 [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 Example #4:
128 Example to support IPv4 and IPv6. You can provide a dedicated
129 command for each of the two protocols.
130 [options]
132 logfile = /var/log/knockd.log
133 [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
146 UseSyslog
147 Log action messages through syslog(). This will insert log en‐
148 tries into your /var/log/messages or equivalent.
149 LogFile = /path/to/file
151 Log actions directly to a file, usually /var/log/knockd.log.
152 PidFile = /path/to/file
154 Pidfile to use when in daemon mode, default:
155 /var/run/knockd.pid.
156 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
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 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 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 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 Note: Do not edit the file while knockd is running!
189 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 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 Separate multiple flags with commas (eg, TCPFlags =
204 syn,ack,urg). Flags can be explicitly excluded by a "!" (eg,
205 TCPFlags = syn,!ack).
206 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 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 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 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 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 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
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
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
262 Judd Vinet <jvinet@zeroflux.org>
263knockd 0.8 April 22, 2021 knockd(1)