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

# 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 without port or with port 0 is configured, 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 (option drop capabilities no when fastd is built with capability support, root privileges otherwise).

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
    • nacl: Use implementation from NaCl or libsodium
  • 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;
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).
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.
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|tun;
Sets the mode of the interface; the default is TAP mode.
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.
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.

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.

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.
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.
secure handshakes yes|no;

fastd v11+ implements a revised handshake scheme which prevents downgrade attacks (i.e. an attacker forcing two peers to use the least secure encryption method supported by both sides, or even half-establishing a session with an encryption method supported by one side only). To maintain backwards compatiblity, the old handshake is still supported when secure handshakes is set to no.

Setting this option to yes (the default) on one side is enough to ensure that a session established by two peers has not been downgraded.

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/ in the fastd repository.
user "<user>";

Sets the user to run fastd as.

Peer configuration

Example config:

key "f05c6f62337d291e34f50897d89b02ae43a6a2476e2969d1c8e8104fd11c1873";
remote [2001:db8::1]:10000;
remote ipv4 "" port 10000;
include "<file>";
Includes another configuration file.
key "<key>";
Sets the peer’s public key.
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;
The float option can be used to accept connections from the peer with the specified key from other addresses that the configured ones.