doc/man-sections/connection-profiles.rst

   1 CONNECTION PROFILES
   2 ===================
   3
   4 Client configuration files may contain multiple remote servers which
   5 it will attempt to connect against.  But there are some configuration
   6 options which are related to specific ``--remote`` options.  For these
   7 use cases, connection profiles are the solution.
   8
   9 By enacpulating the ``--remote`` option and related options within
  10 ``<connection>`` and ``</connection>``, these options are handled as a
  11 group.
  12
  13 An OpenVPN client will try each connection profile sequentially until it
  14 achieves a successful connection.
  15
  16 ``--remote-random`` can be used to initially "scramble" the connection
  17 list.
  18
  19 Here is an example of connection profile usage::
  20
  21    client
  22    dev tun
  23
  24    <connection>
  25    remote 198.19.34.56 1194 udp
  26    </connection>
  27
  28    <connection>
  29    remote 198.19.34.56 443 tcp
  30    </connection>
  31
  32    <connection>
  33    remote 198.19.34.56 443 tcp
  34    http-proxy 192.168.0.8 8080
  35    </connection>
  36
  37    <connection>
  38    remote 198.19.36.99 443 tcp
  39    http-proxy 192.168.0.8 8080
  40    </connection>
  41
  42    persist-tun
  43    pkcs12 client.p12
  44    remote-cert-tls server
  45    verb 3
  46
  47 First we try to connect to a server at 198.19.34.56:1194 using UDP. If
  48 that fails, we then try to connect to 198.19.34.56:443 using TCP. If
  49 that also fails, then try connecting through an HTTP proxy at
  50 192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to connect
  51 through the same proxy to a server at 198.19.36.99:443 using TCP.
  52
  53 The following OpenVPN options may be used inside of a ``<connection>``
  54 block:
  55
  56 ``bind``, ``connect-retry``, ``connect-retry-max``, ``connect-timeout``,
  57 ``explicit-exit-notify``, ``float``, ``fragment``, ``http-proxy``,
  58 ``http-proxy-option``, ``key-direction``, ``link-mtu``, ``local``,
  59 ``lport``, ``mssfix``, ``mtu-disc``, ``nobind``, ``port``, ``proto``,
  60 ``remote``, ``rport``, ``socks-proxy``, ``tls-auth``, ``tls-crypt``,
  61 ``tun-mtu and``, ``tun-mtu-extra``.
  62
  63 A defaulting mechanism exists for specifying options to apply to all
  64 ``<connection>`` profiles. If any of the above options (with the
  65 exception of ``remote`` ) appear outside of a ``<connection>`` block,
  66 but in a configuration file which has one or more ``<connection>``
  67 blocks, the option setting will be used as a default for
  68 ``<connection>`` blocks which follow it in the configuration file.
  69
  70 For example, suppose the ``nobind`` option were placed in the sample
  71 configuration file above, near the top of the file, before the first
  72 ``<connection>`` block. The effect would be as if ``nobind`` were
  73 declared in all ``<connection>`` blocks below it.