[fwknop.git] / server / fwknopd.conf

#
##############################################################################
#
#         [+] fwknopd - Firewall Knock Operator Daemon [+]
#
# This is the configuration file for fwknopd, the Firewall Knock Operator
# daemon.  The primary authentication and authorization mechanism offered
# by fwknop is known as Single Packet Authorization (SPA).  More information
# about SPA can be found at: http://www.cipherdyne.org/fwknop/docs/SPA.html
#
# There are no access control directives in this file.  All access
# control directives are located in the file "/etc/fwknop/access.conf".
# You will need to edit the access.conf file in order for fwknop to function
# correctly.
#
# Most of these can remain commented out unless you need to overide the
# default setting.
#
# It is also important to note that there are some subtle (and some not
# so subtle) differences between this configuration file, its parameters
# and valid values and the configuration file used by the legacy Perl
# version  of fwknopd.  Please pay careful attention to the format and
# values used in this file if you are migrating from the legacy Perl
# version.
#
##############################################################################
#

# Define the ethernet interface on which we will sniff packets.
# Default if not set is eth0.
#
#PCAP_INTF                   eth0;

# By default fwknopd does not put the pcap interface into promiscuous mode.
# Set this to 'Y' to enable promiscuous sniffing.
#
#ENABLE_PCAP_PROMISC         N;

# Define the filter used for PCAP modes; we default 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;".
# Default is "udp port 62201".
#
#PCAP_FILTER                 udp port 62201;

# 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.
#
#ENABLE_SPA_PACKET_AGING     Y;

# 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 two minutes.
#
#MAX_SPA_PACKET_AGE          120;

# Track digest sums associated with previous fwknop process.  This allows
# digest sums to remain persistent across executions of fwknop.
#
#ENABLE_DIGEST_PERSISTENCE   Y;

# 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_DISPATCH_COUNT            0;

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

# 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_FORWARDING       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_LOCAL_NAT        Y;

# By default, if forwarding access is enabled (see the ENABLE_IPT_FORWARDING
# variable above), then fwknop 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.  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 fwknop.conf file), but if you want fwknopd to use the
# SNAT target then also defined an IP address with the SNAT_TRANSLATE_IP
# variable.
#
#ENABLE_IPT_SNAT             N;
#SNAT_TRANSLATE_IP           __CHANGEME__;

# 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.
#
#ENABLE_IPT_OUTPUT           N;

# Specify the the maximum number of bytes to sniff per frame - 1500
# is a good default
#
#MAX_SNIFF_BYTES             1500;

# Flush all existing rules in the fwknop chains at fwknop start time and/or
# exit time. They default to Y and it is recommended setting for both.
#
#FLUSH_IPT_AT_INIT           Y;
#FLUSH_IPT_AT_EXIT           Y;

# If GPG keys are used instead of a Rijndael symmetric key, this is
# the default GPG keys directory.  Note that each access block in
# fwknop access.conf can specify its own GPG directory to override
# this default.
#
#GPG_HOME_DIR        /root/.gnupg;

# Allow fwknopd to acquire SPA data from HTTP requests (generated with the
# fwknop client in --HTTP mode).  Note that the PCAP_FILTER variable would
# need to be updated when this is enabled to sniff traffic over TCP/80
# connections
#
#ENABLE_SPA_OVER_HTTP        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.
#
#ENABLE_TCP_SERVER           N;
#TCPSERV_PORT                62201;

# Set/override the locale (via the LC_ALL locale category).  Leave this
# entry commented out to  have fwknopd honor the default system locale.
#
#LOCALE                      C;

# Override syslog identity and facility (the defaults are usually ok).
# The SYSLOG_FACILITY variable can be set to one of LOG_LOCAL{0-7}
# or LOG_DAEMON (the default).
#
#SYSLOG_IDENTITY             fwknopd;
#SYSLOG_FACILITY             LOG_DAEMON;

##############################################################################
# NOTE: The following EXTERNAL_CMD functionality is not yet implemented.
#       This is a possible future feature of fwknopd.
#
# The following four variables control whether a global set of "open" and
# "close" commands are executed after receving a valid SPA packet.  These
# variables are used only if FIREWALL_TYPE is set to "external_cmd", but
# the same variables can also exist within the access.conf file so that
# mixed deployments are possible - that is, some SPA packets will operate
# as usual and result in firewall commands being executed, but others will
# result in the commands defined by these variables (in access.conf) being
# executed.
#     The "open" and "close" commands might be manually supplied firewall
# commands, and both support variable substitution of any of the variables
# in the access.conf file with "$VAR".  Also, three special variables are
# supported: $SRC, $PORT, and $PROTO, which are derived from actual values
# from within valid SPA packets (as opposed to $SOURCE from access.conf
# which may contain a list of networks instead of a single IP address).
# Here are some examples:
#     - Execute a specific iptables command on behalf of the source IP
#     in a valid SPA packet to add a new ACCEPT rule, and execute
#     another command (to delete the same rule after a timeout):
#         EXTERNAL_CMD_OPEN       iptables -A INPUT -s $SRC -j ACCEPT
#         EXTERNAL_CMD_CLOSE      iptables -D INPUT -s $SRC -j ACCEPT
#     - Execute a custom binary with the SOURCE and OPEN_PORTS variables
#     from the access.conf file as input on the command line, and after
#     a timeout execute a different program but use the real SPA source
#     IP:
#         EXTERNAL_CMD_OPEN       /path/someprog $SOURCE $OPEN_PORTS
#         EXTERNAL_CMD_OPEN       /path/otherprog $SRC
#
#ENABLE_EXTERNAL_CMDS        N;
#EXTERNAL_CMD_OPEN           __NONE__;
#EXTERNAL_CMD_CLOSE          __NONE__;
#EXTERNAL_CMD_ALARM          30;

# if EXTERNAL_CMD_OPEN is used above, then the following two variables can
# be used to enforce a prefix on variable substitutions - useful if there
# are any naming conflicts with the external script and command line
# arguments that are named the same as the variables to be substituted.
#
#ENABLE_EXT_CMD_PREFIX       N;
#EXT_CMD_PREFIX              FWKNOP_;

##############################################################################
# Parameters specific to iptables:
#
# fwknopd adds allow rules to a custom iptables chain "FWKNOP_INPUT".
# This chain is called from the INPUT chain, and by default no other
# iptables chains are used.  However, additional chains can be added
# (say, if access needs to be allowed through the local system via the
# FORWARD chain) by altering the IPT_FORWARD_ACCESS variable below.
# For a discussion of the format followed by these keywords, read on:
#
# Specify chain names to which iptables blocking rules will be
# added with the IPT_INPUT_ACCESS and IPT_FORWARD_ACCESS keyword.
# The format for these variables is:
#
#   <Target>,<Direction>,<Table>,<From_chain>,<Jump_rule_position>,\
#       <To_chain>,<Rule_position>.
#
# "Target":
#   Can be any legitimate iptables target, but should usually just be "DROP".
#
# "Table":
#   Can be any iptables table, but the default is "filter".
#
# "From_chain":
#   Is the chain from which packets will be jumped.
#
# "Jump_rule_position":
#   Defines the position within the From_chain where the jump rule is added.
#
# "To_chain":
#   Is the chain to which packets will be jumped. This is the main chain
#   where fwknop rules are added.
#
# "Rule_position":
#   Defines the position where rule are added within the To_chain.
#
#IPT_INPUT_ACCESS        ACCEPT, filter, INPUT, 1, FWKNOP_INPUT, 1;

# The IPT_OUTPUT_ACCESS variable is only used if ENABLE_IPT_OUTPUT is enabled
#
#IPT_OUTPUT_ACCESS       ACCEPT, filter, OUTPUT, 1, FWKNOP_OUTPUT, 1;

# The IPT_FORWARD_ACCESS variable is only used if ENABLE_IPT_FORWARDING is
# enabled.
#
#IPT_FORWARD_ACCESS      ACCEPT, filter, FORWARD, 1, FWKNOP_FORWARD, 1;
#IPT_DNAT_ACCESS         DNAT, nat, PREROUTING, 1, FWKNOP_PREROUTING, 1;

# The IPT_SNAT_ACCESS variable is not used unless both ENABLE_IPT_SNAT and
# ENABLE_IPT_FORWARDING are enabled.  Also, the external static IP must be
# set with the SNAT_TRANSLATE_IP variable.  The default is to use the
# IPT_MASQUERADE_ACCESS variable.
#
#IPT_SNAT_ACCESS         SNAT, nat, POSTROUTING, 1, FWKNOP_POSTROUTING, 1;
#IPT_MASQUERADE_ACCESS   MASQUERADE, nat, POSTROUTING, 1, FWKNOP_POSTROUTING, 1;

##############################################################################
# Parameters specific to ipfw:
#
#
# This variable defines the rule number that fwknopd uses to insert an ipfw
# pass rule.  You would most likely want to change this parameter to a
# number that makes sense in your current ipfw firewall configuration.
#
#IPFW_START_RULE_NUM         10000;

# This variable defines the maximum number of rules fwknopd will create at
# a time. This also tells fwknopd where to stop when flushing all rules.
#
#IPFW_MAX_RULES              1000;

# This variable defines the rule set fwknopd uses for active rules. By
# default, it is set 0, but can be set to any number between 0 and 31 in
# case you want to keep fwknopd generated rules segregated from the default
# ruleset.
#
#IPFW_ACTIVE_SET_NUM         1;

# This variable defines the rule set that will be used to store expired rules
# that still have a dynamic rule associated to them. That set will be disabled
# by fwknop and should not be enabled while fwknop is running. Not used when
# ipfw isn't using dynamic rules.
#
#IPFW_EXPIRE_SET_NUM         2;

# Set the interval (in seconds) over which rules that are expired and
# have no remaining dynamic rules associated with them will be removed.
#
#IPFW_EXPIRE_PURGE_INTERVAL  30;

# Set this variable to "Y" if you want fwknopd to create its own "check-state"
# rule as the first rule in the set.  This would only be needed if there
# was not already a check-state rule in the current firewall configuration.
#
# IPFW_ADD_CHECK_STATE       N;

##############################################################################
# Parameters specific to the pf firewall:
#
#
# This variable defines the pf anchor name to which fwknopd will add and
# delete rules.  This anchor must be linked into the pf policy (typically
# done by adding it into the /etc/pf.conf file), and fwknopd runs a check at
# init time to ensure that the anchor exists.
#
#PF_ANCHOR_NAME             fwknop;

# Set the interval (in seconds) over which rules that are expired
#
#PF_EXPIRE_INTERVAL         30;


# Directories - These can override compile-time defaults.
#
#FWKNOP_RUN_DIR              /var/run/fwknop;
#FWKNOP_CONF_DIR             /etc/fwknop;

# Files
#
#ACCESS_FILE                 access.conf;
#FWKNOP_PID_FILE             $FWKNOP_RUN_DIR/fwknopd.pid;
#DIGEST_FILE                 $FWKNOP_RUN_DIR/digest.cache;
### The DB version is only used if fwknopd was built with gdbm/ndbm
### support (not needed by default).
#DIGEST_DB_FILE              $FWKNOP_RUN_DIR/digest_db.cache;

# System binaries
#
#FIREWALL_EXE                /sbin/iptables;

###EOF###