Configuration file format
*************************


Main configuration
==================

Example config:

   # Log warnings and errors to stderr
   log level warn;

   # Log everything to syslog
   log to syslog level debug;

   # Set the interface name
   interface "mesh-vpn";

   # Support salsa2012+umac and null methods, prefer salsa2012+umac
   method "salsa2012+umac";
   method "null";

   # Bind to a fixed port, IPv4 only
   bind 0.0.0.0:10000;

   # Secret key generated by `fastd --generate-key`
   secret "78dfb05fe0aa586fb017de566b0d21398ac64032fcf1c765855f4d538cc5a357";

   # Set the interface MTU for TAP mode with xsalsa20/aes128 over IPv4 with a base MTU of 1492 (PPPoE)
   # (see MTU selection documentation)
   mtu 1426;

   # Include peers from the directory 'peers'
   include peers from "peers";

   "bind <IPv4 address>[:<port>] [ interface "<interface>" ] [ default [ ipv4 ] ];"
   "bind <IPv6 address>[:<port>] [ interface "<interface>" ] [ default [ ipv6 ] ];"
   "bind any[:<port>] [ interface "<interface>" ] [ default [ ipv4|ipv6 ] ];"
   "bind <IPv4 address> [port <port>] [ interface "<interface>" ] [ default [ ipv4 ] ];"
   "bind <IPv6 address> [port <port>] [ interface "<interface>" ] [ default [ ipv6 ] ];"
   "bind any [port <port>] [ interface "<interface>" ] [ default [ ipv4|ipv6 ] ];"

   Sets the bind address, port and possibly interface. May be
   specified multiple times. The keyword any makes fastd bind to the
   unspecified address for both IPv4 and IPv6.

   IPv6 address must be put in square brackets. It is possible to
   specify an IPv6 link-local address with an interface in the usual
   notation (e.g. [fe80::1%eth0]).

   The default option makes it the default address for outgoing
   connections for IPv4, IPv6 or both.

   When an address with port 0 is configured, a random port will be
   selected, which will not change as long as fastd is running.

   When the port is omitted completely, a new socket with a random
   port will be created for each outgoing connection. This has the
   side effect that the options for packet marks and interface-
   specific binds (except IPv6 link-local addresses) will only work
   with the "CAP_NET_ADMIN" capability. If fastd is built with
   capability support, it will automatically retain these
   capabilities; otherwise, fastd must run as root.

   Configuring no bind address at all is equivalent to the setting
   "bind any", meaning fastd will use a random port for each outgoing
   connection both for IPv4 and IPv6.

   "cipher "<cipher>" use "<implementation>";"

   Chooses a specific impelemenation for a cipher. Normally, the
   default setting is already the best choice. Note that specific
   implementations may be unavailable on some platforms or disabled
   during compilation. The available ciphers and implementations are:

   * "aes128-ctr": AES128 in counter mode

     * "openssl": Use implementation from OpenSSL's libcrypto

   * "null": No encryption (for authenticated-only methods using
     composed_gmac)

     * "memcpy": Simple memcpy-based implementation

   * "salsa20": The Salsa20 stream cipher

     * "xmm": Optimized implementation for x86/amd64 CPUs with SSE2
       support

     * "nacl": Use implementation from NaCl or libsodium

   * "salsa2012": The Salsa20/12 stream cipher

     * "xmm": Optimized implementation for x86/amd64 CPUs with SSE2
       support

     * "nacl": Use implementation from NaCl or libsodium

   "drop capabilities yes|no|early|force;"

   By default, fastd switches to the configured user and/or drops its
   POSIX capabilities after the on-up command has been run. When drop
   capabilities is set to *early*, the on-up command is run after the
   privileges have been dropped, when set to *no*, the POSIX
   capabilities aren't dropped at all (but the user is switched after
   the on-up command has been run nevertheless).

   fastd automatically detects which capabilities are required for
   normal operation and retains these capabilities. This can be
   overridden using the *force* value (this may make sense if
   persistent TUN/TAP interfaces are used which may be used without
   special privileges by fastd.)

   "forward yes|no;"

   Enables or disabled forwarding packets between peers. Care must be
   taken not to create forwarding loops.

   "group "<group>";"

   Sets the group to run fastd as.

   "hide ip addresses yes|no;"

   Hides IP addresses in log output.

   "hide mac addresses yes|no;"

   Hides MAC addresses in log output.

   "include "<file>";"

   Includes another configuration file. Relative paths are interpreted
   relatively to the including file.

   "include peer "<file>" [ as "<name>" ];"

   Includes a peer configuration (and optionally gives the peer a
   name).

   "include peers from "<dir>";"

   Includes each file in a directory as a peer configuration. These
   peers are reloaded when fastd receives a SIGHUP signal.

   "interface "<name>";"

   Sets the name of the TUN/TAP interface to use; it will be set by
   the OS when no name is configured explicitly.

   In TUN/multi-TAP mode, either peer-specific interface names need to
   be configured, or one (but not both) of the following patterns must
   be used to set a unique interface name for each peer:

   * "%n": The peer's name

   * "%k": The first 16 hex digits of the peer's public key

   "log level fatal|error|warn|info|verbose|debug|debug2;"

   Sets the default log level, meaning syslog if there is currently a
   level set for syslog, and stderr otherwise.

   "log to stderr level fatal|error|warn|info|verbose|debug|debug2;"

   Sets the stderr log level. By default no log messages are printed
   on stderr, unless no other log destination is configured, which
   causes fastd to log to stderr with level info.

   "log to syslog [ as "<ident>" ] [ level fatal|error|warn|info|verbose|debug|debug2 ];"

   Sets the syslog log level. By default syslog isn't used.

   "mac "<MAC>" use "<implementation>";"

   Chooses a specific impelemenation for a message authentication
   code. Normally, the default setting is already the best choice.
   Note that specific implementations may be unavailable on some
   platforms or disabled during compilation. The available MACs and
   implementations are:

   * "ghash": The MAC used by the GCM and GMAC methods

     * "pclmulqdq": An optimized implementation for modern x86/amd64
       CPUs supporting the PCLMULQDQ instruction

     * "builtin": A generic implementation

   * "uhash": The MAC used by the UMAC methods

     * "builtin": A generic implementation

   "method "<method>";"

   Sets the encryption/authentication method. See the page Encryption
   & authentication methods for more information about the supported
   methods. When multiple method statements are given, the first one
   has the highest preference.

   "mode tap|multitap|tun;"

   Sets the mode of the interface; the default is TAP mode.

   In TAP mode, a single interface will be created for all peers, in
   multi-TAP and TUN mode, each peers gets its own interface.

   "mtu <MTU>;"

   Sets the MTU; must be at least 576. You should read the page MTU
   configuration as the default 1500 is suboptimal in most setups.

   "offload l2tp yes|no;"

   Use the L2TP kernel implementation for the "null@l2tp" method.
   Enabling offloading allows for significantly higher throughput, as
   data packets don't need to be copied between kernel and userspace.

   L2TP offloading is only avaiable when the following conditions are
   met:

   * A Linux kernel with L2TP Ethernet Pseudowire support is
     required

   * L2TP offloading must be enabled in the fastd build (default on
     Linux)

   * "mode" must be set to "multitap"

   * "persist interface" must be set to "no"

   Using the multi-TAP mode can be inconvenient with high numbers of
   peers, as it will create a separate network interface for each
   peer. As peers in TAP and multi-TAP modes can communicate with each
   other, using TAP mode without offloading on a powerful server, but
   multi-TAP on weak devices that only establish a single connection
   anyways is an option that combines convenience with high
   performance.

   Using L2TP offloading requires fastd to set the *SO_REUSEADDR* flag
   flag on its sockets. This allows other local users to open a socket
   with the same address/port combination, making it possible to
   monitor and inject traffic on such unencrypted connections without
   special privileges. For this reason, using a privileged bind port
   (below 1024) is recommended when using the offload feature on hosts
   shared with other users.

   "on pre-up [ sync | async ] "<command>";"
   "on up [ sync | async ] "<command>";"
   "on down [ sync | async ] "<command>";"
   "on post-down [ sync | async ] "<command>";"
   "on connect [ sync | async ] "<command>";"
   "on establish [ sync | async ] "<command>";"
   "on disestablish [ sync | async ] "<command>";"

   Configures a shell command that is run after the interface is
   created, before the interface is destroyed, when a handshake is
   sent to make a new connection, when a new peer connection has been
   established, or after a peer connection has been lost. fastd will
   block until the command has finished, to long-running processes
   should be started in the background.

   pre-up, up, down and post-down commands are executed synchronously
   by default, meaning fastd will block until the commands have
   finished, while the other commands are executed asynchronously by
   default. This can be changed using the keywords sync and async.

   All commands except pre-up and post-down may be overriden per peer
   group.

   The following environment variables are set by fastd for all
   commands:

      * "FASTD_PID": fastd's PID

      * "INTERFACE": the interface name

      * "INTERFACE_MTU": the configured MTU

      * "LOCAL_KEY": the local public key

   For on connect, on establish and on disestablish the following
   variables are set in addition:

      * "LOCAL_ADDRESS": the local IP address

      * "LOCAL_PORT": the local UDP port

      * "PEER_ADDRESS": the peer's IP address

      * "PEER_PORT": the peer's UDP port

      * "PEER_NAME": the peer's name in the local configuration

      * "PEER_KEY": the peer's public key

   "on verify [ sync | async ] "<command>";"

   Configures a shell command that is run on connection attempts by
   unknown peers. The same environment variables as in the on
   establish command are supplied. When the commands returns 0, the
   connection is accepted, otherwise the handshake is ignored. By
   default, fastd ignores connections from unknown peers.

   Verify commands are executed asynchronously by default. This can be
   changed using the keywords sync and async.

   The on-verify command my be put into a peer group to define which
   peer group unknown peers are added to. This may be used to apply a
   peer limit only to unknown peers.

   "packet mark <mark>;"

   Defines a packet mark to set on fastd's packets, which can be used
   in an ip rule.

   Marks can be specified in decimal, hexadecimal (with a leading 0x),
   and octal (with a leading 0).

   "peer "<name>" {" *peer configuration* "}"

   An inline peer configuration.

   "peer group "<name>" {" *configuration* "}"

   Configures a peer group.

   "peer limit <limit>;"

   Sets the maximum number of connections for the current peer group.

   "persist interface yes|no;"

   If set to *no*, fastd will create peer-specific interfaces only as
   long as there's an active session with the peer. Does not have an
   effect in TUN mode.

   By default, interfaces are persistent.

   "pmtu yes|no|auto;"

   Does nothing; the "pmtu" option is only supported for compatiblity
   with older versions of fastd.

   "protocol "<protocol>";"

   Sets the handshake protocol; at the moment only ec25519-fhmqvc is
   supported.

   "secret "<secret>";"

   Sets the secret key.

   "status socket "<socket>";"

   Configures a UNIX socket which can be used to retrieve the current
   state of fastd. An example script to get the status can be found at
   "doc/examples/status.pl" in the fastd repository.

   "user "<user>";"

Sets the user to run fastd as.


Peer configuration
==================

Example config:

   key "f05c6f62337d291e34f50897d89b02ae43a6a2476e2969d1c8e8104fd11c1873";
   remote 192.0.2.1:10000;
   remote [2001:db8::1]:10000;
   remote ipv4 "fastd.example.com" port 10000;

   "include "<file>";"

   Includes another configuration file.

   "interface "<name>";"

   Sets the name of the peer-specific TUN/TAP interface to use.

   Does have no effect in TAP mode.

   "key "<key>";"

   Sets the peer's public key.

   "mtu <MTU>;"

   Sets the MTU for a peer-specific interface; must be at least 576.

   Does have no effect in TAP mode.

   "remote <IPv4 address>:<port>;"
   "remote <IPv6 address>:<port>;"
   "remote [ ipv4|ipv6 ] "<hostname>":<port>;"
   "remote <IPv4 address> port <port>;"
   "remote <IPv6 address> port <port>;"
   "remote [ ipv4|ipv6 ] "<hostname>" port <port>;"

   Sets the IP address or host name to connect to. If a peer doesn't
   have a remote address configured, incoming connections are
   accepted, but no own connection attempts will be made.

   The ipv4 or ipv6 options can be used to force fastd to resolve the
   host name for the specified protocol version only.

   Starting with fastd v9, multiple remotes may be given for a single
   peer. If this is the case, they will be tried one after another.
   Starting with fastd v11, all addresses a given hostname resolves to
   are taken into account, not only the first one. This can be use to
   specify alternative hostname, addresses and/or ports for the same
   host; all remotes must still refer to the same peer as the public
   key must be unique.

   "float yes|no;"

   Set to "yes" to allow incoming connections from any IP address/port
   for this peer. By default, incoming connections are only accepted
   from the addresses/ports configured using the "remote" option when
   such an option exists. Peers without "remote" are always floating.
