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 -v, --verbose
41 Output verbose status messages.
42 -V, --version
44 Display the version.
45 -h, --help
47 Syntax help.
48
50 knockd reads all knock/event sets from a configuration file. Each
51 knock/event begins with a title marker, in the form [name], where name
52 is the name of the event that will appear in the log. A special
53 marker, [options], is used to define global options.
54 Example #1:
57 This example uses two knocks. The first will allow the knocker
58 to access port 22 (SSH), and the second will close the port when
59 the knocker is complete. As you can see, this could be useful
60 if you run a very restrictive (DENY policy) firewall and would
61 like to access it discreetly.
62 [options]
64 logfile = /var/log/knockd.log
65 [openSSH]
67 sequence = 7000,8000,9000
68 seq_timeout = 10
69 tcpflags = syn
70 command = /usr/sbin/iptables -A INPUT -s %IP% --dport 22 -j ACCEPT
71 [closeSSH]
73 sequence = 9000,8000,7000
74 seq_timeout = 10
75 tcpflags = syn
76 command = /usr/sbin/iptables -D INPUT -s %IP% --dport 22 -j ACCEPT
77 Example #2:
81 This example uses a single knock to control access to port 22
82 (SSH). After receiving a successful knock, the daemon will run
83 the start_command, wait for the time specified in cmd_timeout,
84 then execute the stop_command. This is useful to automatically
85 close the door behind a knocker. The knock sequence uses both
86 UDP and TCP ports.
87 [options]
89 logfile = /var/log/knockd.log
90 [opencloseSSH]
92 sequence = 2222:udp,3333:tcp,4444:udp
93 seq_timeout = 15
94 tcpflags = syn,ack
95 start_command = /usr/sbin/iptables -A INPUT -s %IP% -p tcp --syn -j ACCEPT
96 cmd_timeout = 5
97 stop_command = /usr/sbin/iptables -D INPUT -s %IP% -p tcp --syn -j ACCEPT
98 Example #3:
102 This example doesn't use a single, fixed knock sequence to trig‐
103 ger an event, but a set of sequences taken from a sequence file
104 (one time sequences), specified by the one_time_sequences direc‐
105 tive. After each successful knock, the used sequence will be
106 invalidated and the next sequence from the sequence file has to
107 be used for a successful knock. This prevents an attacker from
108 doing a replay attack after having discovered a sequence (eg,
109 while sniffing the network).
110 [options]
112 logfile = /var/log/knockd.log
113 [opencloseSMTP]
115 one_time_sequences = /etc/knockd/smtp_sequences
116 seq_timeout = 15
117 tcpflags = fin,!ack
118 start_command = /usr/sbin/iptables -A INPUT -s %IP% -p tcp --dport 25 -j ACCEPT
119 cmd_timeout = 5
120 stop_command = /usr/sbin/iptables -D INPUT -s %IP% -p tcp --dport 25 -j ACCEPT
121
124 UseSyslog
125 Log action messages through syslog(). This will insert log
126 entries into your /var/log/messages or equivalent.
127 LogFile = /path/to/file
129 Log actions directly to a file, usually /var/log/knockd.log.
130 PidFile = /path/to/file
132 Pidfile to use when in daemon mode, default:
133 /var/run/knockd.pid.
134 Interface = <interface_name>
136 Network interface to listen on. Only its name has to be given,
137 not the path to the device (eg, "eth0" and not "/dev/eth0").
138 Default: eth0.
139
141 Sequence = <port1>[:<tcp|udp>],<port2>[:<tcp|udp>][,<port3>[:<tcp|udp>]
142 ...]
143 Specify the sequence of ports in the special knock. If a wrong
144 port with the same flags is received, the knock is discarded.
145 Optionally, you can define the protocol to be used on a per-port
146 basis (default is TCP).
147 One_Time_Sequences = /path/to/one_time_sequences_file
149 File containing the one time sequences to be used. Instead of
150 using a fixed sequence, knockd will read the sequence to be used
151 from that file. After each successful knock attempt this
152 sequence will be disabled by writing a '#' character at the
153 first position of the line containing the used sequence. That
154 used sequence will then be replaced by the next valid sequence
155 from the file.
156 Because the first character is replaced by a '#', it is recom‐
158 mended that you leave a space at the beginning of each line.
159 Otherwise the first digit in your knock sequence will be over‐
160 written with a '#' after it has been used.
161 Each line in the one time sequences file contains exactly one
163 sequence and has the same format as the one for the Sequence
164 directive. Lines beginning with a '#' character will be
165 ignored.
166 Note: Do not edit the file while knockd is running!
168 Seq_Timeout = <timeout>
170 Time to wait for a sequence to complete in seconds. If the time
171 elapses before the knock is complete, it is discarded.
172 TCPFlags = fin|syn|rst|psh|ack|urg
174 Only pay attention to packets that have this flag set. When
175 using TCP flags, knockd will IGNORE tcp packets that don't match
176 the flags. This is different than the normal behavior, where an
177 incorrect packet would invalidate the entire knock, forcing the
178 client to start over. Using "TCPFlags = syn" is useful if you
179 are testing over an SSH connection, as the SSH traffic will usu‐
180 ally interfere with (and thus invalidate) the knock.
181 Separate multiple flags with commas (eg, TCPFlags =
183 syn,ack,urg). Flags can be explicitly excluded by a "!" (eg,
184 TCPFlags = syn,!ack).
185 Target = <ip-address>
187 Use the specified IP address instead of the address determined
188 for the Interface when matching the Sequence. This is useful if
189 knockd is running on a router and you want to do something in
190 response to an actual connection attempt to a routed host -
191 e.g., invoking etherwake to send the host a WOL packet.
192 Start_Command = <command>
194 Specify the command to be executed when a client makes the cor‐
195 rect port-knock. All instances of %IP% will be replaced with
196 the knocker's IP address. The Command directive is an alias for
197 Start_Command.
198 Cmd_Timeout = <timeout>
200 Time to wait (in seconds) between Start_Command and Stop_Com‐
201 mand. This directive is optional, only required if Stop_Command
202 is used.
203 Stop_Command = <command>
205 Specify the command to be executed when Cmd_Timeout seconds have
206 passed since Start_Command has been executed. All instances of
207 %IP% will be replaced with the knocker's IP address. This
208 directive is optional.
209
211 Using the -l or --lookup commandline option to resolve DNS names for
212 log entries may be a security risk! An attacker may find out the first
213 port of a sequence if he can monitor the DNS traffic of the host run‐
214 ning knockd. Also a host supposed to be stealth (eg, dropping packets
215 to closed TCP ports instead of replying with an ACK+RST packet) may
216 give itself away by resolving a DNS name if an attacker manages to hit
217 the first (unknown) port of a sequence.
218
220 knock is the accompanying port-knock client, though telnet or netcat
221 could be used for simple TCP knocks instead. For more advanced knocks,
222 see hping, sendip or packit.
223
225 Judd Vinet <jvinet@zeroflux.org>
226knockd 0.7.8 June 26, 2005 knockd(1)