diff options
Diffstat (limited to 'doc/source/manual/config.rst')
| -rw-r--r-- | doc/source/manual/config.rst | 309 |
1 files changed, 309 insertions, 0 deletions
diff --git a/doc/source/manual/config.rst b/doc/source/manual/config.rst new file mode 100644 index 0000000..ba924e8 --- /dev/null +++ b/doc/source/manual/config.rst @@ -0,0 +1,309 @@ +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 xsalsa20 and aes128 encryption methods, prefer xsalsa20 + method "xsalsa20-poly1305"; + method "aes128-gcm"; + + # 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. When + no bind address is configured at all, for each outgoing connection a new socket with a random + port is created. + + 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. + + +| ``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 :doc:`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 :doc:`mtu` 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. + +.. _option-pmtu: + +| ``pmtu yes|no|auto;`` + + Enables or disables Path MTU detection for IPv4. If enabled, all packets are sent with DF set, and all + fragmentation happens on the sending host itself. If disabled, routers may fragment the packets themselves, + possibly leading to multiple fragmentation. In general, disabling this should not be necessary, but in some + networks ICMP MTU Too Big packets are lost, so PMTU detection doesn't work correctly. + + If possible, fastd's mtu setting should be adjusted so the packets aren't fragmented at all instead of + relying on this option. + + The default is auto, which uses the system default as specified in /proc/sys/net/ipv4/ip_no_pmtu_disc. + + The pmtu option is available on Linux platforms only. + +| ``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. + +| ``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. + +| ``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. |