summaryrefslogtreecommitdiff
path: root/doc/man-sections/link-options.rst
diff options
context:
space:
mode:
authorBernhard Schmidt <berni@debian.org>2020-09-01 16:52:17 +0200
committerBernhard Schmidt <berni@debian.org>2020-09-01 16:52:17 +0200
commit9fc3b98112217f2d92a67977dbde0987cc7a1803 (patch)
tree29fcc8654ee65d9dd89ade797bea2f3d9dfd9cfd /doc/man-sections/link-options.rst
parenta8758c0e03eed188dcb9da0e4fd781a67c25bf1e (diff)
parent69b02b1f7fd609d84ace13ab04697158de2418a9 (diff)
Merge branch 'debian/experimental-2.5'
Diffstat (limited to 'doc/man-sections/link-options.rst')
-rw-r--r--doc/man-sections/link-options.rst409
1 files changed, 409 insertions, 0 deletions
diff --git a/doc/man-sections/link-options.rst b/doc/man-sections/link-options.rst
new file mode 100644
index 0000000..c132a62
--- /dev/null
+++ b/doc/man-sections/link-options.rst
@@ -0,0 +1,409 @@
+Link Options
+------------
+This link options section covers options related to the connection between
+the local and the remote host.
+
+--bind keywords
+ Bind to local address and port. This is the default unless any of
+ ``--proto tcp-client`` , ``--http-proxy`` or ``--socks-proxy`` are used.
+
+ If the optional :code:`ipv6only` keyword is present OpenVPN will bind only
+ to IPv6 (as opposed to IPv6 and IPv4) when a IPv6 socket is opened.
+
+--float
+ Allow remote peer to change its IP address and/or port number, such as
+ due to DHCP (this is the default if ``--remote`` is not used).
+ ``--float`` when specified with ``--remote`` allows an OpenVPN session
+ to initially connect to a peer at a known address, however if packets
+ arrive from a new address and pass all authentication tests, the new
+ address will take control of the session. This is useful when you are
+ connecting to a peer which holds a dynamic address such as a dial-in
+ user or DHCP client.
+
+ Essentially, ``--float`` tells OpenVPN to accept authenticated packets
+ from any address, not only the address which was specified in the
+ ``--remote`` option.
+
+--fragment max
+ Enable internal datagram fragmentation so that no UDP datagrams are sent
+ which are larger than ``max`` bytes.
+
+ The ``max`` parameter is interpreted in the same way as the
+ ``--link-mtu`` parameter, i.e. the UDP packet size after encapsulation
+ overhead has been added in, but not including the UDP header itself.
+
+ The ``--fragment`` option only makes sense when you are using the UDP
+ protocol (``--proto udp``).
+
+ ``--fragment`` adds 4 bytes of overhead per datagram.
+
+ See the ``--mssfix`` option below for an important related option to
+ ``--fragment``.
+
+ It should also be noted that this option is not meant to replace UDP
+ fragmentation at the IP stack level. It is only meant as a last resort
+ when path MTU discovery is broken. Using this option is less efficient
+ than fixing path MTU discovery for your IP link and using native IP
+ fragmentation instead.
+
+ Having said that, there are circumstances where using OpenVPN's internal
+ fragmentation capability may be your only option, such as tunneling a
+ UDP multicast stream which requires fragmentation.
+
+--keepalive args
+ A helper directive designed to simplify the expression of ``--ping`` and
+ ``--ping-restart``.
+
+ Valid syntax:
+ ::
+
+ keepalive interval timeout
+
+ This option can be used on both client and server side, but it is enough
+ to add this on the server side as it will push appropriate ``--ping``
+ and ``--ping-restart`` options to the client. If used on both server and
+ client, the values pushed from server will override the client local
+ values.
+
+ The ``timeout`` argument will be twice as long on the server side. This
+ ensures that a timeout is detected on client side before the server side
+ drops the connection.
+
+ For example, ``--keepalive 10 60`` expands as follows:
+ ::
+
+ if mode server:
+ ping 10 # Argument: interval
+ ping-restart 120 # Argument: timeout*2
+ push "ping 10" # Argument: interval
+ push "ping-restart 60" # Argument: timeout
+ else
+ ping 10 # Argument: interval
+ ping-restart 60 # Argument: timeout
+
+--link-mtu n
+ Sets an upper bound on the size of UDP packets which are sent between
+ OpenVPN peers. *It's best not to set this parameter unless you know what
+ you're doing.*
+
+--local host
+ Local host name or IP address for bind. If specified, OpenVPN will bind
+ to this address only. If unspecified, OpenVPN will bind to all
+ interfaces.
+
+--lport port
+ Set local TCP/UDP port number or name. Cannot be used together with
+ ``--nobind`` option.
+
+--mark value
+ Mark encrypted packets being sent with value. The mark value can be
+ matched in policy routing and packetfilter rules. This option is only
+ supported in Linux and does nothing on other operating systems.
+
+--mode m
+ Set OpenVPN major mode. By default, OpenVPN runs in point-to-point mode
+ (:code:`p2p`). OpenVPN 2.0 introduces a new mode (:code:`server`) which
+ implements a multi-client server capability.
+
+--mssfix max
+ Announce to TCP sessions running over the tunnel that they should limit
+ their send packet sizes such that after OpenVPN has encapsulated them,
+ the resulting UDP packet size that OpenVPN sends to its peer will not
+ exceed ``max`` bytes. The default value is :code:`1450`.
+
+ The ``max`` parameter is interpreted in the same way as the
+ ``--link-mtu`` parameter, i.e. the UDP packet size after encapsulation
+ overhead has been added in, but not including the UDP header itself.
+ Resulting packet would be at most 28 bytes larger for IPv4 and 48 bytes
+ for IPv6 (20/40 bytes for IP header and 8 bytes for UDP header). Default
+ value of 1450 allows IPv4 packets to be transmitted over a link with MTU
+ 1473 or higher without IP level fragmentation.
+
+ The ``--mssfix`` option only makes sense when you are using the UDP
+ protocol for OpenVPN peer-to-peer communication, i.e. ``--proto udp``.
+
+ ``--mssfix`` and ``--fragment`` can be ideally used together, where
+ ``--mssfix`` will try to keep TCP from needing packet fragmentation in
+ the first place, and if big packets come through anyhow (from protocols
+ other than TCP), ``--fragment`` will internally fragment them.
+
+ Both ``--fragment`` and ``--mssfix`` are designed to work around cases
+ where Path MTU discovery is broken on the network path between OpenVPN
+ peers.
+
+ The usual symptom of such a breakdown is an OpenVPN connection which
+ successfully starts, but then stalls during active usage.
+
+ If ``--fragment`` and ``--mssfix`` are used together, ``--mssfix`` will
+ take its default ``max`` parameter from the ``--fragment max`` option.
+
+ Therefore, one could lower the maximum UDP packet size to 1300 (a good
+ first try for solving MTU-related connection problems) with the
+ following options:
+ ::
+
+ --tun-mtu 1500 --fragment 1300 --mssfix
+
+--mtu-disc type
+ Should we do Path MTU discovery on TCP/UDP channel? Only supported on
+ OSes such as Linux that supports the necessary system call to set.
+
+ Valid types:
+
+ :code:`no` Never send DF (Don't Fragment) frames
+
+ :code:`maybe` Use per-route hints
+
+ :code:`yes` Always DF (Don't Fragment)
+
+--mtu-test
+ To empirically measure MTU on connection startup, add the ``--mtu-test``
+ option to your configuration. OpenVPN will send ping packets of various
+ sizes to the remote peer and measure the largest packets which were
+ successfully received. The ``--mtu-test`` process normally takes about 3
+ minutes to complete.
+
+--nobind
+ Do not bind to local address and port. The IP stack will allocate a
+ dynamic port for returning packets. Since the value of the dynamic port
+ could not be known in advance by a peer, this option is only suitable
+ for peers which will be initiating connections by using the --remote
+ option.
+
+--passtos
+ Set the TOS field of the tunnel packet to what the payload's TOS is.
+
+--ping n
+ Ping remote over the TCP/UDP control channel if no packets have been
+ sent for at least ``n`` seconds (specify ``--ping`` on both peers to
+ cause ping packets to be sent in both directions since OpenVPN ping
+ packets are not echoed like IP ping packets). When used in one of
+ OpenVPN's secure modes (where ``--secret``, ``--tls-server`` or
+ ``--tls-client`` is specified), the ping packet will be
+ cryptographically secure.
+
+ This option has two intended uses:
+
+ (1) Compatibility with stateful firewalls. The periodic ping will ensure
+ that a stateful firewall rule which allows OpenVPN UDP packets to
+ pass will not time out.
+
+ (2) To provide a basis for the remote to test the existence of its peer
+ using the ``--ping-exit`` option.
+
+--ping-exit n
+ Causes OpenVPN to exit after ``n`` seconds pass without reception of a
+ ping or other packet from remote. This option can be combined with
+ ``--inactive``, ``--ping`` and ``--ping-exit`` to create a two-tiered
+ inactivity disconnect.
+
+ For example,
+ ::
+
+ openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60
+
+ when used on both peers will cause OpenVPN to exit within 60 seconds if
+ its peer disconnects, but will exit after one hour if no actual tunnel
+ data is exchanged.
+
+--ping-restart n
+ Similar to ``--ping-exit``, but trigger a :code:`SIGUSR1` restart after
+ ``n`` seconds pass without reception of a ping or other packet from
+ remote.
+
+ This option is useful in cases where the remote peer has a dynamic IP
+ address and a low-TTL DNS name is used to track the IP address using a
+ service such as http://dyndns.org/ + a dynamic DNS client such as
+ ``ddclient``.
+
+ If the peer cannot be reached, a restart will be triggered, causing the
+ hostname used with ``--remote`` to be re-resolved (if ``--resolv-retry``
+ is also specified).
+
+ In server mode, ``--ping-restart``, ``--inactive`` or any other type of
+ internally generated signal will always be applied to individual client
+ instance objects, never to whole server itself. Note also in server mode
+ that any internally generated signal which would normally cause a
+ restart, will cause the deletion of the client instance object instead.
+
+ In client mode, the ``--ping-restart`` parameter is set to 120 seconds
+ by default. This default will hold until the client pulls a replacement
+ value from the server, based on the ``--keepalive`` setting in the
+ server configuration. To disable the 120 second default, set
+ ``--ping-restart 0`` on the client.
+
+ See the signals section below for more information on :code:`SIGUSR1`.
+
+ Note that the behavior of ``SIGUSR1`` can be modified by the
+ ``--persist-tun``, ``--persist-key``, ``--persist-local-ip`` and
+ ``--persist-remote-ip`` options.
+
+ Also note that ``--ping-exit`` and ``--ping-restart`` are mutually
+ exclusive and cannot be used together.
+
+--ping-timer-rem
+ Run the ``--ping-exit`` / ``--ping-restart`` timer only if we have a
+ remote address. Use this option if you are starting the daemon in listen
+ mode (i.e. without an explicit ``--remote`` peer), and you don't want to
+ start clocking timeouts until a remote peer connects.
+
+--proto p
+ Use protocol ``p`` for communicating with remote host. ``p`` can be
+ :code:`udp`, :code:`tcp-client`, or :code:`tcp-server`.
+
+ The default protocol is :code:`udp` when ``--proto`` is not specified.
+
+ For UDP operation, ``--proto udp`` should be specified on both peers.
+
+ For TCP operation, one peer must use ``--proto tcp-server`` and the
+ other must use ``--proto tcp-client``. A peer started with
+ :code:`tcp-server` will wait indefinitely for an incoming connection. A peer
+ started with :code:`tcp-client` will attempt to connect, and if that fails,
+ will sleep for 5 seconds (adjustable via the ``--connect-retry`` option)
+ and try again infinite or up to N retries (adjustable via the
+ ``--connect-retry-max`` option). Both TCP client and server will
+ simulate a SIGUSR1 restart signal if either side resets the connection.
+
+ OpenVPN is designed to operate optimally over UDP, but TCP capability is
+ provided for situations where UDP cannot be used. In comparison with
+ UDP, TCP will usually be somewhat less efficient and less robust when
+ used over unreliable or congested networks.
+
+ This article outlines some of problems with tunneling IP over TCP:
+ http://sites.inka.de/sites/bigred/devel/tcp-tcp.html
+
+ There are certain cases, however, where using TCP may be advantageous
+ from a security and robustness perspective, such as tunneling non-IP or
+ application-level UDP protocols, or tunneling protocols which don't
+ possess a built-in reliability layer.
+
+--port port
+ TCP/UDP port number or port name for both local and remote (sets both
+ ``--lport`` and ``--rport`` options to given port). The current default
+ of 1194 represents the official IANA port number assignment for OpenVPN
+ and has been used since version 2.0-beta17. Previous versions used port
+ 5000 as the default.
+
+--rport port
+ Set TCP/UDP port number or name used by the ``--remote`` option. The
+ port can also be set directly using the ``--remote`` option.
+
+--replay-window args
+ Modify the replay protection sliding-window size and time window.
+
+ Valid syntax:
+ ::
+
+ replay-window n [t]
+
+ Use a replay protection sliding-window of size **n** and a time window
+ of **t** seconds.
+
+ By default **n** is 64 (the IPSec default) and **t** is 15 seconds.
+
+ This option is only relevant in UDP mode, i.e. when either **--proto
+ udp** is specified, or no **--proto** option is specified.
+
+ When OpenVPN tunnels IP packets over UDP, there is the possibility that
+ packets might be dropped or delivered out of order. Because OpenVPN,
+ like IPSec, is emulating the physical network layer, it will accept an
+ out-of-order packet sequence, and will deliver such packets in the same
+ order they were received to the TCP/IP protocol stack, provided they
+ satisfy several constraints.
+
+ (a) The packet cannot be a replay (unless ``--no-replay`` is
+ specified, which disables replay protection altogether).
+
+ (b) If a packet arrives out of order, it will only be accepted if
+ the difference between its sequence number and the highest sequence
+ number received so far is less than ``n``.
+
+ (c) If a packet arrives out of order, it will only be accepted if it
+ arrives no later than ``t`` seconds after any packet containing a higher
+ sequence number.
+
+ If you are using a network link with a large pipeline (meaning that the
+ product of bandwidth and latency is high), you may want to use a larger
+ value for ``n``. Satellite links in particular often require this.
+
+ If you run OpenVPN at ``--verb 4``, you will see the message
+ "Replay-window backtrack occurred [x]" every time the maximum sequence
+ number backtrack seen thus far increases. This can be used to calibrate
+ ``n``.
+
+ There is some controversy on the appropriate method of handling packet
+ reordering at the security layer.
+
+ Namely, to what extent should the security layer protect the
+ encapsulated protocol from attacks which masquerade as the kinds of
+ normal packet loss and reordering that occur over IP networks?
+
+ The IPSec and OpenVPN approach is to allow packet reordering within a
+ certain fixed sequence number window.
+
+ OpenVPN adds to the IPSec model by limiting the window size in time as
+ well as sequence space.
+
+ OpenVPN also adds TCP transport as an option (not offered by IPSec) in
+ which case OpenVPN can adopt a very strict attitude towards message
+ deletion and reordering: Don't allow it. Since TCP guarantees
+ reliability, any packet loss or reordering event can be assumed to be an
+ attack.
+
+ In this sense, it could be argued that TCP tunnel transport is preferred
+ when tunneling non-IP or UDP application protocols which might be
+ vulnerable to a message deletion or reordering attack which falls within
+ the normal operational parameters of IP networks.
+
+ So I would make the statement that one should never tunnel a non-IP
+ protocol or UDP application protocol over UDP, if the protocol might be
+ vulnerable to a message deletion or reordering attack that falls within
+ the normal operating parameters of what is to be expected from the
+ physical IP layer. The problem is easily fixed by simply using TCP as
+ the VPN transport layer.
+
+--replay-persist file
+ Persist replay-protection state across sessions using ``file`` to save
+ and reload the state.
+
+ This option will strengthen protection against replay attacks,
+ especially when you are using OpenVPN in a dynamic context (such as with
+ ``--inetd``) when OpenVPN sessions are frequently started and stopped.
+
+ This option will keep a disk copy of the current replay protection state
+ (i.e. the most recent packet timestamp and sequence number received from
+ the remote peer), so that if an OpenVPN session is stopped and
+ restarted, it will reject any replays of packets which were already
+ received by the prior session.
+
+ This option only makes sense when replay protection is enabled (the
+ default) and you are using either ``--secret`` (shared-secret key mode)
+ or TLS mode with ``--tls-auth``.
+
+--socket-flags flags
+ Apply the given flags to the OpenVPN transport socket. Currently, only
+ :code:`TCP_NODELAY` is supported.
+
+ The :code:`TCP_NODELAY` socket flag is useful in TCP mode, and causes the
+ kernel to send tunnel packets immediately over the TCP connection without
+ trying to group several smaller packets into a larger packet. This can
+ result in a considerably improvement in latency.
+
+ This option is pushable from server to client, and should be used on
+ both client and server for maximum effect.
+
+--tcp-nodelay
+ This macro sets the :code:`TCP_NODELAY` socket flag on the server as well
+ as pushes it to connecting clients. The :code:`TCP_NODELAY` flag disables
+ the Nagle algorithm on TCP sockets causing packets to be transmitted
+ immediately with low latency, rather than waiting a short period of time
+ in order to aggregate several packets into a larger containing packet.
+ In VPN applications over TCP, :code:`TCP_NODELAY` is generally a good
+ latency optimization.
+
+ The macro expands as follows:
+ ::
+
+ if mode server:
+ socket-flags TCP_NODELAY
+ push "socket-flags TCP_NODELAY"