summaryrefslogtreecommitdiffstats
path: root/doc/source/manual
diff options
context:
space:
mode:
authorMatthias Schiffer <mschiffer@universe-factory.net>2016-03-20 20:57:03 +0100
committerMatthias Schiffer <mschiffer@universe-factory.net>2016-03-20 20:57:03 +0100
commit9256105618b2a9d7e1eec4994a5ffddb6b1e5a7f (patch)
tree6a8850130ba77ad148b8110418f1b61d4a2f1504 /doc/source/manual
parenta86d2f5d898523ddaa95044d45a6210a6c733645 (diff)
downloadfastd-9256105618b2a9d7e1eec4994a5ffddb6b1e5a7f.tar
fastd-9256105618b2a9d7e1eec4994a5ffddb6b1e5a7f.zip
doc: update with new configuration options
Diffstat (limited to 'doc/source/manual')
-rw-r--r--doc/source/manual/cmdline.rst6
-rw-r--r--doc/source/manual/config.rst54
2 files changed, 49 insertions, 11 deletions
diff --git a/doc/source/manual/cmdline.rst b/doc/source/manual/cmdline.rst
index bd17249..ffc593a 100644
--- a/doc/source/manual/cmdline.rst
+++ b/doc/source/manual/cmdline.rst
@@ -18,12 +18,12 @@ Command line options and config files are parsed in order they are specified, so
--status-socket <socket>
Configures a socket to get fastd's status.
---log-level <error|warn|info|verbose|debug|debug2>
+--log-level error|warn|info|verbose|debug|debug2
Sets the stderr log level; default is info,
if no alternative log destination ist configured.
If logging to syslog or files is enabled, the default is not to log to stderr.
---syslog-level <error|warn|info|verbose|debug|debug2>
+--syslog-level error|warn|info|verbose|debug|debug2
Sets the log level for syslog output; default is not to use syslog.
--syslog-ident <ident>
@@ -38,7 +38,7 @@ Command line options and config files are parsed in order they are specified, so
--config-peer-dir <dir>
Loads all files from a directory as peer configs. On SIGHUP fastd will reload peer directories.
---mode, -m <tap|tun>
+--mode, -m tap|multitap|tun
Sets the mode of the interface; default is TAP mode.
--interface, -i <name>
diff --git a/doc/source/manual/config.rst b/doc/source/manual/config.rst
index f9d874e..ea42c4e 100644
--- a/doc/source/manual/config.rst
+++ b/doc/source/manual/config.rst
@@ -54,8 +54,8 @@ Example config:
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).
+ ``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.
@@ -87,15 +87,20 @@ Example config:
- ``nacl``: Use implementation from NaCl or libsodium
-| ``drop capabilities yes|no|early;``
+| ``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
+ 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.
@@ -130,6 +135,12 @@ Example config:
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
@@ -164,10 +175,13 @@ Example config:
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;``
+| ``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 :doc:`mtu` as the default 1500 is suboptimal in most setups.
@@ -189,6 +203,8 @@ Example config:
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
@@ -215,6 +231,9 @@ Example config:
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.
@@ -233,6 +252,13 @@ Example config:
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.
+
.. _option-pmtu:
| ``pmtu yes|no|auto;``
@@ -283,10 +309,22 @@ Example config:
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>;``