diff options
Diffstat (limited to 'doc/man-sections/link-options.rst')
| -rw-r--r-- | doc/man-sections/link-options.rst | 409 |
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" |