summaryrefslogtreecommitdiff
path: root/doc/man-sections/windows-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/windows-options.rst
parenta8758c0e03eed188dcb9da0e4fd781a67c25bf1e (diff)
parent69b02b1f7fd609d84ace13ab04697158de2418a9 (diff)
Merge branch 'debian/experimental-2.5'
Diffstat (limited to 'doc/man-sections/windows-options.rst')
-rw-r--r--doc/man-sections/windows-options.rst244
1 files changed, 244 insertions, 0 deletions
diff --git a/doc/man-sections/windows-options.rst b/doc/man-sections/windows-options.rst
new file mode 100644
index 0000000..eacb9af
--- /dev/null
+++ b/doc/man-sections/windows-options.rst
@@ -0,0 +1,244 @@
+Windows-Specific Options
+-------------------------
+
+--allow-nonadmin TAP-adapter
+ (Standalone) Set ``TAP-adapter`` to allow access from non-administrative
+ accounts. If ``TAP-adapter`` is omitted, all TAP adapters on the system
+ will be configured to allow non-admin access. The non-admin access
+ setting will only persist for the length of time that the TAP-Win32
+ device object and driver remain loaded, and will need to be re-enabled
+ after a reboot, or if the driver is unloaded and reloaded. This
+ directive can only be used by an administrator.
+
+--block-outside-dns
+ Block DNS servers on other network adapters to prevent DNS leaks. This
+ option prevents any application from accessing TCP or UDP port 53 except
+ one inside the tunnel. It uses Windows Filtering Platform (WFP) and
+ works on Windows Vista or later.
+
+ This option is considered unknown on non-Windows platforms and
+ unsupported on Windows XP, resulting in fatal error. You may want to use
+ ``--setenv opt`` or ``--ignore-unknown-option`` (not suitable for
+ Windows XP) to ignore said error. Note that pushing unknown options from
+ server does not trigger fatal errors.
+
+--cryptoapicert select-string
+ *(Windows/OpenSSL Only)* Load the certificate and private key from the
+ Windows Certificate System Store.
+
+ Use this option instead of ``--cert`` and ``--key``.
+
+ This makes it possible to use any smart card, supported by Windows, but
+ also any kind of certificate, residing in the Cert Store, where you have
+ access to the private key. This option has been tested with a couple of
+ different smart cards (GemSAFE, Cryptoflex, and Swedish Post Office eID)
+ on the client side, and also an imported PKCS12 software certificate on
+ the server side.
+
+ To select a certificate, based on a substring search in the
+ certificate's subject:
+ ::
+
+ cryptoapicert "SUBJ:Peter Runestig"
+
+ To select a certificate, based on certificate's thumbprint:
+ ::
+
+ cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."
+
+ The thumbprint hex string can easily be copy-and-pasted from the Windows
+ Certificate Store GUI.
+
+--dhcp-release
+ Ask Windows to release the TAP adapter lease on shutdown. This option
+ has no effect now, as it is enabled by default starting with
+ OpenVPN 2.4.1.
+
+--dhcp-renew
+ Ask Windows to renew the TAP adapter lease on startup. This option is
+ normally unnecessary, as Windows automatically triggers a DHCP
+ renegotiation on the TAP adapter when it comes up, however if you set
+ the TAP-Win32 adapter Media Status property to "Always Connected", you
+ may need this flag.
+
+--ip-win32 method
+ When using ``--ifconfig`` on Windows, set the TAP-Win32 adapter IP
+ address and netmask using ``method``. Don't use this option unless you
+ are also using ``--ifconfig``.
+
+ :code:`manual`
+ Don't set the IP address or netmask automatically. Instead
+ output a message to the console telling the user to configure the
+ adapter manually and indicating the IP/netmask which OpenVPN
+ expects the adapter to be set to.
+
+ :code:`dynamic [offset] [lease-time]`
+ Automatically set the IP address and netmask by replying to DHCP
+ query messages generated by the kernel. This mode is probably the
+ "cleanest" solution for setting the TCP/IP properties since it
+ uses the well-known DHCP protocol. There are, however, two
+ prerequisites for using this mode:
+
+ (1) The TCP/IP properties for the TAP-Win32 adapter must be set
+ to "Obtain an IP address automatically", and
+
+ (2) OpenVPN needs to claim an IP address in the subnet for use
+ as the virtual DHCP server address.
+
+ By default in ``--dev tap`` mode, OpenVPN will take the normally
+ unused first address in the subnet. For example, if your subnet is
+ :code:`192.168.4.0 netmask 255.255.255.0`, then OpenVPN will take
+ the IP address :code:`192.168.4.0` to use as the virtual DHCP
+ server address. In ``--dev tun`` mode, OpenVPN will cause the DHCP
+ server to masquerade as if it were coming from the remote endpoint.
+
+ The optional offset parameter is an integer which is > :code:`-256`
+ and < :code:`256` and which defaults to -1. If offset is positive,
+ the DHCP server will masquerade as the IP address at network
+ address + offset. If offset is negative, the DHCP server will
+ masquerade as the IP address at broadcast address + offset.
+
+ The Windows :code:`ipconfig /all` command can be used to show what
+ Windows thinks the DHCP server address is. OpenVPN will "claim"
+ this address, so make sure to use a free address. Having said that,
+ different OpenVPN instantiations, including different ends of
+ the same connection, can share the same virtual DHCP server
+ address.
+
+ The ``lease-time`` parameter controls the lease time of the DHCP
+ assignment given to the TAP-Win32 adapter, and is denoted in
+ seconds. Normally a very long lease time is preferred because it
+ prevents routes involving the TAP-Win32 adapter from being lost
+ when the system goes to sleep. The default lease time is one year.
+
+ :code:`netsh`
+ Automatically set the IP address and netmask using the Windows
+ command-line "netsh" command. This method appears to work correctly
+ on Windows XP but not Windows 2000.
+
+ :code:`ipapi`
+ Automatically set the IP address and netmask using the Windows IP
+ Helper API. This approach does not have ideal semantics, though
+ testing has indicated that it works okay in practice. If you use
+ this option, it is best to leave the TCP/IP properties for the
+ TAP-Win32 adapter in their default state, i.e. "Obtain an IP
+ address automatically."
+
+ :code:`adaptive` (Default)
+ Try :code:`dynamic` method initially and fail over to :code:`netsh`
+ if the DHCP negotiation with the TAP-Win32 adapter does not succeed
+ in 20 seconds. Such failures have been known to occur when certain
+ third-party firewall packages installed on the client machine block
+ the DHCP negotiation used by the TAP-Win32 adapter. Note that if
+ the :code:`netsh` failover occurs, the TAP-Win32 adapter TCP/IP
+ properties will be reset from DHCP to static, and this will cause
+ future OpenVPN startups using the :code:`adaptive` mode to use
+ :code:`netsh` immediately, rather than trying :code:`dynamic` first.
+
+ To "unstick" the :code:`adaptive` mode from using :code:`netsh`,
+ run OpenVPN at least once using the :code:`dynamic` mode to restore
+ the TAP-Win32 adapter TCP/IP properties to a DHCP configuration.
+
+--pause-exit
+ Put up a "press any key to continue" message on the console prior to
+ OpenVPN program exit. This option is automatically used by the Windows
+ explorer when OpenVPN is run on a configuration file using the
+ right-click explorer menu.
+
+--register-dns
+ Run :code:`ipconfig /flushdns` and :code:`ipconfig /registerdns` on
+ connection initiation. This is known to kick Windows into recognizing
+ pushed DNS servers.
+
+--route-method m
+ Which method ``m`` to use for adding routes on Windows?
+
+ :code:`adaptive` (default)
+ Try IP helper API first. If that fails, fall back to the route.exe
+ shell command.
+
+ :code:`ipapi`
+ Use IP helper API.
+
+ :code:`exe`
+ Call the route.exe shell command.
+
+--service args
+ Should be used when OpenVPN is being automatically executed by another
+ program in such a context that no interaction with the user via display
+ or keyboard is possible.
+
+ Valid syntax:
+ ::
+
+ service exit-event [0|1]
+
+ In general, end-users should never need to explicitly use this option,
+ as it is automatically added by the OpenVPN service wrapper when a given
+ OpenVPN configuration is being run as a service.
+
+ ``exit-event`` is the name of a Windows global event object, and OpenVPN
+ will continuously monitor the state of this event object and exit when
+ it becomes signaled.
+
+ The second parameter indicates the initial state of ``exit-event`` and
+ normally defaults to 0.
+
+ Multiple OpenVPN processes can be simultaneously executed with the same
+ ``exit-event`` parameter. In any case, the controlling process can
+ signal ``exit-event``, causing all such OpenVPN processes to exit.
+
+ When executing an OpenVPN process using the ``--service`` directive,
+ OpenVPN will probably not have a console window to output status/error
+ messages, therefore it is useful to use ``--log`` or ``--log-append`` to
+ write these messages to a file.
+
+--show-adapters
+ (Standalone) Show available TAP-Win32 adapters which can be selected
+ using the ``--dev-node`` option. On non-Windows systems, the
+ ``ifconfig``\(8) command provides similar functionality.
+
+--show-net
+ (Standalone) Show OpenVPN's view of the system routing table and network
+ adapter list.
+
+--show-net-up
+ Output OpenVPN's view of the system routing table and network adapter
+ list to the syslog or log file after the TUN/TAP adapter has been
+ brought up and any routes have been added.
+
+--show-valid-subnets
+ (Standalone) Show valid subnets for ``--dev tun`` emulation. Since the
+ TAP-Win32 driver exports an ethernet interface to Windows, and since TUN
+ devices are point-to-point in nature, it is necessary for the TAP-Win32
+ driver to impose certain constraints on TUN endpoint address selection.
+
+ Namely, the point-to-point endpoints used in TUN device emulation must
+ be the middle two addresses of a /30 subnet (netmask 255.255.255.252).
+
+--tap-sleep n
+ Cause OpenVPN to sleep for ``n`` seconds immediately after the TAP-Win32
+ adapter state is set to "connected".
+
+ This option is intended to be used to troubleshoot problems with the
+ ``--ifconfig`` and ``--ip-win32`` options, and is used to give the
+ TAP-Win32 adapter time to come up before Windows IP Helper API
+ operations are applied to it.
+
+--win-sys path
+ Set the Windows system directory pathname to use when looking for system
+ executables such as ``route.exe`` and ``netsh.exe``. By default, if this
+ directive is not specified, OpenVPN will use the SystemRoot environment
+ variable.
+
+ This option has changed behaviour since OpenVPN 2.3. Earlier you had to
+ define ``--win-sys env`` to use the SystemRoot environment variable,
+ otherwise it defaulted to :code:`C:\\WINDOWS`. It is not needed to use
+ the ``env`` keyword any more, and it will just be ignored. A warning is
+ logged when this is found in the configuration file.
+
+--windows-driver drv
+ Specifies which tun driver to use. Values are :code:`tap-windows6`
+ (default) and :code:`wintun`. This is a Windows-only option.
+ :code:`wintun`" requires ``--dev tun`` and the OpenVPN process to run
+ elevated, or be invoked using the Interactive Service.