summaryrefslogtreecommitdiff
path: root/doc/man-sections/server-options.rst
diff options
context:
space:
mode:
authorBernhard Schmidt <berni@debian.org>2020-08-15 21:29:50 +0200
committerBernhard Schmidt <berni@debian.org>2020-08-15 21:29:50 +0200
commit1079962e4c06f88a54e50d997c1b7e84303d30b4 (patch)
tree4d019426928435425214ccedd6f89b70dbdf035d /doc/man-sections/server-options.rst
parent620785fe268a1221c1ba7a9cb5a70f3140a4f1ca (diff)
New upstream version 2.5~beta1upstream/2.5_beta1
Diffstat (limited to 'doc/man-sections/server-options.rst')
-rw-r--r--doc/man-sections/server-options.rst774
1 files changed, 774 insertions, 0 deletions
diff --git a/doc/man-sections/server-options.rst b/doc/man-sections/server-options.rst
new file mode 100644
index 0000000..f1f0667
--- /dev/null
+++ b/doc/man-sections/server-options.rst
@@ -0,0 +1,774 @@
+Server Options
+--------------
+Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is
+supported, and can be enabled with the ``--mode server`` option. In
+server mode, OpenVPN will listen on a single port for incoming client
+connections. All client connections will be routed through a single tun
+or tap interface. This mode is designed for scalability and should be
+able to support hundreds or even thousands of clients on sufficiently
+fast hardware. SSL/TLS authentication must be used in this mode.
+
+--auth-gen-token args
+ Returns an authentication token to successfully authenticated clients.
+
+ Valid syntax:
+ ::
+
+ auth-gen-token [lifetime] [external-auth]
+
+ After successful user/password authentication, the OpenVPN server will
+ with this option generate a temporary authentication token and push that
+ to the client. On the following renegotiations, the OpenVPN client will pass
+ this token instead of the users password. On the server side the server
+ will do the token authentication internally and it will NOT do any
+ additional authentications against configured external user/password
+ authentication mechanisms.
+
+ The tokens implemented by this mechanism include an initial timestamp and
+ a renew timestamp and are secured by HMAC.
+
+ The ``lifetime`` argument defines how long the generated token is valid.
+ The lifetime is defined in seconds. If lifetime is not set or it is set
+ to :code:`0`, the token will never expire.
+
+ The token will expire either after the configured ``lifetime`` of the
+ token is reached or after not being renewed for more than 2 \*
+ ``reneg-sec`` seconds. Clients will be sent renewed tokens on every TLS
+ renogiation to keep the client's token updated. This is done to
+ invalidate a token if a client is disconnected for a sufficently long
+ time, while at the same time permitting much longer token lifetimes for
+ active clients.
+
+ This feature is useful for environments which are configured to use One
+ Time Passwords (OTP) as part of the user/password authentications and
+ that authentication mechanism does not implement any auth-token support.
+
+ When the :code:`external-auth` keyword is present the normal
+ authentication method will always be called even if auth-token succeeds.
+ Normally other authentications method are skipped if auth-token
+ verification suceeds or fails.
+
+ This option postpones this decision to the external authentication
+ methods and checks the validity of the account and do other checks.
+
+ In this mode the environment will have a ``session_id`` variable that
+ holds the session id from auth-gen-token. Also an environment variable
+ ``session_state`` is present. This variable indicates whether the
+ auth-token has succeeded or not. It can have the following values:
+
+ :code:`Initial`
+ No token from client.
+
+ :code:`Authenticated`
+ Token is valid and not expired.
+
+ :code:`Expired`
+ Token is valid but has expired.
+
+ :code:`Invalid`
+ Token is invalid (failed HMAC or wrong length)
+
+ :code:`AuthenticatedEmptyUser` / :code:`ExpiredEmptyUser`
+ The token is not valid with the username sent from the client but
+ would be valid (or expired) if we assume an empty username was
+ used instead. These two cases are a workaround for behaviour in
+ OpenVPN 3. If this workaround is not needed these two cases should
+ be handled in the same way as :code:`Invalid`.
+
+ **Warning:** Use this feature only if you want your authentication
+ method called on every verification. Since the external authentication
+ is called it needs to also indicate a success or failure of the
+ authentication. It is strongly recommended to return an authentication
+ failure in the case of the Invalid/Expired auth-token with the
+ external-auth option unless the client could authenticate in another
+ acceptable way (e.g. client certificate), otherwise returning success
+ will lead to authentication bypass (as does returning success on a wrong
+ password from a script).
+
+--auth-gen-token-secret file
+ Specifies a file that holds a secret for the HMAC used in
+ ``--auth-gen-token`` If ``file`` is not present OpenVPN will generate a
+ random secret on startup. This file should be used if auth-token should
+ validate after restarting a server or if client should be able to roam
+ between multiple OpenVPN servers with their auth-token.
+
+--auth-user-pass-optional
+ Allow connections by clients that do not specify a username/password.
+ Normally, when ``--auth-user-pass-verify`` or
+ ``--management-client-auth`` are specified (or an authentication plugin
+ module), the OpenVPN server daemon will require connecting clients to
+ specify a username and password. This option makes the submission of a
+ username/password by clients optional, passing the responsibility to the
+ user-defined authentication module/script to accept or deny the client
+ based on other factors (such as the setting of X509 certificate fields).
+ When this option is used, and a connecting client does not submit a
+ username/password, the user-defined authentication module/script will
+ see the username and password as being set to empty strings (""). The
+ authentication module/script MUST have logic to detect this condition
+ and respond accordingly.
+
+--ccd-exclusive
+ Require, as a condition of authentication, that a connecting client has
+ a ``--client-config-dir`` file.
+
+--client-config-dir dir
+ Specify a directory ``dir`` for custom client config files. After a
+ connecting client has been authenticated, OpenVPN will look in this
+ directory for a file having the same name as the client's X509 common
+ name. If a matching file exists, it will be opened and parsed for
+ client-specific configuration options. If no matching file is found,
+ OpenVPN will instead try to open and parse a default file called
+ "DEFAULT", which may be provided but is not required. Note that the
+ configuration files must be readable by the OpenVPN process after it has
+ dropped it's root privileges.
+
+ This file can specify a fixed IP address for a given client using
+ ``--ifconfig-push``, as well as fixed subnets owned by the client using
+ ``--iroute``.
+
+ One of the useful properties of this option is that it allows client
+ configuration files to be conveniently created, edited, or removed while
+ the server is live, without needing to restart the server.
+
+ The following options are legal in a client-specific context: ``--push``,
+ ``--push-reset``, ``--push-remove``, ``--iroute``, ``--ifconfig-push``,
+ ``--vlan-pvid`` and ``--config``.
+
+--client-to-client
+ Because the OpenVPN server mode handles multiple clients through a
+ single tun or tap interface, it is effectively a router. The
+ ``--client-to-client`` flag tells OpenVPN to internally route
+ client-to-client traffic rather than pushing all client-originating
+ traffic to the TUN/TAP interface.
+
+ When this option is used, each client will "see" the other clients which
+ are currently connected. Otherwise, each client will only see the
+ server. Don't use this option if you want to firewall tunnel traffic
+ using custom, per-client rules.
+
+--disable
+ Disable a particular client (based on the common name) from connecting.
+ Don't use this option to disable a client due to key or password
+ compromise. Use a CRL (certificate revocation list) instead (see the
+ ``--crl-verify`` option).
+
+ This option must be associated with a specific client instance, which
+ means that it must be specified either in a client instance config file
+ using ``--client-config-dir`` or dynamically generated using a
+ ``--client-connect`` script.
+
+--connect-freq args
+ Allow a maximum of ``n`` new connections per ``sec`` seconds from
+ clients.
+
+ Valid syntax:
+ ::
+
+ connect-freq n sec
+
+ This is designed to contain DoS attacks which flood the server
+ with connection requests using certificates which will ultimately fail
+ to authenticate.
+
+ This is an imperfect solution however, because in a real DoS scenario,
+ legitimate connections might also be refused.
+
+ For the best protection against DoS attacks in server mode, use
+ ``--proto udp`` and either ``--tls-auth`` or ``--tls-crypt``.
+
+--duplicate-cn
+ Allow multiple clients with the same common name to concurrently
+ connect. In the absence of this option, OpenVPN will disconnect a client
+ instance upon connection of a new client having the same common name.
+
+--ifconfig-pool args
+ Set aside a pool of subnets to be dynamically allocated to connecting
+ clients, similar to a DHCP server.
+
+ Valid syntax:
+ ::
+
+ ifconfig-pool start-IP end-IP [netmask]
+
+ For tun-style tunnels, each client
+ will be given a /30 subnet (for interoperability with Windows clients).
+ For tap-style tunnels, individual addresses will be allocated, and the
+ optional ``netmask`` parameter will also be pushed to clients.
+
+--ifconfig-ipv6-pool args
+ Specify an IPv6 address pool for dynamic assignment to clients.
+
+ Valid args:
+ ::
+
+ ifconfig-ipv6-pool ipv6addr/bits
+
+ The pool starts at ``ipv6addr`` and matches the offset determined from
+ the start of the IPv4 pool.
+
+--ifconfig-pool-persist args
+ Persist/unpersist ifconfig-pool data to ``file``, at ``seconds``
+ intervals (default :code:`600`), as well as on program startup and shutdown.
+
+ Valid syntax:
+ ::
+
+ ifconfig-pool-persist file [seconds]
+
+ The goal of this option is to provide a long-term association between
+ clients (denoted by their common name) and the virtual IP address
+ assigned to them from the ifconfig-pool. Maintaining a long-term
+ association is good for clients because it allows them to effectively
+ use the ``--persist-tun`` option.
+
+ ``file`` is a comma-delimited ASCII file, formatted as
+ :code:`<Common-Name>,<IP-address>`.
+
+ If ``seconds`` = :code:`0`, ``file`` will be treated as read-only. This
+ is useful if you would like to treat ``file`` as a configuration file.
+
+ Note that the entries in this file are treated by OpenVPN as
+ *suggestions* only, based on past associations between a common name and
+ IP address. They do not guarantee that the given common name will always
+ receive the given IP address. If you want guaranteed assignment, use
+ ``--ifconfig-push``
+
+--ifconfig-push args
+ Push virtual IP endpoints for client tunnel, overriding the
+ ``--ifconfig-pool`` dynamic allocation.
+
+ Valid syntax:
+ ::
+
+ ifconfig-push local remote-netmask [alias]
+
+ The parameters ``local`` and ``remote-netmask`` are set according to the
+ ``--ifconfig`` directive which you want to execute on the client machine
+ to configure the remote end of the tunnel. Note that the parameters
+ ``local`` and ``remote-netmask`` are from the perspective of the client,
+ not the server. They may be DNS names rather than IP addresses, in which
+ case they will be resolved on the server at the time of client
+ connection.
+
+ The optional ``alias`` parameter may be used in cases where NAT causes
+ the client view of its local endpoint to differ from the server view. In
+ this case ``local/remote-netmask`` will refer to the server view while
+ ``alias/remote-netmask`` will refer to the client view.
+
+ This option must be associated with a specific client instance, which
+ means that it must be specified either in a client instance config file
+ using ``--client-config-dir`` or dynamically generated using a
+ ``--client-connect`` script.
+
+ Remember also to include a ``--route`` directive in the main OpenVPN
+ config file which encloses ``local``, so that the kernel will know to
+ route it to the server's TUN/TAP interface.
+
+ OpenVPN's internal client IP address selection algorithm works as
+ follows:
+
+ 1. Use ``--client-connect script`` generated file for static IP
+ (first choice).
+
+ 2. Use ``--client-config-dir`` file for static IP (next choice).
+
+ 3. Use ``--ifconfig-pool`` allocation for dynamic IP (last
+ choice).
+
+--ifconfig-ipv6-push args
+ for ``--client-config-dir`` per-client static IPv6 interface
+ configuration, see ``--client-config-dir`` and ``--ifconfig-push`` for
+ more details.
+
+ Valid syntax:
+ ::
+
+ ifconfig-ipv6-push ipv6addr/bits ipv6remote
+
+--inetd args
+ Valid syntaxes:
+ ::
+
+ inetd
+ inetd wait
+ inetd nowait
+ inetd wait progname
+
+ Use this option when OpenVPN is being run from the inetd or ``xinetd``\(8)
+ server.
+
+ The :code:`wait` and :code:`nowait` option must match what is specified
+ in the inetd/xinetd config file. The :code:`nowait` mode can only be used
+ with ``--proto tcp-server`` The default is :code:`wait`. The
+ :code:`nowait` mode can be used to instantiate the OpenVPN daemon as a
+ classic TCP server, where client connection requests are serviced on a
+ single port number. For additional information on this kind of
+ configuration, see the OpenVPN FAQ:
+ https://community.openvpn.net/openvpn/wiki/325-openvpn-as-a--forking-tcp-server-which-can-service-multiple-clients-over-a-single-tcp-port
+
+ This option precludes the use of ``--daemon``, ``--local`` or
+ ``--remote``. Note that this option causes message and error output to
+ be handled in the same way as the ``--daemon`` option. The optional
+ ``progname`` parameter is also handled exactly as in ``--daemon``.
+
+ Also note that in ``wait`` mode, each OpenVPN tunnel requires a separate
+ TCP/UDP port and a separate inetd or xinetd entry. See the OpenVPN 1.x
+ HOWTO for an example on using OpenVPN with xinetd:
+ https://openvpn.net/community-resources/1xhowto/
+
+--multihome
+ Configure a multi-homed UDP server. This option needs to be used when a
+ server has more than one IP address (e.g. multiple interfaces, or
+ secondary IP addresses), and is not using ``--local`` to force binding
+ to one specific address only. This option will add some extra lookups to
+ the packet path to ensure that the UDP reply packets are always sent
+ from the address that the client is talking to. This is not supported on
+ all platforms, and it adds more processing, so it's not enabled by
+ default.
+
+ *Notes:*
+ - This option is only relevant for UDP servers.
+ - If you do an IPv6+IPv4 dual-stack bind on a Linux machine with
+ multiple IPv4 address, connections to IPv4 addresses will not
+ work right on kernels before 3.15, due to missing kernel
+ support for the IPv4-mapped case (some distributions have
+ ported this to earlier kernel versions, though).
+
+--iroute args
+ Generate an internal route to a specific client. The ``netmask``
+ parameter, if omitted, defaults to :code:`255.255.255.255`.
+
+ Valid syntax:
+ ::
+
+ iroute network [netmask]
+
+ This directive can be used to route a fixed subnet from the server to a
+ particular client, regardless of where the client is connecting from.
+ Remember that you must also add the route to the system routing table as
+ well (such as by using the ``--route`` directive). The reason why two
+ routes are needed is that the ``--route`` directive routes the packet
+ from the kernel to OpenVPN. Once in OpenVPN, the ``--iroute`` directive
+ routes to the specific client.
+
+ This option must be specified either in a client instance config file
+ using ``--client-config-dir`` or dynamically generated using a
+ ``--client-connect`` script.
+
+ The ``--iroute`` directive also has an important interaction with
+ ``--push "route ..."``. ``--iroute`` essentially defines a subnet which
+ is owned by a particular client (we will call this client *A*). If you
+ would like other clients to be able to reach *A*'s subnet, you can use
+ ``--push "route ..."`` together with ``--client-to-client`` to effect
+ this. In order for all clients to see *A*'s subnet, OpenVPN must push
+ this route to all clients EXCEPT for *A*, since the subnet is already
+ owned by *A*. OpenVPN accomplishes this by not not pushing a route to
+ a client if it matches one of the client's iroutes.
+
+--iroute-ipv6 args
+ for ``--client-config-dir`` per-client static IPv6 route configuration,
+ see ``--iroute`` for more details how to setup and use this, and how
+ ``--iroute`` and ``--route`` interact.
+
+ Valid syntax:
+ ::
+
+ iroute-ipv6 ipv6addr/bits
+
+--max-clients n
+ Limit server to a maximum of ``n`` concurrent clients.
+
+--max-routes-per-client n
+ Allow a maximum of ``n`` internal routes per client (default
+ :code:`256`). This is designed to help contain DoS attacks where an
+ authenticated client floods the server with packets appearing to come
+ from many unique MAC addresses, forcing the server to deplete virtual
+ memory as its internal routing table expands. This directive can be used
+ in a ``--client-config-dir`` file or auto-generated by a
+ ``--client-connect`` script to override the global value for a particular
+ client.
+
+ Note that this directive affects OpenVPN's internal routing table, not
+ the kernel routing table.
+
+--opt-verify
+ Clients that connect with options that are incompatible with those of the
+ server will be disconnected.
+
+ Options that will be compared for compatibility include ``dev-type``,
+ ``link-mtu``, ``tun-mtu``, ``proto``, ``ifconfig``,
+ ``comp-lzo``, ``fragment``, ``keydir``, ``cipher``,
+ ``auth``, ``keysize``, ``secret``, ``no-replay``,
+ ``tls-auth``, ``key-method``, ``tls-server``
+ and ``tls-client``.
+
+ This option requires that ``--disable-occ`` NOT be used.
+
+--port-share args
+ Share OpenVPN TCP with another service
+
+ Valid syntax:
+ ::
+
+ port-share host port [dir]
+
+ When run in TCP server mode, share the OpenVPN port with another
+ application, such as an HTTPS server. If OpenVPN senses a connection to
+ its port which is using a non-OpenVPN protocol, it will proxy the
+ connection to the server at ``host``:``port``. Currently only designed to
+ work with HTTP/HTTPS, though it would be theoretically possible to
+ extend to other protocols such as ssh.
+
+ ``dir`` specifies an optional directory where a temporary file with name
+ N containing content C will be dynamically generated for each proxy
+ connection, where N is the source IP:port of the client connection and C
+ is the source IP:port of the connection to the proxy receiver. This
+ directory can be used as a dictionary by the proxy receiver to determine
+ the origin of the connection. Each generated file will be automatically
+ deleted when the proxied connection is torn down.
+
+ Not implemented on Windows.
+
+--push option
+ Push a config file option back to the client for remote execution. Note
+ that ``option`` must be enclosed in double quotes (:code:`""`). The
+ client must specify ``--pull`` in its config file. The set of options
+ which can be pushed is limited by both feasibility and security. Some
+ options such as those which would execute scripts are banned, since they
+ would effectively allow a compromised server to execute arbitrary code
+ on the client. Other options such as TLS or MTU parameters cannot be
+ pushed because the client needs to know them before the connection to the
+ server can be initiated.
+
+ This is a partial list of options which can currently be pushed:
+ ``--route``, ``--route-gateway``, ``--route-delay``,
+ ``--redirect-gateway``, ``--ip-win32``, ``--dhcp-option``,
+ ``--inactive``, ``--ping``, ``--ping-exit``, ``--ping-restart``,
+ ``--setenv``, ``--auth-token``, ``--persist-key``, ``--persist-tun``,
+ ``--echo``, ``--comp-lzo``, ``--socket-flags``, ``--sndbuf``,
+ ``--rcvbuf``
+
+--push-peer-info
+ Push additional information about the client to server. The following
+ data is always pushed to the server:
+
+ :code:`IV_VER=<version>`
+ The client OpenVPN version
+
+ :code:`IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]`
+ The client OS platform
+
+ :code:`IV_LZO_STUB=1`
+ If client was built with LZO stub capability
+
+ :code:`IV_LZ4=1`
+ If the client supports LZ4 compressions.
+
+ :code:`IV_PROTO`
+ Details about protocol extensions that the peer supports. The
+ variable is a bitfield and the bits are defined as follows
+ (starting a bit 0 for the first (unused) bit:
+
+ - bit 1: The peer supports peer-id floating mechanism
+ - bit 2: The client expects a push-reply and the server may
+ send this reply without waiting for a push-request first.
+
+ :code:`IV_NCP=2`
+ Negotiable ciphers, client supports ``--cipher`` pushed by
+ the server, a value of 2 or greater indicates client supports
+ *AES-GCM-128* and *AES-GCM-256*.
+
+ :code:`IV_CIPHERS=<ncp-ciphers>`
+ The client announces the list of supported ciphers configured with the
+ ``--data-ciphers`` option to the server.
+
+ :code:`IV_GUI_VER=<gui_id> <version>`
+ The UI version of a UI if one is running, for example
+ :code:`de.blinkt.openvpn 0.5.47` for the Android app.
+
+ When ``--push-peer-info`` is enabled the additional information consists
+ of the following data:
+
+ :code:`IV_HWADDR=<mac address>`
+ The MAC address of clients default gateway
+
+ :code:`IV_SSL=<version string>`
+ The ssl version used by the client, e.g.
+ :code:`OpenSSL 1.0.2f 28 Jan 2016`.
+
+ :code:`IV_PLAT_VER=x.y`
+ The version of the operating system, e.g. 6.1 for Windows 7.
+
+ :code:`UV_<name>=<value>`
+ Client environment variables whose names start with
+ :code:`UV_`
+
+--push-remove opt
+ Selectively remove all ``--push`` options matching "opt" from the option
+ list for a client. ``opt`` is matched as a substring against the whole
+ option string to-be-pushed to the client, so ``--push-remove route``
+ would remove all ``--push route ...`` and ``--push route-ipv6 ...``
+ statements, while ``--push-remove "route-ipv6 2001:"`` would only remove
+ IPv6 routes for :code:`2001:...` networks.
+
+ ``--push-remove`` can only be used in a client-specific context, like in
+ a ``--client-config-dir`` file, or ``--client-connect`` script or plugin
+ -- similar to ``--push-reset``, just more selective.
+
+ *NOTE*: to *change* an option, ``--push-remove`` can be used to first
+ remove the old value, and then add a new ``--push`` option with the new
+ value.
+
+ *NOTE 2*: due to implementation details, 'ifconfig' and 'ifconfig-ipv6'
+ can only be removed with an exact match on the option (
+ :code:`push-remove ifconfig`), no substring matching and no matching on
+ the IPv4/IPv6 address argument is possible.
+
+--push-reset
+ Don't inherit the global push list for a specific client instance.
+ Specify this option in a client-specific context such as with a
+ ``--client-config-dir`` configuration file. This option will ignore
+ ``--push`` options at the global config file level.
+
+--server args
+ A helper directive designed to simplify the configuration of OpenVPN's
+ server mode. This directive will set up an OpenVPN server which will
+ allocate addresses to clients out of the given network/netmask. The
+ server itself will take the :code:`.1` address of the given network for
+ use as the server-side endpoint of the local TUN/TAP interface. If the
+ optional :code:`nopool` flag is given, no dynamic IP address pool will
+ prepared for VPN clients.
+
+ Valid syntax:
+ ::
+
+ server network netmask [nopool]
+
+ For example, ``--server 10.8.0.0 255.255.255.0`` expands as follows:
+ ::
+
+ mode server
+ tls-server
+ push "topology [topology]"
+
+ if dev tun AND (topology == net30 OR topology == p2p):
+ ifconfig 10.8.0.1 10.8.0.2
+ if !nopool:
+ ifconfig-pool 10.8.0.4 10.8.0.251
+ route 10.8.0.0 255.255.255.0
+ if client-to-client:
+ push "route 10.8.0.0 255.255.255.0"
+ else if topology == net30:
+ push "route 10.8.0.1"
+
+ if dev tap OR (dev tun AND topology == subnet):
+ ifconfig 10.8.0.1 255.255.255.0
+ if !nopool:
+ ifconfig-pool 10.8.0.2 10.8.0.253 255.255.255.0
+ push "route-gateway 10.8.0.1"
+ if route-gateway unset:
+ route-gateway 10.8.0.2
+
+ Don't use ``--server`` if you are ethernet bridging. Use
+ ``--server-bridge`` instead.
+
+--server-bridge args
+ A helper directive similar to ``--server`` which is designed to simplify
+ the configuration of OpenVPN's server mode in ethernet bridging
+ configurations.
+
+ Valid syntaxes:
+ ::
+
+ server-bridge gateway netmask pool-start-IP pool-end-IP
+ server-bridge [nogw]
+
+ If ``--server-bridge`` is used without any parameters, it will enable a
+ DHCP-proxy mode, where connecting OpenVPN clients will receive an IP
+ address for their TAP adapter from the DHCP server running on the
+ OpenVPN server-side LAN. Note that only clients that support the binding
+ of a DHCP client with the TAP adapter (such as Windows) can support this
+ mode. The optional :code:`nogw` flag (advanced) indicates that gateway
+ information should not be pushed to the client.
+
+ To configure ethernet bridging, you must first use your OS's bridging
+ capability to bridge the TAP interface with the ethernet NIC interface.
+ For example, on Linux this is done with the :code:`brctl` tool, and with
+ Windows XP it is done in the Network Connections Panel by selecting the
+ ethernet and TAP adapters and right-clicking on "Bridge Connections".
+
+ Next you you must manually set the IP/netmask on the bridge interface.
+ The ``gateway`` and ``netmask`` parameters to ``--server-bridge`` can be
+ set to either the IP/netmask of the bridge interface, or the IP/netmask
+ of the default gateway/router on the bridged subnet.
+
+ Finally, set aside a IP range in the bridged subnet, denoted by
+ ``pool-start-IP`` and ``pool-end-IP``, for OpenVPN to allocate to
+ connecting clients.
+
+ For example, ``server-bridge 10.8.0.4 255.255.255.0 10.8.0.128
+ 10.8.0.254`` expands as follows:
+ ::
+
+ mode server
+ tls-server
+
+ ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0
+ push "route-gateway 10.8.0.4"
+
+ In another example, ``--server-bridge`` (without parameters) expands as
+ follows:
+ ::
+
+ mode server
+ tls-server
+
+ push "route-gateway dhcp"
+
+ Or ``--server-bridge nogw`` expands as follows:
+ ::
+
+ mode server
+ tls-server
+
+--stale-routes-check args
+ Remove routes which haven't had activity for ``n`` seconds (i.e. the ageing
+ time). This check is run every ``t`` seconds (i.e. check interval).
+
+ Valid syntax:
+ ::
+
+ stale-routes-check n [t]
+
+ If ``t`` is not present it defaults to ``n``.
+
+ This option helps to keep the dynamic routing table small. See also
+ ``--max-routes-per-client``
+
+--username-as-common-name
+ For ``--auth-user-pass-verify`` authentication, use the authenticated
+ username as the common name, rather than the common name from the client
+ cert.
+
+--verify-client-cert mode
+ Specify whether the client is required to supply a valid certificate.
+
+ Possible ``mode`` options are:
+
+ :code:`none`
+ A client certificate is not required. the client needs to
+ authenticate using username/password only. Be aware that using this
+ directive is less secure than requiring certificates from all
+ clients.
+
+ If you use this directive, the entire responsibility of authentication
+ will rest on your ``--auth-user-pass-verify`` script, so keep in mind
+ that bugs in your script could potentially compromise the security of
+ your VPN.
+
+ ``--verify-client-cert none`` is functionally equivalent to
+ ``--client-cert-not-required``.
+
+ :code:`optional`
+ A client may present a certificate but it is not required to do so.
+ When using this directive, you should also use a
+ ``--auth-user-pass-verify`` script to ensure that clients are
+ authenticated using a certificate, a username and password, or
+ possibly even both.
+
+ Again, the entire responsibility of authentication will rest on your
+ ``--auth-user-pass-verify`` script, so keep in mind that bugs in your
+ script could potentially compromise the security of your VPN.
+
+ :code:`require`
+ This is the default option. A client is required to present a
+ certificate, otherwise VPN access is refused.
+
+ If you don't use this directive (or use ``--verify-client-cert require``)
+ but you also specify an ``--auth-user-pass-verify`` script, then OpenVPN
+ will perform double authentication. The client certificate verification
+ AND the ``--auth-user-pass-verify`` script will need to succeed in order
+ for a client to be authenticated and accepted onto the VPN.
+
+--vlan-tagging
+ Server-only option. Turns the OpenVPN server instance into a switch that
+ understands VLAN-tagging, based on IEEE 802.1Q.
+
+ The server TAP device and each of the connecting clients is seen as a
+ port of the switch. All client ports are in untagged mode and the server
+ TAP device is VLAN-tagged, untagged or accepts both, depending on the
+ ``--vlan-accept`` setting.
+
+ Ethernet frames with a prepended 802.1Q tag are called "tagged". If the
+ VLAN Identifier (VID) field in such a tag is non-zero, the frame is
+ called "VLAN-tagged". If the VID is zero, but the Priority Control Point
+ (PCP) field is non-zero, the frame is called "prio-tagged". If there is
+ no 802.1Q tag, the frame is "untagged".
+
+ Using the ``--vlan-pvid v`` option once per client (see
+ --client-config-dir), each port can be associated with a certain VID.
+ Packets can only be forwarded between ports having the same VID.
+ Therefore, clients with differing VIDs are completely separated from
+ one-another, even if ``--client-to-client`` is activated.
+
+ The packet filtering takes place in the OpenVPN server. Clients should
+ not have any VLAN tagging configuration applied.
+
+ The ``--vlan-tagging`` option is off by default. While turned off,
+ OpenVPN accepts any Ethernet frame and does not perform any special
+ processing for VLAN-tagged packets.
+
+ This option can only be activated in ``--dev tap mode``.
+
+--vlan-accept args
+ Configure the VLAN tagging policy for the server TAP device.
+
+ Valid syntax:
+ ::
+
+ vlan-accept all|tagged|untagged
+
+ The following modes are available:
+
+ :code:`tagged`
+ Admit only VLAN-tagged frames. Only VLAN-tagged packets are accepted,
+ while untagged or priority-tagged packets are dropped when entering
+ the server TAP device.
+
+ :code:`untagged`
+ Admit only untagged and prio-tagged frames. VLAN-tagged packets are
+ not accepted, while untagged or priority-tagged packets entering the
+ server TAP device are tagged with the value configured for the global
+ ``--vlan-pvid`` setting.
+
+ :code:`all` (default)
+ Admit all frames. All packets are admitted and then treated like
+ untagged or tagged mode respectively.
+
+ *Note*:
+ Some vendors refer to switch ports running in :code:`tagged` mode
+ as "trunk ports" and switch ports running in :code:`untagged` mode
+ as "access ports".
+
+ Packets forwarded from clients to the server are VLAN-tagged with the
+ originating client's PVID, unless the VID matches the global
+ ``--vlan-pvid``, in which case the tag is removed.
+
+ If no *PVID* is configured for a given client (see --vlan-pvid) packets
+ are tagged with 1 by default.
+
+--vlan-pvid v
+ Specifies which VLAN identifier a "port" is associated with. Only valid
+ when ``--vlan-tagging`` is speficied.
+
+ In the client context, the setting specifies which VLAN ID a client is
+ associated with. In the global context, the VLAN ID of the server TAP
+ device is set. The latter only makes sense for ``--vlan-accept
+ untagged`` and ``--vlan-accept all`` modes.
+
+ Valid values for ``v`` go from :code:`1` through to :code:`4094`. The
+ global value defaults to :code:`1`. If no ``--vlan-pvid`` is specified in
+ the client context, the global value is inherited.
+
+ In some switch implementations, the *PVID* is also referred to as "Native
+ VLAN".