added fwknoprc gpg signing pw test conf files to Makefile.am

[fwknop.git] / perl / legacy / fwknop / fwknop.8

.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH FWKNOP 8 "August, 2009" Linux
.SH NAME
.B fwknop
\- Firewall Knock Operator
.SH SYNOPSIS
.B fwknop \-A <ports> \-R|\-a|\-s \-D <host> [options]
.SH DESCRIPTION

.B fwknop
implements an authorization scheme known as Single Packet Authorization (SPA) for
Linux systems running iptables, and for Mac OS X and FreeBSD systems running ipfw.
This mechanism requires only a single encrypted and non-replayed
packet to communicate various pieces of information including desired access
through an iptables or ipfw policy.  The main application of this program is to
use iptables or ipfw in a default-drop stance to protect services such as
.B SSH
with an additional layer of security in order to make the exploitation of
vulnerabilities (both 0-day and unpatched code) much more difficult.  An
authorization server
.B fwknopd
passively monitors authorization packets via
.B libpcap
and hence there is no "server" to which to connect in the traditional sense.
Any service protected by fwknop is inaccessible (by using iptables or ipfw to intercept
packets within the kernel) before authenticating; anyone scanning for
the service will not be able to detect that it is even listening.  Single Packet
Authorization offers many advantages over port knocking, including non-replayability
of SPA packets, ability to use asymmetric ciphers (such as Elgamal), and SPA cannot
be broken by simply spoofing packets to duplicate ports within the knock sequence
on the server to break port knocking authentication.  SPA packets can easily be
spoofed as well (this is a good thing in this context), and this makes it possible
to make it appear as though, say, www.yahoo.com is trying to authenticate to a
target system but in reality the actual connection will come from a seemingly
unrelated IP. Although the default data collection method in Single Packet
Authorization mode is to use libpcap to sniff packets off the wire, fwknop can also
read packets out of a file that is written by the iptables
. B ulogd
pcap writer (or a separate sniffer process that is writing packet data to a file).
.PP
Authorization packets are either encrypted with the Rijndael block cipher
or via GnuPG and associated asymmetric ciphers.  If the symmetric encryption
method is chosen, then the encryption key is shared between the
client and server (see the
.I /etc/fwknop/access.conf
file).  If the GnuPG
method is chosen, then the encryption keys are derived from GnuPG key
rings.  SPA packets generated by fwknop running as a client adhere
to the following format (before they are encrypted):
.PP
    random number (16 bytes)
    username
    timestamp
    software version
    mode (command mode (0) or access mode (1))
    if command mode => command to execute
    else access mode  => IP,proto,port
    message digest (SHA256 / SHA1 / MD5)
.PP
Each of the above fields are separated by a ":" character due to the
variable length of several of the fields, and those that might contain
":" characters are base64 encoded.  The message digest (SHA256 by default
in all versions of
.B fwknop
greater than 1.9.1) allows the server to check message integrity after decryption,
and the 16 bytes of random data ensures (with high probability) that no two messages
are identical.  This ensures that replay attacks are not possible against fwknop.
For each packet coming from an
.B fwknop
client, the
.B fwknopd
server caches the SHA256 digest calculated over the entire packet and compares against
previous packet digests in order to detect attempted replay attacks.  The digest
cache file is located at
.I /var/log/fwknop/digest.cache
and is not rotated so that the detection of duplicate SPA messages is maximized.
Both syslog and email alerts are generated if a replay is detected (although
this can be tuned via the
.B ALERTING_METHODS
variable in the
.I /etc/fwknop/fwknop.conf
file).  By default, the
.B fwknop
client sends authorization packets over UDP
port 62201, but this can be altered with the
.B \-\-Server-port
argument. The server must first be configured to acquire the SPA data on
the changed protocol-port.  Also, fwknop can send the SPA packet over a random
port via the \-\-rand-port argument.  See
.B fwknopd(8)
for further details.  See the
.B EXAMPLES
section for example invocations of the
.B fwknop
client.

.SH REQUIRED ARGUMENTS

.TP
.BR \-D "\fR,\fP " \-\^\-Destination\ \<IP-address>
Direct the
.B fwknop
client to authenticate with the
.B fwknopd
daemon/service at the destination address <IP> .  The connection mode is discovered by the
.B fwknopd
daemon/service when it decrypts and parses the authentication packet.
.TP
.BR \-A "\fR,\fP " \-\^\-Access\ \<port\ list>
Provide a list of ports and protocols to access on a remote computer running
.B fwknopd.
The format of this list is '<proto>/<port>...<proto>/<port>,
e.g. "tcp/22,udp/53".
.B NOTE:
The vast majority of usages for
.B fwknop
require the \-A argument, but sending full commands with the \-\-Server-cmd
argument via an SPA packet to be executed by
.B fwknopd
does not require this argument.
.TP
.BR \-R|\-a|\-s
One of these options (see below) is required to tell the remote
.B fwknopd
daemon what IP should be let through the local firewall.  It is recommend to use
the \-R or \-a options instead of \-s in order to harden SPA communications against
possible MITM attacks.

.SH OPTIONS

.TP
.BR \-a "\fR,\fP " \-\^\-allow-IP\ \<IP-address>
Specify IP address that should be permitted through the destination
.B fwknopd
server firewall (this IP is encrypted within the SPA packet itself). This is
useful to prevent a Man-In-The-Middle (MTIM) attack where an SPA packet can be
intercepted en-route and sent from a different IP than the original. Hence, if
the
.B fwknopd
server trusts the source address on the SPA packet IP header then the attacker
gains access.  The
.B \-a
option puts the source address within the encrypted
SPA packet, and so thwarts this attack.  The
.B \-a
option is also useful to specify the IP that will be granted access when SPA
packet itself is spoofed with the
.B \-\-Spoof-src
option.  Another related option is \-R (see below) which instructs the
.B fwknop
client to automatically resolve the externally routable IP address the local
system is connected to by querying the
.B http://www.whatismyip.com
website.
.TP
.BR \-R "\fR,\fP " \-\^\-Resolve-external-IP
This is an important option, and instructs the
.B fwknop
client and the
.B fwknopd
daemon/service to query
.B http://www.whatismyip.com
to determine the IP address that should be allowed through the iptables policy
at the remote
.B fwknopd
server side.  This is useful if the
.B fwknop
client is being used on a system that is behind an obscure NAT address.  Note
that you can use the
.B \-\-URL
option to have fwknop resolve an externally routable address by using the
specific web service instead of http://www.whatismyip.org (see below).
.TP

.BR \-\^\-NAT-access\ \<internalIP:forwardPort>
The
.B fwknopd
server offers the ability to provide SPA access through an iptables firewall
to an internal service by interfacing with the iptables NAT capabilities.  So,
if the fwknopd server is protecting an internal network on RFC 1918 address
space, an external fwknop client can request that the server port forward an
external port to an internal IP, i.e. "\-\-NAT-access 192.168.10.2:55000".  In
this case access will be granted to 192.168.10.2 via port 55000 to whatever
service is requested via the \-\-Access argument (usually tcp/22). Hence, after
sending such an SPA packet, one would then do "ssh \-p 55000 user@host" and
the connection would be forwarded on through to the internal 192.168.10.2
system automatically.  Note that the port "55000" can be randomly generated
via the \-\-NAT-rand-port argument (described later).
.TP
.BR \-\^\-NAT-local
On the
.B fwknopd
server, a NAT operation can apply to the local system instead of being
forwarded through the system.  That is, for iptables firewalls, a connection
to, say, port 55,000 can be translated to port 22 on the local system.  By
making use of the \-\-NAT-local argument, the fwknop client can be made to
request such access.  This means that any external attacker would only see
a connection over port 55,000 instead of the expected port 22 after the SPA
packet is sent.
.TP
.BR \-\^\-URL\ \<web\ resolution\ \URL>
This option is used in conjunction with the
.B \-R
option so that fwknop will resolve the externally routable IP address (useful
if fwknop is run on a system being a NAT) via a web service URL supplied on
the command line. A custom web resolution CGI script is available at the URL
below if http://www.whatismyip.org is not available:
.B http://www.cipherdyne.org/cgi/clientip.cgi
.TP
.BR \-\^\-gpg-agent
Instruct
.B fwknop
to acquire GnuPG key password from a running
.B gpg-agent
instance.
.TP
.BR \-\^\-gpg-agent-info\ \<connection\ \info>
Specify the value of the GPG_AGENT_INFO environment variable as returned
by the
.B gpg-agent \-\-daemon
command. If the
.B fwknop \-\-gpg-agent
command line argument is used instead of
.B \-\-gpg-agent-info,
then fwknop assumes that the GPG_AGENT_INFO environment variable has already
been set in the current shell.
.TP
.BR \-\^\-gpg-default-key
Use the key that GnuPG defines as the default, i.e. the key that is specified
by the
.B default-key
variable in
.I ~/.gnupg/options.
If the
.B default-key
variable is not defined
within
.I ~/.gnupg/options
, then GnuPG tries to use the first suitable key on
its key ring.  If the user does not know the password for this key, then the
standard password error will be thrown by GnuPG and reported back to the
user.
.TP
.BR \-\^\-gpg-home-dir\ \<dir>
Specify the path to the GnuPG directory; normally this path is derived from the
home directory of the user that is running the
.B fwknop
client.  This is useful when a 'root' user wishes to log into a remote machine
whose
.B sshd
daemon/service does not permit 'root' login.
.TP
.BR \-\^\-gpg-recipient\ \<key\ \ID>
Specify the GnuPG key ID, e.g. "1234ABCD" (see the output of "gpg \-\-list-keys")
of the recipient of the Single Packet Authorization message.  This key is imported
by the
.B fwknopd
server and the associated private key is used to decrypt the SPA packet.  The
recipient's key must first be imported into the client GnuPG key ring.
.TP
.BR \-\^\-gpg-signing-key\ \<key\ \ID>
Specify the GnuPG key ID, e.g. "ABCD1234" (see the output of "gpg \-\-list-keys")
to use when signing the SPA message.  The user is prompted for
the associated GnuPG password to create the signature.  This
adds a cryptographically strong mechanism to allow the
.B fwknopd
daemon on the remote server to authenticate who created the SPA message.
.TP
.BR \-\^\-gpg-verbose
Instruct
.B fwknop
to allow all output from the
.B gpg
process that is used by fwknop in GnuPG mode.  This is primarily used for debugging
purposes if it appears that the GnuPG encrypt/decrypt is not performing correctly.
.TP
.BR \-\^\-gpg-use-options
By default the
.B fwknop
client instructs gpg to not reference any options file in gpg mode, but this
command line argument can be used to re-enable them.
.TP
.BR \-\^\-Home-dir\ \<dir>
Specify the path to the user home directory where files such as .fwknop.hosts
or .fwknop.run should be stored or retrieved.
.TP
.BR \-l "\fR,\fP " \-\^\-last-cmd
Instruct
.B fwknop
client to run with the same command line arguments that were used in a previous execution.
This option is useful because the clients'
.B fwknop
command line can be complex and difficult to recall.
.TP
.BR \-\^\-Last-host\ \<host>
Instruct
.B fwknop
to use the same command line arguments that were used to authenticate to
.B host.
.TP
.BR \-q "\fR,\fP " \-\^\-quiet
This option instructs the
.B fwknop
to be as quiet as possible and only print absolutely necessary information to
the terminal.
.TP
.BR \-s "\fR,\fP " \-\^\-source-ip
Instruct the
.B fwknop
client to form an SPA packet that contains the special-case IP
address "0.0.0.0" which will inform the destination
.B fwknopd
SPA server to use the source IP address from which the SPA packet originates as
the IP that will be allowed through upon modification of the firewall ruleset.
This option is useful if the fwknop client is deployed on a machine that is
behind a NAT device. The permit-address options
.B \-s
(default),
.B \-R
and
.B \-a
are mutually exclusive.
.TP
.BR \-\^\-Server-port\ \<port>
Specify the port number where
.B fwknopd
accepts packets via libpcap or ulogd pcap writer.  By default fwknopd looks for
authorization packets over UDP port 62201.
.TP
.BR \-\^\-rand-port
Instruct the fwknop client to send an SPA packet over a random destination port
between 10,000 and 65535.  The fwknopd server must use a PCAP_FILTER variable
that is configured to accept such packets.  For example, the PCAP_FILTER variable
could be set to:
.B udp dst portrange 10000-65535
.TP
.BR \-\^\-NAT-rand-port
Usually fwknop is used to request access to a specific port such as tcp/22 on a
system running fwknopd.  However, by using the \-\-NAT-rand-port argument, it is
possible to request access to a particular service (again, such as tcp/22), but
have this access granted via a random translated port.  That is, once the fwknop
client has been executed in this mode and the random port selected by fwknop is
displayed, the destination port used by the follow-on client must be changed to
match this random port.  For SSH, this is accomplished via the \-p argument.
See the \-\-NAT-local and \-\-NAT-access command line arguments to fwknop for
additional details on gaining access to services via a NAT operation.
.TP
.BR \-\^\-Save-packet
Instruct the
.B fwknop
client to write a newly created SPA packet out to a file so that it can be
examined off-line.  The default path is
.I ~/fwknop_save_packet.<pid>
where <pid> is the process ID of the fwknop client process, but this can be
changed with the \-\-Save-packet-file argument (see below).
.TP
.BR \-\^\-Save-packet-file\ \<file>
Specify the file to write a new SPA packet to in
.I \-\-Save-packet
mode.
.TP
.BR \-\^\-Save-packet-append
In
.I \-\-Save-packet
mode fwknop normally overwrite the file used to save a new SPA packet, but
this command line argument instructs fwknop to append a new SPA packet to
the file instead.  This is useful for generating large sets of SPA packets
in order to test randomness or encryption properties.
.TP
.BR \-\^\-time-offset-plus\ \<time>
By default, the
.B fwknopd
daemon on the server side enforces time synchronization between the clocks
running on client and server systems.  The fwknop client places the local time
within each SPA packet as a time stamp to be validated by the fwknopd server
after decryption.  However, in some circumstances, if the clocks are out of
sync and the user on the client system does not have the required access to
change the local clock setting, it can be difficult to construct and SPA
packet with a time stamp the server will accept.  In this situation, the
\-\-time-offset-plus option can allow the user to specify an offset (e.g.
"60sec", "60min", "2days", etc.) that is added to the local time.
.TP
.BR \-\^\-time-offset-minus\ \<time>
This is similar to the \-\-time-offset-plus option (see above), but subtracts
the specified time offset instead of adding it to the local time stamp.
.TP
.BR \-\^\-Show-last-cmd
Display the last command-line arguments used by
.B fwknop.
.TP
.BR \-\^\-Show-host-cmd\ \<host>
Display the last command-line arguments used to contact a SPA server running on
a specific
.B host.
.TP
.BR \-\^\-Spoof-proto\ \<protocol>
Send an SPA packet over a raw socket of the specified protocol.  Accepted
values are tcp, udp, and icmp.  This is useful if you want to send the SPA
packet over an orphaned TCP ACK or an ICMP packet.
.TP
.BR \-\^\-Spoof-src\ \<IP>
Spoof the source address from which the
.B fwknop
client sends SPA packets.  This requires root on the client side access since a raw socket
is required to accomplish this.  Note that the
.B \-\-Spoof-user
argument can be given in this mode in order to pass any
.B REQUIRE_USERNAME
keyword that might
be specified in
.I /etc/fwknop/access.conf.
.TP
.BR \-\^\-Spoof-user\ \<user>
Specify the username that is included within SPA packet.  This allows
the
.B fwknop
client to satisfy any non-root
.B REQUIRE_USERNAME
keyword on the
.B fwknopd
server (
.B \-\-Spoof-src
mode requires that the
.B fwknop
client is executed as root).
.TP
.BR \-\^\-icmp-type\ \<type>
When using the
.B \-\-Spoof-proto
argument to send an SPA packet over and ICMP packet, the ICMP type may be set
with this command line argument.  The default is "8" for an ICMP echo-request
(see also the
.B \-\-icmp-code
argument below).
.TP
.BR \-\^\-icmp-code\ \<code>
When using the
.B \-\-Spoof-proto
argument to send an SPA packet over and ICMP packet, the ICMP code may be set
with this command line argument.  The default is "0" for an ICMP echo-request
(see also the
.B \-\-icmp-type
argument above).
.TP
.BR \-\^\-Max-packet-size\ \<size>
Instruct
.B fwknop
to restrict message length to
.B size
bytes, and the client will not send an SPA packet that is larger than this
(i.e. perhaps a long command was included in \-\-Server-cmd mode). This alters
the default value of 1500 bytes. See also the
MAX_SNIFF_BYTES variable in
.B fwknop.conf
on the SPA server.
.TP
.BR \-\^\-HTTP
Have the
.B fwknop
client send an SPA packet as a web request over HTTP.  This requires that the
system running
.B fwknopd
is also running a webserver to receive the SPA web request.  The web request
is built as a modified version of base64-encoded data where the "+" and "/"
chars are replace with "-" and "_" respectively (to avoid URL encoding issues).
.TP
.BR \-\^\-HTTP-proxy\ \<proxy\ host>
The
.I HTTP-proxy
option allows the
.B fwknop
client to send SPA packets through an HTTP proxy when the
.I \-\-HTTP
option is also used.  The expected format for the argument is
.B http://some.host.com
and an optional port number is supported with the
.B http://some.host.com:PORT
format.
.TP
.BR \-\^\-HTTP-user-agent\ \<agent\ string>
Specify the HTTP user-agent whenver the
.B fwknop
client is used to send an SPA packet over an HTTP request, or when the
.I \-\-Resolve-external-IP
option is used.  The default user-agent is "Fwknop/VERSION", so "Fwknop/1.9.12"
for the 1.9.12 release.
.TP
.BR \-T "\fR,\fP " \-\^\-TCP-sock
Have the
.B fwknop
client send an SPA packet over an established TCP connection (created by the fwknop
client to the specified listening port on the server with the
.I --Server-port
argument).  This is not normally done, but is useful for compatibility with the Tor
for strong anonymity; see
.B http://tor.eff.org/.
In this case, the
.B fwknopd
server uses the
.B fwknop_serv
daemon to listen on a TCP port (62201 by default).
.TP
.BR \-h "\fR,\fP " \-\^\-help
Display usage information and exit.
.TP
.BR \-V "\fR,\fP " \-\^\-Version
Display version information and exit.
.TP
.BR \-v "\fR,\fP " \-\^\-verbose
Run the
.B fwknop
client in verbose mode.
.TP
.BR \-\^\-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 \-\^\-Server-cmd\ \<cmd>
.B NOTE:
This is for command mode only (i.e. when you want to send a command across
to a system running
.B fwknopd
and have it execute the command). This option is not needed when trying to
gain access to a service via the SPA mechanism.  To use this feature, please
ensure that ENABLE_CMD_EXEC; is set in the file
.I /etc/fwknop/access.conf
on the
.B fwknopd
server you are sending the command to.
The \-\-Server-cmd argument allows a complete command (e.g. "ping \-c 1 www.yahoo.com",
or "iptables \-t nat \-A PREROUTING \-p tcp \-s 65.x.x.x \-\-dport 443 \-i eth0 \-j DNAT \-\-to 192.168.10.20:443")
to be send to an
.B fwknop
server, which will execute the command as root.  Command execution is enabled only
if the
.B ENABLE_CMD_EXEC keyword is given in
.I /etc/fwknop/access.conf
(note that commands can easily be restricted with the
.B CMD_REGEX
keyword as well).
.TP

.B Legacy Port-knock mode only

All of the following options in this section are for the traditional port knocking
mode mode.  This is a legacy mode and is
.B not
the preferred or recommended mode next to Single Packet Authorization ( see
.B http://www.cipherdyne.org/fwknop/docs/SPA.html
for details on why).
.RS
.TP
.BR \-\^\-offset\ \<port>
Specify a port offset to use when running
.B fwknop
in encrypted knock mode.  The default is 61000.
.TP
.BR \-r "\fR,\fP " \-\^\-rotate-proto
Rotate the protocol across tcp and udp for
encrypted sequences.  This just adds one more additional layer of obfuscation
to an encrypted sequence.
.TP
.BR \-\^\-Server-mode\ \<mode>
This command line switch provides an interface to
the old port knocking method if
the mode argument is "knock".  If the
.B \-\-Server-mode
argument is not given then the
.B fwknop
client defaults to using the SPA method which provides much better
security characteristics than port knocking (encrypted or not).
.TP
.BR \-t "\fR,\fP " \-\^\-time-delay\ \<seconds>
Specify a time delay to introduce between successive
connection attempts.  This option is used by the
.B fwknop
client.  On the server side,
.B fwknopd
uses the variables MIN_TIME_DIFF
and MAX_TIME_DIFF to control whether the time delay actually means
something (i.e. if the MIN_TIME_DIFF is 2 seconds for a SOURCE block,
then the argument to the \-\-time-delay option must be at least 2 at the
client side).
.TP
.BR \-u "\fR,\fP " \-\^\-user-rc\ \<rc-file>
The default connection rc file the
.B fwknop
client uses to know what shared port knocking sequence to send to a destination machine
is defined in the file
.I ~/.fwknoprc.
The path to this file can be changed with the
.B \-\-user-rc
command line option.
.RE

.SH FILES
.TP
.B ~/.fwknop.run
Contains the last command line arguments that the
.B fwknop
client was invoked with.

.TP
.B ~/.fwknop.hosts
Contains the last command line arguments for individual hosts that the
.B fwknop
client has been used to gain access to.  By using the
.B \-\-Last-host
switch, these arguments can be recalled and used.

.SH ENVIRONMENT:

.B GPG_AGENT_INFO
(only used in \-\-gpg-agent mode).

.SH EXAMPLES:
The following examples illustrate the command line arguments that could
be supplied to the
.B fwknop
client in a few situations:

.B Access mode examples
.RS
Packet contents printed to stdout at the
.B fwknop
client when creating a 'access mode' SPA packet:
.PP
        Random data:    6565240948266426
        Username:       mbr
        Timestamp:      1203863233
        Version:        1.9.2
        Type:           1 (access mode)
        Access:         127.0.0.2,tcp/22
        SHA256 sum:     gngquSL8AuM7r27XsR4qPmJhuBo9pG2PYwII06AaJHw
.PP

Use the Single Packet Authorization mode to gain access to tcp/22 (ssh)
and udp/53 running on the system 10.0.0.123 from the IP 192.168.10.4:
.PP
.B $ fwknop \-A 'tcp/22,udp/53' \-a 192.168.10.4 \-D 10.0.0.123
.PP
Same as above example, but gain access from whatever source IP is seen
by the fwknop server (useful if the fwknop client is behind a NAT device):
.PP
.B $ fwknop \-A 'tcp/22,udp/53' \-s \-D 10.0.0.123
.PP
Same as above example, but use the IP identification website http://www.whatismyip.com/
to derive the client IP address.  This is a safer method of acquiring the client IP
address than using the
.B \-s
option because the source IP is put within the encrypted
packet instead of having the
.B fwknopd
daemon grant the requested access from whatever IP address the SPA packet originates:
.PP
.B $ fwknop \-A 'tcp/22,udp/53' \-R \-D 10.0.0.123
.PP
Use the Single Packet Authorization mode to gain access to tcp/22 (ssh)
and udp/53 running on the system 10.0.0.123, and use GnuPG keys to encrypt
and decrypt:
.PP
.B $ fwknop \-A 'tcp/22,udp/53' \-\-gpg-sign ABCD1234 \-\-gpg--recipient 1234ABCD \-R \-D 10.0.0.123
.PP
Instruct the fwknop server running at 10.0.0.123 to allow 172.16.5.4 to
connect to TCP/22, but spoof the authorization packet from an IP associated
with www.yahoo.com:
.PP
.B # fwknop \-\-Spoof-src 'www.yahoo.com' \-A tcp/22 \-a 172.16.5.4 \-D 10.0.0.123
.PP
.RE

.B Command mode examples
.RS
.B NOTE:
Please ensure that ENABLE_CMD_EXEC; is set in the file
.I /etc/fwknop/access.conf
on the
.B fwknopd
server you are attempting to connect to.
Packet contents printed to stdout at the
.B fwknop
client when creating a 'command mode' SPA packet:
.PP
        Random data:    4621962433020664
        Username:       mbr
        Timestamp:      1203864394
        Version:        1.9.2
        Type:           0 (command mode)
        Cmd:            echo "The commands sent \- minus quote charaters around the command" & sleep 10; echo "The End"
        SHA256 sum:     eN8c8mNArZxF066iulbxlTK4Gt/EO0ALLYwzVzCkXww
.PP
Instruct the fwknop server running at 10.0.0.123 to send a single ICMP
echo request to www.yahoo.com:
.PP
.B $ fwknop \-\-Server-cmd 'ping \-c 1 www.yahoo.com' \-D 10.0.0.123
.PP
.RE

.B Port-knock mode (legacy) examples
.RS
This connection mode is a legacy mode and is
.B not
the preferred or recommended mode.

Packet contents printed to stdout at the
.B fwknop
client when in 'port-knock mode':
<TODO>

Send an encrypted knock sequence to the IP "10.0.0.123" instructing the
fwknop daemon running there to open tcp port 22 to source address
192.168.10.4:
.PP
.B $ fwknop \-\-Server-mode 'knock' \-A tcp/22 \-a 192.168.10.4 \-D 10.0.0.123
.PP
Same as above, but this time instruct the remote fwknop daemon to open
tcp port 22 to whatever source address the encrypted sequence originates
from (useful if the fwknop client is behind a NAT device):
.PP
.B $ fwknop \-\-Server-mode 'knock' \-A tcp/22 \-s \-D 10.0.0.123
.PP
Same as above, but rotate the knock sequence through the tcp and udp
protocols (remember that iptables must be configured to log both tcp and
udp packets to the default port range of 61000-61255):
.PP
.B $ fwknop \-\-Server-mode 'knock' \-A tcp/22 \-s \-r \-D 10.0.0.123
.PP
Same as above, but change the base port for the encrypted sequence to
55000 (the default is 61000):
.PP
.B $ fwknop \-\-Server-mode 'knock' \-A tcp/22 \-s \-r \-\-offset 55000 \-D 10.0.0.123
.PP
Send a shared knock sequence to the IP 10.11.11.123.  The fwknop client
will read the sequence out of the file
.B ~/.fwknoprc
and the server will read the sequence out of
.B /etc/fwknop/access.conf:
.PP
.B $ fwknop \-\-Server-mode 'knock' \-D 10.11.11.123
.RE

.SH DEPENDENCIES
.B fwknop
requires perl.  To take advantage of all of the authentication and access management features of the
.B fwknopd
daemon/service a functioning iptables firewall is required on the underlying
operating system.  If fwknop is being run in the legacy port knocking mode,
then iptables must log packets via syslog, and ideally the
.B \-\-log-tcp-options
argument will be specified in the iptables logging rule so that the
.B fwknopd
daemon/service 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
.B \-\-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 fwknopd (8),
.BR iptables (8),
.BR gpg (1),
.BR gpg-agent (1),
.BR knopmd (8),
.BR knopwatchd (8)
.BR p0f (1),
More information on the
differences between port knocking and Single Packet Authorization can be found
in the paper "Single Packet Authorization with fwknop" available here:
.B http://www.cipherdyne.org/fwknop/docs/SPA.html

.SH AUTHOR
Michael Rash <mbr@cipherdyne.org>

.SH CONTRIBUTORS
Many people who are active in the open source community have contributed to fwknop.
See the
.B CREDITS
file in the fwknop sources, or visit
.B http://www.cipherdyne.org/fwknop/docs/contributors.html
to view the online list of contributors.

The phrase "Single Packet Authorization" was coined by MadHat and Simple
Nomad at the BlackHat Briefings of 2005 (see: http://www.nmrc.org/).
The term "port knocking" was coined by Martin Krzywinski (see:
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/