Provided by: fwknop-server_2.6.10-13build1_amd64 bug

NAME

       fwknopd - Firewall Knock Operator Daemon

SYNOPSIS

       fwknopd [options]

DESCRIPTION

       fwknopd is the server component for the FireWall Knock Operator, and is responsible for
       monitoring and processing Single Packet Authorization (SPA) packets that are generated by
       fwknop clients, modifying a firewall or ACL policy to allow the desired access after
       authenticating and decrypting a valid SPA packet (in that order), and removing access
       after a configurable timeout.

       The main application of this program is to conceal 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. In addition, services that are concealed in this
       fashion naturally cannot be scanned for with Nmap or Shodan.

       The main configuration for fwknopd is maintained within two files: fwknopd.conf and
       access.conf. The default location for these files is determined at package configuration
       (typically /etc/fwknop). The configuration variables within these files are described
       below.

       Additional information may be found in the tutorial “Single Packet Authorization: A
       Comprehensive Guide to Strong Service Concealment with fwknop” available online (see:
       http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html).

COMMAND-LINE OPTIONS

       -i, --interface=<interface>
           Manually specify interface on which to sniff, e.g. “-i eth0”. This option is not
           usually needed because the “PCAP_INTF” keyword in the fwknopd.conf file defines the
           sniffing interface.

       -f, --foreground
           Run fwknopd in the foreground instead of becoming a daemon. When run in the
           foreground, message that would go to the log would instead be sent to stderr. This
           mode is usually used when testing and/or debugging.

       --fw-list
           List only firewall rules that any running fwknopd daemon has created and then exit.

       -a, --access-file=<access-file>
           Specify the location of the access.conf file. If this option is not given, fwknopd
           will use the compile-time default location (typically /etc/fwknop/access.conf).

       --access-folder=<access-folder>
           Specify the location of the access.conf folder. If this option is given, rather than
           load a single access.conf file, all the .conf files in the given folders are
           processed.

       -c, --config=<config-file>
           Specify the location of the fwknopd.conf file. If this option is not given, fwknopd
           will use the default location (typically /etc/fwknop/fwknopd.conf.

       -C, --packet-limit=<n>
           Specify the number of candidate SPA packets to process and exit when this limit is
           reached.

       -d, --digest-file=<digest-file>
           Specify the location of the digest.cache file. If this option is not given, fwknopd
           will use the compile-time default location (typically
           @runstatedir@/fwknop/digest.cache).

       -D, --dump-config
           Dump the configuration values that fwknopd derives from the /etc/fwknop/fwknopd.conf
           (or override files) and /etc/fwknop/access.conf on stderr.

       --dump-serv-err-codes
           Dump all possible fwknopd error codes to stdout and exit. This option is rarely needed
           in practice, and was added to assist with test coverage.

       --fault-injection-tag=<tag>
           This option is only used for fault injection testing when fwknop is compiled to
           support the libfiu library (see: http://blitiri.com.ar/p/libfiu/). Under normal
           circumstances this option is not used, and any packaged version of fwknop will not
           have code compiled in so this capability is not enabled at run time. It is documented
           here for completeness. version of fwknop will not have code compiled in to enable this
           capability at run time. It is documented here for completeness.

       -A, --afl-fuzzing
           Instruct fwknopd to acquire SPA packets directly from stdin in support of fuzzing
           operations from the American Fuzzy Lop (AFL) fuzzer written by Michal Zalewski. This
           requires that fwknop is compiled with the --enable-afl-fuzzing argument to the
           configure script as this allows encryption/digest short circuiting in a manner
           necessary for AFL to function properly. The benefit of this strategy is that AFL can
           fuzz the SPA packet decoding routines implemented by libfko.

       --fw-list-all
           List all firewall rules including those that have nothing to do with fwknopd.

       --fw-flush
           Flush any firewall rules created by a running fwknopd process. This option allows the
           used to easily delete fwknopd firewall rules without having to wait for them to be
           timed out.

       -K, --kill
           Kill the current fwknopd process. This provides a quick and easy way to stop fwknopd
           without having to look in the process table.

       --exit-parse-config
           Parse config files (/etc/fwknop/fwknopd.conf, and /etc/fwknop/access.conf) and then
           exit. This provides a way to test whether the config files are properly structured
           without having to start processing network traffic.

       --exit-parse-digest-cache
           Parse the digest cache file @runstatedir@/fwknop/digest.cache and exit. This validates
           the structure of the digest cache file without having to start processing network
           traffic. Note that the standard configuration files are also parsed in this mode.

       -l, --locale=<locale>
           Set/override the system default locale setting.

       --no-ipt-check-support
           Disable the usage of the iptables -C option. This is not normally needed, and is only
           useful on older Linux distributions where iptables does not have -C support.

       -O, --override-config=<file>
           Override config variable values that are normally read from the
           /etc/fwknop/fwknopd.conf file with values from the specified file. Multiple override
           config files can be given as a comma-separated list.

       --key-gen
           Have fwknopd generate both Rijndael and HMAC keys that can be used for SPA packet
           encryption and authentication. These keys are derived from /dev/urandom and then
           base64 encoded before being printed to stdout, and are meant to be manually included
           in a stanza within the /etc/fwknop/access.conf file. Such keys are generally more
           secure than passphrases.

       --key-gen-file=<file>
           Write generated keys to the specified file. Note that the file is overwritten if it
           already exists. If this option is not given, then --key-gen writes the keys to stdout.

       --key-len=<length>
           Specify the number of bytes for a generated Rijndael key. The maximum size is
           currently 128 bytes.

       --hmac-key-len=<length>
           Specify the number of bytes for a generated HMAC key. The maximum size is currently
           128 bytes.

       -p, --pid-file=<pid-file>
           Specify the location of the fwknopd.pid file. If this option is not given, fwknopd
           will use the compile-time default location (typically
           @runstatedir@/fwknop/fwknopd.pid).

       -P, --pcap-filter=<filter>
           Specify a Berkeley packet filter statement on the fwknopd command line. This overrides
           the value of the PCAP_FILTER variable taken from the /etc/fwknop/fwknopd.conf file.

       --pcap-file=<pcap-file>
           This option instructs fwknopd to read packet data from a pcap file instead of sniffing
           an interface directly. This mode is usually used for debugging purposes, and will
           disable SPA packet age checking unless it is manually enabled in the
           /etc/fwknop/fwknopd.conf file.

       --pcap-any-direction
           Allow fwknopd to sniff SPA packets regardless of whether they are received on the
           sniffing interface or sent from the sniffing interface. In the later case, this can be
           useful to have fwknopd sniff SPA packets that are forwarded through a system and
           destined for a different network. If the sniffing interface is the egress interface
           for such packets (and hence SPA packets are sent by this interface instead of
           received), then this option will need to used in order for fwknopd to see them. The
           default is to only sniff packets that are received on the sniffing interface. Note
           that this setting is independent of promiscuous mode.

       -R, --restart
           Restart the currently running fwknopd processes. This option will preserve the command
           line options that were supplied to the original fwknopd process but will force fwknopd
           to re-read the fwknopd.conf and /etc/fwknop/access.conf files. This will also force a
           flush of the current “FWKNOP” iptables chain(s).

       --rotate-digest-cache
           Rotate the digest cache file by renaming it to “<name>-old”, and starting a new one.
           The digest cache file is typically found in @runstatedir@/fwknop/digest.cache.

       -r, --run-dir=<path>
           Specify the directory where fwknopd writes run time state files. The default is
           @runstatedir@.

       -S, --status
           Display the status of any fwknopd processes that may or not be running. If there is an
           existing fwknopd process then 0 is returned for the exit status and 1 is returned
           otherwise.

       --syslog-enable
           Allow messages to be sent to syslog even if the foreground mode is set.

       -t, --test
           Run fwknopd in test mode. This instructs fwknopd to acquire and process SPA packets,
           but not manipulate firewall rules or execute commands that are provided by SPA
           clients. This option is mostly useful for the fuzzing tests in the test suite to
           ensure broad code coverage under adverse conditions.

       -U, --udp-server
           Run fwknopd in UDP server mode so that SPA packets are acquired via a UDP socket
           directly without having to use libpcap. See the discussion of the “ENABLE_UDP_SERVER”
           configuration variable below for more information.

       -v, --verbose
           Run fwknopd in verbose mode. This can option can be specified multiple times to
           increase the verbosity of the output to the system log file (or to the screen if
           running in the foreground).

       -h, --help
           Display usage information and exit.

       -V, --Version
           Display version information and exit.

FWKNOPD CONFIG AND ACCESS VARIABLES

       fwknopd references the /etc/fwknop/fwknopd.conf file for configuration variables to define
       operational parameters (what network interface and port to sniff, what features to
       enable/disable, etc.). The fwknopd.conf file does not define any access control directives
       or set any encryption or authentication keys.

       The access control directives are contained in the /etc/fwknop/access.conf file. Access
       control directives define encryption keys and level of access that is granted to an fwknop
       client that has generated the appropriate encrypted SPA message.

   FWKNOPD.CONF VARIABLES
       This section list the more prominent configuration variables used by fwknopd. You will
       want to make sure to check these to make sure they have appropriate values, but sensible
       defaults are provided for most systems. See the /etc/fwknop/fwknopd.conf file for
       additional details.

       PCAP_INTF <interface>
           Specify the ethernet interface on which fwknopd will sniff packets.

       ENABLE_PCAP_PROMISC <Y/N>
           By default fwknopd puts the pcap interface into promiscuous mode. Set this to “N” to
           disable that behavior (non-promiscuous).

       PCAP_FILTER <pcap filter spec>
           Define the filter used for PCAP modes; fwknopd defaults to UDP port 62201. However, if
           an fwknop client uses the --rand-port option to send the SPA packet over a random
           port, then this variable should be updated to something like “udp dst portrange
           10000-65535”.

       ENABLE_SPA_PACKET_AGING <Y/N>
           This instructs fwknopd to not honor SPA packets that have an old time stamp. The value
           for “old” is defined by the “MAX_SPA_PACKET_AGE” variable. If
           “ENABLE_SPA_PACKET_AGING” is set to “N”, fwknopd will not use the client time stamp at
           all.

       MAX_SPA_PACKET_AGE <seconds>
           Defines the maximum age (in seconds) that an SPA packet will be accepted. This
           requires that the client system is in relatively close time synchronization with the
           fwknopd server system (NTP is good). The default age is 120 seconds (two minutes).

       ENABLE_DIGEST_PERSISTENCE <Y/N>
           Track digest sums associated with previous SPA packets processed by fwknopd. This
           allows digest sums to remain persistent across executions of fwknopd. The default is
           “Y”. If set to “N”, fwknopd will not check incoming SPA packet data against any
           previously save digests. It is a good idea to leave this feature on to reduce the
           possibility of being vulnerable to a replay attack.

       RULES_CHECK_THRESHOLD <count>
           Defines the number of times firewall rule expiration times must be checked before a
           "deep" check is run. This allows fwknopd to remove rules that contain a proper
           exp<time> even if a third party program added them instead of fwknopd. The default
           value for this variable is 20, and this typically results in this check being run
           every two seconds or so. To disable this type of checking altogether, set this
           variable to zero.

       ENABLE_IPT_FORWARDING <Y/N>
           Allow SPA clients to request access to services through an iptables firewall instead
           of just to it (i.e. access through the FWKNOP_FORWARD chain instead of the INPUT
           chain).

       ENABLE_IPT_LOCAL_NAT <Y/N>
           Allow SPA clients to request access to a local socket via NAT. This still puts an
           ACCEPT rule into the FWKNOP_INPUT chain, but a different port is translated via DNAT
           rules to the real one. So, the user would do “ssh -p <port>” to access the local
           service (see the --NAT-local and --NAT-rand-port on the fwknop client command line).

       ENABLE_IPT_SNAT <Y/N>
           Set this to “Y” to enable a corresponding SNAT rule. By default, if forwarding access
           is enabled (see the “ENABLE_IPT_FORWARDING” variable above), then fwknopd creates DNAT
           rules for incoming connections, but does not also complement these rules with SNAT
           rules at the same time. In some situations, internal systems may not have a route back
           out for the source address of the incoming connection, so it is necessary to also
           apply SNAT rules so that the internal systems see the IP of the internal interface
           where fwknopd is running.

       SNAT_TRANSLATE_IP <ip_address>
           Specify the IP address for SNAT. This functionality is only enabled when
           “ENABLE_IPT_SNAT” is set to “Y” and by default SNAT rules are built with the
           MASQUERADE target (since then the internal IP does not have to be defined here in the
           /etc/fwknop/fwknopd.conf file), but if you want fwknopd to use the SNAT target, you
           must also define an IP address with the “SNAT_TRANSLATE_IP” variable. Note that this
           variable is generally deprecated in favor of the “FORCE_SNAT” variable in the
           /etc/fwknop/access.conf file which enables per-stanza control over the SNAT IP.

       ENABLE_IPT_OUTPUT <Y/N>
           Add ACCEPT rules to the FWKNOP_OUTPUT chain. This is usually only useful if there are
           no state tracking rules to allow connection responses out and the OUTPUT chain has a
           default-drop stance.

       MAX_SNIFF_BYTES <bytes>
           Specify the the maximum number of bytes to sniff per frame. 1500 is the default.

       FLUSH_IPT_AT_INIT <Y/N>
           Flush all existing rules in the fwknop chains at fwknopd start time. The default is
           “Y”.

       FLUSH_IPT_AT_EXIT <Y/N>
           Flush all existing rules in the fwknop chains when fwknopd is stopped or otherwise
           exits cleanly. The default is “Y”.

       EXIT_AT_INTF_DOWN <Y/N>
           When fwknopd is sniffing an interface, if the interface is administratively downed or
           unplugged, fwknopd will cleanly exit and an assumption is made that any process
           monitoring infrastructure like systemd or upstart will restart it. However, if fwknopd
           is not being monitored by systemd, upstart, or anything else, this behavior can be
           disabled with the “EXIT_AT_INTF_DOWN” variable. If disabled, fwknopd will try to
           recover when a downed interface comes back up.

       ENABLE_RULE_PREPEND <Y/N>
           For systems running iptables or firewalld, have fwknopd insert new SPA rules at the
           beginning of the relevant chain (such as “FWKNOP_INPUT”) instead of appending them to
           the end of the chain. This causes newly created rules to have precedence over older
           ones.

       ENABLE_NAT_DNS <Y/N>
           Allow fwknopd to resolve hostnames in NAT access messages.

       GPG_HOME_DIR <path>
           If GPG keys are used instead of a Rijndael symmetric key, this is the default GPG keys
           directory. Note that each access stanza in /etc/fwknop/access.conf can specify its own
           GPG directory to override this default. If not set here or in an access.conf stanza,
           then the $HOME/.gnupg directory of the user running fwknopd (most likely root).

       GPG_EXE <path>
           Specify the path to GPG, and defaults to /usr/bin/gpg if not set.

       LOCALE <locale>
           Set the locale (via the LC_ALL variable). This can be set to override the default
           system locale.

       ENABLE_SPA_OVER_HTTP <Y/N>
           Allow fwknopd to acquire SPA data from HTTP requests (generated with the fwknop client
           in --HTTP mode). Note that when this is enabled, the “PCAP_FILTER” variable would need
           to be updated to sniff traffic over TCP/80 connections and a web server should be
           running on the same server as fwknopd.

       ENABLE_X_FORWARDED_FOR <Y/N>
           Allows fwknopd to use the X-Forwarded-for header from a captured SPA packet over HTTP
           as the source IP. This can happen when using SPA through an HTTP proxy.

       ENABLE_TCP_SERVER <Y/N>
           Enable the fwknopd TCP server. This is a "dummy" TCP server that will accept TCP
           connection requests on the specified TCPSERV_PORT. If set to "Y", fwknopd will fork
           off a child process to listen for, and accept incoming TCP request. This server only
           accepts the request. It does not otherwise communicate. This is only to allow the
           incoming SPA over TCP packet which is detected via PCAP. The connection is closed
           after 1 second regardless. Note that fwknopd still only gets its data via pcap, so the
           filter defined by PCAP_FILTER needs to be updated to include this TCP port.

       TCPSERV_PORT <port>
           Set the port number that the “dummy” TCP server listens on. This server is only
           spawned when “ENABLE_TCP_SERVER” is set to “Y”.

       ENABLE_UDP_SERVER <Y/N>
           Enable the fwknopd UDP server. This instructs fwknopd to acquire SPA packets via a UDP
           socket directly without having to use libpcap. When this mode is enabled, fwknop
           should be compiled with --enable-udp-server (passed to the configure script) so that
           libpcap can be removed as a dependency. As one would expect, when the UDP server is
           used, no incoming packets are ever acknowledged by fwknopd and therefore collecting
           SPA packets in this mode is a good alternative to sniffing the wire directly.

       UDPSERV_PORT <port>
           Set the port number that the UDP server listens on. This server is only spawned when
           “ENABLE_UDP_SERVER” is set to “Y”.

       PCAP_DISPATCH_COUNT <count>
           Sets the number of packets that are processed when the pcap_dispatch() call is made.
           The default is zero, since this allows fwknopd to process as many packets as possible
           in the corresponding callback where the SPA handling routine is called for packets
           that pass a set of prerequisite checks. However, if fwknopd is running on a platform
           with an old version of libpcap, it may be necessary to change this value to a positive
           non-zero integer. More information can be found in the pcap_dispatch(3) man page.

       PCAP_LOOP_SLEEP <microseconds>
           Sets the number of microseconds to passed as an argument to usleep() in the pcap loop.
           The default is 100000, or 1/10th of a second.

       ENABLE_PCAP_ANY_DIRECTION <Y/N>
           Controls whether fwknopd is permitted to sniff SPA packets regardless of whether they
           are received on the sniffing interface or sent from the sniffing interface. In the
           later case, this can be useful to have fwknopd sniff SPA packets that are forwarded
           through a system and destined for a different network. If the sniffing interface is
           the egress interface for such packets, then this variable will need to be set to "Y"
           in order for fwknopd to see them. The default is "N" so that fwknopd only looks for
           SPA packets that are received on the sniffing interface (note that this is independent
           of promiscuous mode).

       SYSLOG_IDENTITY <identity>
           Override syslog identity on message logged by fwknopd. The defaults are usually ok.

       SYSLOG_FACILITY <facility>
           Override syslog facility. The “SYSLOG_FACILITY” variable can be set to

       ENABLE_DESTINATION_RULE <Y/N>
           Controls whether fwknopd will set the destination field on the firewall rule to the
           destination address specified on the incoming SPA packet. This is useful for
           interfaces with multiple IP addresses hosting separate services. If
           “ENABLE_IPT_OUTPUT” is set to “Y”, the source field of the firewall rule is set.
           FORWARD and SNAT rules are not affected however, DNAT rules will also have their
           destination field set. The default is “N”, which sets the destination field to
           0.0.0.0/0 (any).

       FWKNOP_RUN_DIR <path>
           Specify the directory where fwknopd writes run time state files. The default is
           @runstatedir@.

   ACCESS.CONF VARIABLES
       This section describes the access control directives in the /etc/fwknop/access.conf file.
       Theses directives define encryption and authentication keys, and the level of access that
       is granted to fwknop clients that have generated an appropriate encrypted and
       authenticated SPA packet.

       The access.conf variables described below provide the access directives for the SPA
       packets with a source (or embedded request) IP that matches an address or network range
       defined by the “SOURCE” variable. All variables following “SOURCE” apply to the source
       stanza. Each “SOURCE” directive starts a new stanza.

       SOURCE <IP,..,IP/NET,..,NET/ANY>
           This defines the source address from which the SPA packet will be accepted. The string
           “ANY” is also accepted if a valid SPA packet should be honored from any source IP.
           Every authorization stanza in /etc/fwknop/access.conf definition must start with the
           “SOURCE” keyword. Networks should be specified in CIDR notation (e.g.
           “192.168.10.0/24”), 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”)

       DESTINATION <IP,..,IP/NET,..,NET/ANY>
           This defines the destination address for which the SPA packet will be accepted. The
           string “ANY” is also accepted if a valid SPA packet should be honored to any
           destination IP. Networks should be specified in CIDR notation (e.g.
           “192.168.10.0/24”), 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”)

       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. If this entry is not set, fwknopd will attempt to honor any
           proto/port request specified in the SPA data (unless of it matches any
           “RESTRICT_PORTS” entries). Multiple entries are comma-separated.

       RESTRICT_PORTS <proto/port>,...,<proto/port>
           Define a set of ports and protocols (tcp or udp) that are explicitly not allowed
           regardless of the validity of the incoming SPA packet. Multiple entries are
           comma-separated.

       KEY <passphrase>
           Define the symmetric key used for decrypting an incoming SPA packet that is encrypted
           by the fwknop client with Rijndael. The actual encryption key that is used is derived
           from the standard PBKDF1 algorithm. This variable is required for all SPA packets
           unless GnuPG is used instead (see the GPG variables below).

       KEY_BASE64 <base64 encoded passphrase>
           Same as the KEY option above, but specify the symmetric key as a base64 encoded
           string. This allows non-ascii characters to be included in the base64-decoded key.

       HMAC_KEY <key>
           Specify the HMAC key for authenticated encryption of SPA packets. This supports both
           Rijndael and GPG encryption modes, and is applied according to the
           encrypt-then-authenticate model.

       HMAC_KEY_BASE64 <base64 encoded key>
           Specify the HMAC key as a base64 encoded string. This allows non-ascii characters to
           be included in the base64-decoded key.

       FW_ACCESS_TIMEOUT <seconds>
           Define the length of time access will be granted by fwknopd 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 30 seconds will automatically be set.

       %include <file>
           Have fwknopd import an additional access.conf file. This allows more access stanzas to
           be defined in other locations in the filesystem, and this can be advantageous in some
           scenarios by letting non-privileged users define their own encryption and
           authentication keys for SPA operations. This way, users do not need write access to
           the main /etc/fwknop/access.conf file to change keys around or define new ones.

       %include_folder <directory>
           Similarly to the %include option above, the %include_folder directive has fwknopd
           import all .conf files from the specified directory. There is also command line
           support for this via the access-folder option.

       ENCRYPTION_MODE <mode>
           Specify the encryption mode when AES is used. The default is CBC mode, but other modes
           can be selected such as OFB and CFB. In general, it is recommended to not use this
           variable and leave it as the default. Note that the string “legacy” can be specified
           in order to generate SPA packets with the old initialization vector strategy used by
           versions of fwknop before 2.5. With the 2.5 release, fwknop uses PBKDF1 for key
           derivation.

       HMAC_DIGEST_TYPE <digest algorithm>
           Specify the digest algorithm for incoming SPA packet authentication. Must be one of
           MD5, SHA1, SHA256, SHA384, SHA512, SHA3_256, or SHA3_512. This is an optional field,
           and if not specified then fwknopd defaults to using SHA256 if the access stanza
           requires an HMAC.

       ACCESS_EXPIRE <MM/DD/YYYY>
           Defines an expiration date for the access stanza in MM/DD/YYYY format. All SPA packets
           that match an expired stanza will be ignored. This parameter is optional.

       ACCESS_EXPIRE_EPOCH <seconds>
           Defines an expiration date for the access stanza as the epoch time, and is useful if a
           more accurate expiration time needs to be given than the day resolution offered by the
           ACCESS_EXPIRE variable above. All SPA packets that match an expired stanza will be
           ignored. This parameter is optional.

       ENABLE_CMD_EXEC <Y/N>
           This instructs fwknopd to accept complete commands that are contained within an
           authorization packet. Any such command will be executed on the fwknopd server as the
           user specified by the “CMD_EXEC_USER” or as the user that started fwknopd if that is
           not set.

       ENABLE_CMD_SUDO_EXEC <Y/N>
           sudo provides a powerful means of restricting the sets of commands that users can
           execute via the “sudoers” file. By enabling this feature (and in “ENABLE_CMD_EXEC”
           mode), all incoming commands from valid SPA packets will be prefixed by “/path/to/sudo
           -u <user> -g <group>” where the path to sudo is set by the “SUDO_EXE” variable,
           “<user>” is set by the “CMD_SUDO_EXEC_USER” variable (default is “root” if not set),
           and “<group>” is set by “CMD_SUDO_EXEC_GROUP” (default is also “root” if not set).

       CMD_EXEC_USER <username>
           Specify the user (via setuid) that will execute a command contained within a SPA
           packet. If this variable is not given, fwknopd will execute the command as the user it
           is running as (most likely root). Setting this to a non-root user such as “nobody” is
           highly recommended if elevated permissions are not needed.

       CMD_SUDO_EXEC_USER <username>
           Specify the user (via “sudo -u <user>”) that will execute a command contained within a
           SPA packet. If this variable is not given, fwknopd will assume the command should be
           executed as root.

       CMD_EXEC_GROUP <groupname>
           Specify the group (via setgid) that will execute a command contained within a SPA
           packet. If this variable is not given, fwknopd will execute the command as the user it
           is running as (most likely root). Setting this to a non-root user such as “nobody” is
           highly recommended if elevated permissions are not needed.

       CMD_SUDO_EXEC_GROUP <groupname>
           Specify the group (via “sudo -g <group>”) that will execute a command contained within
           a SPA packet. If this variable is not given, fwknopd will assume the command should be
           executed as root.

       CMD_CYCLE_OPEN <command>
           Specify a command open/close cycle to be executed upon receipt of a valid SPA packet.
           This directive sets the initial command, and is meant to be used in conjunction with
           the “CMD_CYCLE_CLOSE” variable below. The main application of this feature is to allow
           fwknopd to interact with firewall or ACL’s that are not natively supported, and
           facilitate the same access model as for the main supported firewalls such as iptables.
           That is, a command is executed to open the firewall or ACL, and then a corresponding
           close command is executed after a timer expires. Both the “CMD_CYCLE_OPEN” and
           “CMD_CYCLE_CLOSE” variables support special substitution strings to allow values to be
           taken from the SPA payload and used on the command line of the executed command. These
           strings begin with a “$” character, and include “$IP” (the allow IP decrypted from the
           SPA payload), “$SRC” (synonym for “$IP”) , “$PKT_SRC” (the source IP in the network
           layer header of the SPA packet), “$DST” (the destination IP), “$PORT” (the allow
           port), and “$PROTO” (the allow protocol), “$TIMEOUT” (set the client timeout if
           specified).

       CMD_CYCLE_CLOSE <command>
           Specify the close command that corresponds to the open command set by the
           “CMD_CYCLE_OPEN” variable described above. The same string substitutions such as
           “$IP”, “$PORT”, and “$PROTO” are supported. In addition, the special value “NONE” can
           be set to allow no close command to be executed after the open command. This might be
           handy in certain situations where, say, indefinite access is desired and allowed.

       CMD_CYCLE_TIMER <seconds>
           Set the number of seconds after which the close command set in “CMD_CYCLE_CLOSE” will
           be executed. This defines the open/close timer interval.

       SUDO_EXE <path>
           Define the path to the sudo binary. Default is “/usr/bin/sudo”.

       REQUIRE_USERNAME <username>
           Require a specific username from the client system as encoded in the SPA data. This
           variable is optional and if not specified, the username data in the SPA data is
           ignored.

       REQUIRE_SOURCE_ADDRESS <Y/N>
           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 fwknop client 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 and set it via the -a
           argument.

       REQUIRE_SOURCE_ADDRESS <Y/N>
           Synonym for “REQUIRE_SOURCE_ADDRESS”.

       FORCE_NAT <IP> <PORT>
           For any valid SPA packet, force the requested connection to be NAT’d through to the
           specified (usually internal) IP and port value. This is useful if there are multiple
           internal systems running a service such as SSHD, and you want to give transparent
           access to only one internal system for each stanza in the access.conf file. This way,
           multiple external users can each directly access only one internal system per SPA key.

       FORCE_SNAT <IP>
           For any valid SPA packet, add an SNAT rule in addition to any DNAT rule created with a
           corresponding (required) FORCE_NAT variable. This is analogous to “SNAT_TRANSLATE_IP”
           from the /etc/fwknop/fwknopd.conf file except that it is per access stanza and
           overrides any value set with “SNAT_TRANSLATE_IP”. This is useful for situations where
           an incoming NAT’d connection may be otherwise unanswerable due to routing constraints
           (i.e. the system receiving the SPA authenticated connection has a default route to a
           different device than the SPA system itself).

       FORCE_MASQUERADE <Y/N>
           This is similar to the “FORCE_SNAT” variable, except that it is not necessary to also
           specify an IP address for SNAT rules because the MASQUERADE target is used instead.

       FORWARD_ALL <Y/N>
           In NAT scenarios, control whether all traffic is forwarded through the fwknopd system
           as opposed to just forwarding connections to specific services as requested by the
           fwknop client.

       DISABLE_DNAT <Y/N>
           Control whether DNAT rules are created in FORCE_NAT scenarios. This is mainly used in
           conjunction with the FORWARD_ALL variable to allow fwknopd to act essentially as an
           SPA gateway. I.e., the fwknop client is used to gain access via SPA to the broader
           Internet after being granted an IP via DHCP, but prior to sending the SPA packet all
           traffic is blocked by default to the Internet.

       GPG_DECRYPT_ID <keyID>
           Define a GnuPG key ID to use for decrypting SPA messages that have been encrypted by
           an fwknop client. This keyword is required for authentication that is based on GPG
           keys. The GPG key ring on the client must have imported and signed the 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 /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: “http://www.cipherdyne.org/fwknop/docs/gpghowto.html”.

       GPG_DECRYPT_PW <decrypt password>
           Specify the decryption password for the gpg key defined by the “GPG_DECRYPT_ID” above.
           This is a required field for gpg-based authentication.

       GPG_ALLOW_NO_PW <Y/N>
           Allow fwknopd to leverage a GnuPG key pair that does not have an associated password.
           While this may sound like a controversial deployment mode, in automated environments
           it makes sense because "there is usually no way to store a password more securely than
           on the secret keyring itself" according to:
           “http://www.gnupg.org/faq/GnuPG-FAQ.html#how-can-i-use-gnupg-in-an-automated-environment”.
           Using this feature and removing the passphrase from a GnuPG key pair is useful in some
           environments where libgpgme is forced to use gpg-agent and/or pinentry to collect a
           passphrase.

       GPG_REQUIRE_SIG <Y/N>
           With this setting set to Y, fwknopd check all GPG-encrypted SPA messages for a
           signature (signed by the sender’s key). If the incoming message is not signed, the
           decryption process will fail. If not set, the default is Y.

       GPG_DISABLE_SIG <Y/N>
           Disable signature verification for incoming SPA messages. This is not a recommended
           setting, and the default is N.

       GPG_IGNORE_SIG_VERIFY_ERROR <Y/N>
           Setting this will allow fwknopd to accept incoming GPG-encrypted packets that are
           signed, but the signature did not pass verification (i.e. the signer key was expired,
           etc.). This setting only applies if the GPG_REQUIRE_SIG is also set to Y.

       GPG_REMOTE_ID <keyID,...,keyID>
           Define a list of gpg key ID’s that are required to have signed any incoming SPA
           message that has been encrypted with the fwknopd server key. This ensures that the
           verification of the remote user is accomplished via a strong cryptographic mechanism.
           Signature verification is enabled by default, and can only be disabled if
           “GPG_DISABLE_SIG” is set to Y (not a recommended setting). Separate multiple entries
           with a comma.

       GPG_FINGERPRINT_ID <keyID,...,keyID>
           Specify a set of full-length GnuPG key fingerprints instead of the shorter key
           identifiers set with the “GPG_REMOTE_ID” variable. Here is an example fingerprint for
           one of the fwknop test suite keys: 00CC95F05BC146B6AC4038C9E36F443C6A3FAD56.

       GPG_HOME_DIR <path>
           Define the path to the GnuPG directory to be used by the fwknopd server. If this
           keyword is not specified within /etc/fwknop/access.conf then fwknopd will default to
           using the /root/.gnupg directory for the server key(s) for incoming SPA packets
           handled by the matching access.conf stanza.

       GPG_EXE <path>
           Define the path to the GnuPG executable. If this keyword is not specified within
           /etc/fwknop/access.conf then fwknopd will default to using /usr/bin/gpg.

FILES

       /etc/fwknop/fwknopd.conf
           The main configuration file for fwknop.

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

DEPENDENCIES

       fwknopd requires libfko which is normally included with both source and binary
       distributions, and is a dedicated library developed by the fwknop project.

       For packet sniffing, fwknopd currently requires libpcap, but future versions will
       (optionally) remove this as a dependency.

       For GPG functionality, GnuPG must also be correctly installed and configured along with
       the libgpgme library.

       To take advantage of all of the authentication and access management features of the
       fwknopd daemon/service a functioning iptables, ipfw, or pf firewall is required on the
       underlying operating system.

DIAGNOSTICS

       fwknopd can be run in debug mode by combining the -f, --foreground and the -v, --verbose
       command line options. This will disable daemon mode execution, and print verbose
       information to the screen on stderr as packets are received.

       The most comprehensive way to gain diagnostic information on fwknopd is to run the test
       suite test-fwknop.pl script located in the test/ directory in the fwknop sources. The test
       suite runs sends fwknop through a large number of run time tests, has valgrind support,
       validates both SPA encryption and HMAC results against OpenSSL, and even has its own built
       in fuzzer for SPA communications.

SEE ALSO

       fwknopd(8), iptables(8), pf(4), pfctl(8), ipfw(8), gpg(1), libfko documentation.

       More information on Single Packet Authorization can be found in the paper “Single Packet
       Authorization with fwknop” available at http://www.cipherdyne.org/fwknop/docs/SPA.html. A
       comprehensive tutorial on fwknop operations and theory can be found at
       http://www.cipherdyne.org/fwknop/docs/fwknop-tutorial.html. This tutorial also includes
       information about the design of fwknop that may be worth reading for those interested in
       why fwknop is different from other SPA implementations.

       fwknop uses the git versioning system as its source code repository along with Github for
       tracking of issues and milestones:

               $ git clone https://github.com/mrash/fwknop.git fwknop.git

       Additional commentary on Single Packet Authorization can be found via Michael Rash’s
       Twitter feed: http://twitter.com/michaelrash, @michaelrash

AUTHORS

       The primary developers of fwknop are Michael Rash (project creator) <mbr@cipherdyne.org>,
       Damien Stuart <dstuart@dstuart.org>, and Jonathan Bennett <jbennett@incomsystems.biz>.

CONTRIBUTORS

       This “C” version of fwknop was derived from the original Perl-based version on which many
       people who are active in the open source community have contributed. See the CREDITS file
       in the fwknop sources, or visit https://github.com/mrash/fwknop/blob/master/CREDITS to
       view the online list of contributors. A few contributors deserve to be singled out
       including: Franck Joncourt, Max Kastanas, Vlad Glagolev, Sean Greven, Hank Leininger,
       Fernando Arnaboldi, and Erik Gomez.

       The phrase “Single Packet Authorization” was coined by MadHat and Simple Nomad at the
       BlackHat Briefings of 2005.

BUGS

       Send bug reports to dstuart@dstuart.org or mbr@cipherdyne.org, or open a new issue on
       Github (see https://github.com/mrash/fwknop.git). Suggestions and/or comments are always
       welcome as well. Additional information may be found in the fwknop mailing list archives
       (see: https://lists.sourceforge.net/lists/listinfo/fwknop-discuss).

DISTRIBUTION

       fwknopd is distributed under the GNU General Public License (GPL v2+), and the latest
       version may be downloaded from http://www.cipherdyne.org.