From 1079962e4c06f88a54e50d997c1b7e84303d30b4 Mon Sep 17 00:00:00 2001 From: Bernhard Schmidt Date: Sat, 15 Aug 2020 21:29:50 +0200 Subject: New upstream version 2.5~beta1 --- doc/man-sections/windows-options.rst | 244 +++++++++++++++++++++++++++++++++++ 1 file changed, 244 insertions(+) create mode 100644 doc/man-sections/windows-options.rst (limited to 'doc/man-sections/windows-options.rst') 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. -- cgit v1.2.3