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"