.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH FWKNOPD 8 "Jun, 2007" Linux
.SH NAME
.B fwknopd
\- Firewall Knock Operator (server component)
.SH SYNOPSIS
.B fwknopd [options]
.SH DESCRIPTION

.B fwknopd
is the server component for the FireWall Knock Operator, and is responsible
for monitoring Single Packet Authorization (SPA) packets that are generated by
.B fwknop
clients, modifying an iptables or ipfw policy to allow the desired access after decrypting
a valid SPA packet, and removing access after a configurable timeout.  The main
application of this program is to protect services such as SSH with an additional
layer of security in order to make the exploitation of vulnerabilities (both 0-day
and unpatched code) much more difficult.
.PP
The main configuration for
.B fwknopd
is maintained within two files:
.B fwknop.conf
and
.B access.conf
within the
.B /etc/fwknop
directory, and configuration variables within these files are desribed below.
.SH OPTIONS
.TP
.BR \-c "\fR,\fP " \-\^\-config\ \<config-file>
When run in server mode
.B fwknop
references the file
.B /etc/fwknop/fwknop.conf
for various run-time configuration
variables.  The path to this file can be changed through the use of the
.B \-\-config
command line option.
.TP
.BR \-i "\fR,\fP " \-\^\-intf\ \<interface>
Manually specify interface on which to sniff, e.g. "\-i eth0".  This option
is not usually needed because the PCAP_INTF keyword in /etc/fwknop/fwknop.conf
file defines the sniffing interface.
.TP
.BR \-\^\-fw-list
List all active rules in the FWKNOP Netfilter chain(s).
.TP
.BR \-\^\-fw-flush
Flush all active rules in the FWKNOP Netfilter chain(s).
.TP
.BR \-O "\fR,\fP " \-\^\-Override-config\ \<file>
Override config variable values that are normally read from the
/etc/fwknop/fwknop.conf file with values from the specified file.  Multiple
override config files can be given as a comma separated list.
.TP
.BR \-D "\fR,\fP " \-\^\-Dump-config
Dump the configuration values that
.B fwknopd
derives from the /etc/fwknop/fwknop.conf (or other override files) on
STDERR.
.TP
.BR \-o "\fR,\fP " \-\^\-os
Parse Netfilter logs and fingerprint operating systems from which tcp SYN
packets have been logged.
.TP
.BR \-\^\-fw-log\ \<file>
Specify the path to the Netfilter log file that is parsed when running in
\-\-os mode.
.TP
.BR \-K "\fR,\fP " \-\^\-Kill
Kill the current fwknop process along with knopwatchd and knopmd.  This
provides a quick and easy way to stop all fwknop processes without having
to look in the process table or appeal to the fwknop init script.
.TP
.BR \-R "\fR,\fP " \-\^\-Restart
Restart the currently running fwknop processes.  This option will preserve
the command line options that were supplied to the original fwknop process.
.TP
.BR \-S "\fR,\fP " \-\^\-Status
Display the status of any fwknop processes that may or not be running.
.TP
.BR \-l ", " " \-\^\-locale\ \<locale>
Provide a locale setting other than the default "C" locale.
.TP
.BR \-\^\-no-locale
Do not set the locale at all so that the default system locale will apply.
.TP
.BR \-v "\fR,\fP " \-\^\-verbose
Run fwknop in verbose mode.
.TP
.BR \-h "\fR,\fP " \-\^\-help
Display usage information and exit.
.TP
.BR \-V "\fR,\fP " \-\^\-Version
Display version information and exit.
.SH FILES
.B /etc/fwknop/fwknop.conf
.RS
The main configuration file for
.B fwknop.
.RE

.B /etc/fwknop/access.conf
.RS
Defines all knock sequences and access control directives.
.RE

.B /etc/fwknop/pf.os
.RS
Defines p0f signatures used by fwknop.
.RE
.SH FWKNOP CONFIG AND ACCESS VARIABLES
.B fwknop
references the file
.B /etc/fwknop/fwknop.conf
for configuration variables such as the path to the firewall logfile,
the sleep interval fwknop uses to check for new log messages, and
paths to system binaries, etc.  The
.B fwknop
config file does not define any access control directives; they are
located in the file
.B /etc/fwknop/access.conf.
Access control directives define encryption keys and level of access that
is granted to an fwknop client that has generated the appropriate encrypted
message.  This file is referenced for this information when run in either
the single packet authorization mode, or the legacy port knocking mode.
.TP
.B SOURCE: <IP,..,IP/NET,..,NET/ANY>
This defines the source address from which an authorization packet (or
legacy knock sequence) will be accepted.  The string "ANY" is also
accepted if a valid authorization packet should be honored from any source
IP.  Every authorization stanza in
.B /etc/fwknop/access.conf
definition must start with the SOURCE keyword.  Networks can be
specified in either CIDR (e.g. "192.168.10.0/24") or regular (e.g.
"192.168.10.0/255.255.255.0") notation, and individual IP addresses
can be specified as well.  Also, multiple IP's and/or networks can
be defined as a comma separated list (e.g. "192.168.10.0/24, 10.1.1.123")
.TP
.B DATA_COLLECT_MODE: PCAP|FILE_PCAP|ULOG_PCAP|ENCRYPT_SEQUENCE
If DATA_COLLECT_MODE is set to "PCAP",
.B fwknop
sniffs the wire directly via libpcap to capture authorization packets.
If set to "FILE_PCAP", fwknop reads a pcap-formatted file (defined by
the PCAP_PKT_FILE keyword in the fwknop.conf file) that is written
to by a separate sniffer process.  If set to "ULOG_PCAP", fwknop collects
packets via the Netfilter ulogd pcap writer.  This requires that packets
are logged via the ULOG target in the Netfilter policy.  If set to
ENCRYPT_SEQUENCE, fwknop falls back to the legacy port knocking method
of network authorization.
.TP
.B ENABLE_CMD_EXEC
This instructs
.B fwknop
to accept complete commands that are contained within an authorization
packet.  Any such command will be executed as root by the
.B fwknop server.
.TP
.B CMD_REGEX: <regex>
If ENABLE_CMD_EXEC is specified, the CMD_REGEX keyword instructs
.B fwknop
to restrict command execution to only those command that match the
given regular expression.
.TP
.B KEY: <8 or more chars>
Define the encryption key for an ENCRYPT_SEQUENCE block.  This variable
is required for all encrypted sequences (each encrypted sequence may
have its own unique key), and must be provided at execution to an
.B fwknop
client attempting to gain access.  When run in client mode, fwknop will
prompt the user for the encryption key, or a path to the key may be
provided on the command line with
.B \-\-get-key <file>.
.TP
.B OPEN_PORTS: <proto/port>, ..., <proto/port>
Define a set of ports and protocols (tcp or udp) that will be opened
if a valid knock sequence is seen.  This variable is required for
shared knock sequences since the port information is not sent within
the sequence, and optional for encrypted knock sequences which can
include the port and protocol within the sequence.
.TP
.B GPG_DECRYPT_ID: <keyID>
Define a GnuPG key ID to use for decrypting SPA messages that have been
encrypted by an
.B fwknop
client.  This keyword is required for authentication that is based on
.B gpg
keys.
The gpg key ring on the client must have imported and signed the
.B fwknopd
server key, and vice versa.  It is ok to use a sensitive personal gpg key
on the client, but each fwknopd server should have its own gpg key that is
generated specifically for fwknop communications.  The reason for this is
that the decryption password for the server key must be placed within the
.B /etc/fwknop/access.conf
file for fwknopd to function (it has to be able to decrypt SPA messages that
have been encrypted with the server's public key).  For more information on
using fwknop with GnuPG keys, see the following link:
.B http://www.cipherdyne.org/fwknop/docs/gpghowto.html
.TP
.B GPG DECRYPT_PW: <decrypt password>
Specify the decryption password for the
.B gpg
key defined by the
.B GPG_DECRYPT_ID
above.  This is a required field for gpg-based authentication.
.TP
.B GPG_REMOTE_ID: <keyID,...,keyID>
Define a list of
.B gpg
key ID's that are required to have signed any incoming SPA message that
has been encrypted with the
.B fwknopd
server key.  This ensures that the verification of the remote user is accomplished
via a strong cryptographic mechanism.
.TP
.B GPG_HOME_DIR: <path>
Define the path to the GnuPG directory to be used by the
.B fwknopd
server.  If this keyword is not specified within
.B /etc/fwknop/access.conf
then fwknopd will default to using the /root/.gnupg directory for the server key(s).
.TP
.B GPG_USE_OPTIONS
By default,
.B fwknopd
instructs gpg to not reference any options file when decrypting incoming
SPA packets that have been encrypted with GnuPG by the fwknop client.  This argument
re-enables options in gpg.
.TP
.B GPG_NO_REQUIRE_PREFIX
This option controls whether the GnuPG 'hQ' prefix is added before base64 decoding
and decrypting.  Normally this option is not needed, but if there appear to be
communications issues between the fwknop client and the fwknopd server in GnuPG
mode, then this option can be useful to ensure that encrypted SPA data is sent
through the GnuPG decryption routine.  The 'hQ' prefix is a heuristic derived from
the file 'magic' database for describing data encrypted with GnuPG, and the fwknop
client normally strips this data from outgoing SPA packets (unless the
\-\-Include-gpg-prefix option is used).
.TP
.B GPG_PATH: <path>
Specify a path to the gpg binary (commonly at /usr/bin/gpg).  This can be used to
switch between gpg vs. gpg2, or provide a path to a custom compiled version of gpg
for testing purposes.
.TP
.B FW_ACCESS_TIMEOUT: <seconds>
Define the length of time access will be granted by fwknop through
the firewall after a valid knock sequence from a source IP address.
If FW_ACCESS_TIMEOUT is not set then the default timeout of 300
seconds (5 minutes) will automatically be set.
.TP
.B REQUIRE_USERNAME: <username>
Require a specific username from the client system.  This username is
sent across the network in an encrypted knock sequence to the fwknop
server.  If there are multiple users on the client system, only a knock
sequence that is initiated by the required username will be honored.
This variable is optional and is only valid with an encrypted sequence
definition.
.TP
.B REQUIRE_SOURCE_ADDRESS
Force all SPA packets to contain a real IP address within the encrypted
data.  This makes it impossible to use the \-s command line argument on
the
.B fwknop
command line, so either \-R has to be used to automatically resolve the
external address (if the client behind a NAT) or the client must know
the external IP.
.TP
.B REQUIRE_OS: <operating system>
Require a specific operating system fingerprint match (e.g.
"Linux:2.4::Linux 2.4/2.6" or "OpenBSD:3.0\-3.5::OpenBSD 3.0\-3.5"
before a knock sequence will be accepted.  The fingerprints are listed
in
.B /etc/fwknop/pf.os.
Note that the corresponding knock sequence must utilize the tcp protocol
(this is only be an issue for shared sequences since encrypted sequences
use tcp by default) since OS fingerprinting requires tcp syn packets.
This variable is optional, and is not applicable in SPA mode.
.TP
.B REQUIRE_OS_REGEX: <regex>
Require an operating system fingerprint that matches <regex>, e.g.
"linux" or "*bsd".  Note that the regex will be matched case in\-
sensitively.  This variable is optional, and is not applicable in SPA
mode.
.TP
.B ENCRYPT_SEQUENCE
Expect that all port knock sequences originating from the SOURCE will
be encrypted.  Fwknop will try to decrypt all such sequences.
ENCRYPT_SEQUENCE does not accept any arguments.  Either this variable
or the "SHARED_SEQUENCE" variable is required for each SOURCE block.
.TP
.B SHARED_SEQUENCE: <proto/port>, ..., <proto/port>
Define the sequence of ports (together with their associated
protocol; tcp or udp) that will be sent to the destination knock
server.  This sequence is not encrypted, and source IP will be
allowed to connect through the destination firewall ruleset to a set
of tcp or udp ports (defined by the OPEN_PORTS variable).  Using
an encrypted sequence is much more secure.  Either this variable or
the "ENCRYPT_SEQUENCE" variable above is required for each SOURCE
block.
.TP
.B KNOCK_INTERVAL: <seconds>
Define the interval of time in which a port knock sequence will be
honored.  I.e. the number of seconds after the first connection
attempt the last connection attempt in the sequence must be received
for the knock sequence to be accepted by the destination fwknop
daemon.  If a KNOCK_INTERVAL is not specified then the default
interval of 60 seconds will automatically be set.
.TP
.B KNOCK_LIMIT: <number>
Define the maximum number of times a knock sequence will be honored.
Note that repetitive access to the fwknop server will eventually be
restricted if this option is used.
.TP
.B PORT_OFFSET: <offset>
Encrypted knock sequences take place over a range of 256 ports
starting at a default port of 61000.  This value can be changed
through the use of the PORT_OFFSET variable.  The PORT_OFFSET
is optional and will be set to 61000 by fwknop if it is not specified
in /etc/fwknop/access.conf.
.TP
.B MIN_TIME_DIFF: <seconds>
Set the minimum number of seconds that must pass between successive
connection attempts in a shared knock sequence.  This variable is
optional.
.TP
.B MAX_TIME_DIFF: <seconds>
Set the maximum number of seconds that must pass between successive
connection attempts in a shared knock sequence.  This variable is
optional.
.SH DEPENDENCIES
.B fwknopd
requires perl.  To take advantage of all of the features in fwknop when run
in server mode a functioning Netfilter firewall is required on the underlying
operating system.  If fwknop is being run in the legacy port knocking mode,
then Netfilter must log packets via syslog, and ideally the \-\-log-tcp-options
argument will be specified in the iptables logging rule so that fwknop will
be able to use a strategy similar to
.B p0f
to passively fingerprint operating systems.
.SH DIAGNOSTICS
.B fwknop
can be run in debug mode with the \-\-debug command line option.  This will
disable daemon mode execution, and print verbose information to the screen
on STDERR as packets are received.
.SH "SEE ALSO"
.BR fwknop (8),
.BR iptables (8),
.BR gpg (1),
.BR gpg-agent (1),
.BR knopmd (8),
.BR knopwatchd (8)
.BR p0f (1),
.SH AUTHOR
Michael Rash <mbr@cipherdyne.org>
.SH CREDITS
The phrase "Single Packet Authorization" was coined by MadHat, see:
.B http://www.nmrc.org/
The term "port knocking" was coined by Martin Krzywinski, see:
.B http://www.portknocking.org/
 The original p0f passive OS fingerprinter was written by Michal Zalewski, and is
available here:
.B http://lcamtuf.coredump.cx/p0f.shtml
.SH BUGS
Send bug reports to mbr@cipherdyne.org.  Suggestions and/or comments are
always welcome as well.
.SH DISTRIBUTION
.B fwknop
is distributed under the GNU General Public License (GPL), and the latest
version may be downloaded from
.B http://www.cipherdyne.org/