credit Blair and Tim with MacPorts and Homebrew maintainer status
[fwknop.git] / perl / legacy / fwknop / fwknopd.8
1 .\" Process this file with
2 .\" groff -man -Tascii foo.1
3 .\"
4 .TH FWKNOPD 8 "Jun, 2007" Linux
6 .B fwknopd
7 \- Firewall Knock Operator (server component)
9 .B fwknopd [options]
12 .B fwknopd
13 is the server component for the FireWall Knock Operator, and is responsible
14 for monitoring Single Packet Authorization (SPA) packets that are generated by
15 .B fwknop
16 clients, modifying an iptables or ipfw policy to allow the desired access after decrypting
17 a valid SPA packet, and removing access after a configurable timeout.  The main
18 application of this program is to protect services such as SSH with an additional
19 layer of security in order to make the exploitation of vulnerabilities (both 0-day
20 and unpatched code) much more difficult.
21 .PP
22 The main configuration for
23 .B fwknopd
24 is maintained within two files:
25 .B fwknop.conf
26 and
27 .B access.conf
28 within the
29 .B /etc/fwknop
30 directory, and configuration variables within these files are desribed below.
32 .TP
33 .BR \-c "\fR,\fP " \-\^\-config\ \<config-file>
34 When run in server mode
35 .B fwknop
36 references the file
37 .B /etc/fwknop/fwknop.conf
38 for various run-time configuration
39 variables.  The path to this file can be changed through the use of the
40 .B \-\-config
41 command line option.
42 .TP
43 .BR \-i "\fR,\fP " \-\^\-intf\ \<interface>
44 Manually specify interface on which to sniff, e.g. "\-i eth0".  This option
45 is not usually needed because the PCAP_INTF keyword in /etc/fwknop/fwknop.conf
46 file defines the sniffing interface.
47 .TP
48 .BR \-\^\-fw-list
49 List all active rules in the FWKNOP Netfilter chain(s).
50 .TP
51 .BR \-\^\-fw-flush
52 Flush all active rules in the FWKNOP Netfilter chain(s).
53 .TP
54 .BR \-O "\fR,\fP " \-\^\-Override-config\ \<file>
55 Override config variable values that are normally read from the
56 /etc/fwknop/fwknop.conf file with values from the specified file.  Multiple
57 override config files can be given as a comma separated list.
58 .TP
59 .BR \-D "\fR,\fP " \-\^\-Dump-config
60 Dump the configuration values that
61 .B fwknopd
62 derives from the /etc/fwknop/fwknop.conf (or other override files) on
64 .TP
65 .BR \-o "\fR,\fP " \-\^\-os
66 Parse Netfilter logs and fingerprint operating systems from which tcp SYN
67 packets have been logged.
68 .TP
69 .BR \-\^\-fw-log\ \<file>
70 Specify the path to the Netfilter log file that is parsed when running in
71 \-\-os mode.
72 .TP
73 .BR \-K "\fR,\fP " \-\^\-Kill
74 Kill the current fwknop process along with knopwatchd and knopmd.  This
75 provides a quick and easy way to stop all fwknop processes without having
76 to look in the process table or appeal to the fwknop init script.
77 .TP
78 .BR \-R "\fR,\fP " \-\^\-Restart
79 Restart the currently running fwknop processes.  This option will preserve
80 the command line options that were supplied to the original fwknop process.
81 .TP
82 .BR \-S "\fR,\fP " \-\^\-Status
83 Display the status of any fwknop processes that may or not be running.
84 .TP
85 .BR \-l ", " " \-\^\-locale\ \<locale>
86 Provide a locale setting other than the default "C" locale.
87 .TP
88 .BR \-\^\-no-locale
89 Do not set the locale at all so that the default system locale will apply.
90 .TP
91 .BR \-v "\fR,\fP " \-\^\-verbose
92 Run fwknop in verbose mode.
93 .TP
94 .BR \-h "\fR,\fP " \-\^\-help
95 Display usage information and exit.
96 .TP
97 .BR \-V "\fR,\fP " \-\^\-Version
98 Display version information and exit.
100 .B /etc/fwknop/fwknop.conf
101 .RS
102 The main configuration file for
103 .B fwknop.
104 .RE
106 .B /etc/fwknop/access.conf
107 .RS
108 Defines all knock sequences and access control directives.
109 .RE
111 .B /etc/fwknop/pf.os
112 .RS
113 Defines p0f signatures used by fwknop.
114 .RE
116 .B fwknop
117 references the file
118 .B /etc/fwknop/fwknop.conf
119 for configuration variables such as the path to the firewall logfile,
120 the sleep interval fwknop uses to check for new log messages, and
121 paths to system binaries, etc.  The
122 .B fwknop
123 config file does not define any access control directives; they are
124 located in the file
125 .B /etc/fwknop/access.conf.
126 Access control directives define encryption keys and level of access that
127 is granted to an fwknop client that has generated the appropriate encrypted
128 message.  This file is referenced for this information when run in either
129 the single packet authorization mode, or the legacy port knocking mode.
130 .TP
131 .B SOURCE: <IP,..,IP/NET,..,NET/ANY>
132 This defines the source address from which an authorization packet (or
133 legacy knock sequence) will be accepted.  The string "ANY" is also
134 accepted if a valid authorization packet should be honored from any source
135 IP.  Every authorization stanza in
136 .B /etc/fwknop/access.conf
137 definition must start with the SOURCE keyword.  Networks can be
138 specified in either CIDR (e.g. "") or regular (e.g.
139 "") notation, and individual IP addresses
140 can be specified as well.  Also, multiple IP's and/or networks can
141 be defined as a comma separated list (e.g. ",")
142 .TP
144 If DATA_COLLECT_MODE is set to "PCAP",
145 .B fwknop
146 sniffs the wire directly via libpcap to capture authorization packets.
147 If set to "FILE_PCAP", fwknop reads a pcap-formatted file (defined by
148 the PCAP_PKT_FILE keyword in the fwknop.conf file) that is written
149 to by a separate sniffer process.  If set to "ULOG_PCAP", fwknop collects
150 packets via the Netfilter ulogd pcap writer.  This requires that packets
151 are logged via the ULOG target in the Netfilter policy.  If set to
152 ENCRYPT_SEQUENCE, fwknop falls back to the legacy port knocking method
153 of network authorization.
154 .TP
156 This instructs
157 .B fwknop
158 to accept complete commands that are contained within an authorization
159 packet.  Any such command will be executed as root by the
160 .B fwknop server.
161 .TP
162 .B CMD_REGEX: <regex>
163 If ENABLE_CMD_EXEC is specified, the CMD_REGEX keyword instructs
164 .B fwknop
165 to restrict command execution to only those command that match the
166 given regular expression.
167 .TP
168 .B KEY: <8 or more chars>
169 Define the encryption key for an ENCRYPT_SEQUENCE block.  This variable
170 is required for all encrypted sequences (each encrypted sequence may
171 have its own unique key), and must be provided at execution to an
172 .B fwknop
173 client attempting to gain access.  When run in client mode, fwknop will
174 prompt the user for the encryption key, or a path to the key may be
175 provided on the command line with
176 .B \-\-get-key <file>.
177 .TP
178 .B OPEN_PORTS: <proto/port>, ..., <proto/port>
179 Define a set of ports and protocols (tcp or udp) that will be opened
180 if a valid knock sequence is seen.  This variable is required for
181 shared knock sequences since the port information is not sent within
182 the sequence, and optional for encrypted knock sequences which can
183 include the port and protocol within the sequence.
184 .TP
185 .B GPG_DECRYPT_ID: <keyID>
186 Define a GnuPG key ID to use for decrypting SPA messages that have been
187 encrypted by an
188 .B fwknop
189 client.  This keyword is required for authentication that is based on
190 .B gpg
191 keys.
192 The gpg key ring on the client must have imported and signed the
193 .B fwknopd
194 server key, and vice versa.  It is ok to use a sensitive personal gpg key
195 on the client, but each fwknopd server should have its own gpg key that is
196 generated specifically for fwknop communications.  The reason for this is
197 that the decryption password for the server key must be placed within the
198 .B /etc/fwknop/access.conf
199 file for fwknopd to function (it has to be able to decrypt SPA messages that
200 have been encrypted with the server's public key).  For more information on
201 using fwknop with GnuPG keys, see the following link:
202 .B
203 .TP
204 .B GPG DECRYPT_PW: <decrypt password>
205 Specify the decryption password for the
206 .B gpg
207 key defined by the
209 above.  This is a required field for gpg-based authentication.
210 .TP
211 .B GPG_REMOTE_ID: <keyID,...,keyID>
212 Define a list of
213 .B gpg
214 key ID's that are required to have signed any incoming SPA message that
215 has been encrypted with the
216 .B fwknopd
217 server key.  This ensures that the verification of the remote user is accomplished
218 via a strong cryptographic mechanism.
219 .TP
220 .B GPG_HOME_DIR: <path>
221 Define the path to the GnuPG directory to be used by the
222 .B fwknopd
223 server.  If this keyword is not specified within
224 .B /etc/fwknop/access.conf
225 then fwknopd will default to using the /root/.gnupg directory for the server key(s).
226 .TP
228 By default,
229 .B fwknopd
230 instructs gpg to not reference any options file when decrypting incoming
231 SPA packets that have been encrypted with GnuPG by the fwknop client.  This argument
232 re-enables options in gpg.
233 .TP
235 This option controls whether the GnuPG 'hQ' prefix is added before base64 decoding
236 and decrypting.  Normally this option is not needed, but if there appear to be
237 communications issues between the fwknop client and the fwknopd server in GnuPG
238 mode, then this option can be useful to ensure that encrypted SPA data is sent
239 through the GnuPG decryption routine.  The 'hQ' prefix is a heuristic derived from
240 the file 'magic' database for describing data encrypted with GnuPG, and the fwknop
241 client normally strips this data from outgoing SPA packets (unless the
242 \-\-Include-gpg-prefix option is used).
243 .TP
244 .B GPG_PATH: <path>
245 Specify a path to the gpg binary (commonly at /usr/bin/gpg).  This can be used to
246 switch between gpg vs. gpg2, or provide a path to a custom compiled version of gpg
247 for testing purposes.
248 .TP
249 .B FW_ACCESS_TIMEOUT: <seconds>
250 Define the length of time access will be granted by fwknop through
251 the firewall after a valid knock sequence from a source IP address.
252 If FW_ACCESS_TIMEOUT is not set then the default timeout of 300
253 seconds (5 minutes) will automatically be set.
254 .TP
255 .B REQUIRE_USERNAME: <username>
256 Require a specific username from the client system.  This username is
257 sent across the network in an encrypted knock sequence to the fwknop
258 server.  If there are multiple users on the client system, only a knock
259 sequence that is initiated by the required username will be honored.
260 This variable is optional and is only valid with an encrypted sequence
261 definition.
262 .TP
264 Force all SPA packets to contain a real IP address within the encrypted
265 data.  This makes it impossible to use the \-s command line argument on
266 the
267 .B fwknop
268 command line, so either \-R has to be used to automatically resolve the
269 external address (if the client behind a NAT) or the client must know
270 the external IP.
271 .TP
272 .B REQUIRE_OS: <operating system>
273 Require a specific operating system fingerprint match (e.g.
274 "Linux:2.4::Linux 2.4/2.6" or "OpenBSD:3.0\-3.5::OpenBSD 3.0\-3.5"
275 before a knock sequence will be accepted.  The fingerprints are listed
276 in
277 .B /etc/fwknop/pf.os.
278 Note that the corresponding knock sequence must utilize the tcp protocol
279 (this is only be an issue for shared sequences since encrypted sequences
280 use tcp by default) since OS fingerprinting requires tcp syn packets.
281 This variable is optional, and is not applicable in SPA mode.
282 .TP
283 .B REQUIRE_OS_REGEX: <regex>
284 Require an operating system fingerprint that matches <regex>, e.g.
285 "linux" or "*bsd".  Note that the regex will be matched case in\-
286 sensitively.  This variable is optional, and is not applicable in SPA
287 mode.
288 .TP
290 Expect that all port knock sequences originating from the SOURCE will
291 be encrypted.  Fwknop will try to decrypt all such sequences.
292 ENCRYPT_SEQUENCE does not accept any arguments.  Either this variable
293 or the "SHARED_SEQUENCE" variable is required for each SOURCE block.
294 .TP
295 .B SHARED_SEQUENCE: <proto/port>, ..., <proto/port>
296 Define the sequence of ports (together with their associated
297 protocol; tcp or udp) that will be sent to the destination knock
298 server.  This sequence is not encrypted, and source IP will be
299 allowed to connect through the destination firewall ruleset to a set
300 of tcp or udp ports (defined by the OPEN_PORTS variable).  Using
301 an encrypted sequence is much more secure.  Either this variable or
302 the "ENCRYPT_SEQUENCE" variable above is required for each SOURCE
303 block.
304 .TP
305 .B KNOCK_INTERVAL: <seconds>
306 Define the interval of time in which a port knock sequence will be
307 honored.  I.e. the number of seconds after the first connection
308 attempt the last connection attempt in the sequence must be received
309 for the knock sequence to be accepted by the destination fwknop
310 daemon.  If a KNOCK_INTERVAL is not specified then the default
311 interval of 60 seconds will automatically be set.
312 .TP
313 .B KNOCK_LIMIT: <number>
314 Define the maximum number of times a knock sequence will be honored.
315 Note that repetitive access to the fwknop server will eventually be
316 restricted if this option is used.
317 .TP
318 .B PORT_OFFSET: <offset>
319 Encrypted knock sequences take place over a range of 256 ports
320 starting at a default port of 61000.  This value can be changed
321 through the use of the PORT_OFFSET variable.  The PORT_OFFSET
322 is optional and will be set to 61000 by fwknop if it is not specified
323 in /etc/fwknop/access.conf.
324 .TP
325 .B MIN_TIME_DIFF: <seconds>
326 Set the minimum number of seconds that must pass between successive
327 connection attempts in a shared knock sequence.  This variable is
328 optional.
329 .TP
330 .B MAX_TIME_DIFF: <seconds>
331 Set the maximum number of seconds that must pass between successive
332 connection attempts in a shared knock sequence.  This variable is
333 optional.
335 .B fwknopd
336 requires perl.  To take advantage of all of the features in fwknop when run
337 in server mode a functioning Netfilter firewall is required on the underlying
338 operating system.  If fwknop is being run in the legacy port knocking mode,
339 then Netfilter must log packets via syslog, and ideally the \-\-log-tcp-options
340 argument will be specified in the iptables logging rule so that fwknop will
341 be able to use a strategy similar to
342 .B p0f
343 to passively fingerprint operating systems.
345 .B fwknop
346 can be run in debug mode with the \-\-debug command line option.  This will
347 disable daemon mode execution, and print verbose information to the screen
348 on STDERR as packets are received.
349 .SH "SEE ALSO"
350 .BR fwknop (8),
351 .BR iptables (8),
352 .BR gpg (1),
353 .BR gpg-agent (1),
354 .BR knopmd (8),
355 .BR knopwatchd (8)
356 .BR p0f (1),
358 Michael Rash <>
360 The phrase "Single Packet Authorization" was coined by MadHat, see:
361 .B
362 The term "port knocking" was coined by Martin Krzywinski, see:
363 .B
364  The original p0f passive OS fingerprinter was written by Michal Zalewski, and is
365 available here:
366 .B
367 .SH BUGS
368 Send bug reports to  Suggestions and/or comments are
369 always welcome as well.
371 .B fwknop
372 is distributed under the GNU General Public License (GPL), and the latest
373 version may be downloaded from
374 .B