doc: update with new configuration options

3 files changed, 50 insertions, 12 deletions

diff --git a/doc/fastd.1 b/doc/fastd.1
index 9c038b7..365f511 100644
--- a/doc/fastd.1
+++ b/doc/fastd.1
@@ -54,7 +54,7 @@ Hides IP addresses in log output.
 \fB\-\-hide\-mac\-addresses\fR
 Hides MAC addresses in log output.
 .TP
-\fB\-\-mode\fR, \fB\-m\fR tap|tun
+\fB\-\-mode\fR, \fB\-m\fR tap|multitap|tun
 Sets the mode of the interface; default is TAP mode.
 .TP
 \fB\-\-interface\fR, \fB\-i\fR <name>
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>;``