summaryrefslogtreecommitdiff
path: root/doc/man-sections/vpn-network-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/vpn-network-options.rst
parenta8758c0e03eed188dcb9da0e4fd781a67c25bf1e (diff)
parent69b02b1f7fd609d84ace13ab04697158de2418a9 (diff)
Merge branch 'debian/experimental-2.5'
Diffstat (limited to 'doc/man-sections/vpn-network-options.rst')
-rw-r--r--doc/man-sections/vpn-network-options.rst534
1 files changed, 534 insertions, 0 deletions
diff --git a/doc/man-sections/vpn-network-options.rst b/doc/man-sections/vpn-network-options.rst
new file mode 100644
index 0000000..7100c1a
--- /dev/null
+++ b/doc/man-sections/vpn-network-options.rst
@@ -0,0 +1,534 @@
+Virtual Network Adapter (VPN interface)
+---------------------------------------
+
+Options in this section relates to configuration of the virtual tun/tap
+network interface, including setting the VPN IP address and network
+routing.
+
+--bind-dev device
+ (Linux only) Set ``device`` to bind the server socket to a
+ `Virtual Routing and Forwarding`_ device
+
+--block-ipv6
+ On the client, instead of sending IPv6 packets over the VPN tunnel, all
+ IPv6 packets are answered with an ICMPv6 no route host message. On the
+ server, all IPv6 packets from clients are answered with an ICMPv6 no
+ route to host message. This options is intended for cases when IPv6
+ should be blocked and other options are not available. ``--block-ipv6``
+ will use the remote IPv6 as source address of the ICMPv6 packets if set,
+ otherwise will use :code:`fe80::7` as source address.
+
+ For this option to make sense you actually have to route traffic to the
+ tun interface. The following example config block would send all IPv6
+ traffic to OpenVPN and answer all requests with no route to host,
+ effectively blocking IPv6.
+
+ **Client config**
+ ::
+
+ --ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1
+ --redirect-gateway ipv6
+ --block-ipv6
+
+ **Server config**
+ Push a "valid" ipv6 config to the client and block on the server
+ ::
+
+ --push "ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1"
+ --push "redirect-gateway ipv6"
+ --block-ipv6
+
+--dev device
+ TUN/TAP virtual network device which can be :code:`tunX`, :code:`tapX`,
+ :code:`null` or an arbitrary name string (:code:`X` can be omitted for
+ a dynamic device.)
+
+ See examples section below for an example on setting up a TUN device.
+
+ You must use either tun devices on both ends of the connection or tap
+ devices on both ends. You cannot mix them, as they represent different
+ underlying network layers:
+
+ :code:`tun`
+ devices encapsulate IPv4 or IPv6 (OSI Layer 3)
+
+ :code:`tap`
+ devices encapsulate Ethernet 802.3 (OSI Layer 2).
+
+ Valid syntaxes:
+ ::
+
+ dev tun2
+ dev tap4
+ dev ovpn
+
+ When the device name starts with :code:`tun` or :code:`tap`, the device
+ type is extracted automatically. Otherwise the ``--dev-type`` option
+ needs to be added as well.
+
+--dev-node node
+ Explicitly set the device node rather than using :code:`/dev/net/tun`,
+ :code:`/dev/tun`, :code:`/dev/tap`, etc. If OpenVPN cannot figure out
+ whether ``node`` is a TUN or TAP device based on the name, you should
+ also specify ``--dev-type tun`` or ``--dev-type tap``.
+
+ Under Mac OS X this option can be used to specify the default tun
+ implementation. Using ``--dev-node utun`` forces usage of the native
+ Darwin tun kernel support. Use ``--dev-node utunN`` to select a specific
+ utun instance. To force using the :code:`tun.kext` (:code:`/dev/tunX`)
+ use ``--dev-node tun``. When not specifying a ``--dev-node`` option
+ openvpn will first try to open utun, and fall back to tun.kext.
+
+ On Windows systems, select the TAP-Win32 adapter which is named ``node``
+ in the Network Connections Control Panel or the raw GUID of the adapter
+ enclosed by braces. The ``--show-adapters`` option under Windows can
+ also be used to enumerate all available TAP-Win32 adapters and will show
+ both the network connections control panel name and the GUID for each
+ TAP-Win32 adapter.
+
+--dev-type device-type
+ Which device type are we using? ``device-type`` should be :code:`tun`
+ (OSI Layer 3) or :code:`tap` (OSI Layer 2). Use this option only if
+ the TUN/TAP device used with ``--dev`` does not begin with :code:`tun`
+ or :code:`tap`.
+
+--dhcp-option args
+ Set additional network settings via DHCP. On Windows, this is parsed by
+ the ``tap-windows6`` or ``wintun`` driver. On other platforms these
+ options can be picked up by an ``--up`` script or plug-in if it has been
+ pushed by the OpenVPN server. The option will then be saved in the
+ client's environment before the ``--up`` script is called, under the name
+ :code:`foreign_option_{n}`.
+
+ Valid syntax:
+ ::
+
+ dhcp-options type [parm]
+
+ :code:`DOMAIN` ``name``
+ Set Connection-specific DNS Suffix to :code:`name`.
+
+ :code:`DNS` ``address``
+ Set primary domain name server IPv4 or IPv6 address.
+ Repeat this option to set secondary DNS server addresses.
+
+ Note: DNS IPv6 servers are currently set using netsh (the existing
+ DHCP code can only do IPv4 DHCP, and that protocol only permits
+ IPv4 addresses anywhere). The option will be put into the
+ environment, so an ``--up`` script could act upon it if needed.
+
+ :code:`WINS` ``address``
+ Set primary WINS server address (NetBIOS over TCP/IP Name Server).
+ Repeat this option to set secondary WINS server addresses.
+
+ :code:`NBDD` ``address``
+ Set primary NBDD server address (NetBIOS over TCP/IP Datagram
+ Distribution Server). Repeat this option to set secondary NBDD
+ server addresses.
+
+ :code:`NTP` ``address``
+ Set primary NTP server address (Network Time Protocol).
+ Repeat this option to set secondary NTP server addresses.
+
+ :code:`NBT` ``type``
+ Set NetBIOS over TCP/IP Node type. Possible options:
+
+ :code:`1`
+ b-node (broadcasts)
+
+ :code:`2`
+ p-node (point-to-point name queries to a WINS server)
+
+ :code:`4`
+ m-node (broadcast then query name server)
+
+ :code:`8`
+ h-node (query name server, then broadcast).
+
+ :code:`NBS` ``scope-id``
+ Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID provides an
+ extended naming service for the NetBIOS over TCP/IP (Known as NBT)
+ module. The primary purpose of a NetBIOS scope ID is to isolate
+ NetBIOS traffic on a single network to only those nodes with the
+ same NetBIOS scope ID. The NetBIOS scope ID is a character string
+ that is appended to the NetBIOS name. The NetBIOS scope ID on two
+ hosts must match, or the two hosts will not be able to communicate.
+ The NetBIOS Scope ID also allows computers to use the same computer
+ name, as they have different scope IDs. The Scope ID becomes a part
+ of the NetBIOS name, making the name unique. (This description of
+ NetBIOS scopes courtesy of NeonSurge@abyss.com)
+
+ :code:`DISABLE-NBT`
+ Disable Netbios-over-TCP/IP.
+
+--ifconfig args
+ Set TUN/TAP adapter parameters. It requires the *IP address* of the local
+ VPN endpoint. For TUN devices in point-to-point mode, the next argument
+ must be the VPN IP address of the remote VPN endpoint. For TAP devices,
+ or TUN devices used with ``--topology subnet``, the second argument
+ is the subnet mask of the virtual network segment which is being created
+ or connected to.
+
+ For TUN devices, which facilitate virtual point-to-point IP connections
+ (when used in ``--topology net30`` or ``p2p`` mode), the proper usage of
+ ``--ifconfig`` is to use two private IP addresses which are not a member
+ of any existing subnet which is in use. The IP addresses may be
+ consecutive and should have their order reversed on the remote peer.
+ After the VPN is established, by pinging ``rn``, you will be pinging
+ across the VPN.
+
+ For TAP devices, which provide the ability to create virtual ethernet
+ segments, or TUN devices in ``--topology subnet`` mode (which create
+ virtual "multipoint networks"), ``--ifconfig`` is used to set an IP
+ address and subnet mask just as a physical ethernet adapter would be
+ similarly configured. If you are attempting to connect to a remote
+ ethernet bridge, the IP address and subnet should be set to values which
+ would be valid on the the bridged ethernet segment (note also that DHCP
+ can be used for the same purpose).
+
+ This option, while primarily a proxy for the ``ifconfig``\(8) command,
+ is designed to simplify TUN/TAP tunnel configuration by providing a
+ standard interface to the different ifconfig implementations on
+ different platforms.
+
+ ``--ifconfig`` parameters which are IP addresses can also be specified
+ as a DNS or /etc/hosts file resolvable name.
+
+ For TAP devices, ``--ifconfig`` should not be used if the TAP interface
+ will be getting an IP address lease from a DHCP server.
+
+ Examples:
+ ::
+
+ # tun device in net30/p2p mode
+ ifconfig 10.8.0.2 10.8.0.1
+
+ # tun/tap device in subnet mode
+ ifconfig 10.8.0.2 255.255.255.0
+
+--ifconfig-ipv6 args
+ Configure an IPv6 address on the *tun* device.
+
+ Valid syntax:
+ ::
+
+ ifconfig-ipv6 ipv6addr/bits [ipv6remote]
+
+ The ``ipv6addr/bits`` argument is the IPv6 address to use. The
+ second parameter is used as route target for ``--route-ipv6`` if no
+ gateway is specified.
+
+ The ``--topology`` option has no influence with ``--ifconfig-ipv6``
+
+--ifconfig-noexec
+ Don't actually execute ifconfig/netsh commands, instead pass
+ ``--ifconfig`` parameters to scripts using environmental variables.
+
+--ifconfig-nowarn
+ Don't output an options consistency check warning if the ``--ifconfig``
+ option on this side of the connection doesn't match the remote side.
+ This is useful when you want to retain the overall benefits of the
+ options consistency check (also see ``--disable-occ`` option) while only
+ disabling the ifconfig component of the check.
+
+ For example, if you have a configuration where the local host uses
+ ``--ifconfig`` but the remote host does not, use ``--ifconfig-nowarn``
+ on the local host.
+
+ This option will also silence warnings about potential address conflicts
+ which occasionally annoy more experienced users by triggering "false
+ positive" warnings.
+
+--lladdr address
+ Specify the link layer address, more commonly known as the MAC address.
+ Only applied to TAP devices.
+
+--persist-tun
+ Don't close and reopen TUN/TAP device or run up/down scripts across
+ :code:`SIGUSR1` or ``--ping-restart`` restarts.
+
+ :code:`SIGUSR1` is a restart signal similar to :code:`SIGHUP`, but which
+ offers finer-grained control over reset options.
+
+--redirect-gateway flags
+ Automatically execute routing commands to cause all outgoing IP traffic
+ to be redirected over the VPN. This is a client-side option.
+
+ This option performs three steps:
+
+ (1) Create a static route for the ``--remote`` address which
+ forwards to the pre-existing default gateway. This is done so that
+ ``(3)`` will not create a routing loop.
+
+ (2) Delete the default gateway route.
+
+ (3) Set the new default gateway to be the VPN endpoint address
+ (derived either from ``--route-gateway`` or the second parameter to
+ ``--ifconfig`` when ``--dev tun`` is specified).
+
+ When the tunnel is torn down, all of the above steps are reversed so
+ that the original default route is restored.
+
+ Option flags:
+
+ :code:`local`
+ Add the :code:`local` flag if both OpenVPN peers are directly
+ connected via a common subnet, such as with wireless. The
+ :code:`local` flag will cause step ``(1)`` above to be omitted.
+
+ :code:`autolocal`
+ Try to automatically determine whether to enable :code:`local`
+ flag above.
+
+ :code:`def1`
+ Use this flag to override the default gateway by using
+ :code:`0.0.0.0/1` and :code:`128.0.0.0/1` rather than
+ :code:`0.0.0.0/0`. This has the benefit of overriding but not
+ wiping out the original default gateway.
+
+ :code:`bypass-dhcp`
+ Add a direct route to the DHCP server (if it is non-local) which
+ bypasses the tunnel (Available on Windows clients, may not be
+ available on non-Windows clients).
+
+ :code:`bypass-dns`
+ Add a direct route to the DNS server(s) (if they are non-local)
+ which bypasses the tunnel (Available on Windows clients, may
+ not be available on non-Windows clients).
+
+ :code:`block-local`
+ Block access to local LAN when the tunnel is active, except for
+ the LAN gateway itself. This is accomplished by routing the local
+ LAN (except for the LAN gateway address) into the tunnel.
+
+ :code:`ipv6`
+ Redirect IPv6 routing into the tunnel. This works similar to
+ the :code:`def1` flag, that is, more specific IPv6 routes are added
+ (:code:`2000::/4`, :code:`3000::/4`), covering the whole IPv6
+ unicast space.
+
+ :code:`!ipv4`
+ Do not redirect IPv4 traffic - typically used in the flag pair
+ :code:`ipv6 !ipv4` to redirect IPv6-only.
+
+--redirect-private flags
+ Like ``--redirect-gateway``, but omit actually changing the default gateway.
+ Useful when pushing private subnets.
+
+--route args
+ Add route to routing table after connection is established. Multiple
+ routes can be specified. Routes will be automatically torn down in
+ reverse order prior to TUN/TAP device close.
+
+ Valid syntaxes:
+ ::
+
+ route network/IP
+ route network/IP netmask
+ route network/IP netmask gateway
+ route network/IP netmask gateway metric
+
+ This option is intended as a convenience proxy for the ``route``\(8)
+ shell command, while at the same time providing portable semantics
+ across OpenVPN's platform space.
+
+ ``netmask``
+ defaults to :code:`255.255.255.255` when not given
+
+ ``gateway``
+ default taken from ``--route-gateway`` or the second
+ parameter to ``--ifconfig`` when ``--dev tun`` is specified.
+
+ ``metric``
+ default taken from ``--route-metric`` if set, otherwise :code:`0`.
+
+ The default can be specified by leaving an option blank or setting it to
+ :code:`default`.
+
+ The ``network`` and ``gateway`` parameters can also be specified as a
+ DNS or :code:`/etc/hosts` file resolvable name, or as one of three special
+ keywords:
+
+ :code:`vpn_gateway`
+ The remote VPN endpoint address (derived either from
+ ``--route-gateway`` or the second parameter to ``--ifconfig``
+ when ``--dev tun`` is specified).
+
+ :code:`net_gateway`
+ The pre-existing IP default gateway, read from the
+ routing table (not supported on all OSes).
+
+ :code:`remote_host`
+ The ``--remote`` address if OpenVPN is being run in
+ client mode, and is undefined in server mode.
+
+--route-delay args
+ Valid syntaxes:
+ ::
+
+ route-delay
+ route-delay n
+ route-delay n m
+
+ Delay ``n`` seconds (default :code:`0`) after connection establishment,
+ before adding routes. If ``n`` is :code:`0`, routes will be added
+ immediately upon connection establishment. If ``--route-delay`` is
+ omitted, routes will be added immediately after TUN/TAP device open and
+ ``--up`` script execution, before any ``--user`` or ``--group`` privilege
+ downgrade (or ``--chroot`` execution.)
+
+ This option is designed to be useful in scenarios where DHCP is used to
+ set tap adapter addresses. The delay will give the DHCP handshake time
+ to complete before routes are added.
+
+ On Windows, ``--route-delay`` tries to be more intelligent by waiting
+ ``w`` seconds (default :code:`30` by default) for the TAP-Win32 adapter
+ to come up before adding routes.
+
+--route-ipv6 args
+ Setup IPv6 routing in the system to send the specified IPv6 network into
+ OpenVPN's *tun*.
+
+ Valid syntax:
+ ::
+
+ route-ipv6 ipv6addr/bits [gateway] [metric]
+
+ The gateway parameter is only used for IPv6 routes across *tap* devices,
+ and if missing, the ``ipv6remote`` field from ``--ifconfig-ipv6`` or
+ ``--route-ipv6-gateway`` is used.
+
+--route-gateway arg
+ Specify a default *gateway* for use with ``--route``.
+
+ If :code:`dhcp` is specified as the parameter, the gateway address will
+ be extracted from a DHCP negotiation with the OpenVPN server-side LAN.
+
+ Valid syntaxes:
+ ::
+
+ route-gateway gateway
+ route-gateway dhcp
+
+--route-ipv6-gateway gw
+ Specify a default gateway ``gw`` for use with ``--route-ipv6``.
+
+--route-metric m
+ Specify a default metric ``m`` for use with ``--route``.
+
+--route-noexec
+ Don't add or remove routes automatically. Instead pass routes to
+ ``--route-up`` script using environmental variables.
+
+--route-nopull
+ When used with ``--client`` or ``--pull``, accept options pushed by
+ server EXCEPT for routes, block-outside-dns and dhcp options like DNS
+ servers.
+
+ When used on the client, this option effectively bars the server from
+ adding routes to the client's routing table, however note that this
+ option still allows the server to set the TCP/IP properties of the
+ client's TUN/TAP interface.
+
+--topology mode
+ Configure virtual addressing topology when running in ``--dev tun``
+ mode. This directive has no meaning in ``--dev tap`` mode, which always
+ uses a :code:`subnet` topology.
+
+ If you set this directive on the server, the ``--server`` and
+ ``--server-bridge`` directives will automatically push your chosen
+ topology setting to clients as well. This directive can also be manually
+ pushed to clients. Like the ``--dev`` directive, this directive must
+ always be compatible between client and server.
+
+ ``mode`` can be one of:
+
+ :code:`net30`
+ Use a point-to-point topology, by allocating one /30 subnet
+ per client. This is designed to allow point-to-point semantics when some
+ or all of the connecting clients might be Windows systems. This is the
+ default on OpenVPN 2.0.
+
+ :code:`p2p`
+ Use a point-to-point topology where the remote endpoint of
+ the client's tun interface always points to the local endpoint of the
+ server's tun interface. This mode allocates a single IP address per
+ connecting client. Only use when none of the connecting clients are
+ Windows systems.
+
+ :code:`subnet`
+ Use a subnet rather than a point-to-point topology by
+ configuring the tun interface with a local IP address and subnet mask,
+ similar to the topology used in ``--dev tap`` and ethernet bridging
+ mode. This mode allocates a single IP address per connecting client and
+ works on Windows as well. Only available when server and clients are
+ OpenVPN 2.1 or higher, or OpenVPN 2.0.x which has been manually patched
+ with the ``--topology`` directive code. When used on Windows, requires
+ version 8.2 or higher of the TAP-Win32 driver. When used on \*nix,
+ requires that the tun driver supports an ``ifconfig``\(8) command which
+ sets a subnet instead of a remote endpoint IP address.
+
+ *Note:* Using ``--topology subnet`` changes the interpretation of the
+ arguments of ``--ifconfig`` to mean "address netmask", no longer "local
+ remote".
+
+--tun-mtu n
+ Take the TUN device MTU to be **n** and derive the link MTU from it
+ (default :code:`1500`). In most cases, you will probably want to leave
+ this parameter set to its default value.
+
+ The MTU (Maximum Transmission Units) is the maximum datagram size in
+ bytes that can be sent unfragmented over a particular network path.
+ OpenVPN requires that packets on the control and data channels be sent
+ unfragmented.
+
+ MTU problems often manifest themselves as connections which hang during
+ periods of active usage.
+
+ It's best to use the ``--fragment`` and/or ``--mssfix`` options to deal
+ with MTU sizing issues.
+
+--tun-mtu-extra n
+ Assume that the TUN/TAP device might return as many as ``n`` bytes more
+ than the ``--tun-mtu`` size on read. This parameter defaults to 0, which
+ is sufficient for most TUN devices. TAP devices may introduce additional
+ overhead in excess of the MTU size, and a setting of 32 is the default
+ when TAP devices are used. This parameter only controls internal OpenVPN
+ buffer sizing, so there is no transmission overhead associated with
+ using a larger value.
+
+
+TUN/TAP standalone operations
+-----------------------------
+These two standalone operations will require ``--dev`` and optionally
+``--user`` and/or ``--group``.
+
+--mktun
+ (Standalone) Create a persistent tunnel on platforms which support them
+ such as Linux. Normally TUN/TAP tunnels exist only for the period of
+ time that an application has them open. This option takes advantage of
+ the TUN/TAP driver's ability to build persistent tunnels that live
+ through multiple instantiations of OpenVPN and die only when they are
+ deleted or the machine is rebooted.
+
+ One of the advantages of persistent tunnels is that they eliminate the
+ need for separate ``--up`` and ``--down`` scripts to run the appropriate
+ ``ifconfig``\(8) and ``route``\(8) commands. These commands can be
+ placed in the the same shell script which starts or terminates an
+ OpenVPN session.
+
+ Another advantage is that open connections through the TUN/TAP-based
+ tunnel will not be reset if the OpenVPN peer restarts. This can be
+ useful to provide uninterrupted connectivity through the tunnel in the
+ event of a DHCP reset of the peer's public IP address (see the
+ ``--ipchange`` option above).
+
+ One disadvantage of persistent tunnels is that it is harder to
+ automatically configure their MTU value (see ``--link-mtu`` and
+ ``--tun-mtu`` above).
+
+ On some platforms such as Windows, TAP-Win32 tunnels are persistent by
+ default.
+
+--rmtun
+ (Standalone) Remove a persistent tunnel.