Merge branch 'debian/experimental-2.5'

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.