summaryrefslogtreecommitdiff
path: root/main/openvpn/doc
diff options
context:
space:
mode:
Diffstat (limited to 'main/openvpn/doc')
m---------main/openvpn0
-rw-r--r--main/openvpn/doc/Makefile.am31
-rw-r--r--main/openvpn/doc/README.plugins47
-rw-r--r--main/openvpn/doc/android.txt91
-rw-r--r--main/openvpn/doc/doxygen/doc_compression.h92
-rw-r--r--main/openvpn/doc/doxygen/doc_control_processor.h189
-rw-r--r--main/openvpn/doc/doxygen/doc_control_tls.h105
-rw-r--r--main/openvpn/doc/doxygen/doc_data_control.h103
-rw-r--r--main/openvpn/doc/doxygen/doc_data_crypto.h73
-rw-r--r--main/openvpn/doc/doxygen/doc_eventloop.h67
-rw-r--r--main/openvpn/doc/doxygen/doc_external_multiplexer.h46
-rw-r--r--main/openvpn/doc/doxygen/doc_fragmentation.h96
-rw-r--r--main/openvpn/doc/doxygen/doc_internal_multiplexer.h44
-rw-r--r--main/openvpn/doc/doxygen/doc_key_generation.h153
-rw-r--r--main/openvpn/doc/doxygen/doc_mainpage.h162
-rw-r--r--main/openvpn/doc/doxygen/doc_memory_management.h99
-rw-r--r--main/openvpn/doc/doxygen/doc_protocol_overview.h196
-rw-r--r--main/openvpn/doc/doxygen/doc_reliable.h49
-rw-r--r--main/openvpn/doc/doxygen/doc_tunnel_state.h155
-rw-r--r--main/openvpn/doc/doxygen/openvpn.doxyfile279
-rw-r--r--main/openvpn/doc/management-notes.txt1039
-rw-r--r--main/openvpn/doc/openvpn.86709
22 files changed, 0 insertions, 9825 deletions
diff --git a/main/openvpn b/main/openvpn
new file mode 160000
+Subproject 7aaf01766f9718375986600216607aeb6397200
diff --git a/main/openvpn/doc/Makefile.am b/main/openvpn/doc/Makefile.am
deleted file mode 100644
index d33e1edd..00000000
--- a/main/openvpn/doc/Makefile.am
+++ /dev/null
@@ -1,31 +0,0 @@
-#
-# OpenVPN -- An application to securely tunnel IP networks
-# over a single UDP port, with support for SSL/TLS-based
-# session authentication and key exchange,
-# packet encryption, packet authentication, and
-# packet compression.
-#
-# Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net>
-# Copyright (C) 2006-2012 Alon Bar-Lev <alon.barlev@gmail.com>
-#
-
-MAINTAINERCLEANFILES = \
- $(srcdir)/Makefile.in
-
-CLEANFILES = openvpn.8.html
-
-dist_doc_DATA = \
- management-notes.txt
-
-dist_noinst_DATA = \
- README.plugins
-
-if WIN32
-dist_noinst_DATA += openvpn.8
-nodist_html_DATA = openvpn.8.html
-openvpn.8.html: $(srcdir)/openvpn.8
- $(MAN2HTML) < $(srcdir)/openvpn.8 > openvpn.8.html
-else
-dist_man_MANS = openvpn.8
-endif
-
diff --git a/main/openvpn/doc/README.plugins b/main/openvpn/doc/README.plugins
deleted file mode 100644
index 6e490c5a..00000000
--- a/main/openvpn/doc/README.plugins
+++ /dev/null
@@ -1,47 +0,0 @@
-OpenVPN Plugins
----------------
-
-Starting with OpenVPN 2.0-beta17, compiled plugin modules are
-supported on any *nix OS which includes libdl or on Windows.
-One or more modules may be loaded into OpenVPN using
-the --plugin directive, and each plugin module is capable of
-intercepting any of the script callbacks which OpenVPN supports:
-
-(1) up
-(2) down
-(3) route-up
-(4) ipchange
-(5) tls-verify
-(6) auth-user-pass-verify
-(7) client-connect
-(8) client-disconnect
-(9) learn-address
-
-See the openvpn-plugin.h file in the top-level directory of the
-OpenVPN source distribution for more detailed information
-on the plugin interface.
-
-Included Plugins
-----------------
-
-auth-pam -- Authenticate using PAM and a split privilege
- execution model which functions even if
- root privileges or the execution environment
- have been altered with --user/--group/--chroot.
- Tested on Linux only.
-
-down-root -- Enable the running of down scripts with root privileges
- even if --user/--group/--chroot have been used
- to drop root privileges or change the execution
- environment. Not applicable on Windows.
-
-examples -- A simple example that demonstrates a portable
- plugin, i.e. one which can be built for *nix
- or Windows from the same source.
-
-Building Plugins
-----------------
-
-cd to the top-level directory of a plugin, and use the
-"make" command to build it. The examples plugin is
-built using a build script, not a makefile.
diff --git a/main/openvpn/doc/android.txt b/main/openvpn/doc/android.txt
deleted file mode 100644
index 137edfc5..00000000
--- a/main/openvpn/doc/android.txt
+++ /dev/null
@@ -1,91 +0,0 @@
-This file documents the support in OpenVPN for Android 4.0 and up.
-
-This support is primarily used in the "OpenVPN for Android" app
-(http://code.google.com/p/ics-openvpn/). For building see the developer
-README: http://code.google.com/p/ics-openvpn/source/browse/doc/README.txt.
-
-Android provides the VPNService API
-(http://developer.android.com/reference/android/net/VpnService.html)
-which allows establishing VPN connections without rooting the device.
-
-Since all the interfaces are are Android specific the calls to this
-interface are made from the UI instead of OpenVPN directly. The API
-needs the following parameters:
-
-- IP and netmask of tun interface
-- Networks that should be routed to the tun interface
-- DNS Servers and DNS Domain
-- MTU
-
-All IPs/Routes are in CIDR style. Non CIDR routes are not supported.
-Notable is the lack of support for setting routes to other interfaces
-usually used to avoid the server connection going over the tun
-interface. The Android VPNService API has the concept of protecting
-a socket from being routed over a interface. Calling protect (fd)
-will internally bind the socket to the interface used for the
-external connection (usually WiFi or mobile data).
-
-To use OpenVPN with the VPNService API OpenVPN must be build with
-the TARGET_ANDROID compile option. Also the UI must use a UNIX
-domain socket to connect to OpenVPN. When compiled as TARGET_ANDROID
-OpenVPN will use management callbacks instead of executing traditional
-ifconfig/route commands use the need-ok callback mechanism which
-will ask
-
-> NEED-OK command
-
-where command can be:
-
-IFCONFIG6 IPv6/netmask
-IFCONFIG local remoteOrNetmask MTU topology
-
-To tell the UI which IPs addresses OpenVPN expects on the interface.
-Topology is one of "net30","p2p","subnet" or "undef".
-
-ROUTE6 network/netmask
-ROUTE network netmask
-
-To tell the UI which routes should be set on the tun interface.
-
-DNSSERVER serverip
-DNSDOMAIN searchdomain
-
-To set the DNS server and search domain.
-
-The GUI will then respond with a "needok 'command' ok' or "needok
-'command' cancel', e.g. "needok 'IFCONFIG' ok".
-
-PERSIST_TUN_ACTION
-
-In Android 4.4-4.4.2 a bug exists that does not allow to open a new tun fd
-while a tun fd is still open. When OpenVPN wants to open an fd it will do
-this query. The UI should compare the last configuration of
-the tun device with the current tun configuration and reply with either (or
-always respond with OPEN_AFTER_BEFORE/OPEN_BEFORE_CLOSE)
-
-- NOACTION: Keep using the old fd
-- OPEN_AFTER_CLOSE: First close the old fd and then open a new to workaround the bug
-- OPEN_BEFORE_CLOSE: the normal behaviour when the VPN configuration changed
-
-For example the UI could respond with
-needok 'PERSIST_TUN_ACTION' OPEN_AFTER_CLOSE
-
-To protect a socket the OpenVPN will send a PROTECTFD to the UI.
-When sending the PROTECTFD command command to the UI it will send
-the fd of the socket as ancillary message over the UNIX socket.
-The UI will then call protect(fd) on the received socket protecting
-it from being routed over the VPN.
-
-When opening a tun device the OpenVPN process will first send all
-route, ifconfig and DNS related configuration to the UI and after
-that calls the OPENTUN command to receive a tun fd with the requested
-configuration. The UI will than use the collected information to
-call the VPNService's establish() method to receive a fd which in
-turn is send to the OpenVPN process as ancillary message to the
-"needok 'OPENTUN' ok' response.
-
-The OpenVPN for Android UI extensively uses other features that
-are not specific to Android but are rarely used on other platform.
-For example using SIGUSR1 and management-hold to restart, pause,
-continue the VPN on network changes or the external key management
---management-external-key option and inline files.
diff --git a/main/openvpn/doc/doxygen/doc_compression.h b/main/openvpn/doc/doxygen/doc_compression.h
deleted file mode 100644
index bdc4a7ed..00000000
--- a/main/openvpn/doc/doxygen/doc_compression.h
+++ /dev/null
@@ -1,92 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file Data Channel Compression module documentation file.
- */
-
-/**
- * @defgroup compression Data Channel Compression module
- *
- * This module offers compression of data channel packets.
- *
- * @par State structures
- * The Data Channel Compression module stores its internal state in a \c
- * lzo_compress_workspace structure. This state includes flags which
- * control the module's behavior and preallocated working memory. One
- * such structure is present for each VPN tunnel, and is stored in the \c
- * context.c2.lzo_compwork of the \c context associated with that VPN
- * tunnel.
- *
- * @par Initialization and cleanup
- * Every time a new \c lzo_compress_workspace is needed, it must be
- * initialized using the \c lzo_compress_init() function. Similarly,
- * every time a \c lzo_compress_workspace is no longer needed, it must be
- * cleaned up using the \c lzo_compress_uninit() function. These
- * functions take care of the allocation and freeing of internal working
- * memory, but not of the \c lzo_compress_workspace structures themselves.
- *
- * @par
- * Because of the one-to-one relationship between \c
- * lzo_compress_workspace structures and VPN tunnels, the above-mentioned
- * initialization and cleanup functions are called directly from the \c
- * init_instance() and \c close_instance() functions, which control the
- * initialization and cleanup of VPN tunnel instances and their associated
- * \c context structures.
- *
- * @par Packet processing functions
- * This module receives data channel packets from the \link data_control
- * Data Channel Control module\endlink and processes them according to the
- * settings of the packet's VPN tunnel. The \link data_control Data
- * Channel Control module\endlink uses the following interface functions:
- * - For packets which will be sent to a remote OpenVPN peer: \c
- * lzo_compress()
- * - For packets which have been received from a remote OpenVPN peer: \c
- * lzo_decompress()
- *
- * @par Settings that control this module's activity
- * Whether or not the Data Channel Compression module is active depends on
- * the compile-time \c ENABLE_LZO preprocessor macro and the runtime flags
- * stored in \c lzo_compress_workspace.flags of the associated VPN tunnel.
- * The latter are initialized from \c options.lzo, which gets its value
- * from the process's configuration sources, such as its configuration
- * file or command line %options.
- *
- * @par Adaptive compression
- * The compression module supports adaptive compression. If this feature
- * is enabled, the compression routines monitor their own performance and
- * turn compression on or off depending on whether it is leading to
- * significantly reduced payload size.
- *
- * @par Compression algorithms
- * This module uses the Lempel-Ziv-Oberhumer (LZO) compression algorithms.
- * These offer lossless compression and are designed for high-performance
- * decompression. This module uses the external \c lzo library's
- * implementation of the algorithms.
- *
- * @par
- * For more information on the LZO library, see:\n
- * http://www.oberhumer.com/opensource/lzo/
- */
diff --git a/main/openvpn/doc/doxygen/doc_control_processor.h b/main/openvpn/doc/doxygen/doc_control_processor.h
deleted file mode 100644
index 072dc372..00000000
--- a/main/openvpn/doc/doxygen/doc_control_processor.h
+++ /dev/null
@@ -1,189 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file
- * Control Channel Processor module documentation file.
- */
-
-/**
- * @defgroup control_processor Control Channel Processor module
- *
- * This module controls the setup and maintenance of VPN tunnels and the
- * associated security parameters.
- *
- * @par This module's role
- * The Control Channel Processor module lies at the core of OpenVPN's
- * activities. It handles the setup of new VPN tunnels, the negotiation
- * of data channel security parameters, the managing of active VPN
- * tunnels, and finally the cleanup of expired VPN tunnels.
- *
- * @par State structures
- * A large amount of VPN tunnel state information must be stored within an
- * OpenVPN process. A wide variety of container structures are used by
- * this module for that purpose. Several of these structures are listed
- * below, and the function of the first three VPN tunnel state containers
- * is described in more detail later.
- * - VPN tunnel state containers:
- * - \c tls_multi, security parameter state for a single VPN tunnel.
- * Contains three instances of the \c tls_session structure.
- * - \c tls_session, security parameter state of a single session
- * within a VPN tunnel. Contains two instances of the \c key_state
- * structure.
- * - \c key_state, security parameter state of one TLS and data
- * channel %key set.
- * - Data channel security parameter containers:
- * - \c key_ctx_bi, container for two sets of OpenSSL cipher and/or
- * HMAC context (both directions). Contains two instances of the \c
- * key_ctx structure.
- * - \c key_ctx, container for one set of OpenSSL cipher and/or HMAC
- * context (one directions.
- * - Key material containers:
- * - \c key2, container for two sets of cipher and/or HMAC %key
- * material (both directions). Contains two instances of the \c key
- * structure.
- * - \c key, container for one set of cipher and/or HMAC %key material
- * (one direction).
- * - \c key_direction_state, ordering of %key material within the \c
- * key2.key array.
- * - Key method 2 random material containers:
- * - \c key_source2, container for both halves of random material used
- * for %key method 2. Contains two instances of the \c key_source
- * structure.
- * - \c key_source, container for one half of random material used for
- * %key method 2.
- *
- * @par The life of a \c tls_multi object
- * A \c tls_multi structure contains all the security parameter state
- * information related to the control and data channels of one VPN tunnel.
- * Its life cycle can be summarized as follows:
- * -# Initialization: \c tls_multi_init() and \c
- * tls_multi_init_finalize(), which are called (indirectly) from \c
- * init_instance() when initializing a new \c context structure.
- * - Initializes a \c tls_multi structure.
- * - Allocates the three \c tls_session objects contained by the \c
- * tls_multi structure, and initializes as appropriate.
- * -# Management: \c tls_multi_process() and \c tls_pre_decrypt()
- * - If a new session is initiated by the remote peer, then \c
- * tls_pre_decrypt() starts the new session negotiation in the
- * un-trusted \c tls_session.
- * - If the, as yet, un-trusted \c tls_session authenticates
- * successfully, then \c tls_multi_process() moves it so as to be
- * the active \c tls_session.
- * - If an error occurs during processing of a \c key_state object,
- * then \c tls_multi_process() cleans up and initializes the
- * associated \c tls_session object. If the error occurred in the
- * active \c key_state of the active \c tls_session and the
- * lame-duck \c key_state of that \c tls_session has not yet
- * expired, it is preserved as fallback.
- * -# Cleanup: \c tls_multi_free(), which is called (indirectly) from \c
- * close_instance() when cleaning up a \c context structure.
- * - Cleans up a \c tls_multi structure.
- * - Cleans up the three \c tls_session objects contained by the \c
- * tls_multi structure.
- *
- * @par The life of a \c tls_session object
- * A \c tls_session structure contains the state information related to an
- * active and a lame-duck \c key_state. Its life cycle can be summarized
- * as follows:
- * -# Initialization: \c tls_session_init()
- * - Initializes a \c tls_session structure.
- * - Initializes the primary \c key_state by calling \c
- * key_state_init().
- * -# Renegotiation: \c key_state_soft_reset()
- * - Cleans up the old lame-duck \c key_state by calling \c
- * key_state_free().
- * - Moves the old primary \c key_state to be the new lame-duck \c
- * key_state.
- * - Initializes a new primary \c key_state by calling \c
- * key_state_init().
- * -# Cleanup: \c tls_session_free()
- * - Cleans up a \c tls_session structure.
- * - Cleans up all \c key_state objects associated with the session by
- * calling \c key_state_free() for each.
- *
- * @par The life of a \c key_state object
- * A \c key_state structure represents one control and data channel %key
- * set. It contains an OpenSSL TLS object that encapsulates the control
- * channel, and the data channel security parameters needed by the \link
- * data_crypto Data Channel Crypto module\endlink to perform cryptographic
- * operations on data channel packets. Its life cycle can be summarized
- * as follows:
- * -# Initialization: \c key_state_init()
- * - Initializes a \c key_state structure.
- * - Creates a new OpenSSL TLS object to encapsulate this new control
- * channel session.
- * - Sets \c key_state.state to \c S_INITIAL.
- * - Allocates several internal buffers.
- * - Initializes new reliability layer structures for this key set.
- * -# Negotiation: \c tls_process()
- * - The OpenSSL TLS object negotiates a TLS session between itself
- * and the remote peer's TLS object.
- * - Key material is generated and exchanged through the TLS session
- * between OpenVPN peers.
- * - Both peers initialize their data channel cipher and HMAC key
- * contexts.
- * - On successful negotiation, the \c key_state.state will progress
- * from \c S_INITIAL to \c S_ACTIVE and \c S_NORMAL.
- * -# Active tunneling: \link data_crypto Data Channel Crypto
- * module\endlink
- * - Data channel packet to be sent to a remote OpenVPN peer:
- * - \c tls_pre_encrypt() loads the security parameters from the \c
- * key_state into a \c crypto_options structure.
- * - \c openvpn_encrypt() uses the \c crypto_options to an encrypt
- * and HMAC sign the data channel packet.
- * - Data channel packet received from a remote OpenVPN peer:
- * - \c tls_pre_decrypt() loads the security parameters from the \c
- * key_state into a \c crypto_options structure.
- * - \c openvpn_encrypt() uses the \c crypto_options to
- * authenticate and decrypt the data channel packet.
- * -# Cleanup: \c key_state_free()
- * - Cleans up a \c key_state structure together with its OpenSSL TLS
- * object, key material, internal buffers, and reliability layer
- * structures.
- *
- * @par Control functions
- * The following two functions drive the Control Channel Processor's
- * activities.
- * - \c tls_multi_process(), iterates through the \c tls_session objects
- * within a given \c tls_multi of a VPN tunnel, and calls \c
- * tls_process() for each \c tls_session which is being set up, is
- * already active, or is busy expiring.
- * - \c tls_process(), performs the Control Channel Processor module's
- * core handling of received control channel messages, and generates
- * appropriate messages to be sent.
- *
- * @par Functions which control data channel key generation
- * - Key method 1 key exchange functions:
- * - \c key_method_1_write(), generates and processes key material to
- * be sent to the remote OpenVPN peer.
- * - \c key_method_1_read(), processes key material received from the
- * remote OpenVPN peer.
- * - Key method 2 key exchange functions:
- * - \c key_method_2_write(), generates and processes key material to
- * be sent to the remote OpenVPN peer.
- * - \c key_method_2_read(), processes key material received from the
- * remote OpenVPN peer.
- */
diff --git a/main/openvpn/doc/doxygen/doc_control_tls.h b/main/openvpn/doc/doxygen/doc_control_tls.h
deleted file mode 100644
index aba55f77..00000000
--- a/main/openvpn/doc/doxygen/doc_control_tls.h
+++ /dev/null
@@ -1,105 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file
- * Control Channel TLS module documentation file.
- */
-
-/**
- * @defgroup control_tls Control Channel TLS module
- *
- * This module provides secure encapsulation of control channel messages
- * exchanged between OpenVPN peers.
- *
- * The Control Channel TLS module uses the Transport Layer Security (TLS)
- * protocol to provide an encrypted communication channel between the
- * local OpenVPN process and a remote peer. This protocol simultaneously
- * offers certificate-based authentication of the communicating parties.
- *
- * @par This module's roles
- * The Control Channel TLS module is essential for the security of any
- * OpenVPN-based system. On the one hand, it performs the security
- * operations necessary to protect control channel messages exchanged
- * between OpenVPN peers. On the other hand, before the control and data
- * channels are even setup, it controls the exchange of certificates and
- * verification of the remote's identity during negotiation of VPN
- * tunnels.
- *
- * @par
- * The former role is described below. The latter is described in the
- * documentation for the \c verify_callback() function.
- *
- * @par
- * In other words, this module takes care of the confidentiality and
- * integrity of data channel communications, and the authentication of
- * both the communicating parties and the control channel messages
- * exchanged.
- *
- * @par Initialization and cleanup
- * Because of the one-to-one relationship between control channel TLS
- * state and \c key_state structures, the initialization and cleanup of an
- * instance of the Control Channel TLS module's state happens within the
- * \c key_state_init() and \c key_state_free() functions. In other words,
- * each \c key_state object contains exactly one OpenSSL SSL-BIO object,
- * which is initialized and cleaned up together with the rest of the \c
- * key_state object.
- *
- * @par Packet processing functions
- * This object behaves somewhat like a black box with a ciphertext and a
- * plaintext I/O port. Its interaction with OpenVPN's control channel
- * during operation takes place within the \c tls_process() function of
- * the \link control_processor Control Channel Processor\endlink. The
- * following functions are available for processing packets:
- * - If ciphertext received from the remote peer is available in the \link
- * reliable Reliability Layer\endlink:
- * - Insert it into the ciphertext-side of the SSL-BIO.
- * - Use function: \c key_state_write_ciphertext()
- * - If ciphertext can be extracted from the ciphertext-side of the
- * SSL-BIO:
- * - Pass it to the \link reliable Reliability Layer\endlink for sending
- * to the remote peer.
- * - Use function: \c key_state_read_ciphertext()
- * - If plaintext can be extracted from the plaintext-side of the SSL-BIO:
- * - Pass it on to the \link control_processor Control Channel
- * Processor\endlink for local processing.
- * - Use function: \c key_state_read_plaintext()
- * - If plaintext from the \link control_processor Control Channel
- * Processor\endlink is available to be sent to the remote peer:
- * - Insert it into the plaintext-side of the SSL-BIO.
- * - Use function: \c key_state_write_plaintext() or \c
- * key_state_write_plaintext_const()
- *
- * @par Transport Layer Security protocol implementation
- * This module uses the OpenSSL library's implementation of the TLS
- * protocol in the form of an OpenSSL SSL-BIO object.
- *
- * @par
- * For more information on the OpenSSL library's BIO objects, please see:
- * - OpenSSL's generic BIO objects:
- * http://www.openssl.org/docs/crypto/bio.html
- * - OpenSSL's SSL-BIO object:
- * http://www.openssl.org/docs/crypto/BIO_f_ssl.html
- */
diff --git a/main/openvpn/doc/doxygen/doc_data_control.h b/main/openvpn/doc/doxygen/doc_data_control.h
deleted file mode 100644
index d0f65ba3..00000000
--- a/main/openvpn/doc/doxygen/doc_data_control.h
+++ /dev/null
@@ -1,103 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file
- * Data Channel Control module documentation file.
- */
-
-/**
- * @defgroup data_control Data Channel Control module
- *
- * This module controls the processing of packets as they pass through the
- * data channel.
- *
- * The Data Channel Control module controls the processing of packets as
- * they pass through the data channel. The processing includes packet
- * compression, fragmentation, and the performing of security operations
- * on the packets. This module does not do the processing itself, but
- * passes the packet to other data channel modules to perform the
- * appropriate actions.
- *
- * Packets can travel in two directions through the data channel. They
- * can be going to a remote destination which is reachable through a VPN
- * tunnel, in which case this module prepares them to be sent out through
- * a VPN tunnel. On the other hand, they can have been received through a
- * VPN tunnel from a remote OpenVPN peer, in which case this module
- * retrieves the packet in its original form as it was before entering the
- * VPN tunnel on the remote OpenVPN peer. How this module processes
- * packets traveling in the two directions is discussed in more detail
- * below.
- *
- * @par Packets to be sent to a remote OpenVPN peer
- * This module's main function for processing packets traveling in this
- * direction is \c encrypt_sign(), which performs the following processing
- * steps:
- * - Call the \link compression Data Channel Compression module\endlink to
- * perform packet compression if necessary.
- * - Call the \link fragmentation Data Channel Fragmentation
- * module\endlink to perform packet fragmentation if necessary.
- * - Call the \link data_crypto Data Channel Crypto module\endlink to
- * perform the required security operations.
- *
- * @par
- * See the \c encrypt_sign() documentation for details of these
- * interactions.
- *
- * @par
- * After the above processing is complete, the packet is ready to be sent
- * to a remote OpenVPN peer as a VPN tunnel packet. The actual sending of
- * the packet is handled by the \link external_multiplexer External
- * Multiplexer\endlink.
- *
- * @par Packets received from a remote OpenVPN peer
- * The function that controls how packets traveling in this direction are
- * processed is \c process_incoming_link(). That function, however, also
- * performs some of the tasks required for the \link external_multiplexer
- * External Multiplexer\endlink and is therefore listed as part of that
- * module, instead of here.
- *
- * @par
- * After the \c process_incoming_link() function has determined that a
- * received packet is a data channel packet, it performs the following
- * processing steps:
- * - Call the \link data_crypto Data Channel Crypto module\endlink to
- * perform the required security operations.
- * - Call the \link fragmentation Data Channel Fragmentation
- * module\endlink to perform packet reassembly if necessary.
- * - Call the \link compression Data Channel Compression module\endlink to
- * perform packet decompression if necessary.
- *
- * @par
- * See the \c process_incoming_link() documentation for details of these
- * interactions.
- *
- * @par
- * After the above processing is complete, the packet is in its original
- * form again as it was received by the remote OpenVPN peer. It can now
- * be routed further to its final destination. If that destination is a
- * locally reachable host, then the \link internal_multiplexer Internal
- * Multiplexer\endlink will send it there.
- */
diff --git a/main/openvpn/doc/doxygen/doc_data_crypto.h b/main/openvpn/doc/doxygen/doc_data_crypto.h
deleted file mode 100644
index 11726724..00000000
--- a/main/openvpn/doc/doxygen/doc_data_crypto.h
+++ /dev/null
@@ -1,73 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file
- * Data Channel Crypto module documentation file.
- */
-
-/**
- * @addtogroup data_crypto Data Channel Crypto module
- *
- * The Data Channel Crypto Module performs cryptographic operations on
- * data channel packets.
- *
- * @par Security parameters
- * This module is merely the user of a VPN tunnel's security parameters.
- * It does not perform the negotiation and setup of the security
- * parameters, nor the %key generation involved. These actions are done
- * by the \link control_processor Control Channel Processor\endlink. This
- * module receives the appropriate security parameters from that module in
- * the form of a \c crypto_options structure when they are necessary for
- * processing a packet.
- *
- * @par Packet processing functions
- * This module receives data channel packets from the \link data_control
- * Data Channel Control module\endlink and processes them according to the
- * security parameters of the packet's VPN tunnel. The \link data_control
- * Data Channel Control module\endlink uses the following interface
- * functions:
- * - For packets which will be sent to a remote OpenVPN peer:
- * - \c tls_pre_encrypt()
- * - \c openvpn_encrypt()
- * - \c tls_post_encrypt()
- * - For packets which have been received from a remote OpenVPN peer:
- * - \c tls_pre_decrypt() (documented as part of the \link
- * external_multiplexer External Multiplexer\endlink)
- * - \c openvpn_decrypt()
- *
- * @par Settings that control this module's activity
- * Whether or not the Data Channel Crypto module is active depends on the
- * compile-time \c ENABLE_CRYPTO preprocessor macro. How it processes packets
- * received from the \link data_control Data Channel Control module\endlink at
- * runtime depends on the associated \c crypto_options structure. To perform
- * cryptographic operations, the \c crypto_options.key_ctx_bi must contain the
- * correct cipher and HMAC security parameters for the direction the packet is
- * traveling in.
- *
- * @par Crypto algorithms
- * This module uses the crypto algorithm implementations of the external
- * crypto library (currently either OpenSSL (default), or PolarSSL).
- */
diff --git a/main/openvpn/doc/doxygen/doc_eventloop.h b/main/openvpn/doc/doxygen/doc_eventloop.h
deleted file mode 100644
index a860db68..00000000
--- a/main/openvpn/doc/doxygen/doc_eventloop.h
+++ /dev/null
@@ -1,67 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file
- * Main Event Loop module documentation file.
- */
-
-/**
- * @defgroup eventloop Main Event Loop module
- *
- * This main event loop module drives the packet processing of OpenVPN.
- *
- * OpenVPN is an event driven system. Its activities are driven by a main
- * event loop, which repeatedly waits for one of several predefined events
- * to occur, and then calls the appropriate module to handle the event.
- * The major types of network events that OpenVPN processes are:
- * - A packet can be read from the external network interface.
- * - The main event loop activates the \link external_multiplexer
- * External Multiplexer\endlink to read and process the packet.
- * - A packet can be read from the virtual tun/tap network interface.
- * - The main event loop activates the \link internal_multiplexer
- * Internal Multiplexer\endlink to read and process the packet.
- * - If a packet is ready to be sent out as a VPN tunnel packet: the
- * external network interface can be written to.
- * - The main event loop activates the \link external_multiplexer
- * External Multiplexer\endlink to send the packet.
- * - If a packet is ready to be sent to a locally reachable destination:
- * the virtual tun/tap network interface can be written to.
- * - The main event loop activates the \link internal_multiplexer
- * Internal Multiplexer\endlink to send the packet.
- *
- * Beside these external events, OpenVPN also processes other types of
- * internal events. These include scheduled events, such as resending of
- * non-acknowledged control channel messages.
- *
- * @par Main event loop implementations
- *
- * Depending on the mode in which OpenVPN is running, a different main
- * event loop function is called to drive the event processing. The
- * following implementations are available:
- * - Client mode using UDP or TCP: \c tunnel_point_to_point()
- * - Server mode using UDP: \c tunnel_server_udp_single_threaded()
- * - Server mode using TCP: \c tunnel_server_tcp()
- */
diff --git a/main/openvpn/doc/doxygen/doc_external_multiplexer.h b/main/openvpn/doc/doxygen/doc_external_multiplexer.h
deleted file mode 100644
index 76532557..00000000
--- a/main/openvpn/doc/doxygen/doc_external_multiplexer.h
+++ /dev/null
@@ -1,46 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file
- * External Multiplexer module documentation file.
- */
-
-/**
- * @addtogroup external_multiplexer External Multiplexer module
- *
- * The External Multiplexer is the link between the external network
- * interface and the other OpenVPN modules. It reads packets from the
- * external network interface, determines which remote OpenVPN peer and
- * VPN tunnel they are associated with, and whether they are data channel
- * or control channel packets. It then passes the packets on to the
- * appropriate processing module.
- *
- * This module also handles packets traveling in the reverse direction,
- * which have been generated by the local control channel or which have
- * already been processed by the \link data_control Data Channel Control
- * module\endlink and are destined for a remote host reachable through a
- * VPN tunnel.
- */
diff --git a/main/openvpn/doc/doxygen/doc_fragmentation.h b/main/openvpn/doc/doxygen/doc_fragmentation.h
deleted file mode 100644
index ef34cdb2..00000000
--- a/main/openvpn/doc/doxygen/doc_fragmentation.h
+++ /dev/null
@@ -1,96 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file
- * Data Channel Fragmentation module documentation file.
- */
-
-/**
- * @defgroup fragmentation Data Channel Fragmentation module
- *
- * The Data Channel Fragmentation module offers fragmentation of data
- * channel packets.
- *
- * @par State structures
- * The Data Channel Fragmentation module stores its internal state in a \c
- * fragment_master structure. One such structure is present for each VPN
- * tunnel, and is stored in \c context.c2.fragment of the \c context
- * associated with that VPN tunnel.
- *
- * @par
- * The \c fragment_master structure contains one \c fragment_list
- * structure \c fragment_master.incoming. This is a list of \c fragment
- * structures, each of which can store the parts of one fragmented packet
- * while it is being reassembled. The \c fragment_master structure also
- * contains one \c buffer called \c fragment_master.outgoing, in which a
- * data channel large packet to be sent to a remote OpenVPN peer can be
- * broken up into parts to be sent one by one.
- *
- * @par Initialization and cleanup
- * Every time a new \c fragment_master is needed, it must be allocated and
- * initialized by the \c fragment_init() function. Similarly, every time
- * a \c fragment_master is no longer needed, it must be cleaned up using
- * the \c fragment_free() function. These functions take care of the
- * allocation and freeing of the \c fragment_master structure itself and
- * all internal memory required for the use of that structure. Note that
- * this behavior is different from that displayed by the \link compression
- * Data Channel Compression module\endlink.
- *
- * @par
- * Because of the one-to-one relationship between \c fragment_master
- * structures and VPN tunnels, the above-mentioned initialization and
- * cleanup functions are called directly from the \c init_instance() and
- * \c close_instance() functions, which control the initialization and
- * cleanup of VPN tunnel instances and their associated \c context
- * structures.
- *
- * @par Packet processing functions
- * This module receives data channel packets from the \link data_control
- * Data Channel Control module\endlink and processes them according to the
- * settings of the packet's VPN tunnel. The \link data_control Data
- * Channel Control module\endlink uses the following interface functions:
- * - For packets which will be sent to a remote OpenVPN peer: \c
- * fragment_outgoing() \n This function inspects data channel packets as
- * they are being made ready to be sent as VPN tunnel packets to a
- * remote OpenVPN peer. If a packet's size is larger than its
- * destination VPN tunnel's maximum transmission unit (MTU), then this
- * module breaks that packet up into smaller parts, each of which is
- * smaller than or equal to the VPN tunnel's MTU. See \c
- * fragment_outgoing() for details.
- * - For packets which have been received from a remote OpenVPN peer: \c
- * fragment_incoming() \n This function inspects data channel packets
- * that have been received from a remote OpenVPN peer through a VPN
- * tunnel. It reads the fragmentation header of the packet, and
- * depending on its value performs the appropriate action. See \c
- * fragment_incoming() for details.
- *
- * @par Settings that control this module's activity
- * Whether the Data Channel Fragmentation module is active or not depends
- * on the compile-time \c ENABLE_FRAGMENT preprocessor macro and the
- * runtime flag \c options.fragment, which gets its value from the
- * process's configuration sources, such as the configuration file and
- * commandline %options.
- */
diff --git a/main/openvpn/doc/doxygen/doc_internal_multiplexer.h b/main/openvpn/doc/doxygen/doc_internal_multiplexer.h
deleted file mode 100644
index 5142dd0d..00000000
--- a/main/openvpn/doc/doxygen/doc_internal_multiplexer.h
+++ /dev/null
@@ -1,44 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file
- * Internal Multiplexer module documentation file.
- */
-
-/**
- * @addtogroup internal_multiplexer Internal Multiplexer module
- *
- * The Internal Multiplexer is the link between the virtual tun/tap
- * network interface and the \link data_control Data Channel Control
- * module\endlink. It reads packets from the virtual network interface,
- * determines for which remote OpenVPN peer they are destined, and then
- * passes the packets on to the Data Channel Control module together with
- * information about their destination VPN tunnel instance.
- *
- * This module also handles packets traveling in the reverse direction,
- * which have already been processed by the Data Channel Control module
- * and are destined for a locally reachable host.
- */
diff --git a/main/openvpn/doc/doxygen/doc_key_generation.h b/main/openvpn/doc/doxygen/doc_key_generation.h
deleted file mode 100644
index 903a4652..00000000
--- a/main/openvpn/doc/doxygen/doc_key_generation.h
+++ /dev/null
@@ -1,153 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file
- * Key generation documentation file.
- */
-
-/**
- * @page key_generation Data channel %key generation
- *
- * This section describes how OpenVPN peers generate and exchange %key
- * material necessary for the security operations performed on data
- * channel packets.
- *
- * The %key generation and exchange process between OpenVPN client and
- * server occurs every time data channel security parameters are
- * negotiated, for example during the initial setup of a VPN tunnel or
- * when the active security parameters expire. In source code terms, this
- * is when a new key_state structure is initialized.
- *
- * @section key_generation_method Key methods
- *
- * OpenVPN supports two different ways of generating and exchanging %key
- * material between client and server. These are known as %key method 1
- * and %key method 2. %Key method 2 is the recommended method. Both are
- * explained below.
- *
- * @subsection key_generation_method_1 Key method 1
- *
- * -# Each host generates its own random material.
- * -# Each host uses its locally generated random material as %key data
- * for encrypting and signing packets sent to the remote peer.
- * -# Each host then sends its random material to the remote peer, so that
- * the remote peer can use that %key data for authenticating and
- * decrypting received packets.
- *
- * @subsection key_generation_method_2 Key method 2
- *
- * -# The client generates random material in the following amounts:
- * - Pre-master secret: 48 bytes
- * - Client's PRF seed for master secret: 32 bytes
- * - Client's PRF seed for %key expansion: 32 bytes
- * -# The client sends its share of random material to the server.
- * -# The server generates random material in the following amounts:
- * - Server's PRF seed for master secret: 32 bytes
- * - Server's PRF seed for %key expansion: 32 bytes
- * -# The server computes the %key expansion using its own and the
- * client's random material.
- * -# The server sends its share of random material to the client.
- * -# The client computes the %key expansion using its own and the
- * server's random material.
- *
- * %Key method 2 %key expansion is performed by the \c
- * generate_key_expansion() function. Please refer to its source code for
- * details of the %key expansion process.
- *
- * @subsection key_generation_random Source of random material
- *
- * OpenVPN uses the either the OpenSSL library or the PolarSSL library as its
- * source of random material.
- *
- * In OpenSSL, the \c RAND_bytes() function is called
- * to supply cryptographically strong pseudo-random data. The following links
- * contain more information on this subject:
- * - For OpenSSL's \c RAND_bytes() function:
- * http://www.openssl.org/docs/crypto/RAND_bytes.html
- * - For OpenSSL's pseudo-random number generating system:
- * http://www.openssl.org/docs/crypto/rand.html
- * - For OpenSSL's support for external crypto modules:
- * http://www.openssl.org/docs/crypto/engine.html
- *
- * In PolarSSL, the Havege random number generator is used. For details, see
- * the PolarSSL documentation.
- *
- * @section key_generation_exchange Key exchange:
- *
- * The %key exchange process is initiated by the OpenVPN process running
- * in client mode. After the initial three-way handshake has successfully
- * completed, the client sends its share of random material to the server,
- * after which the server responds with its part. This process is
- * depicted below:
- *
-@verbatim
- Client Client Server Server
- State Action Action State
----------- -------------------- -------------------- ----------
-
- ... waiting until three-way handshake complete ...
-S_START S_START
- key_method_?_write()
- send to server --> --> --> --> receive from client
-S_SENT_KEY key_method_?_read()
- S_GOT_KEY
- key_method_?_write()
- receive from server <-- <-- <-- <-- send to client
- key_method_?_read() S_SENT_KEY
-S_GOT_KEY
- ... waiting until control channel fully synchronized ...
-S_ACTIVE S_ACTIVE
-@endverbatim
- *
- * For more information about the client and server state values, see the
- * \link control_processor Control Channel Processor module\endlink.
- *
- * Depending on which %key method is used, the \c ? in the function names
- * of the diagram above is a \c 1 or a \c 2. For example, if %key method
- * 2 is used, that %key exchange would be started by the client calling \c
- * key_method_2_write(). These functions are called from the \link
- * control_processor Control Channel Processor module's\endlink \c
- * tls_process() function and control the %key generation and exchange
- * process as follows:
- * - %Key method 1:
- * - \c key_method_1_write(): generate random material locally, and load
- * as "sending" keys.
- * - \c key_method_1_read(): read random material received from remote
- * peer, and load as "receiving" keys.
- * - %Key method 2:
- * - \c key_method_2_write(): generate random material locally, and if
- * in server mode generate %key expansion.
- * - \c key_method_2_read(): read random material received from remote
- * peer, and if in client mode generate %key expansion.
- *
- * @subsection key_generation_encapsulation Transmission of key material
- *
- * The OpenVPN client and server communicate with each other through their
- * control channel. This means that all of the data transmitted over the
- * network, such as random material for %key generation, is encapsulated
- * in a TLS layer. For more details, see the \link control_tls Control
- * Channel TLS module\endlink documentation.
- */
diff --git a/main/openvpn/doc/doxygen/doc_mainpage.h b/main/openvpn/doc/doxygen/doc_mainpage.h
deleted file mode 100644
index ed8e324e..00000000
--- a/main/openvpn/doc/doxygen/doc_mainpage.h
+++ /dev/null
@@ -1,162 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file
- * Main page documentation file.
- */
-
-/**
- * @mainpage OpenVPN source code documentation
- *
- * This documentation describes the internal structure of OpenVPN. It was
- * automatically generated from specially formatted comment blocks in
- * OpenVPN's source code using Doxygen. (See
- * http://www.stack.nl/~dimitri/doxygen/ for more information on Doxygen)
- *
- * The \ref mainpage_modules "Modules section" below gives an introduction
- * into the high-level module concepts used throughout this documentation.
- * The \ref mainpage_relatedpages "Related Pages section" below describes
- * various special subjects related to OpenVPN's implementation which are
- * discussed in the related pages section.
- *
- * @section mainpage_modules Modules
- *
- * For the purpose of describing the internal structure of OpenVPN, this
- * documentation and the underlying source code has been broken up into a
- * number of conceptually well-defined parts, known as modules. Each
- * module plays a specific role within the OpenVPN process, and in most
- * cases each module has a clear interfacing strategy for interacting with
- * other modules.
- *
- * The following modules have been defined:
- * - Driver module:
- * - The \link eventloop Main Event Loop\endlink: this module drives the
- * event handling of OpenVPN. It implements various types of
- * select-loop which wait until an event happens, and then delegate
- * the handling of that event to the appropriate module.
- * - Network interface modules:
- * - The \link external_multiplexer External Multiplexer\endlink: this
- * module sends and receives packets to and from remote OpenVPN peers
- * over the external network interface. It also takes care of
- * demultiplexing received packets to their appropriate VPN tunnel and
- * splitting control channel and data channel packets.
- * - The \link internal_multiplexer Internal Multiplexer\endlink: this
- * module sends and receives packets to and from locally reachable
- * posts over the virtual tun/tap network interface. It also takes
- * care of determining through which VPN tunnel a received packet must
- * be sent to reach its destination.
- * - Control channel modules:
- * - The \link reliable Reliability Layer\endlink: this module offers a
- * %reliable and sequential transport layer for control channel
- * messages.
- * - The \link control_tls Control Channel TLS module\endlink: this
- * module offers a secure encapsulation of control channel messages
- * using the TLS protocol.
- * - The \link control_processor Control Channel Processor\endlink: his
- * module manages the setup, maintenance, and shut down of VPN
- * tunnels.
- * - Data channel modules:
- * - The \link data_control Data Channel Control module\endlink: this
- * module controls the processing of data channel packets and,
- * depending on the settings of the packet's VPN tunnel, passes the
- * packet to the three modules below for handling.
- * - The \link data_crypto Data Channel Crypto module\endlink: this
- * module performs security operations on data channel packets.
- * - The \link fragmentation Data Channel Fragmentation module\endlink:
- * this module offers fragmentation of data channel packets larger
- * than the VPN tunnel's MTU.
- * - The \link compression Data Channel Compression module\endlink: this
- * module offers compression of data channel packets.
- *
- * @subsection mainpage_modules_example Example event: receiving a packet
- *
- * OpenVPN handles many types of events during operation. These include
- * external events, such as network traffic being received, and internal
- * events, such as a %key session timing out causing renegotiation. An
- * example event, receiving a packet over the network, is described here
- * together with which modules play what roles:
- * -# The \link eventloop Main Event Loop\endlink detects that a packet
- * can be read from the external or the virtual tun/tap network
- * interface.
- * -# The \link eventloop Main Event Loop\endlink calls the \link
- * external_multiplexer External Multiplexer\endlink or \link
- * internal_multiplexer Internal Multiplexer\endlink to read and
- * process the packet.
- * -# The multiplexer module determines the type of packet and its
- * destination, and passes the packet on to the appropriate handling
- * module:
- * - A control channel packet received by the \link
- * external_multiplexer External Multiplexer\endlink is passed on
- * through the \link reliable Reliability Layer\endlink and the \link
- * control_tls Control Channel TLS module\endlink to the \link
- * control_processor Control Channel Processor\endlink.
- * - A data channel packet received by either multiplexer module is
- * passed on to the \link data_control Data Channel Control
- * module\endlink.
- * -# The packet is processed by the appropriate control channel or data
- * channel modules.
- * -# If, after processing the packet, a resulting packet is generated
- * that needs to be sent to a local or remote destination, it is given
- * to the \link external_multiplexer External Multiplexer\endlink or
- * \link internal_multiplexer Internal Multiplexer\endlink for sending.
- * -# If a packet is waiting to be sent by either multiplexer module and
- * the \link eventloop Main Event Loop\endlink detects that data can be
- * written to the associated network interface, it calls the
- * multiplexer module to send the packet.
- *
- * @section mainpage_relatedpages Related pages
- *
- * This documentation includes a number of descriptions of various aspects
- * of OpenVPN and its implementation. These are not directly related to
- * one module, function, or data structure, and are therefore listed
- * separately under "Related Pages".
- *
- * @subsection mainpage_relatedpages_key_generation Data channel key generation
- *
- * The @ref key_generation "Data channel key generation" related page
- * describes how, during VPN tunnel setup and renegotiation, OpenVPN peers
- * generate and exchange the %key material required for the symmetric
- * encryption/decryption and HMAC signing/verifying security operations
- * performed on data channel packets.
- *
- * @subsection mainpage_relatedpages_tunnel_state VPN tunnel state
- *
- * The @ref tunnel_state "Structure of VPN tunnel state storage" related
- * page describes how an OpenVPN process manages the state information
- * associated with its active VPN tunnels.
- *
- * @subsection mainpage_relatedpages_network_protocol Network protocol
- *
- * The @ref network_protocol "Network protocol" related page describes the
- * format and content of VPN tunnel packets exchanged between OpenVPN
- * peers.
- *
- * @subsection mainpage_relatedpages_memory_management Memory management
- *
- * The @ref memory_management "Memory management strategies" related page
- * gives a brief introduction into OpenVPN's memory %buffer library and
- * garbage collection facilities.
- */
diff --git a/main/openvpn/doc/doxygen/doc_memory_management.h b/main/openvpn/doc/doxygen/doc_memory_management.h
deleted file mode 100644
index f948783e..00000000
--- a/main/openvpn/doc/doxygen/doc_memory_management.h
+++ /dev/null
@@ -1,99 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file
- * Memory management strategies documentation file.
- */
-
-/**
- * @page memory_management OpenVPN's memory management strategies
- *
- * This section describes several implementation details relating to
- * OpenVPN's memory management strategies.
- *
- * During operation, the OpenVPN process performs all kinds of operations
- * on blocks of data. Receiving packets, encrypting content, prepending
- * headers, etc. To make the programmer's job easier and to decrease the
- * likelihood of memory-related bugs, OpenVPN uses its own memory %buffer
- * library and garbage collection facilities. These are described in
- * brief here.
- *
- * @section memory_management_buffer The buffer structure
- *
- * The \c buffer structure is a wrapper around a block of dynamically
- * allocated memory which keeps track of the block's capacity \c
- * buffer.capacity and location in memory \c buffer.data. This structure
- * supports efficient prepending and appending within the allocated memory
- * through the use of offset \c buffer.offset and length \c buffer.len
- * fields. See the \c buffer documentation for more details on the
- * structure itself.
- *
- * OpenVPN's %buffer library, implemented in the \c buffer.h and \c
- * buffer.c files, contains many utility functions for working with \c
- * buffer structures. These functions facilitate common operations, such
- * as allocating, freeing, reading and writing to \c buffer structures,
- * and even offer several more advanced operations, such as string
- * matching and creating sub-buffers.
- *
- * Not only do these utility functions make working with \c buffer
- * structures easy, they also perform extensive error checking. Each
- * function, where necessary, checks whether enough space is available
- * before performing its actions. This minimizes the chance of bugs
- * leading to %buffer overflows and other vulnerabilities.
- *
- * @section memory_management_frame The frame structure
- *
- * The \c frame structure keeps track of the maximum allowed packet
- * geometries of a network connection.
- *
- * It is used, for example, to determine the size of \c buffer structures
- * in which to store data channel packets. This is done by having each
- * data channel processing module register the maximum amount of extra
- * space it will need for header prepending and content expansion in the
- * \c frame structure. Once these parameters are known, \c buffer
- * structures can be allocated, based on the \c frame parameters, so that
- * they are large enough to allow efficient prepending of headers and
- * processing of content.
- *
- * @section memory_management_garbage Garbage collection
- *
- * OpenVPN has many sizable functions which perform various actions
- * depending on their %context. This makes it difficult to know in advance
- * exactly how much memory must be allocated. The garbage collection
- * facilities are used to keep track of dynamic allocations, thereby
- * allowing easy collective freeing of the allocated memory.
- *
- * The garbage collection system is implemented by the \c gc_arena and \c
- * gc_entry structures. The arena represents a garbage collecting unit,
- * and contains a linked list of entries. Each entry represents one block
- * of dynamically allocated memory.
- *
- * The garbage collection system also contains various utility functions
- * for working with the garbage collection structures. These include
- * functions for initializing new arenas, allocating memory of a given
- * size and registering the allocation in an arena, and freeing all the
- * allocated memory associated with an arena.
- */
diff --git a/main/openvpn/doc/doxygen/doc_protocol_overview.h b/main/openvpn/doc/doxygen/doc_protocol_overview.h
deleted file mode 100644
index 9edafcfb..00000000
--- a/main/openvpn/doc/doxygen/doc_protocol_overview.h
+++ /dev/null
@@ -1,196 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010-2014 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file Network protocol overview documentation file.
- */
-
-/**
- * @page network_protocol OpenVPN's network protocol
- *
- * Description of packet structure in OpenVPN's network protocol.
- *
- * This document describes the structure of packets exchanged between
- * OpenVPN peers. It is based on the protocol description in the \c ssl.h
- * file.
- *
- * @section network_protocol_external Outer structure of packets exchanged between OpenVPN peers
- *
- * VPN tunnel packets are transported between OpenVPN peers using the UDP
- * or TCP protocols. Their structure is described below.
- *
- * @subsection network_protocol_external_structure External packet structure
- *
- * - packet length (16 bits, unsigned) [TCP-mode only]: always sent as
- * plain text. Since TCP is a stream protocol, this packet length
- * defines the packetization of the stream.
- * - packet opcode and key_id (8 bits) [TLS-mode only]:
- * - package message type (high 5 bits)
- * - key_id (low 3 bits): the key_id refers to an already negotiated
- * TLS session. OpenVPN seamlessly renegotiates the TLS session by
- * using a new key_id for the new session. Overlap (controlled by
- * user definable parameters) between old and new TLS sessions is
- * allowed, providing a seamless transition during tunnel operation.
- * - payload (n bytes)
- *
- * @subsection network_protocol_external_types Message types
- *
- * The type of a VPN tunnel packet is indicated by its opcode. The
- * following describes the various opcodes available.
- *
- * - Control channel messages:
- * - \ref P_CONTROL_HARD_RESET_CLIENT_V1 -- %Key method 1, initial %key
- * from client, forget previous state.
- * - \ref P_CONTROL_HARD_RESET_SERVER_V1 -- %Key method 1, initial %key
- * from server, forget previous state.
- * - \ref P_CONTROL_HARD_RESET_CLIENT_V2 -- %Key method 2, initial %key
- * from client, forget previous state.
- * - \ref P_CONTROL_HARD_RESET_SERVER_V2 -- %Key method 2, initial %key
- * from server, forget previous state.
- * - \ref P_CONTROL_SOFT_RESET_V1 -- New %key, with a graceful
- * transition from old to new %key in the sense that a transition
- * window exists where both the old or new key_id can be used.
- * - \ref P_CONTROL_V1 -- Control channel packet (usually TLS
- * ciphertext).
- * - \ref P_ACK_V1 -- Acknowledgement for control channel packets
- * received.
- * - Data channel messages:
- * - \ref P_DATA_V1 -- Data channel packet containing data channel
- * ciphertext.
- * - \ref P_DATA_V2 -- Data channel packet containing peer-id and data
- * channel ciphertext.
- *
- * @subsection network_protocol_external_key_id Session IDs and Key IDs
- *
- * OpenVPN uses two different forms of packet identifiers:
- * - The first form is 64 bits and is used for all control channel
- * messages. This form is referred to as a \c session_id.
- * - Data channel messages on the other hand use a shortened form of 3
- * bits for efficiency reasons since the vast majority of OpenVPN
- * packets in an active tunnel will be data channel messages. This
- * form is referred to as a \c key_id.
- *
- * The control and data channels use independent packet-id sequences,
- * because the data channel is an unreliable channel while the control
- * channel is a %reliable channel. Each use their own independent HMAC
- * keys.
- *
- * @subsection network_protocol_external_reliable Control channel reliability layer
- *
- * Control channel messages (\c P_CONTROL_* and \c P_ACK_* message types)
- * are TLS ciphertext packets which have been encapsulated inside of a
- * reliability layer. The reliability layer is implemented as a
- * straightforward acknowledge and retransmit model.
- *
- * Acknowledgments of received messages can be encoded in either the
- * dedicated \c P_ACK_* record or they can be prepended to a \c
- * P_CONTROL_* message.
- *
- * See the \link reliable Reliability Layer\endlink module for a detailed
- * description.
- *
- * @section network_protocol_control Structure of control channel messages
- *
- * @subsection network_protocol_control_ciphertext Structure of ciphertext control channel messages
- *
- * Control channel packets in ciphertext form consist of the following
- * parts:
- *
- * - local \c session_id (random 64 bit value to identify TLS session).
- * - HMAC signature of entire encapsulation header for HMAC firewall
- * [only if \c --tls-auth is specified] (usually 16 or 20 bytes).
- * - packet-id for replay protection (4 or 8 bytes, includes sequence
- * number and optional \c time_t timestamp).
- * - acknowledgment packet-id array length (1 byte).
- * - acknowledgment packet-id array (if length > 0).
- * - acknowledgment remote session-id (if length > 0).
- * - packet-id of this message (4 bytes).
- * - TLS payload ciphertext (n bytes) (only for \c P_CONTROL_V1).
- *
- * Note that when \c --tls-auth is used, all message types are protected
- * with an HMAC signature, even the initial packets of the TLS handshake.
- * This makes it easy for OpenVPN to throw away bogus packets quickly,
- * without wasting resources on attempting a TLS handshake which will
- * ultimately fail.
- *
- * @subsection network_protocol_control_key_methods Control channel key methods and
- *
- * Once the TLS session has been initialized and authenticated, the TLS
- * channel is used to exchange random %key material for bidirectional
- * cipher and HMAC keys which will be used to secure data channel packets.
- * OpenVPN currently implements two %key methods. %Key method 1 directly
- * derives keys using random bits obtained from the \c rand_bytes() function.
- * %Key method 2 mixes random %key material from both sides of the connection
- * using the TLS PRF mixing function. %Key method 2 is the preferred method and
- * is the default for OpenVPN 2.0+.
- *
- * The @ref key_generation "Data channel key generation" related page
- * describes the %key methods in more detail.
- *
- * @subsection network_protocol_control_plaintext Structure of plaintext control channel messages
- *
- * - %Key method 1:
- * - Cipher %key length in bytes (1 byte).
- * - Cipher %key (n bytes).
- * - HMAC %key length in bytes (1 byte).
- * - HMAC %key (n bytes).
- * - %Options string (n bytes, null terminated, client/server %options
- * string should match).
- * - %Key method 2:
- * - Literal 0 (4 bytes).
- * - %Key method (1 byte).
- * - \c key_source structure (\c key_source.pre_master only defined
- * for client -> server).
- * - %Options string length, including null (2 bytes).
- * - %Options string (n bytes, null terminated, client/server %options
- * string must match).
- * - [The username/password data below is optional, record can end at
- * this point.]
- * - Username string length, including null (2 bytes).
- * - Username string (n bytes, null terminated).
- * - Password string length, including null (2 bytes).
- * - Password string (n bytes, null terminated).
- *
- * @section network_protocol_data Structure of data channel messages
- *
- * The P_DATA_* payload represents encapsulated tunnel packets which tend to be
- * either IP packets or Ethernet frames. This is essentially the "payload" of
- * the VPN. Data channel packets consist of a data channel header, and a
- * payload. There are two possible formats:
- *
- * @par P_DATA_V1
- * P_DATA_V1 packets have a 1-byte header, carrying the \ref P_DATA_V1 \c opcode
- * and \c key_id, followed by the payload:\n
- * <tt> [ 5-bit opcode | 3-bit key_id ] [ payload ] </tt>
- *
- * @par P_DATA_V2
- * P_DATA_V2 packets have the same 1-byte opcode/key_id, but carrying the \ref
- * P_DATA_V2 opcode, followed by a 3-byte peer-id, which uniquely identifies
- * the peer:\n
- * <tt> [ 5-bit opcode | 3-bit key_id ] [ 24-bit peer-id ] [ payload ] </tt>
- *
- * See @ref data_crypto for details on the data channel payload format.
- *
- */
diff --git a/main/openvpn/doc/doxygen/doc_reliable.h b/main/openvpn/doc/doxygen/doc_reliable.h
deleted file mode 100644
index 5264906a..00000000
--- a/main/openvpn/doc/doxygen/doc_reliable.h
+++ /dev/null
@@ -1,49 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file
- * Reliability Layer module documentation file.
- */
-
-/**
- * @defgroup reliable Reliability Layer module
- *
- * The Reliability Layer is part of OpenVPN's control channel. It
- * provides a reliable and sequential transport mechanism for control
- * channel messages between OpenVPN peers. This module forms the
- * interface between the \link external_multiplexer External
- * Multiplexer\endlink and the \link control_tls Control Channel TLS
- * module\endlink.
- *
- * @par UDP or TCP as VPN tunnel transport
- *
- * This is especially important when OpenVPN is configured to communicate
- * over UDP, because UDP does not offer a reliable and sequential
- * transport. OpenVPN endpoints can also communicate over TCP which does
- * provide a reliable and sequential transport. In both cases, using UDP
- * or TCP as an external transport, the internal Reliability Layer is
- * active.
- */
diff --git a/main/openvpn/doc/doxygen/doc_tunnel_state.h b/main/openvpn/doc/doxygen/doc_tunnel_state.h
deleted file mode 100644
index 6c93e71b..00000000
--- a/main/openvpn/doc/doxygen/doc_tunnel_state.h
+++ /dev/null
@@ -1,155 +0,0 @@
-/*
- * OpenVPN -- An application to securely tunnel IP networks
- * over a single TCP/UDP port, with support for SSL/TLS-based
- * session authentication and key exchange,
- * packet encryption, packet authentication, and
- * packet compression.
- *
- * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
- *
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License version 2
- * as published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program (see the file COPYING included with this
- * distribution); if not, write to the Free Software Foundation, Inc.,
- * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- */
-
-/**
- * @file
- * VPN tunnel state documentation file.
- */
-
-/**
- * @page tunnel_state Structure of the VPN tunnel state storage
- *
- * This section describes how OpenVPN stores its VPN tunnel state during
- * operation.
- *
- * OpenVPN uses several data structures as storage containers for state
- * information of active VPN tunnels. These are described in this
- * section, together with a little bit of history to help understand the
- * origin of the current architecture.
- *
- * Whether an OpenVPN process is running in client-mode or server-mode
- * determines whether it can support only one or multiple simultaneously
- * active VPN tunnels. This consequently also determines how the
- * associated state information is wrapped up internally. This section
- * gives an overview of the differences.
- *
- * @section tunnel_state_history Historic developments
- *
- * In the old v1.x series, an OpenVPN process managed only one single VPN
- * tunnel. This allowed the VPN tunnel state to be stored together with
- * process-global information in one single \c context structure.
- *
- * This changed, however, in the v2.x series, as new OpenVPN versions
- * running in server-mode can support multiple simultaneously active VPN
- * tunnels. This necessitated a redesign of the VPN tunnel state
- * container structures, and modification of the \link
- * external_multiplexer External Multiplexer\endlink and \link
- * internal_multiplexer Internal Multiplexer\endlink systems. The
- * majority of these changes are only relevant for OpenVPN processes
- * running in server-mode, and the client-mode structure has remained very
- * similar to the v1.x single-tunnel form.
- *
- * @section tunnel_state_client Client-mode state
- *
- * An OpenVPN process running in client-mode can manage at most one single
- * VPN tunnel at any one time. The state information for a client's VPN
- * tunnel is stored in a \c context structure.
- *
- * The \c context structure is created in the \c main() function. That is
- * also where process-wide initialization takes place, such as parsing
- * command line %options and reading configuration files. The \c context
- * is then passed to \c tunnel_point_to_point() which drives OpenVPN's
- * main event processing loop. These functions are both part of the \link
- * eventloop Main Event Loop\endlink module.
- *
- * @subsection tunnel_state_client_init Initialization and cleanup
- *
- * Because there is only one \c context structure present, it can be
- * initialized and cleaned up from the client's main event processing
- * function. Before the \c tunnel_point_to_point() function enters its
- * event loop, it calls \c init_instance_handle_signals() which calls \c
- * init_instance() to initialize the single \c context structure. After
- * the event loop stops, it calls \c close_instance() to clean up the \c
- * context.
- *
- * @subsection tunnel_state_client_event Event processing
- *
- * When the main event processing loop activates the external or internal
- * multiplexer to handle a network event, it is not necessary to determine
- * which VPN tunnel the event is associated with, because there is only
- * one VPN tunnel active.
- *
- * @section tunnel_state_server Server-mode state
- *
- * An OpenVPN process running in server-mode can manage multiple
- * simultaneously active VPN tunnels. For every VPN tunnel active, in
- * other words for every OpenVPN client which is connected to a server,
- * the OpenVPN server has one \c context structure in which it stores that
- * particular VPN tunnel's state information.
- *
- * @subsection tunnel_state_server_multi Multi_context and multi_instance structures
- *
- * To support multiple \c context structures, each is wrapped in a \c
- * multi_instance structure, and all the \c multi_instance structures are
- * registered in one single \c multi_context structure. The \link
- * external_multiplexer External Multiplexer\endlink and \link
- * internal_multiplexer Internal Multiplexer\endlink then use the \c
- * multi_context to retrieve the correct \c multi_instance and \c context
- * associated with a given network address.
- *
- * @subsection tunnel_state_server_init Startup and initialization
- *
- * An OpenVPN process running in server-mode starts in the same \c main()
- * function as it would in client-mode. The same process-wide
- * initialization is performed, and the resulting state and configuration
- * is stored in a \c context structure. The server-mode and client-mode
- * processes diverge when the \c main() function calls one of \c
- * tunnel_point_to_point() or \c tunnel_server().
- *
- * In server-mode, \c main() calls the \c tunnel_server() function, which
- * transfers control to \c tunnel_server_udp_single_threaded() or \c
- * tunnel_server_tcp() depending on the external transport protocol.
- *
- * These functions receive the \c context created in \c main(). This
- * object has a special status in server-mode, as it does not represent an
- * active VPN tunnel, but does contain process-wide configuration
- * parameters. In the source code, it is often stored in "top" variables.
- * To distinguish this object from other instances of the same type, its
- * \c context.mode value is set to \c CM_TOP. Other \c context objects,
- * which do represent active VPN tunnels, have a \c context.mode set to \c
- * CM_CHILD_UDP or \c CM_CHILD_TCP, depending on the external transport
- * protocol.
- *
- * Both \c tunnel_server_udp_single_threaded() and \c tunnel_server_tcp()
- * perform similar initialization. In either case, a \c multi_context
- * structure is created, and it is initialized according to the
- * configuration stored in the top \c context by the \c multi_init() and
- * \c multi_top_init() functions.
- *
- * @subsection tunnel_state_server_tunnels Creating and destroying VPN tunnels
- *
- * When an OpenVPN client makes a new connection to a server, the server
- * creates a new \c context and \c multi_instance. The latter is
- * registered in the \c multi_context, which makes it possible for the
- * external and internal multiplexers to retrieve the correct \c
- * multi_instance and \c context when a network event occurs.
- *
- * @subsection tunnel_state_server_cleanup Final cleanup
- *
- * After the main event loop exits, both \c
- * tunnel_server_udp_single_threaded() and \c tunnel_server_tcp() perform
- * similar cleanup. They call \c multi_uninit() followed by \c
- * multi_top_free() to clean up the \c multi_context structure.
- */
diff --git a/main/openvpn/doc/doxygen/openvpn.doxyfile b/main/openvpn/doc/doxygen/openvpn.doxyfile
deleted file mode 100644
index 7a02028a..00000000
--- a/main/openvpn/doc/doxygen/openvpn.doxyfile
+++ /dev/null
@@ -1,279 +0,0 @@
-# Doxyfile 1.5.5
-
-#---------------------------------------------------------------------------
-# Project related configuration options
-#---------------------------------------------------------------------------
-DOXYFILE_ENCODING = UTF-8
-PROJECT_NAME = "OpenVPN"
-PROJECT_NUMBER =
-OUTPUT_DIRECTORY = doxygen
-CREATE_SUBDIRS = NO
-OUTPUT_LANGUAGE = English
-BRIEF_MEMBER_DESC = YES
-REPEAT_BRIEF = YES
-ABBREVIATE_BRIEF = "The $name class" \
- "The $name widget" \
- "The $name file" \
- is \
- provides \
- specifies \
- contains \
- represents \
- a \
- an \
- the
-ALWAYS_DETAILED_SEC = NO
-INLINE_INHERITED_MEMB = NO
-FULL_PATH_NAMES = YES
-STRIP_FROM_PATH = ""
-STRIP_FROM_INC_PATH =
-SHORT_NAMES = NO
-JAVADOC_AUTOBRIEF = YES # NO
-QT_AUTOBRIEF = NO
-MULTILINE_CPP_IS_BRIEF = NO
-DETAILS_AT_TOP = NO
-INHERIT_DOCS = YES
-SEPARATE_MEMBER_PAGES = NO
-TAB_SIZE = 8
-ALIASES =
-OPTIMIZE_OUTPUT_FOR_C = YES
-OPTIMIZE_OUTPUT_JAVA = NO
-OPTIMIZE_FOR_FORTRAN = NO
-OPTIMIZE_OUTPUT_VHDL = NO
-BUILTIN_STL_SUPPORT = NO
-CPP_CLI_SUPPORT = NO
-SIP_SUPPORT = NO
-DISTRIBUTE_GROUP_DOC = NO
-SUBGROUPING = YES
-TYPEDEF_HIDES_STRUCT = NO
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-EXTRACT_ALL = YES
-EXTRACT_PRIVATE = YES
-EXTRACT_STATIC = YES
-EXTRACT_LOCAL_CLASSES = YES
-EXTRACT_LOCAL_METHODS = YES
-EXTRACT_ANON_NSPACES = YES
-HIDE_UNDOC_MEMBERS = NO
-HIDE_UNDOC_CLASSES = NO
-HIDE_FRIEND_COMPOUNDS = NO
-HIDE_IN_BODY_DOCS = NO
-INTERNAL_DOCS = NO
-CASE_SENSE_NAMES = NO
-HIDE_SCOPE_NAMES = NO
-SHOW_INCLUDE_FILES = YES
-INLINE_INFO = YES
-SORT_MEMBER_DOCS = YES
-SORT_BRIEF_DOCS = NO
-SORT_GROUP_NAMES = NO
-SORT_BY_SCOPE_NAME = NO
-GENERATE_TODOLIST = YES
-GENERATE_TESTLIST = YES
-GENERATE_BUGLIST = YES
-GENERATE_DEPRECATEDLIST= YES
-ENABLED_SECTIONS =
-MAX_INITIALIZER_LINES = 30
-SHOW_USED_FILES = YES
-SHOW_DIRECTORIES = NO
-FILE_VERSION_FILTER =
-#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-QUIET = NO
-WARNINGS = YES
-WARN_IF_UNDOCUMENTED = YES
-WARN_IF_DOC_ERROR = YES
-WARN_NO_PARAMDOC = NO
-WARN_FORMAT = "$file:$line: $text"
-WARN_LOGFILE =
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-INPUT = .
-INPUT_ENCODING = UTF-8
-FILE_PATTERNS = *.c \
- *.cc \
- *.cxx \
- *.cpp \
- *.c++ \
- *.d \
- *.java \
- *.ii \
- *.ixx \
- *.ipp \
- *.i++ \
- *.inl \
- *.h \
- *.hh \
- *.hxx \
- *.hpp \
- *.h++ \
- *.idl \
- *.odl \
- *.cs \
- *.php \
- *.php3 \
- *.inc \
- *.m \
- *.mm \
- *.dox \
- *.py \
- *.f90 \
- *.f \
- *.vhd \
- *.vhdl
-RECURSIVE = YES
-EXCLUDE =
-EXCLUDE_SYMLINKS = NO
-EXCLUDE_PATTERNS =
-EXCLUDE_SYMBOLS =
-EXAMPLE_PATH =
-EXAMPLE_PATTERNS = *
-EXAMPLE_RECURSIVE = NO
-IMAGE_PATH =
-INPUT_FILTER =
-FILTER_PATTERNS =
-FILTER_SOURCE_FILES = NO
-#---------------------------------------------------------------------------
-# configuration options related to source browsing
-#---------------------------------------------------------------------------
-SOURCE_BROWSER = YES
-INLINE_SOURCES = NO
-STRIP_CODE_COMMENTS = YES
-REFERENCED_BY_RELATION = YES
-REFERENCES_RELATION = YES
-REFERENCES_LINK_SOURCE = YES
-USE_HTAGS = NO
-VERBATIM_HEADERS = YES
-#---------------------------------------------------------------------------
-# configuration options related to the alphabetical class index
-#---------------------------------------------------------------------------
-ALPHABETICAL_INDEX = NO
-COLS_IN_ALPHA_INDEX = 5
-IGNORE_PREFIX =
-#---------------------------------------------------------------------------
-# configuration options related to the HTML output
-#---------------------------------------------------------------------------
-GENERATE_HTML = YES
-HTML_OUTPUT = html
-HTML_FILE_EXTENSION = .html
-HTML_HEADER =
-HTML_FOOTER =
-HTML_STYLESHEET =
-HTML_ALIGN_MEMBERS = YES
-GENERATE_HTMLHELP = NO
-GENERATE_DOCSET = NO
-DOCSET_FEEDNAME = "Doxygen generated docs"
-DOCSET_BUNDLE_ID = org.doxygen.Project
-HTML_DYNAMIC_SECTIONS = NO
-CHM_FILE =
-HHC_LOCATION =
-GENERATE_CHI = NO
-BINARY_TOC = NO
-TOC_EXPAND = NO
-DISABLE_INDEX = NO
-ENUM_VALUES_PER_LINE = 4
-GENERATE_TREEVIEW = NO
-TREEVIEW_WIDTH = 250
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX = YES
-LATEX_OUTPUT = latex
-LATEX_CMD_NAME = latex
-MAKEINDEX_CMD_NAME = makeindex
-COMPACT_LATEX = YES # NO
-PAPER_TYPE = a4wide
-EXTRA_PACKAGES =
-LATEX_HEADER =
-PDF_HYPERLINKS = YES
-USE_PDFLATEX = YES
-LATEX_BATCHMODE = NO
-LATEX_HIDE_INDICES = NO
-#---------------------------------------------------------------------------
-# configuration options related to the RTF output
-#---------------------------------------------------------------------------
-GENERATE_RTF = NO
-RTF_OUTPUT = rtf
-COMPACT_RTF = NO
-RTF_HYPERLINKS = NO
-RTF_STYLESHEET_FILE =
-RTF_EXTENSIONS_FILE =
-#---------------------------------------------------------------------------
-# configuration options related to the man page output
-#---------------------------------------------------------------------------
-GENERATE_MAN = NO
-MAN_OUTPUT = man
-MAN_EXTENSION = .3
-MAN_LINKS = NO
-#---------------------------------------------------------------------------
-# configuration options related to the XML output
-#---------------------------------------------------------------------------
-GENERATE_XML = NO
-XML_OUTPUT = xml
-XML_SCHEMA =
-XML_DTD =
-XML_PROGRAMLISTING = YES
-#---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-GENERATE_AUTOGEN_DEF = NO
-#---------------------------------------------------------------------------
-# configuration options related to the Perl module output
-#---------------------------------------------------------------------------
-GENERATE_PERLMOD = NO
-PERLMOD_LATEX = NO
-PERLMOD_PRETTY = YES
-PERLMOD_MAKEVAR_PREFIX =
-#---------------------------------------------------------------------------
-# Configuration options related to the preprocessor
-#---------------------------------------------------------------------------
-ENABLE_PREPROCESSING = YES
-MACRO_EXPANSION = NO
-EXPAND_ONLY_PREDEF = NO
-SEARCH_INCLUDES = YES
-INCLUDE_PATH =
-INCLUDE_FILE_PATTERNS =
-PREDEFINED = WIN32 NTLM USE_LZO ENABLE_FRAGMENT P2MP P2MP_SERVER ENABLE_CRYPTO ENABLE_CRYPTO_OPENSSL ENABLE_PLUGIN ENABLE_MANAGEMENT ENABLE_OCC HAVE_GETTIMEOFDAY
-EXPAND_AS_DEFINED =
-SKIP_FUNCTION_MACROS = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to external references
-#---------------------------------------------------------------------------
-TAGFILES =
-GENERATE_TAGFILE =
-ALLEXTERNALS = NO
-EXTERNAL_GROUPS = YES
-PERL_PATH = /usr/bin/perl
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool
-#---------------------------------------------------------------------------
-CLASS_DIAGRAMS = NO
-MSCGEN_PATH =
-HIDE_UNDOC_RELATIONS = YES
-HAVE_DOT = YES
-CLASS_GRAPH = YES
-COLLABORATION_GRAPH = YES
-GROUP_GRAPHS = YES
-UML_LOOK = NO
-TEMPLATE_RELATIONS = NO
-INCLUDE_GRAPH = YES
-INCLUDED_BY_GRAPH = YES
-CALL_GRAPH = NO # YES
-CALLER_GRAPH = NO # YES
-GRAPHICAL_HIERARCHY = YES
-DIRECTORY_GRAPH = YES
-DOT_IMAGE_FORMAT = png
-DOT_PATH = "/usr/bin/dot"
-DOTFILE_DIRS =
-DOT_GRAPH_MAX_NODES = 50
-MAX_DOT_GRAPH_DEPTH = 1000
-DOT_TRANSPARENT = YES
-DOT_MULTI_TARGETS = NO
-GENERATE_LEGEND = YES
-DOT_CLEANUP = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to the search engine
-#---------------------------------------------------------------------------
-SEARCHENGINE = NO
diff --git a/main/openvpn/doc/management-notes.txt b/main/openvpn/doc/management-notes.txt
deleted file mode 100644
index ef39b855..00000000
--- a/main/openvpn/doc/management-notes.txt
+++ /dev/null
@@ -1,1039 +0,0 @@
-OpenVPN Management Interface Notes
-----------------------------------
-
-The OpenVPN Management interface allows OpenVPN to
-be administratively controlled from an external program via
-a TCP or unix domain socket.
-
-The interface has been specifically designed for developers
-who would like to programmatically or remotely control
-an OpenVPN daemon, and can be used when OpenVPN is running
-as a client or server.
-
-The management interface is implemented using a client/server TCP
-connection or unix domain socket where OpenVPN will listen on a
-provided IP address and port for incoming management client connections.
-
-The management protocol is currently cleartext without an explicit
-security layer. For this reason, it is recommended that the
-management interface either listen on a unix domain socket,
-localhost (127.0.0.1), or on the local VPN address. It's possible
-to remotely connect to the management interface over the VPN itself,
-though some capabilities will be limited in this mode, such as the
-ability to provide private key passwords.
-
-The management interface is enabled in the OpenVPN
-configuration file using the following directive:
-
---management
-
-See the man page for documentation on this and related
-directives.
-
-Once OpenVPN has started with the management layer enabled,
-you can telnet to the management port (make sure to use
-a telnet client which understands "raw" mode).
-
-Once connected to the management port, you can use
-the "help" command to list all commands.
-
-COMMAND -- bytecount
---------------------
-
-The bytecount command is used to request real-time notification
-of OpenVPN bandwidth usage.
-
-Command syntax:
-
- bytecount n (where n > 0) -- set up automatic notification of
- bandwidth usage once every n seconds
- bytecount 0 -- turn off bytecount notifications
-
-If OpenVPN is running as a client, the bytecount notification
-will look like this:
-
- >BYTECOUNT:{BYTES_IN},{BYTES_OUT}
-
-BYTES_IN is the number of bytes that have been received from
-the server and BYTES_OUT is the number of bytes that have been
-sent to the server.
-
-If OpenVPN is running as a server, the bytecount notification
-will look like this:
-
- >BYTECOUNT_CLI:{CID},{BYTES_IN},{BYTES_OUT}
-
-CID is the Client ID, BYTES_IN is the number of bytes that have
-been received from the client and BYTES_OUT is the number of
-bytes that have been sent to the client.
-
-Note that when the bytecount command is used on the server, every
-connected client will report its bandwidth numbers once every n
-seconds.
-
-When the client disconnects, the final bandwidth numbers will be
-placed in the 'bytes_received' and 'bytes_sent' environmental variables
-as included in the >CLIENT:DISCONNECT notification.
-
-COMMAND -- echo
----------------
-
-The echo capability is used to allow GUI-specific
-parameters to be either embedded in the OpenVPN config file
-or pushed to an OpenVPN client from a server.
-
-Command examples:
-
- echo on -- turn on real-time notification of echo messages
- echo all -- print the current echo history list
- echo off -- turn off real-time notification of echo messages
- echo on all -- atomically enable real-time notification,
- plus show any messages in history buffer
-
-For example, suppose you are developing a OpenVPN GUI and
-you want to give the OpenVPN server the ability to ask
-the GUI to forget any saved passwords.
-
-In the OpenVPN server config file, add:
-
- push "echo forget-passwords"
-
-When the OpenVPN client receives its pulled list of directives
-from the server, the "echo forget-passwords" directive will
-be in the list, and it will cause the management interface
-to save the "forget-passwords" string in its list of echo
-parameters.
-
-The management client can use "echo all" to output the full
-list of echoed parameters, "echo on" to turn on real-time
-notification of echoed parameters via the ">ECHO:" prefix,
-or "echo off" to turn off real-time notification.
-
-When the GUI connects to the OpenVPN management socket, it
-can issue an "echo all" command, which would produce output
-like this:
-
- 1101519562,forget-passwords
- END
-
-Essentially the echo command allowed us to pass parameters from
-the OpenVPN server to the OpenVPN client, and then to the
-management client (such as a GUI). The large integer is the
-unix date/time when the echo parameter was received.
-
-If the management client had issued the command "echo on",
-it would have enabled real-time notifications of echo
-parameters. In this case, our "forget-passwords" message
-would be output like this:
-
- >ECHO:1101519562,forget-passwords
-
-Like the log command, the echo command can atomically show
-history while simultaneously activating real-time updates:
-
- echo on all
-
-The size of the echo buffer is currently hardcoded to 100
-messages.
-
-COMMAND -- exit, quit
----------------------
-
-Close the managment session, and resume listening on the
-management port for connections from other clients. Currently,
-the OpenVPN daemon can at most support a single management client
-any one time.
-
-COMMAND -- help
----------------
-
-Print a summary of commands.
-
-COMMAND -- hold
----------------
-
-The hold command can be used to manipulate the hold flag,
-or release OpenVPN from a hold state.
-
-If the hold flag is set on initial startup or
-restart, OpenVPN will hibernate prior to initializing
-the tunnel until the management interface receives
-a "hold release" command.
-
-The --management-hold directive of OpenVPN can be used
-to start OpenVPN with the hold flag set.
-
-The hold flag setting is persistent and will not
-be reset by restarts.
-
-OpenVPN will indicate that it is in a hold state by
-sending a real-time notification to the management
-client:
-
- >HOLD:Waiting for hold release
-
-Command examples:
-
- hold -- show current hold flag, 0=off, 1=on.
- hold on -- turn on hold flag so that future restarts
- will hold.
- hold off -- turn off hold flag so that future restarts will
- not hold.
- hold release -- leave hold state and start OpenVPN, but
- do not alter the current hold flag setting.
-
-COMMAND -- kill
----------------
-
-In server mode, kill a particlar client instance.
-
-Command examples:
-
- kill Test-Client -- kill the client instance having a
- common name of "Test-Client".
- kill 1.2.3.4:4000 -- kill the client instance having a
- source address and port of 1.2.3.4:4000
-
-Use the "status" command to see which clients are connected.
-
-COMMAND -- log
---------------
-
-Show the OpenVPN log file. Only the most recent n lines
-of the log file are cached by the management interface, where
-n is controlled by the OpenVPN --management-log-cache directive.
-
-Command examples:
-
- log on -- Enable real-time output of log messages.
- log all -- Show currently cached log file history.
- log on all -- Atomically show all currently cached log file
- history then enable real-time notification of
- new log file messages.
- log off -- Turn off real-time notification of log messages.
- log 20 -- Show the most recent 20 lines of log file history.
-
-Real-time notification format:
-
-Real-time log messages begin with the ">LOG:" prefix followed
-by the following comma-separated fields:
-
- (a) unix integer date/time,
- (b) zero or more message flags in a single string:
- I -- informational
- F -- fatal error
- N -- non-fatal error
- W -- warning
- D -- debug, and
- (c) message text.
-
-COMMAND -- mute
----------------
-
-Change the OpenVPN --mute parameter. The mute parameter is
-used to silence repeating messages of the same message
-category.
-
-Command examples:
-
- mute 40 -- change the mute parameter to 40
- mute -- show the current mute setting
-
-COMMAND -- net
---------------
-
-(Windows Only) Produce output equivalent to the OpenVPN
---show-net directive. The output includes OpenVPN's view
-of the system network adapter list and routing table based
-on information returned by the Windows IP helper API.
-
-COMMAND -- pid
---------------
-
-Shows the process ID of the current OpenVPN process.
-
-COMMAND -- password and username
---------------------------------
-
- The password command is used to pass passwords to OpenVPN.
-
- If OpenVPN is run with the --management-query-passwords
- directive, it will query the management interface for RSA
- private key passwords and the --auth-user-pass
- username/password.
-
- When OpenVPN needs a password from the management interface,
- it will produce a real-time ">PASSWORD:" message.
-
- Example 1:
-
- >PASSWORD:Need 'Private Key' password
-
- OpenVPN is indicating that it needs a password of type
- "Private Key".
-
- The management client should respond to this query as follows:
-
- password "Private Key" foo
-
- Example 2:
-
- >PASSWORD:Need 'Auth' username/password
-
- OpenVPN needs a --auth-user-pass password. The management
- client should respond:
-
- username "Auth" foo
- password "Auth" bar
-
- The username/password itself can be in quotes, and special
- characters such as double quote or backslash must be escaped,
- for example,
-
- password "Private Key" "foo\"bar"
-
- The escaping rules are the same as for the config file.
- See the "Command Parsing" section below for more info.
-
- The PASSWORD real-time message type can also be used to
- indicate password or other types of authentication failure:
-
- Example 3: The private key password is incorrect and OpenVPN
- is exiting:
-
- >PASSWORD:Verification Failed: 'Private Key'
-
- Example 4: The --auth-user-pass username/password failed,
- and OpenVPN is exiting:
-
- >PASSWORD:Verification Failed: 'Auth'
-
- Example 5: The --auth-user-pass username/password failed,
- and the server provided a custom client-reason-text string
- using the client-deny server-side management interface command.
-
- >PASSWORD:Verification Failed: 'custom server-generated string'
-
-COMMAND -- forget-passwords
----------------------------
-
-The forget-passwords command will cause the daemon to forget passwords
-entered during the session.
-
-Command example:
-
- forget-passwords -- forget passwords entered so far.
-
-COMMAND -- signal
------------------
-
-The signal command will send a signal to the OpenVPN daemon.
-The signal can be one of SIGHUP, SIGTERM, SIGUSR1, or SIGUSR2.
-
-Command example:
-
- signal SIGUSR1 -- send a SIGUSR1 signal to daemon
-
-COMMAND -- state
-----------------
-
-Show the current OpenVPN state, show state history, or
-enable real-time notification of state changes.
-
-These are the OpenVPN states:
-
-CONNECTING -- OpenVPN's initial state.
-WAIT -- (Client only) Waiting for initial response
- from server.
-AUTH -- (Client only) Authenticating with server.
-GET_CONFIG -- (Client only) Downloading configuration options
- from server.
-ASSIGN_IP -- Assigning IP address to virtual network
- interface.
-ADD_ROUTES -- Adding routes to system.
-CONNECTED -- Initialization Sequence Completed.
-RECONNECTING -- A restart has occurred.
-EXITING -- A graceful exit is in progress.
-
-Command examples:
-
- state -- Print current OpenVPN state.
- state on -- Enable real-time notification of state changes.
- state off -- Disable real-time notification of state changes.
- state all -- Print current state history.
- state 3 -- Print the 3 most recent state transitions.
- state on all -- Atomically show state history while at the
- same time enable real-time state notification
- of future state transitions.
-
-The output format consists of 4 comma-separated parameters:
- (a) the integer unix date/time,
- (b) the state name,
- (c) optional descriptive string (used mostly on RECONNECTING
- and EXITING to show the reason for the disconnect),
- (d) optional TUN/TAP local IP address (shown for ASSIGN_IP
- and CONNECTED), and
- (e) optional address of remote server (OpenVPN 2.1 or higher).
-
-Real-time state notifications will have a ">STATE:" prefix
-prepended to them.
-
-COMMAND -- status
------------------
-
-Show current daemon status information, in the same format as
-that produced by the OpenVPN --status directive.
-
-Command examples:
-
-status -- Show status information using the default status
- format version.
-
-status 3 -- Show status information using the format of
- --status-version 3.
-
-COMMAND -- username
--------------------
-
-See the "password" section above.
-
-COMMAND -- verb
----------------
-
-Change the OpenVPN --verb parameter. The verb parameter
-controls the output verbosity, and may range from 0 (no output)
-to 15 (maximum output). See the OpenVPN man page for additional
-info on verbosity levels.
-
-Command examples:
-
- verb 4 -- change the verb parameter to 4
- mute -- show the current verb setting
-
-COMMAND -- version
-------------------
-
-Show the current OpenVPN and Management Interface versions.
-
-
-COMMAND -- auth-retry
----------------------
-
-Set the --auth-retry setting to control how OpenVPN responds to
-username/password authentication errors. See the manual page
-for more info.
-
-Command examples:
-
- auth-retry interact -- Don't exit when bad username/passwords are entered.
- Query for new input and retry.
-
-COMMAND -- needok (OpenVPN 2.1 or higher)
-------------------------------------------
-
-Confirm a ">NEED-OK" real-time notification, normally used by
-OpenVPN to block while waiting for a specific user action.
-
-Example:
-
- OpenVPN needs the user to insert a cryptographic token,
- so it sends a real-time notification:
-
- >NEED-OK:Need 'token-insertion-request' confirmation MSG:Please insert your cryptographic token
-
- The management client, if it is a GUI, can flash a dialog
- box containing the text after the "MSG:" marker to the user.
- When the user acknowledges the dialog box,
- the management client can issue this command:
-
- needok token-insertion-request ok
- or
- needok token-insertion-request cancel
-
-COMMAND -- needstr (OpenVPN 2.1 or higher)
--------------------------------------------
-
-Confirm a ">NEED-STR" real-time notification, normally used by
-OpenVPN to block while waiting for a specific user input.
-
-Example:
-
- OpenVPN needs the user to specify some input, so it sends a
- real-time notification:
-
- >NEED-STR:Need 'name' input MSG:Please specify your name
-
- The management client, if it is a GUI, can flash a dialog
- box containing the text after the "MSG:" marker to the user.
- When the user acknowledges the dialog box,
- the management client can issue this command:
-
- needstr name "John"
-
-COMMAND -- pkcs11-id-count (OpenVPN 2.1 or higher)
----------------------------------------------------
-
-Retrieve available number of certificates.
-
-Example:
-
- pkcs11-id-count
- >PKCS11ID-COUNT:5
-
-COMMAND -- pkcs11-id-get (OpenVPN 2.1 or higher)
--------------------------------------------------
-
-Retrieve certificate by index, the ID string should be provided
-as PKCS#11 identity, the blob is BASE64 encoded certificate.
-
-Example:
-
- pkcs11-id-get 1
- PKCS11ID-ENTRY:'1', ID:'<snip>', BLOB:'<snip>'
-
-COMMAND -- client-auth (OpenVPN 2.1 or higher)
------------------------------------------------
-
-Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request and specify
-"client-connect" configuration directives in a subsequent text block.
-
-The OpenVPN server should have been started with the
---management-client-auth directive so that it will ask the management
-interface to approve client connections.
-
-
- client-auth {CID} {KID}
- line_1
- line_2
- ...
- line_n
- END
-
-CID,KID -- client ID and Key ID. See documentation for ">CLIENT:"
-notification for more info.
-
-line_1 to line_n -- client-connect configuration text block, as would be
-returned by a --client-connect script. The text block may be null, with
-"END" immediately following the "client-auth" line (using a null text
-block is equivalent to using the client-auth-nt command).
-
-A client-connect configuration text block contains OpenVPN directives
-that will be applied to the client instance object representing a newly
-connected client.
-
-COMMAND -- client-auth-nt (OpenVPN 2.1 or higher)
---------------------------------------------------
-
-Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request without specifying
-client-connect configuration text.
-
-The OpenVPN server should have been started with the
---management-client-auth directive so that it will ask the management
-interface to approve client connections.
-
- client-auth-nt {CID} {KID}
-
-CID,KID -- client ID and Key ID. See documentation for ">CLIENT:"
-notification for more info.
-
-COMMAND -- client-deny (OpenVPN 2.1 or higher)
------------------------------------------------
-
-Deny a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request.
-
- client-deny {CID} {KID} "reason-text" ["client-reason-text"]
-
-CID,KID -- client ID and Key ID. See documentation for ">CLIENT:"
-notification for more info.
-
-reason-text: a human-readable message explaining why the authentication
-request was denied. This message will be output to the OpenVPN log
-file or syslog.
-
-client-reason-text: a message that will be sent to the client as
-part of the AUTH_FAILED message.
-
-Note that client-deny denies a specific Key ID (pertaining to a
-TLS renegotiation). A client-deny command issued in response to
-an initial TLS key negotiation (notified by ">CLIENT:CONNECT") will
-terminate the client session after returning "AUTH-FAILED" to the client.
-On the other hand, a client-deny command issued in response to
-a TLS renegotiation (">CLIENT:REAUTH") will invalidate the renegotiated
-key, however the TLS session associated with the currently active
-key will continue to live for up to --tran-window seconds before
-expiration.
-
-To immediately kill a client session, use "client-kill".
-
-COMMAND -- client-kill (OpenVPN 2.1 or higher)
------------------------------------------------
-
-Immediately kill a client instance by CID.
-
- client-kill {CID}
-
-CID -- client ID. See documentation for ">CLIENT:" notification for more
-info.
-
-COMMAND -- client-pf (OpenVPN 2.1 or higher)
----------------------------------------------
-
-Push a packet filter file to a specific client.
-
-The OpenVPN server should have been started with the
---management-client-pf directive so that it will require that
-VPN tunnel packets sent or received by client instances must
-conform to that client's packet filter configuration.
-
- client-pf {CID}
- line_1
- line_2
- ...
- line_n
- END
-
-CID -- client ID. See documentation for ">CLIENT:" notification for
-more info.
-
-line_1 to line_n -- the packet filter configuration file for this
-client.
-
-Packet filter file grammar:
-
- [CLIENTS DROP|ACCEPT]
- {+|-}common_name1
- {+|-}common_name2
- . . .
- [SUBNETS DROP|ACCEPT]
- {+|-}subnet1
- {+|-}subnet2
- . . .
- [END]
-
- Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS | "unknown"
-
- CLIENTS refers to the set of clients (by their common-name) which
- this instance is allowed ('+') to connect to, or is excluded ('-')
- from connecting to. Note that in the case of client-to-client
- connections, such communication must be allowed by the packet filter
- configuration files of both clients AND the --client-to-client
- directive must have been specified in the OpenVPN server config.
-
- SUBNETS refers to IP addresses or IP address subnets which this
- client instance may connect to ('+') or is excluded ('-') from
- connecting to, and applies to IPv4 and ARP packets. The special
- "unknown" tag refers to packets of unknown type, i.e. a packet that
- is not IPv4 or ARP.
-
- DROP or ACCEPT defines default policy when there is no explicit match
- for a common-name or subnet. The [END] tag must exist.
-
- Notes:
-
- * The SUBNETS section currently only supports IPv4 addresses and
- subnets.
-
- * A given client or subnet rule applies to both incoming and
- outgoing packets.
-
- * The CLIENTS list is order-invariant. Because the list is stored
- as a hash-table, the order of the list does not affect its function.
-
- * The SUBNETS table is scanned sequentially, and the first item to
- match is chosen. Therefore the SUBNETS table is NOT order-invariant.
-
- * No client-to-client communication is allowed unless the
- --client-to-client configuration directive is enabled AND
- the CLIENTS list of BOTH clients allows the communication.
-
-Example packet filter spec, as transmitted to the management interface:
-
- client-pf 42
- [CLIENTS ACCEPT]
- -accounting
- -enigma
- [SUBNETS DROP]
- -10.46.79.9
- +10.0.0.0/8
- [END]
- END
-
-The above example sets the packet filter policy for the client
-identified by CID=42. This client may connect to all other clients
-except those having a common name of "accounting" or "enigma".
-The client may only interact with external IP addresses in the
-10.0.0.0/8 subnet, however access to 10.46.79.9 is specifically
-excluded.
-
-Another example packet filter spec, as transmitted to the
-management interface:
-
- client-pf 99
- [CLIENTS DENY]
- +public
- [SUBNETS ACCEPT]
- +10.10.0.1
- -10.0.0.0/8
- -unknown
- [END]
- END
-
-The above example sets the packet filter policy for the client
-identified by CID=99. This client may not connect to any other
-clients except those having a common name of "public". It may
-interact with any external IP address except those in the
-10.0.0.0/8 netblock. However interaction with one address in
-the 10.0.0.0/8 netblock is allowed: 10.10.0.1. Also, the client
-may not interact with external IP addresses using an "unknown"
-protocol (i.e. one that is not IPv4 or ARP).
-
-COMMAND -- remote (OpenVPN AS 2.1.5/OpenVPN 2.3 or higher)
---------------------------------------------
-
-Provide remote host/port in response to a >REMOTE notification
-(client only). Requires that the --management-query-remote
-directive is used.
-
- remote ACTION [HOST PORT]
-
-The "remote" command should only be given in response to a >REMOTE
-notification. For example, the following >REMOTE notification
-indicates that the client config file would ordinarily connect
-to vpn.example.com port 1194 (UDP):
-
- >REMOTE:vpn.example.com,1194,udp
-
-Now, suppose we want to override the host and port, connecting
-instead to vpn.otherexample.com port 1234. After receiving
-the above notification, use this command:
-
- remote MOD vpn.otherexample.com 1234
-
-To accept the same host and port as the client would ordinarily
-have connected to, use this command:
-
- remote ACCEPT
-
-To skip the current connection entry and advance to the next one,
-use this command:
-
- remote SKIP
-
-COMMAND -- proxy (OpenVPN 2.3 or higher)
---------------------------------------------
-
-Provide proxy server host/port and flags in response to a >PROXY
-notification (client only). Requires that the --management-query-proxy
-directive is used.
-
- proxy TYPE HOST PORT ["nct"]
-
-The "proxy" command must only be given in response to a >PROXY
-notification. Use the "nct" flag if you only want to allow
-non-cleartext auth with the proxy server. The following >PROXY
-notification indicates that the client config file would ordinarily
-connect to the first --remote configured, vpn.example.com using TCP:
-
- >PROXY:1,TCP,vpn.example.com
-
-Now, suppose we want to connect to the remote host using the proxy server
-proxy.intranet port 8080 with secure authentication only, if required.
-After receiving the above notification, use this command:
-
- proxy HTTP proxy.intranet 8080 nct
-
-You can also use the SOCKS keyword to pass a SOCKS server address, like:
-
- proxy SOCKS fe00::1 1080
-
-To accept connecting to the host and port directly, use this command:
-
- proxy NONE
-
-COMMAND -- rsa-sig (OpenVPN 2.3 or higher)
-------------------------------------------
-Provides support for external storage of the private key. Requires the
---management-external-key option. This option can be used instead of "key"
-in client mode, and allows the client to run without the need to load the
-actual private key. When the SSL protocol needs to perform an RSA sign
-operation, the data to be signed will be sent to the management interface
-via a notification as follows:
-
->RSA_SIGN:[BASE64_DATA]
-
-The management interface client should then sign BASE64_DATA
-using the private key and return the SSL signature as follows:
-
-rsa-sig
-[BASE64_SIG_LINE]
-.
-.
-.
-END
-
-Base64 encoded output of RSA_sign(NID_md5_sha1,... will provide a
-correct signature.
-
-This capability is intended to allow the use of arbitrary cryptographic
-service providers with OpenVPN via the management interface.
-
-
-OUTPUT FORMAT
--------------
-
-(1) Command success/failure indicated by "SUCCESS: [text]" or
- "ERROR: [text]".
-
-(2) For commands which print multiple lines of output,
- the last line will be "END".
-
-(3) Real-time messages will be in the form ">[source]:[text]",
- where source is "CLIENT", "ECHO", "FATAL", "HOLD", "INFO", "LOG",
- "NEED-OK", "PASSWORD", or "STATE".
-
-REAL-TIME MESSAGE FORMAT
-------------------------
-
-The OpenVPN management interface produces two kinds of
-output: (a) output from a command, or (b) asynchronous,
-real-time output which can be generated at any time.
-
-Real-time messages start with a '>' character in the first
-column and are immediately followed by a type keyword
-indicating the type of real-time message. The following
-types are currently defined:
-
-BYTECOUNT -- Real-time bandwidth usage notification, as enabled
- by "bytecount" command when OpenVPN is running as
- a client.
-
-BYTECOUNT_CLI -- Real-time bandwidth usage notification per-client,
- as enabled by "bytecount" command when OpenVPN is
- running as a server.
-
-CLIENT -- Notification of client connections and disconnections
- on an OpenVPN server. Enabled when OpenVPN is started
- with the --management-client-auth option. CLIENT
- notifications may be multi-line. See "The CLIENT
- notification" section below for detailed info.
-
-ECHO -- Echo messages as controlled by the "echo" command.
-
-FATAL -- A fatal error which is output to the log file just
- prior to OpenVPN exiting.
-
-HOLD -- Used to indicate that OpenVPN is in a holding state
- and will not start until it receives a
- "hold release" command.
-
-INFO -- Informational messages such as the welcome message.
-
-LOG -- Log message output as controlled by the "log" command.
-
-NEED-OK -- OpenVPN needs the end user to do something, such as
- insert a cryptographic token. The "needok" command can
- be used to tell OpenVPN to continue.
-
-NEED-STR -- OpenVPN needs information from end, such as
- a certificate to use. The "needstr" command can
- be used to tell OpenVPN to continue.
-
-PASSWORD -- Used to tell the management client that OpenVPN
- needs a password, also to indicate password
- verification failure.
-
-STATE -- Shows the current OpenVPN state, as controlled
- by the "state" command.
-
-The CLIENT notification
------------------------
-
-The ">CLIENT:" notification is enabled by the --management-client-auth
-OpenVPN configuration directive that gives the management interface client
-the responsibility to authenticate OpenVPN clients after their client
-certificate has been verified. CLIENT notifications may be multi-line, and
-the sequentiality of a given CLIENT notification, its associated environmental
-variables, and the terminating ">CLIENT:ENV,END" line are guaranteed to be
-atomic.
-
-CLIENT notification types:
-
-(1) Notify new client connection ("CONNECT") or existing client TLS session
- renegotiation ("REAUTH"). Information about the client is provided
- by a list of environmental variables which are documented in the OpenVPN
- man page. The environmental variables passed are equivalent to those
- that would be passed to an --auth-user-pass-verify script.
-
- >CLIENT:CONNECT|REAUTH,{CID},{KID}
- >CLIENT:ENV,name1=val1
- >CLIENT:ENV,name2=val2
- >CLIENT:ENV,...
- >CLIENT:ENV,END
-
-(2) Notify successful client authentication and session initiation.
- Called after CONNECT.
-
- >CLIENT:ESTABLISHED,{CID}
- >CLIENT:ENV,name1=val1
- >CLIENT:ENV,name2=val2
- >CLIENT:ENV,...
- >CLIENT:ENV,END
-
-(3) Notify existing client disconnection. The environmental variables passed
- are equivalent to those that would be passed to a --client-disconnect
- script.
-
- >CLIENT:DISCONNECT,{CID}
- >CLIENT:ENV,name1=val1
- >CLIENT:ENV,name2=val2
- >CLIENT:ENV,...
- >CLIENT:ENV,END
-
-(4) Notify that a particular virtual address or subnet
- is now associated with a specific client.
-
- >CLIENT:ADDRESS,{CID},{ADDR},{PRI}
-
-Variables:
-
-CID -- Client ID, numerical ID for each connecting client, sequence = 0,1,2,...
-KID -- Key ID, numerical ID for the key associated with a given client TLS session,
- sequence = 0,1,2,...
-PRI -- Primary (1) or Secondary (0) VPN address/subnet. All clients have at least
- one primary IP address. Secondary address/subnets are associated with
- client-specific "iroute" directives.
-ADDR -- IPv4 address/subnet in the form 1.2.3.4 or 1.2.3.0/255.255.255.0
-
-In the unlikely scenario of an extremely long-running OpenVPN server,
-CID and KID should be assumed to recycle to 0 after (2^32)-1, however this
-recycling behavior is guaranteed to be collision-free.
-
-Command Parsing
----------------
-
-The management interface uses the same command line lexical analyzer
-as is used by the OpenVPN config file parser.
-
-Whitespace is a parameter separator.
-
-Double quotation or single quotation characters ("", '') can be used
-to enclose parameters containing whitespace.
-
-Backslash-based shell escaping is performed, using the following
-mappings, when not in single quotations:
-
-\\ Maps to a single backslash character (\).
-\" Pass a literal doublequote character ("), don't
- interpret it as enclosing a parameter.
-\[SPACE] Pass a literal space or tab character, don't
- interpret it as a parameter delimiter.
-
-Challenge/Response Protocol
----------------------------
-
-The OpenVPN Challenge/Response Protocol allows an OpenVPN server to
-generate challenge questions that are shown to the user, and to see
-the user's responses to those challenges. Based on the responses, the
-server can allow or deny access.
-
-In this way, the OpenVPN Challenge/Response Protocol can be used
-to implement multi-factor authentication. Two different
-variations on the challenge/response protocol are supported: the
-"Dynamic" and "Static" protocols.
-
-The basic idea of Challenge/Response is that the user must enter an
-additional piece of information, in addition to the username and
-password, to successfully authenticate. Normally, this information
-is used to prove that the user posesses a certain key-like device
-such as cryptographic token or a particular mobile phone.
-
-Dynamic protocol:
-
-The OpenVPN dynamic challenge/response protocol works by returning
-a specially formatted error message after initial successful
-authentication. This error message contains the challenge question,
-and is formatted as such:
-
- CRV1:<flags>:<state_id>:<username_base64>:<challenge_text>
-
-flags: a series of optional, comma-separated flags:
- E : echo the response when the user types it
- R : a response is required
-
-state_id: an opaque string that should be returned to the server
- along with the response.
-
-username_base64 : the username formatted as base64
-
-challenge_text : the challenge text to be shown to the user
-
-Example challenge:
-
- CRV1:R,E:Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l:Y3Ix:Please enter token PIN
-
-After showing the challenge_text and getting a response from the user
-(if R flag is specified), the client should submit the following
-auth creds back to the OpenVPN server:
-
-Username: [username decoded from username_base64]
-Password: CRV1::<state_id>::<response_text>
-
-Where state_id is taken from the challenge request and response_text
-is what the user entered in response to the challenge_text.
-If the R flag is not present, response_text may be the empty
-string.
-
-Example response (suppose the user enters "8675309" for the token PIN):
-
- Username: cr1 ("Y3Ix" base64 decoded)
- Password: CRV1::Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l::8675309
-
-Static protocol:
-
-The static protocol differs from the dynamic protocol in that the
-challenge question and response field is given to the user in the
-initial username/password dialog, and the username, password, and
-response are delivered back to the server in a single transaction.
-
-The "static-challenge" directive is used to give the challenge text
-to OpenVPN and indicate whether or not the response should be echoed.
-
-When the "static-challenge" directive is used, the management
-interface will respond as such when credentials are needed:
-
- >PASSWORD:Need 'Auth' username/password SC:<ECHO>,<TEXT>
-
- ECHO: "1" if response should be echoed, "0" to not echo
- TEXT: challenge text that should be shown to the user to
- facilitate their response
-
-For example:
-
- >PASSWORD:Need 'Auth' username/password SC:1,Please enter token PIN
-
-The above notification indicates that OpenVPN needs a --auth-user-pass
-password plus a response to a static challenge ("Please enter token PIN").
-The "1" after the "SC:" indicates that the response should be echoed.
-
-The management interface client in this case should add the static
-challenge text to the auth dialog followed by a field for the user to
-enter a response. Then the client should pack the password and response
-together into an encoded password:
-
- username "Auth" foo
- password "Auth" "SCRV1:<BASE64_PASSWORD>:<BASE64_RESPONSE>"
-
-For example, if the user entered "bar" as the password and 8675309
-as the PIN, the following management interface commands should be
-issued:
-
- username "Auth" foo
- password "Auth" "SCRV1:Zm9v:ODY3NTMwOQ=="
-
-Client-side support for challenge/response protocol:
-
-Currently, the Access Server client and standalone OpenVPN
-client support both static and dynamic challenge/response
-protocols. However, any OpenVPN client UI that drives OpenVPN
-via the management interface needs to add explicit support
-for the challenge/response protocol.
diff --git a/main/openvpn/doc/openvpn.8 b/main/openvpn/doc/openvpn.8
deleted file mode 100644
index 32cdcb9b..00000000
--- a/main/openvpn/doc/openvpn.8
+++ /dev/null
@@ -1,6709 +0,0 @@
-.\" OpenVPN -- An application to securely tunnel IP networks
-.\" over a single TCP/UDP port, with support for SSL/TLS-based
-.\" session authentication and key exchange,
-.\" packet encryption, packet authentication, and
-.\" packet compression.
-.\"
-.\" Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net>
-.\"
-.\" This program is free software; you can redistribute it and/or modify
-.\" it under the terms of the GNU General Public License version 2
-.\" as published by the Free Software Foundation.
-.\"
-.\" This program is distributed in the hope that it will be useful,
-.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-.\" GNU General Public License for more details.
-.\"
-.\" You should have received a copy of the GNU General Public License
-.\" along with this program (see the file COPYING included with this
-.\" distribution); if not, write to the Free Software Foundation, Inc.,
-.\" 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-.\"
-.\" Manual page for openvpn
-.\
-.\" SH section heading
-.\" SS subsection heading
-.\" LP paragraph
-.\" IP indented paragraph
-.\" TP hanging label
-.\
-.\" .nf -- no formatting
-.\" .fi -- resume formatting
-.\" .ft 3 -- boldface
-.\" .ft -- normal face
-.\" .in +|-{n} -- indent
-.\"
-.TH openvpn 8 "17 November 2008"
-.\"*********************************************************
-.SH NAME
-openvpn \- secure IP tunnel daemon.
-.\"*********************************************************
-.SH SYNOPSIS
-.ft 3
-openvpn [ options ... ]
-.ft
-.\"*********************************************************
-.SH INTRODUCTION
-.LP
-OpenVPN is an open source VPN daemon by James Yonan.
-Because OpenVPN tries to
-be a universal VPN tool offering a great deal of flexibility,
-there are a lot of options on this manual page.
-If you're new to OpenVPN, you might want to skip ahead to the
-examples section where you will see how to construct simple
-VPNs on the command line without even needing a configuration file.
-
-Also note that there's more documentation and examples on
-the OpenVPN web site:
-.I http://openvpn.net/
-
-And if you would like to see a shorter version of this manual,
-see the openvpn usage message which can be obtained by
-running
-.B openvpn
-without any parameters.
-.\"*********************************************************
-.SH DESCRIPTION
-.LP
-OpenVPN is a robust and highly flexible VPN daemon.
-OpenVPN supports SSL/TLS security, ethernet bridging,
-TCP or UDP tunnel transport through proxies or NAT,
-support for dynamic IP addresses and DHCP,
-scalability to hundreds or thousands of users,
-and portability to most major OS platforms.
-
-OpenVPN is tightly bound to the OpenSSL library, and derives much
-of its crypto capabilities from it.
-
-OpenVPN supports
-conventional encryption
-using a pre-shared secret key
-.B (Static Key mode)
-or
-public key security
-.B (SSL/TLS mode)
-using client & server certificates.
-OpenVPN also
-supports non-encrypted TCP/UDP tunnels.
-
-OpenVPN is designed to work with the
-.B TUN/TAP
-virtual networking interface that exists on most platforms.
-
-Overall, OpenVPN aims to offer many of the key features of IPSec but
-with a relatively lightweight footprint.
-.\"*********************************************************
-.SH OPTIONS
-OpenVPN allows any option to be placed either on the command line
-or in a configuration file. Though all command line options are preceded
-by a double-leading-dash ("\-\-"), this prefix can be removed when
-an option is placed in a configuration file.
-.\"*********************************************************
-.TP
-.B \-\-help
-Show options.
-.\"*********************************************************
-.TP
-.B \-\-config file
-Load additional config options from
-.B file
-where each line corresponds to one command line option,
-but with the leading '\-\-' removed.
-
-If
-.B \-\-config file
-is the only option to the openvpn command,
-the
-.B \-\-config
-can be removed, and the command can be given as
-.B openvpn file
-
-Note that
-configuration files can be nested to a reasonable depth.
-
-Double quotation or single quotation characters ("", '')
-can be used to enclose single parameters containing whitespace,
-and "#" or ";" characters in the first column
-can be used to denote comments.
-
-Note that OpenVPN 2.0 and higher performs backslash-based shell
-escaping for characters not in single quotations,
-so the following mappings should be observed:
-
-.nf
-.ft 3
-.in +4
-\\\\ Maps to a single backslash character (\\).
-\\" Pass a literal doublequote character ("), don't
- interpret it as enclosing a parameter.
-\\[SPACE] Pass a literal space or tab character, don't
- interpret it as a parameter delimiter.
-.in -4
-.ft
-.fi
-
-For example on Windows, use double backslashes to
-represent pathnames:
-
-.nf
-.ft 3
-.in +4
-secret "c:\\\\OpenVPN\\\\secret.key"
-.in -4
-.ft
-.fi
-
-For examples of configuration files,
-see
-.I http://openvpn.net/examples.html
-
-Here is an example configuration file:
-
-.nf
-.ft 3
-.in +4
-#
-# Sample OpenVPN configuration file for
-# using a pre-shared static key.
-#
-# '#' or ';' may be used to delimit comments.
-
-# Use a dynamic tun device.
-dev tun
-
-# Our remote peer
-remote mypeer.mydomain
-
-# 10.1.0.1 is our local VPN endpoint
-# 10.1.0.2 is our remote VPN endpoint
-ifconfig 10.1.0.1 10.1.0.2
-
-# Our pre-shared static key
-secret static.key
-.in -4
-.ft
-.fi
-.\"*********************************************************
-.SS Tunnel Options:
-.TP
-.B \-\-mode m
-Set OpenVPN major mode. By default, OpenVPN runs in
-point-to-point mode ("p2p"). OpenVPN 2.0 introduces
-a new mode ("server") which implements a multi-client
-server capability.
-.\"*********************************************************
-.TP
-.B \-\-local host
-Local host name or IP address for bind.
-If specified, OpenVPN will bind to this address only.
-If unspecified, OpenVPN will bind to all interfaces.
-.\"*********************************************************
-.TP
-.B \-\-remote host [port] [proto]
-Remote host name or IP address. On the client, multiple
-.B \-\-remote
-options may be specified for redundancy, each referring
-to a different OpenVPN server. Specifying multiple
-.B \-\-remote
-options for this purpose is a special case of the more
-general connection-profile feature. See the
-.B <connection>
-documentation below.
-
-The OpenVPN client will try to connect to a server at
-.B host:port
-in the order specified by the list of
-.B \-\-remote
-options.
-
-.B proto
-indicates the protocol to use when connecting with the
-remote, and may be "tcp" or "udp".
-
-For forcing IPv4 or IPv6 connection suffix tcp or udp
-with 4/6 like udp4/udp6/tcp4/tcp6.
-
-The client will move on to the next host in the list,
-in the event of connection failure.
-Note that at any given time, the OpenVPN client
-will at most be connected to
-one server.
-
-Note that since UDP is connectionless, connection failure
-is defined by the
-.B \-\-ping
-and
-.B \-\-ping-restart
-options.
-
-Note the following corner case: If you use multiple
-.B \-\-remote
-options, AND you are dropping root privileges on
-the client with
-.B \-\-user
-and/or
-.B \-\-group,
-AND the client is running a non-Windows OS, if the client needs
-to switch to a different server, and that server pushes
-back different TUN/TAP or route settings, the client may lack
-the necessary privileges to close and reopen the TUN/TAP interface.
-This could cause the client to exit with a fatal error.
-
-If
-.B \-\-remote
-is unspecified, OpenVPN will listen
-for packets from any IP address, but will not act on those packets unless
-they pass all authentication tests. This requirement for authentication
-is binding on all potential peers, even those from known and supposedly
-trusted IP addresses (it is very easy to forge a source IP address on
-a UDP packet).
-
-When used in TCP mode,
-.B \-\-remote
-will act as a filter, rejecting connections from any host which does
-not match
-.B host.
-
-If
-.B host
-is a DNS name which resolves to multiple IP addresses,
-one will be randomly
-chosen, providing a sort of basic load-balancing and
-failover capability.
-.\"*********************************************************
-.TP
-.B \-\-remote-random-hostname
-Prepend a random string (6 bytes, 12 hex characters) to hostname to prevent
-DNS caching. For example, "foo.bar.gov" would be modified to
-"<random-chars>.foo.bar.gov".
-.\"*********************************************************
-.TP
-.B <connection>
-Define a client connection
-profile. Client connection profiles are groups of OpenVPN options that
-describe how to connect to a given OpenVPN server. Client connection
-profiles are specified within an OpenVPN configuration file, and
-each profile is bracketed by
-.B <connection>
-and
-.B </connection>.
-
-An OpenVPN client will try each connection profile sequentially
-until it achieves a successful connection.
-
-.B \-\-remote-random
-can be used to initially "scramble" the connection
-list.
-
-Here is an example of connection profile usage:
-
-.nf
-.ft 3
-.in +4
-client
-dev tun
-
-<connection>
-remote 198.19.34.56 1194 udp
-</connection>
-
-<connection>
-remote 198.19.34.56 443 tcp
-</connection>
-
-<connection>
-remote 198.19.34.56 443 tcp
-http-proxy 192.168.0.8 8080
-http-proxy-retry
-</connection>
-
-<connection>
-remote 198.19.36.99 443 tcp
-http-proxy 192.168.0.8 8080
-http-proxy-retry
-</connection>
-
-persist-key
-persist-tun
-pkcs12 client.p12
-ns-cert-type server
-verb 3
-.in -4
-.ft
-.fi
-
-First we try to connect to a server at 198.19.34.56:1194 using UDP.
-If that fails, we then try to connect to 198.19.34.56:443 using TCP.
-If that also fails, then try connecting through an HTTP proxy at
-192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to
-connect through the same proxy to a server at 198.19.36.99:443
-using TCP.
-
-The following OpenVPN options may be used inside of
-a
-.B <connection>
-block:
-
-.B bind,
-.B connect-retry,
-.B connect-retry-max,
-.B connect-timeout,
-.B explicit-exit-notify,
-.B float,
-.B fragment,
-.B http-proxy,
-.B http-proxy-option,
-.B http-proxy-retry,
-.B http-proxy-timeout,
-.B link-mtu,
-.B local,
-.B lport,
-.B mssfix,
-.B mtu-disc,
-.B nobind,
-.B port,
-.B proto,
-.B remote,
-.B rport,
-.B socks-proxy,
-.B socks-proxy-retry,
-.B tun-mtu and
-.B tun-mtu-extra.
-
-A defaulting mechanism exists for specifying options to apply to
-all
-.B <connection>
-profiles. If any of the above options (with the exception of
-.B remote
-) appear outside of a
-.B <connection>
-block, but in a configuration file which has one or more
-.B <connection>
-blocks, the option setting will be used as a default for
-.B <connection>
-blocks which follow it in the configuration file.
-
-For example, suppose the
-.B nobind
-option were placed in the sample configuration file above, near
-the top of the file, before the first
-.B <connection>
-block. The effect would be as if
-.B nobind
-were declared in all
-.B <connection>
-blocks below it.
-.\"*********************************************************
-.TP
-.B \-\-proto-force p
-When iterating through connection profiles,
-only consider profiles using protocol
-.B p
-('tcp'|'udp').
-.\"*********************************************************
-.TP
-.B \-\-remote-random
-When multiple
-.B \-\-remote
-address/ports are specified, or if connection profiles are being
-used, initially randomize the order of the list
-as a kind of basic load-balancing measure.
-.\"*********************************************************
-.TP
-.B \-\-proto p
-Use protocol
-.B p
-for communicating with remote host.
-.B p
-can be
-.B udp,
-.B tcp-client,
-or
-.B tcp-server.
-
-The default protocol is
-.B udp
-when
-.B \-\-proto
-is not specified.
-
-For UDP operation,
-.B \-\-proto udp
-should be specified on both peers.
-
-For TCP operation, one peer must use
-.B \-\-proto tcp-server
-and the other must use
-.B \-\-proto tcp-client.
-A peer started with
-.B tcp-server
-will wait indefinitely for an incoming connection. A peer
-started with
-.B tcp-client
-will attempt to connect, and if that fails, will sleep for 5
-seconds (adjustable via the
-.B \-\-connect-retry
-option) and try again infinite or up to N retries (adjustable via the
-.B \-\-connect-retry-max
-option). Both TCP client and server will simulate
-a SIGUSR1 restart signal if either side resets the connection.
-
-OpenVPN is designed to operate optimally over UDP, but TCP capability is provided
-for situations where UDP cannot be used.
-In comparison with UDP, TCP will usually be
-somewhat less efficient and less robust when used over unreliable or congested
-networks.
-
-This article outlines some of problems with tunneling IP over TCP:
-
-.I http://sites.inka.de/sites/bigred/devel/tcp-tcp.html
-
-There are certain cases, however, where using TCP may be advantageous from
-a security and robustness perspective, such as tunneling non-IP or
-application-level UDP protocols, or tunneling protocols which don't
-possess a built-in reliability layer.
-.\"*********************************************************
-.TP
-.B \-\-connect-retry n
-Wait
-.B n
-seconds between connection attempts (default=5).
-.\"*********************************************************
-.TP
-.B \-\-connect-timeout n
-For
-.B \-\-proto tcp-client,
-set connection timeout to
-.B n
-seconds (default=10).
-.\"*********************************************************
-.TP
-.B \-\-connect-retry-max n
-.B n
-specifies the number of times all
-.B \-\-remote
-respectively
-.B <connection>
-statements are tried. Specifiying
-.B n
-as one would try each entry exactly once. A sucessful connection
-resets the counter. (default=umlimited).
-.\"*********************************************************
-.TP
-.B \-\-show-proxy-settings
-Show sensed HTTP or SOCKS proxy settings. Currently, only Windows clients
-support this option.
-.\"*********************************************************
-.TP
-.B \-\-http-proxy server port [authfile|'auto'|'auto-nct'] [auth-method]
-Connect to remote host through an HTTP proxy at address
-.B server
-and port
-.B port.
-If HTTP Proxy-Authenticate is required,
-.B authfile
-is a file containing a username and password on 2 lines, or
-"stdin" to prompt from console.
-
-.B auth-method
-should be one of "none", "basic", or "ntlm".
-
-HTTP Digest authentication is supported as well, but only via
-the
-.B auto
-or
-.B auto-nct
-flags (below).
-
-The
-.B auto
-flag causes OpenVPN to automatically determine the
-.B auth-method
-and query stdin or the management interface for
-username/password credentials, if required. This flag
-exists on OpenVPN 2.1 or higher.
-
-The
-.B auto-nct
-flag (no clear-text auth) instructs OpenVPN to automatically
-determine the authentication method, but to reject weak
-authentication protocols such as HTTP Basic Authentication.
-.\"*********************************************************
-.TP
-.B \-\-http-proxy-retry
-Retry indefinitely on HTTP proxy errors. If an HTTP proxy error
-occurs, simulate a SIGUSR1 reset.
-.\"*********************************************************
-.TP
-.B \-\-http-proxy-timeout n
-Set proxy timeout to
-.B n
-seconds, default=5.
-.\"*********************************************************
-.TP
-.B \-\-http-proxy-option type [parm]
-Set extended HTTP proxy options.
-Repeat to set multiple options.
-
-.B VERSION version \-\-
-Set HTTP version number to
-.B version
-(default=1.0).
-
-.B AGENT user-agent \-\-
-Set HTTP "User-Agent" string to
-.B user-agent.
-
-.B CUSTOM\-HEADER name content \-\-
-Adds the custom Header with
-.B name
-as name and
-.B content
-as the content of the custom HTTP header.
-.\"*********************************************************
-.TP
-.B \-\-socks-proxy server [port] [authfile]
-Connect to remote host through a Socks5 proxy at address
-.B server
-and port
-.B port
-(default=1080).
-.B authfile
-(optional) is a file containing a username and password on 2 lines, or
-"stdin" to prompt from console.
-.\"*********************************************************
-.TP
-.B \-\-socks-proxy-retry
-Retry indefinitely on Socks proxy errors. If a Socks proxy error
-occurs, simulate a SIGUSR1 reset.
-.\"*********************************************************
-.TP
-.B \-\-resolv-retry n
-If hostname resolve fails for
-.B \-\-remote,
-retry resolve for
-.B n
-seconds before failing.
-
-Set
-.B n
-to "infinite" to retry indefinitely.
-
-By default,
-.B \-\-resolv-retry infinite
-is enabled. You can disable by setting n=0.
-.\"*********************************************************
-.TP
-.B \-\-float
-Allow remote peer to change its IP address and/or port number, such as due to
-DHCP (this is the default if
-.B \-\-remote
-is not used).
-.B \-\-float
-when specified with
-.B \-\-remote
-allows an OpenVPN session to initially connect to a peer
-at a known address, however if packets arrive from a new
-address and pass all authentication tests, the new address
-will take control of the session. This is useful when
-you are connecting to a peer which holds a dynamic address
-such as a dial-in user or DHCP client.
-
-Essentially,
-.B \-\-float
-tells OpenVPN to accept authenticated packets
-from any address, not only the address which was specified in the
-.B \-\-remote
-option.
-.\"*********************************************************
-.TP
-.B \-\-ipchange cmd
-Run command
-.B cmd
-when our remote ip-address is initially authenticated or
-changes.
-
-.B cmd
-consists of a path to script (or executable program), optionally
-followed by arguments. The path and arguments may be single- or double-quoted
-and/or escaped using a backslash, and should be separated by one or more spaces.
-
-When
-.B cmd
-is executed two arguments are appended after any arguments specified in
-.B cmd
-, as follows:
-
-.B cmd ip_address port_number
-
-Don't use
-.B \-\-ipchange
-in
-.B \-\-mode server
-mode. Use a
-.B \-\-client-connect
-script instead.
-
-See the "Environmental Variables" section below for
-additional parameters passed as environmental variables.
-
-If you are running in a dynamic IP address environment where
-the IP addresses of either peer could change without notice,
-you can use this script, for example, to edit the
-.I /etc/hosts
-file with the current address of the peer. The script will
-be run every time the remote peer changes its IP address.
-
-Similarly if
-.I our
-IP address changes due to DHCP, we should configure
-our IP address change script (see man page for
-.BR dhcpcd (8)
-) to deliver a
-.B SIGHUP
-or
-.B SIGUSR1
-signal to OpenVPN. OpenVPN will then
-reestablish a connection with its most recently authenticated
-peer on its new IP address.
-.\"*********************************************************
-.TP
-.B \-\-port port
-TCP/UDP port number or port name for both local and remote. The current
-default of 1194 represents the official IANA port number
-assignment for OpenVPN and has been used since version 2.0-beta17.
-Previous versions used port 5000 as the default.
-.\"*********************************************************
-.TP
-.B \-\-lport port
-TCP/UDP port number or name for bind.
-.\"*********************************************************
-.TP
-.B \-\-rport port
-TCP/UDP port number or name for remote.
-.\"*********************************************************
-.TP
-.B \-\-bind [ipv6only]
-Bind to local address and port. This is the default unless any of
-.B \-\-proto tcp-client
-,
-.B \-\-http-proxy
-or
-.B \-\-socks-proxy
-are used.
-
-If the
-.B ipv6only
-keyword is present OpenVPN will bind only to IPv6 (as oposed
-to IPv6 and IPv4) when a IPv6 socket is opened.
-
-.\"*********************************************************
-.TP
-.B \-\-nobind
-Do not bind to local address and port. The IP stack will allocate
-a dynamic port for returning packets. Since the value of the dynamic port
-could not be known in advance by a peer, this option is only suitable for
-peers which will be initiating connections by using the
-.B \-\-remote
-option.
-.\"*********************************************************
-.TP
-.B \-\-dev tunX | tapX | null
-TUN/TAP virtual network device (
-.B 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.
-
-.B tun
-devices encapsulate IPv4 or IPv6 (OSI Layer 3) while
-.B tap
-devices encapsulate Ethernet 802.3 (OSI Layer 2).
-.\"*********************************************************
-.TP
-.B \-\-dev-type device-type
-Which device type are we using?
-.B device-type
-should be
-.B tun
-(OSI Layer 3)
-or
-.B tap
-(OSI Layer 2).
-Use this option only if the TUN/TAP device used with
-.B \-\-dev
-does not begin with
-.B tun
-or
-.B tap.
-.\"*********************************************************
-.TP
-.B \-\-topology mode
-Configure virtual addressing topology when running in
-.B \-\-dev tun
-mode. This directive has no meaning in
-.B \-\-dev tap
-mode, which always uses a
-.B subnet
-topology.
-
-If you set this directive on the server, the
-.B \-\-server
-and
-.B \-\-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
-.B \-\-dev
-directive, this directive must always be compatible between client and server.
-
-.B mode
-can be one of:
-
-.B 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.
-
-.B 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. This mode
-is functionally equivalent to the
-.B \-\-ifconfig-pool-linear
-directive which is available in OpenVPN 2.0 and is now deprecated.
-
-.B 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
-.B \-\-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
-.B \-\-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
-.BR ifconfig (8)
-command which sets a subnet instead of a remote endpoint IP address.
-
-This option exists in OpenVPN 2.1 or higher.
-.\"*********************************************************
-.TP
-.B \-\-tun-ipv6
-Build a tun link capable of forwarding IPv6 traffic.
-Should be used in conjunction with
-.B \-\-dev tun
-or
-.B \-\-dev tunX.
-A warning will be displayed
-if no specific IPv6 TUN support for your OS has been compiled into OpenVPN.
-
-See below for further IPv6-related configuration options.
-.\"*********************************************************
-.TP
-.B \-\-dev-node node
-Explicitly set the device node rather than using
-/dev/net/tun, /dev/tun, /dev/tap, etc. If OpenVPN
-cannot figure out whether
-.B node
-is a TUN or TAP device based on the name, you should
-also specify
-.B \-\-dev-type tun
-or
-.B \-\-dev-type tap.
-
-Under Mac OS X this option can be used to specify the default tun
-implementation. Using
-.B \-\-dev\-node utun
-forces usage of the native Darwin tun kernel support. Use
-.B \-\-dev\-node utunN
-to select a specific utun instance. To force using the tun.kext (/dev/tunX) use
-.B \-\-dev\-node tun\fR.
-When not specifying a
-.B \-\-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
-.B node
-in the Network Connections Control Panel or the
-raw GUID of the adapter enclosed by braces.
-The
-.B \-\-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.
-.TP
-.B \-\-lladdr address
-Specify the link layer address, more commonly known as the MAC address.
-Only applied to TAP devices.
-.\"*********************************************************
-.TP
-.B \-\-iproute cmd
-Set alternate command to execute instead of default iproute2 command.
-May be used in order to execute OpenVPN in unprivileged environment.
-.\"*********************************************************
-.TP
-.B \-\-ifconfig l rn
-Set TUN/TAP adapter parameters.
-.B l
-is the IP address of the local VPN endpoint.
-For TUN devices,
-.B rn
-is the IP address of the remote VPN endpoint.
-For TAP devices,
-.B rn
-is the subnet mask of the virtual ethernet segment
-which is being created or connected to.
-
-For TUN devices, which facilitate virtual
-point-to-point IP connections,
-the proper usage of
-.B \-\-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
-.B rn,
-you will be pinging across the VPN.
-
-For TAP devices, which provide
-the ability to create virtual
-ethernet segments,
-.B \-\-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
-.BR ifconfig (8)
-command, is designed to simplify TUN/TAP
-tunnel configuration by providing a
-standard interface to the different
-ifconfig implementations on different
-platforms.
-
-.B \-\-ifconfig
-parameters which are IP addresses can
-also be specified as a DNS or /etc/hosts
-file resolvable name.
-
-For TAP devices,
-.B \-\-ifconfig
-should not be used if the TAP interface will be
-getting an IP address lease from a DHCP
-server.
-.\"*********************************************************
-.TP
-.B \-\-ifconfig-noexec
-Don't actually execute ifconfig/netsh commands, instead
-pass
-.B \-\-ifconfig
-parameters to scripts using environmental variables.
-.\"*********************************************************
-.TP
-.B \-\-ifconfig-nowarn
-Don't output an options consistency check warning
-if the
-.B \-\-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
-.B \-\-disable-occ
-option) while only disabling the ifconfig component of
-the check.
-
-For example,
-if you have a configuration where the local host uses
-.B \-\-ifconfig
-but the remote host does not, use
-.B \-\-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.
-.\"*********************************************************
-.TP
-.B \-\-route network/IP [netmask] [gateway] [metric]
-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.
-
-This option is intended as
-a convenience proxy for the
-.BR route (8)
-shell command,
-while at the same time providing portable semantics
-across OpenVPN's platform space.
-
-.B netmask
-default \-\- 255.255.255.255
-
-.B gateway
-default \-\- taken from
-.B \-\-route-gateway
-or the second parameter to
-.B \-\-ifconfig
-when
-.B \-\-dev tun
-is specified.
-
-.B metric
-default \-\- taken from
-.B \-\-route-metric
-otherwise 0.
-
-The default can be specified by leaving an option blank or setting
-it to "default".
-
-The
-.B network
-and
-.B gateway
-parameters can
-also be specified as a DNS or /etc/hosts
-file resolvable name, or as one of three special keywords:
-
-.B vpn_gateway
-\-\- The remote VPN endpoint address
-(derived either from
-.B \-\-route-gateway
-or the second parameter to
-.B \-\-ifconfig
-when
-.B \-\-dev tun
-is specified).
-
-.B net_gateway
-\-\- The pre-existing IP default gateway, read from the routing
-table (not supported on all OSes).
-
-.B remote_host
-\-\- The
-.B \-\-remote
-address if OpenVPN is being run in client mode, and is undefined in server mode.
-.\"*********************************************************
-.TP
-.B \-\-route-gateway gw|'dhcp'
-Specify a default gateway
-.B gw
-for use with
-.B \-\-route.
-
-If
-.B dhcp
-is specified as the parameter,
-the gateway address will be extracted from a DHCP
-negotiation with the OpenVPN server-side LAN.
-.\"*********************************************************
-.TP
-.B \-\-route-metric m
-Specify a default metric
-.B m
-for use with
-.B \-\-route.
-.\"*********************************************************
-.TP
-.B \-\-route-delay [n] [w]
-Delay
-.B n
-seconds (default=0) after connection
-establishment, before adding routes. If
-.B n
-is 0, routes will be added immediately upon connection
-establishment. If
-.B \-\-route-delay
-is omitted, routes will be added immediately after TUN/TAP device
-open and
-.B \-\-up
-script execution, before any
-.B \-\-user
-or
-.B \-\-group
-privilege downgrade (or
-.B \-\-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,
-.B \-\-route-delay
-tries to be more intelligent by waiting
-.B w
-seconds (w=30 by default)
-for the TAP-Win32 adapter to come up before adding routes.
-.\"*********************************************************
-.TP
-.B \-\-route-up cmd
-Run command
-.B cmd
-after routes are added, subject to
-.B \-\-route-delay.
-
-.B cmd
-consists of a path to script (or executable program), optionally
-followed by arguments. The path and arguments may be single- or double-quoted
-and/or escaped using a backslash, and should be separated by one or more spaces.
-
-See the "Environmental Variables" section below for
-additional parameters passed as environmental variables.
-.\"*********************************************************
-.TP
-.B \-\-route-pre-down cmd
-Run command
-.B cmd
-before routes are removed upon disconnection.
-
-.B cmd
-consists of a path to script (or executable program), optionally
-followed by arguments. The path and arguments may be single- or double-quoted
-and/or escaped using a backslash, and should be separated by one or more spaces.
-
-See the "Environmental Variables" section below for
-additional parameters passed as environmental variables.
-.\"*********************************************************
-.TP
-.B \-\-route-noexec
-Don't add or remove routes automatically. Instead pass routes to
-.B \-\-route-up
-script using environmental variables.
-.\"*********************************************************
-.TP
-.B \-\-route-nopull
-When used with
-.B \-\-client
-or
-.B \-\-pull,
-accept options pushed by server EXCEPT for routes 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.
-.\"*********************************************************
-.TP
-.B \-\-allow-pull-fqdn
-Allow client to pull DNS names from server (rather than being limited
-to IP address) for
-.B \-\-ifconfig,
-.B \-\-route,
-and
-.B \-\-route-gateway.
-.\"*********************************************************
-.TP
-.B \-\-client-nat snat|dnat network netmask alias
-This pushable client option sets up a stateless one-to-one NAT
-rule on packet addresses (not ports), and is useful in cases
-where routes or ifconfig settings pushed to the client would
-create an IP numbering conflict.
-
-.B network/netmask
-(for example 192.168.0.0/255.255.0.0)
-defines the local view of a resource from the client perspective, while
-.B alias/netmask
-(for example 10.64.0.0/255.255.0.0)
-defines the remote view from the server perspective.
-
-Use
-.B snat
-(source NAT) for resources owned by the client and
-.B dnat
-(destination NAT) for remote resources.
-
-Set
-.B \-\-verb 6
-for debugging info showing the transformation of src/dest
-addresses in packets.
-.\"*********************************************************
-.TP
-.B \-\-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:
-
-.B (1)
-Create a static route for the
-.B \-\-remote
-address which forwards to the pre-existing default gateway.
-This is done so that
-.B (3)
-will not create a routing loop.
-
-.B (2)
-Delete the default gateway route.
-
-.B (3)
-Set the new default gateway to be the VPN endpoint address (derived either from
-.B \-\-route-gateway
-or the second parameter to
-.B \-\-ifconfig
-when
-.B \-\-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:
-
-.B local \-\-
-Add the
-.B local
-flag if both OpenVPN servers are directly connected via a common subnet,
-such as with wireless. The
-.B local
-flag will cause step
-.B 1
-above to be omitted.
-
-.B autolocal \-\-
-Try to automatically determine whether to enable
-.B local
-flag above.
-
-.B def1 \-\-
-Use this flag to override
-the default gateway by using 0.0.0.0/1 and 128.0.0.0/1
-rather than 0.0.0.0/0. This has the benefit of overriding
-but not wiping out the original default gateway.
-
-.B 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).
-
-.B 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).
-
-.B 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.
-.\"*********************************************************
-.TP
-.B \-\-link-mtu n
-Sets an upper bound on the size of UDP packets which are sent
-between OpenVPN peers. It's best not to set this parameter unless
-you know what you're doing.
-.\"*********************************************************
-.\"*********************************************************
-.TP
-.B \-\-redirect-private [flags]
-Like \-\-redirect-gateway, but omit actually changing the default
-gateway. Useful when pushing private subnets.
-.\"*********************************************************
-.TP
-.B \-\-tun-mtu n
-Take the TUN device MTU to be
-.B n
-and derive the link MTU
-from it (default=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 or 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
-.B \-\-fragment
-and/or
-.B \-\-mssfix
-options to deal with MTU sizing issues.
-.\"*********************************************************
-.TP
-.B \-\-tun-mtu-extra n
-Assume that the TUN/TAP device might return as many as
-.B n
-bytes more than the
-.B \-\-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.
-.\"*********************************************************
-.TP
-.B \-\-mtu-disc type
-Should we do Path MTU discovery on TCP/UDP channel? Only supported on OSes such
-as Linux that supports the necessary system call to set.
-
-.B 'no'
-\-\- Never send DF (Don't Fragment) frames
-.br
-.B 'maybe'
-\-\- Use per-route hints
-.br
-.B 'yes'
-\-\- Always DF (Don't Fragment)
-.br
-.\"*********************************************************
-.TP
-.B \-\-mtu-test
-To empirically measure MTU on connection startup,
-add the
-.B \-\-mtu-test
-option to your configuration.
-OpenVPN will send ping packets of various sizes
-to the remote peer and measure the largest packets
-which were successfully received. The
-.B \-\-mtu-test
-process normally takes about 3 minutes to complete.
-.\"*********************************************************
-.TP
-.B \-\-fragment max
-Enable internal datagram fragmentation so
-that no UDP datagrams are sent which
-are larger than
-.B max
-bytes.
-
-The
-.B max
-parameter is interpreted in the same way as the
-.B \-\-link-mtu
-parameter, i.e. the UDP packet size after encapsulation
-overhead has been added in, but not including
-the UDP header itself.
-
-The
-.B \-\-fragment
-option only makes sense when you are using the UDP protocol (
-.B \-\-proto udp
-).
-
-.B \-\-fragment
-adds 4 bytes of overhead per datagram.
-
-See the
-.B \-\-mssfix
-option below for an important related option to
-.B \-\-fragment.
-
-It should also be noted that this option is not meant to replace
-UDP fragmentation at the IP stack level. It is only meant as a
-last resort when path MTU discovery is broken. Using this option
-is less efficient than fixing path MTU discovery for your IP link and
-using native IP fragmentation instead.
-
-Having said that, there are circumstances where using OpenVPN's
-internal fragmentation capability may be your only option, such
-as tunneling a UDP multicast stream which requires fragmentation.
-.\"*********************************************************
-.TP
-.B \-\-mssfix max
-Announce to TCP sessions running over the tunnel that they should limit
-their send packet sizes such that after OpenVPN has encapsulated them,
-the resulting UDP packet size that OpenVPN sends to its peer will not
-exceed
-.B max
-bytes. The default value is
-.B 1450.
-
-The
-.B max
-parameter is interpreted in the same way as the
-.B \-\-link-mtu
-parameter, i.e. the UDP packet size after encapsulation
-overhead has been added in, but not including
-the UDP header itself.
-
-The
-.B \-\-mssfix
-option only makes sense when you are using the UDP protocol
-for OpenVPN peer-to-peer communication, i.e.
-.B \-\-proto udp.
-
-.B \-\-mssfix
-and
-.B \-\-fragment
-can be ideally used together, where
-.B \-\-mssfix
-will try to keep TCP from needing
-packet fragmentation in the first place,
-and if big packets come through anyhow
-(from protocols other than TCP),
-.B \-\-fragment
-will internally fragment them.
-
-Both
-.B \-\-fragment
-and
-.B \-\-mssfix
-are designed to work around cases where Path MTU discovery
-is broken on the network path between OpenVPN peers.
-
-The usual symptom of such a breakdown is an OpenVPN
-connection which successfully starts, but then stalls
-during active usage.
-
-If
-.B \-\-fragment
-and
-.B \-\-mssfix
-are used together,
-.B \-\-mssfix
-will take its default
-.B max
-parameter from the
-.B \-\-fragment max
-option.
-
-Therefore, one could lower the maximum UDP packet size
-to 1300 (a good first try for solving MTU-related
-connection problems) with the following options:
-
-.B \-\-tun-mtu 1500 \-\-fragment 1300 \-\-mssfix
-.\"*********************************************************
-.TP
-.B \-\-sndbuf size
-Set the TCP/UDP socket send buffer size.
-Currently defaults to 65536 bytes.
-.\"*********************************************************
-.TP
-.B \-\-rcvbuf size
-Set the TCP/UDP socket receive buffer size.
-Currently defaults to 65536 bytes.
-.\"*********************************************************
-.TP
-.B \-\-mark value
-Mark encrypted packets being sent with value. The mark value can be
-matched in policy routing and packetfilter rules. This option is
-only supported in Linux and does nothing on other operating systems.
-.\"*********************************************************
-.TP
-.B \-\-socket-flags flags...
-Apply the given flags to the OpenVPN transport socket.
-Currently, only
-.B TCP_NODELAY
-is supported.
-
-The
-.B TCP_NODELAY
-socket flag is useful in TCP mode, and causes the kernel
-to send tunnel packets immediately over the TCP connection without
-trying to group several smaller packets into a larger packet.
-This can result in a considerably improvement in latency.
-
-This option is pushable from server to client, and should be used
-on both client and server for maximum effect.
-.\"*********************************************************
-.TP
-.B \-\-txqueuelen n
-(Linux only) Set the TX queue length on the TUN/TAP interface.
-Currently defaults to 100.
-.\"*********************************************************
-.TP
-.B \-\-shaper n
-Limit bandwidth of outgoing tunnel data to
-.B n
-bytes per second on the TCP/UDP port.
-Note that this will only work if mode is set to p2p.
-If you want to limit the bandwidth
-in both directions, use this option on both peers.
-
-OpenVPN uses the following algorithm to implement
-traffic shaping: Given a shaper rate of
-.I n
-bytes per second, after a datagram write of
-.I b
-bytes is queued on the TCP/UDP port, wait a minimum of
-.I (b / n)
-seconds before queuing the next write.
-
-It should be noted that OpenVPN supports multiple
-tunnels between the same two peers, allowing you
-to construct full-speed and reduced bandwidth tunnels
-at the same time,
-routing low-priority data such as off-site backups
-over the reduced bandwidth tunnel, and other data
-over the full-speed tunnel.
-
-Also note that for low bandwidth tunnels
-(under 1000 bytes per second), you should probably
-use lower MTU values as well (see above), otherwise
-the packet latency will grow so large as to trigger
-timeouts in the TLS layer and TCP connections running
-over the tunnel.
-
-OpenVPN allows
-.B n
-to be between 100 bytes/sec and 100 Mbytes/sec.
-.\"*********************************************************
-.TP
-.B \-\-inactive n [bytes]
-Causes OpenVPN to exit after
-.B n
-seconds of inactivity on the TUN/TAP device. The time length of
-inactivity is measured since the last incoming or outgoing tunnel
-packet. The default value is 0 seconds, which disables this feature.
-
-If the optional
-.B bytes
-parameter is included,
-exit if less than
-.B bytes
-of combined in/out traffic are produced on the tun/tap device
-in
-.B n
-seconds.
-
-In any case, OpenVPN's internal ping packets (which are just
-keepalives) and TLS control packets are not considered
-"activity", nor are they counted as traffic, as they are used
-internally by OpenVPN and are not an indication of actual user
-activity.
-.\"*********************************************************
-.TP
-.B \-\-ping n
-Ping remote over the TCP/UDP control channel
-if no packets have been sent for at least
-.B n
-seconds (specify
-.B \-\-ping
-on both peers to cause ping packets to be sent in both directions since
-OpenVPN ping packets are not echoed like IP ping packets).
-When used in one of OpenVPN's secure modes (where
-.B \-\-secret, \-\-tls-server,
-or
-.B \-\-tls-client
-is specified), the ping packet
-will be cryptographically secure.
-
-This option has two intended uses:
-
-(1) Compatibility
-with stateful firewalls. The periodic ping will ensure that
-a stateful firewall rule which allows OpenVPN UDP packets to
-pass will not time out.
-
-(2) To provide a basis for the remote to test the existence
-of its peer using the
-.B \-\-ping-exit
-option.
-.\"*********************************************************
-.TP
-.B \-\-ping-exit n
-Causes OpenVPN to exit after
-.B n
-seconds pass without reception of a ping
-or other packet from remote.
-This option can be combined with
-.B \-\-inactive, \-\-ping,
-and
-.B \-\-ping-exit
-to create a two-tiered inactivity disconnect.
-
-For example,
-
-.B openvpn [options...] \-\-inactive 3600 \-\-ping 10 \-\-ping-exit 60
-
-when used on both peers will cause OpenVPN to exit within 60
-seconds if its peer disconnects, but will exit after one
-hour if no actual tunnel data is exchanged.
-.\"*********************************************************
-.TP
-.B \-\-ping-restart n
-Similar to
-.B \-\-ping-exit,
-but trigger a
-.B SIGUSR1
-restart after
-.B n
-seconds pass without reception of a ping
-or other packet from remote.
-
-This option is useful in cases
-where the remote peer has a dynamic IP address and
-a low-TTL DNS name is used to track the IP address using
-a service such as
-.I http://dyndns.org/
-+ a dynamic DNS client such
-as
-.B ddclient.
-
-If the peer cannot be reached, a restart will be triggered, causing
-the hostname used with
-.B \-\-remote
-to be re-resolved (if
-.B \-\-resolv-retry
-is also specified).
-
-In server mode,
-.B \-\-ping-restart, \-\-inactive,
-or any other type of internally generated signal will always be
-applied to
-individual client instance objects, never to whole server itself.
-Note also in server mode that any internally generated signal
-which would normally cause a restart, will cause the deletion
-of the client instance object instead.
-
-In client mode, the
-.B \-\-ping-restart
-parameter is set to 120 seconds by default. This default will
-hold until the client pulls a replacement value from the server, based on
-the
-.B \-\-keepalive
-setting in the server configuration.
-To disable the 120 second default, set
-.B \-\-ping-restart 0
-on the client.
-
-See the signals section below for more information
-on
-.B SIGUSR1.
-
-Note that the behavior of
-.B SIGUSR1
-can be modified by the
-.B \-\-persist-tun, \-\-persist-key, \-\-persist-local-ip,
-and
-.B \-\-persist-remote-ip
-options.
-
-Also note that
-.B \-\-ping-exit
-and
-.B \-\-ping-restart
-are mutually exclusive and cannot be used together.
-.\"*********************************************************
-.TP
-.B \-\-keepalive n m
-A helper directive designed to simplify the expression of
-.B \-\-ping
-and
-.B \-\-ping-restart
-in server mode configurations.
-
-The server timeout is set twice the value of the second argument.
-This ensures that a timeout is detected on client side
-before the server side drops the connection.
-
-For example,
-.B \-\-keepalive 10 60
-expands as follows:
-
-.nf
-.ft 3
-.in +4
- if mode server:
- ping 10
- ping-restart 120
- push "ping 10"
- push "ping-restart 60"
- else
- ping 10
- ping-restart 60
-.in -4
-.ft
-.fi
-.\"*********************************************************
-.TP
-.B \-\-ping-timer-rem
-Run the
-.B \-\-ping-exit
-/
-.B \-\-ping-restart
-timer only if we have a remote address. Use this option if you are
-starting the daemon in listen mode (i.e. without an explicit
-.B \-\-remote
-peer), and you don't want to start clocking timeouts until a remote
-peer connects.
-.\"*********************************************************
-.TP
-.B \-\-persist-tun
-Don't close and reopen TUN/TAP device or run up/down scripts
-across
-.B SIGUSR1
-or
-.B \-\-ping-restart
-restarts.
-
-.B SIGUSR1
-is a restart signal similar to
-.B SIGHUP,
-but which offers finer-grained control over
-reset options.
-.\"*********************************************************
-.TP
-.B \-\-persist-key
-Don't re-read key files across
-.B SIGUSR1
-or
-.B \-\-ping-restart.
-
-This option can be combined with
-.B \-\-user nobody
-to allow restarts triggered by the
-.B SIGUSR1
-signal.
-Normally if you drop root privileges in OpenVPN,
-the daemon cannot be restarted since it will now be unable to re-read protected
-key files.
-
-This option solves the problem by persisting keys across
-.B SIGUSR1
-resets, so they don't need to be re-read.
-.\"*********************************************************
-.TP
-.B \-\-persist-local-ip
-Preserve initially resolved local IP address and port number
-across
-.B SIGUSR1
-or
-.B \-\-ping-restart
-restarts.
-.\"*********************************************************
-.TP
-.B \-\-persist-remote-ip
-Preserve most recently authenticated remote IP address and port number
-across
-.B SIGUSR1
-or
-.B \-\-ping-restart
-restarts.
-.\"*********************************************************
-.TP
-.B \-\-mlock
-Disable paging by calling the POSIX mlockall function.
-Requires that OpenVPN be initially run as root (though
-OpenVPN can subsequently downgrade its UID using the
-.B \-\-user
-option).
-
-Using this option ensures that key material and tunnel
-data are never written to disk due to virtual
-memory paging operations which occur under most
-modern operating systems. It ensures that even if an
-attacker was able to crack the box running OpenVPN, he
-would not be able to scan the system swap file to
-recover previously used
-ephemeral keys, which are used for a period of time
-governed by the
-.B \-\-reneg
-options (see below), then are discarded.
-
-The downside
-of using
-.B \-\-mlock
-is that it will reduce the amount of physical
-memory available to other applications.
-.\"*********************************************************
-.TP
-.B \-\-up cmd
-Run command
-.B cmd
-after successful TUN/TAP device open
-(pre
-.B \-\-user
-UID change).
-
-.B cmd
-consists of a path to script (or executable program), optionally
-followed by arguments. The path and arguments may be single- or double-quoted
-and/or escaped using a backslash, and should be separated by one or more spaces.
-
-The up command is useful for specifying route
-commands which route IP traffic destined for
-private subnets which exist at the other
-end of the VPN connection into the tunnel.
-
-For
-.B \-\-dev tun
-execute as:
-
-.B cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [ init | restart ]
-
-For
-.B \-\-dev tap
-execute as:
-
-.B cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [ init | restart ]
-
-See the "Environmental Variables" section below for
-additional parameters passed as environmental variables.
-
-Note that if
-.B cmd
-includes arguments, all OpenVPN-generated arguments will be appended
-to them to build an argument list with which the executable will be
-called.
-
-Typically,
-.B cmd
-will run a script to add routes to the tunnel.
-
-Normally the up script is called after the TUN/TAP device is opened.
-In this context, the last command line parameter passed to the script
-will be
-.I init.
-If the
-.B \-\-up-restart
-option is also used, the up script will be called for restarts as
-well. A restart is considered to be a partial reinitialization
-of OpenVPN where the TUN/TAP instance is preserved (the
-.B \-\-persist-tun
-option will enable such preservation). A restart
-can be generated by a SIGUSR1 signal, a
-.B \-\-ping-restart
-timeout, or a connection reset when the TCP protocol is enabled
-with the
-.B \-\-proto
-option. If a restart occurs, and
-.B \-\-up-restart
-has been specified, the up script will be called with
-.I restart
-as the last parameter.
-
-The following standalone example shows how the
-.B \-\-up
-script can be called in both an initialization and restart context.
-(NOTE: for security reasons, don't run the following example unless UDP port
-9999 is blocked by your firewall. Also, the example will run indefinitely,
-so you should abort with control-c).
-
-.B openvpn \-\-dev tun \-\-port 9999 \-\-verb 4 \-\-ping-restart 10 \-\-up 'echo up' \-\-down 'echo down' \-\-persist-tun \-\-up-restart
-
-Note that OpenVPN also provides the
-.B \-\-ifconfig
-option to automatically ifconfig the TUN device,
-eliminating the need to define an
-.B \-\-up
-script, unless you also want to configure routes
-in the
-.B \-\-up
-script.
-
-If
-.B \-\-ifconfig
-is also specified, OpenVPN will pass the ifconfig local
-and remote endpoints on the command line to the
-.B \-\-up
-script so that they can be used to configure routes such as:
-
-.B route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
-.\"*********************************************************
-.TP
-.B \-\-up-delay
-Delay TUN/TAP open and possible
-.B \-\-up
-script execution
-until after TCP/UDP connection establishment with peer.
-
-In
-.B \-\-proto udp
-mode, this option normally requires the use of
-.B \-\-ping
-to allow connection initiation to be sensed in the absence
-of tunnel data, since UDP is a "connectionless" protocol.
-
-On Windows, this option will delay the TAP-Win32 media state
-transitioning to "connected" until connection establishment,
-i.e. the receipt of the first authenticated packet from the peer.
-.\"*********************************************************
-.TP
-.B \-\-down cmd
-Run command
-.B cmd
-after TUN/TAP device close
-(post
-.B \-\-user
-UID change and/or
-.B \-\-chroot
-).
-.B cmd
-consists of a path to script (or executable program), optionally
-followed by arguments. The path and arguments may be single- or double-quoted
-and/or escaped using a backslash, and should be separated by one or more spaces.
-
-Called with the same parameters and environmental
-variables as the
-.B \-\-up
-option above.
-
-Note that if you reduce privileges by using
-.B \-\-user
-and/or
-.B \-\-group,
-your
-.B \-\-down
-script will also run at reduced privilege.
-.\"*********************************************************
-.TP
-.B \-\-down-pre
-Call
-.B \-\-down
-cmd/script before, rather than after, TUN/TAP close.
-.\"*********************************************************
-.TP
-.B \-\-up-restart
-Enable the
-.B \-\-up
-and
-.B \-\-down
-scripts to be called for restarts as well as initial program start.
-This option is described more fully above in the
-.B \-\-up
-option documentation.
-.\"*********************************************************
-.TP
-.B \-\-setenv name value
-Set a custom environmental variable
-.B name=value
-to pass to script.
-.\"*********************************************************
-.TP
-.B \-\-setenv FORWARD_COMPATIBLE 1
-Relax config file syntax checking so that unknown directives
-will trigger a warning but not a fatal error,
-on the assumption that a given unknown directive might be valid
-in future OpenVPN versions.
-
-This option should be used with caution, as there are good security
-reasons for having OpenVPN fail if it detects problems in a
-config file. Having said that, there are valid reasons for wanting
-new software features to gracefully degrade when encountered by
-older software versions.
-
-It is also possible to tag a single directive so as not to trigger
-a fatal error if the directive isn't recognized. To do this,
-prepend the following before the directive:
-.B setenv opt
-
-Versions prior to OpenVPN 2.3.3 will always ignore options set with the
-.B setenv opt
-directive.
-
-See also
-.B \-\-ignore-unknown-option
-.\"*********************************************************
-.TP
-.B \-\-setenv-safe name value
-Set a custom environmental variable
-.B OPENVPN_name=value
-to pass to script.
-
-This directive is designed to be pushed by the server to clients,
-and the prepending of "OPENVPN_" to the environmental variable
-is a safety precaution to prevent a LD_PRELOAD style attack
-from a malicious or compromised server.
-.\"*********************************************************
-.TP
-.B \-\-ignore-unknown-option opt1 opt2 opt3 ... optN
-When one of options
-.B opt1 ... optN
-is encountered in the configuration file the configuration
-file parsing does not fail if this OpenVPN version does not
-support the option. Multiple
-.B \-\-ignore-unknown-option
-options can be given to support a larger number of options to ignore.
-
-This option should be used with caution, as there are good security
-reasons for having OpenVPN fail if it detects problems in a
-config file. Having said that, there are valid reasons for wanting
-new software features to gracefully degrade when encountered by
-older software versions.
-
-.B \-\-ignore-unknown-option
-is available since OpenVPN 2.3.3.
-.\"*********************************************************
-.TP
-.B \-\-script-security level
-This directive offers policy-level control over OpenVPN's usage of external programs
-and scripts. Lower
-.B level
-values are more restrictive, higher values are more permissive. Settings for
-.B level:
-
-.B 0 \-\-
-Strictly no calling of external programs.
-.br
-.B 1 \-\-
-(Default) Only call built-in executables such as ifconfig, ip, route, or netsh.
-.br
-.B 2 \-\-
-Allow calling of built-in executables and user-defined scripts.
-.br
-.B 3 \-\-
-Allow passwords to be passed to scripts via environmental variables (potentially unsafe).
-
-OpenVPN releases before v2.3 also supported a
-.B method
-flag which indicated how OpenVPN should call external commands and scripts. This
-could be either
-.B execve
-or
-.B system.
-As of OpenVPN v2.3, this flag is no longer accepted. In most *nix environments the execve()
-approach has been used without any issues.
-
-To run scripts in Windows in earlier OpenVPN
-versions you needed to either add a full path to the script interpreter which can parse the
-script or use the
-.B system
-flag to run these scripts. As of OpenVPN v2.3 it is now a strict requirement to have
-full path to the script interpreter when running non-executables files.
-This is not needed for executable files, such as .exe, .com, .bat or .cmd files. For
-example, if you have a Visual Basic script, you must use this syntax now:
-
-.nf
-.ft 3
-.in +4
-\-\-up 'C:\\\\Windows\\\\System32\\\\wscript.exe C:\\\\Program\\ Files\\\\OpenVPN\\\\config\\\\my-up-script.vbs'
-.in -4
-.ft
-.fi
-
-Please note the single quote marks and the escaping of the backslashes (\\) and
-the space character.
-
-The reason the support for the
-.B system
-flag was removed is due to the security implications with shell expansions
-when executing scripts via the system() call.
-.\"*********************************************************
-.TP
-.B \-\-disable-occ
-Don't output a warning message if option inconsistencies are detected between
-peers. An example of an option inconsistency would be where one peer uses
-.B \-\-dev tun
-while the other peer uses
-.B \-\-dev tap.
-
-Use of this option is discouraged, but is provided as
-a temporary fix in situations where a recent version of OpenVPN must
-connect to an old version.
-.\"*********************************************************
-.TP
-.B \-\-user user
-Change the user ID of the OpenVPN process to
-.B user
-after initialization, dropping privileges in the process.
-This option is useful to protect the system
-in the event that some hostile party was able to gain control of
-an OpenVPN session. Though OpenVPN's security features make
-this unlikely, it is provided as a second line of defense.
-
-By setting
-.B user
-to
-.I nobody
-or somebody similarly unprivileged, the hostile party would be
-limited in what damage they could cause. Of course once
-you take away privileges, you cannot return them
-to an OpenVPN session. This means, for example, that if
-you want to reset an OpenVPN daemon with a
-.B SIGUSR1
-signal
-(for example in response
-to a DHCP reset), you should make use of one or more of the
-.B \-\-persist
-options to ensure that OpenVPN doesn't need to execute any privileged
-operations in order to restart (such as re-reading key files
-or running
-.BR ifconfig
-on the TUN device).
-.\"*********************************************************
-.TP
-.B \-\-group group
-Similar to the
-.B \-\-user
-option,
-this option changes the group ID of the OpenVPN process to
-.B group
-after initialization.
-.\"*********************************************************
-.TP
-.B \-\-cd dir
-Change directory to
-.B dir
-prior to reading any files such as
-configuration files, key files, scripts, etc.
-.B dir
-should be an absolute path, with a leading "/",
-and without any references
-to the current directory such as "." or "..".
-
-This option is useful when you are running
-OpenVPN in
-.B \-\-daemon
-mode, and you want to consolidate all of
-your OpenVPN control files in one location.
-.\"*********************************************************
-.TP
-.B \-\-chroot dir
-Chroot to
-.B dir
-after initialization.
-.B \-\-chroot
-essentially redefines
-.B dir
-as being the top
-level directory tree (/). OpenVPN will therefore
-be unable to access any files outside this tree.
-This can be desirable from a security standpoint.
-
-Since the chroot operation is delayed until after
-initialization, most OpenVPN options that reference
-files will operate in a pre-chroot context.
-
-In many cases, the
-.B dir
-parameter can point to an empty directory, however
-complications can result when scripts or restarts
-are executed after the chroot operation.
-
-Note: if OpenVPN is built using the PolarSSL SSL
-library,
-.B \-\-chroot
-will only work if a /dev/urandom device node is available
-inside the chroot directory
-.B dir.
-This is due to the way PolarSSL works (it wants to open
-/dev/urandom every time randomness is needed, not just once
-at startup) and nothing OpenVPN can influence.
-.\"*********************************************************
-.TP
-.B \-\-setcon context
-Apply SELinux
-.B context
-after initialization. This
-essentially provides the ability to restrict OpenVPN's
-rights to only network I/O operations, thanks to
-SELinux. This goes further than
-.B \-\-user
-and
-.B \-\-chroot
-in that those two, while being great security features,
-unfortunately do not protect against privilege escalation
-by exploitation of a vulnerable system call. You can of
-course combine all three, but please note that since
-setcon requires access to /proc you will have to provide
-it inside the chroot directory (e.g. with mount \-\-bind).
-
-Since the setcon operation is delayed until after
-initialization, OpenVPN can be restricted to just
-network-related system calls, whereas by applying the
-context before startup (such as the OpenVPN one provided
-in the SELinux Reference Policies) you will have to
-allow many things required only during initialization.
-
-Like with chroot, complications can result when scripts
-or restarts are executed after the setcon operation,
-which is why you should really consider using the
-.B \-\-persist-key
-and
-.B \-\-persist-tun
-options.
-.\"*********************************************************
-.TP
-.B \-\-daemon [progname]
-Become a daemon after all initialization functions are completed.
-This option will cause all message and error output to
-be sent to the syslog file (such as /var/log/messages),
-except for the output of scripts and
-ifconfig commands,
-which will go to /dev/null unless otherwise redirected.
-The syslog redirection occurs immediately at the point
-that
-.B \-\-daemon
-is parsed on the command line even though
-the daemonization point occurs later. If one of the
-.B \-\-log
-options is present, it will supercede syslog
-redirection.
-
-The optional
-.B progname
-parameter will cause OpenVPN to report its program name
-to the system logger as
-.B progname.
-This can be useful in linking OpenVPN messages
-in the syslog file with specific tunnels.
-When unspecified,
-.B progname
-defaults to "openvpn".
-
-When OpenVPN is run with the
-.B \-\-daemon
-option, it will try to delay daemonization until the majority of initialization
-functions which are capable of generating fatal errors are complete. This means
-that initialization scripts can test the return status of the
-openvpn command for a fairly reliable indication of whether the command
-has correctly initialized and entered the packet forwarding event loop.
-
-In OpenVPN, the vast majority of errors which occur after initialization are non-fatal.
-.\"*********************************************************
-.TP
-.B \-\-syslog [progname]
-Direct log output to system logger, but do not become a daemon.
-See
-.B \-\-daemon
-directive above for description of
-.B progname
-parameter.
-.TP
-.B \-\-errors-to-stderr
-Output errors to stderr instead of stdout unless log output is redirected by one of the
-.B \-\-log
-options.
-.\"*********************************************************
-.TP
-.B \-\-passtos
-Set the TOS field of the tunnel packet to what the payload's TOS is.
-.\"*********************************************************
-.TP
-.B \-\-inetd [wait|nowait] [progname]
-Use this option when OpenVPN is being run from the inetd or
-.BR xinetd(8)
-server.
-
-The
-.B wait/nowait
-option must match what is specified in the inetd/xinetd
-config file. The
-.B nowait
-mode can only be used with
-.B \-\-proto tcp-server.
-The default is
-.B wait.
-The
-.B nowait
-mode can be used to instantiate the OpenVPN daemon as a classic TCP server,
-where client connection requests are serviced on a single
-port number. For additional information on this kind of configuration,
-see the OpenVPN FAQ:
-.I http://openvpn.net/faq.html#oneport
-
-This option precludes the use of
-.B \-\-daemon, \-\-local,
-or
-.B \-\-remote.
-Note that this option causes message and error output to be handled in the same
-way as the
-.B \-\-daemon
-option. The optional
-.B progname
-parameter is also handled exactly as in
-.B \-\-daemon.
-
-Also note that in
-.B wait
-mode, each OpenVPN tunnel requires a separate TCP/UDP port and
-a separate inetd or xinetd entry. See the OpenVPN 1.x HOWTO for an example
-on using OpenVPN with xinetd:
-.I http://openvpn.net/1xhowto.html
-.\"*********************************************************
-.TP
-.B \-\-log file
-Output logging messages to
-.B file,
-including output to stdout/stderr which
-is generated by called scripts.
-If
-.B file
-already exists it will be truncated.
-This option takes effect
-immediately when it is parsed in the command line
-and will supercede syslog output if
-.B \-\-daemon
-or
-.B \-\-inetd
-is also specified.
-This option is persistent over the entire course of
-an OpenVPN instantiation and will not be reset by SIGHUP,
-SIGUSR1, or
-.B \-\-ping-restart.
-
-Note that on Windows, when OpenVPN is started as a service,
-logging occurs by default without the need to specify
-this option.
-.\"*********************************************************
-.TP
-.B \-\-log-append file
-Append logging messages to
-.B file.
-If
-.B file
-does not exist, it will be created.
-This option behaves exactly like
-.B \-\-log
-except that it appends to rather
-than truncating the log file.
-.\"*********************************************************
-.TP
-.B \-\-suppress-timestamps
-Avoid writing timestamps to log messages, even when they
-otherwise would be prepended. In particular, this applies to
-log messages sent to stdout.
-.\"*********************************************************
-.TP
-.B \-\-machine-readable-output
-Always write timestamps and message flags to log messages, even when they
-otherwise would not be prefixed. In particular, this applies to
-log messages sent to stdout.
-.\"*********************************************************
-.TP
-.B \-\-writepid file
-Write OpenVPN's main process ID to
-.B file.
-.\"*********************************************************
-.TP
-.B \-\-nice n
-Change process priority after initialization
-(
-.B n
-greater than 0 is lower priority,
-.B n
-less than zero is higher priority).
-.\"*********************************************************
-.\".TP
-.\".B \-\-nice-work n
-.\"Change priority of background TLS work thread. The TLS thread
-.\"feature is enabled when OpenVPN is built
-.\"with pthread support, and you are running OpenVPN
-.\"in TLS mode (i.e. with
-.\".B \-\-tls-client
-.\"or
-.\".B \-\-tls-server
-.\"specified).
-.\"
-.\"Using a TLS thread offloads the CPU-intensive process of SSL/TLS-based
-.\"key exchange to a background thread so that it does not become
-.\"a latency bottleneck in the tunnel packet forwarding process.
-.\"
-.\"The parameter
-.\".B n
-.\"is interpreted exactly as with the
-.\".B \-\-nice
-.\"option above, but in relation to the work thread rather
-.\"than the main thread.
-.\"*********************************************************
-.TP
-.B \-\-fast-io
-(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding
-a call to poll/epoll/select prior to the write operation. The purpose
-of such a call would normally be to block until the device
-or socket is ready to accept the write. Such blocking is unnecessary
-on some platforms which don't support write blocking on UDP sockets
-or TUN/TAP devices. In such cases, one can optimize the event loop
-by avoiding the poll/epoll/select call, improving CPU efficiency
-by 5% to 10%.
-
-This option can only be used on non-Windows systems, when
-.B \-\-proto udp
-is specified, and when
-.B \-\-shaper
-is NOT specified.
-.\"*********************************************************
-.TP
-.B \-\-multihome
-Configure a multi-homed UDP server. This option needs to be used when
-a server has more than one IP address (e.g. multiple interfaces, or
-secondary IP addresses), and is not using
-.B \-\-local
-to force binding to one specific address only. This option will
-add some extra lookups to the packet path to ensure that the UDP reply
-packets are always sent from the address that the client is
-talking to. This is not supported on all platforms, and it adds more
-processing, so it's not enabled by default.
-
-Note: this option is only relevant for UDP servers.
-
-Note 2: if you do an IPv6+IPv4 dual-stack bind on a Linux machine with
-multiple IPv4 address, connections to IPv4 addresses will not work
-right on kernels before 3.15, due to missing kernel support for the
-IPv4-mapped case (some distributions have ported this to earlier kernel
-versions, though).
-.\"*********************************************************
-.TP
-.B \-\-echo [parms...]
-Echo
-.B parms
-to log output.
-
-Designed to be used to send messages to a controlling application
-which is receiving the OpenVPN log output.
-.\"*********************************************************
-.TP
-.B \-\-remap-usr1 signal
-Control whether internally or externally
-generated SIGUSR1 signals are remapped to
-SIGHUP (restart without persisting state) or
-SIGTERM (exit).
-
-.B signal
-can be set to "SIGHUP" or "SIGTERM". By default, no remapping
-occurs.
-.\"*********************************************************
-.TP
-.B \-\-verb n
-Set output verbosity to
-.B n
-(default=1). Each level shows all info from the previous levels.
-Level 3 is recommended if you want a good summary
-of what's happening without being swamped by output.
-
-.B 0 \-\-
-No output except fatal errors.
-.br
-.B 1 to 4 \-\-
-Normal usage range.
-.br
-.B 5 \-\-
-Output
-.B R
-and
-.B W
-characters to the console for each packet read and write, uppercase is
-used for TCP/UDP packets and lowercase is used for TUN/TAP packets.
-.br
-.B 6 to 11 \-\-
-Debug info range (see errlevel.h for additional
-information on debug levels).
-.\"*********************************************************
-.TP
-.B \-\-status file [n]
-Write operational status to
-.B file
-every
-.B n
-seconds.
-
-Status can also be written to the syslog by sending a
-.B SIGUSR2
-signal.
-.\"*********************************************************
-.TP
-.B \-\-status-version [n]
-Choose the status file format version number. Currently
-.B n
-can be 1, 2, or 3 and defaults to 1.
-.\"*********************************************************
-.TP
-.B \-\-mute n
-Log at most
-.B n
-consecutive messages in the same category. This is useful to
-limit repetitive logging of similar message types.
-.\"*********************************************************
-.TP
-.B \-\-compress [algorithm]
-Enable a compression algorithm.
-
-The
-.B algorithm
-parameter may be "snappy", "lzo", "lz4", or empty. Snappy, LZO and LZ4
-are different compression algorithms, with Snappy generally
-offering the best performance while LZ4 is faster with less CPU usage.
-For backwards compatibility with OpenVPN versions before 2.4, use "lzo"
-(which is identical to the older option "\-\-comp-lzo yes").
-
-If the
-.B algorithm
-parameter is empty, compression will be turned off, but the packet
-framing for compression will still be enabled, allowing a different
-setting to be pushed later.
-.\"*********************************************************
-.TP
-.B \-\-comp-lzo [mode]
-Use LZO compression \-\- may add up to 1 byte per
-packet for incompressible data.
-.B mode
-may be "yes", "no", or "adaptive" (default).
-
-This option is deprecated in favor of the newer
-.B --compress
-option.
-
-In a server mode setup, it is possible to selectively turn
-compression on or off for individual clients.
-
-First, make sure the client-side config file enables selective
-compression by having at least one
-.B \-\-comp-lzo
-directive, such as
-.B \-\-comp-lzo no.
-This will turn off compression by default,
-but allow a future directive push from the server to
-dynamically change the
-on/off/adaptive setting.
-
-Next in a
-.B \-\-client-config-dir
-file, specify the compression setting for the client,
-for example:
-
-.nf
-.ft 3
-.in +4
-comp-lzo yes
-push "comp-lzo yes"
-.in -4
-.ft
-.fi
-
-The first line sets the
-.B comp-lzo
-setting for the server
-side of the link, the second sets the client side.
-.\"*********************************************************
-.TP
-.B \-\-comp-noadapt
-When used in conjunction with
-.B \-\-comp-lzo,
-this option will disable OpenVPN's adaptive compression algorithm.
-Normally, adaptive compression is enabled with
-.B \-\-comp-lzo.
-
-Adaptive compression tries to optimize the case where you have
-compression enabled, but you are sending predominantly incompressible
-(or pre-compressed) packets over the tunnel, such as an FTP or rsync transfer
-of a large, compressed file. With adaptive compression,
-OpenVPN will periodically sample the compression process to measure its
-efficiency. If the data being sent over the tunnel is already compressed,
-the compression efficiency will be very low, triggering openvpn to disable
-compression for a period of time until the next re-sample test.
-.\"*********************************************************
-.TP
-.B \-\-management IP port [pw-file]
-Enable a TCP server on
-.B IP:port
-to handle daemon management functions.
-.B pw-file,
-if specified,
-is a password file (password on first line)
-or "stdin" to prompt from standard input. The password
-provided will set the password which TCP clients will need
-to provide in order to access management functions.
-
-The management interface can also listen on a unix domain socket,
-for those platforms that support it. To use a unix domain socket, specify
-the unix socket pathname in place of
-.B IP
-and set
-.B port
-to 'unix'. While the default behavior is to create a unix domain socket
-that may be connected to by any process, the
-.B \-\-management-client-user
-and
-.B \-\-management-client-group
-directives can be used to restrict access.
-
-The management interface provides a special mode where the TCP
-management link can operate over the tunnel itself. To enable this mode,
-set
-.B IP
-= "tunnel". Tunnel mode will cause the management interface
-to listen for a TCP connection on the local VPN address of the
-TUN/TAP interface.
-
-While the management port is designed for programmatic control
-of OpenVPN by other applications, it is possible to telnet
-to the port, using a telnet client in "raw" mode. Once connected,
-type "help" for a list of commands.
-
-For detailed documentation on the management interface, see
-the management-notes.txt file in the
-.B management
-folder of
-the OpenVPN source distribution.
-
-It is strongly recommended that
-.B IP
-be set to 127.0.0.1
-(localhost) to restrict accessibility of the management
-server to local clients.
-.TP
-.B \-\-management-client
-Management interface will connect as a TCP/unix domain client to
-.B IP:port
-specified by
-.B \-\-management
-rather than listen as a TCP server or on a unix domain socket.
-
-If the client connection fails to connect or is disconnected,
-a SIGTERM signal will be generated causing OpenVPN to quit.
-.\"*********************************************************
-.TP
-.B \-\-management-query-passwords
-Query management channel for private key password and
-.B \-\-auth-user-pass
-username/password. Only query the management channel
-for inputs which ordinarily would have been queried from the
-console.
-.\"*********************************************************
-.TP
-.B \-\-management-query-proxy
-Query management channel for proxy server information for a specific
-.B \-\-remote
-(client-only).
-.\"*********************************************************
-.TP
-.B \-\-management-query-remote
-Allow management interface to override
-.B \-\-remote
-directives (client-only).
-.\"*********************************************************
-.TP
-.B \-\-management-external-key
-Allows usage for external private key file instead of
-.B \-\-key
-option (client-only).
-.\"*********************************************************
-.TP
-.B \-\-management-forget-disconnect
-Make OpenVPN forget passwords when management session
-disconnects.
-
-This directive does not affect the
-.B \-\-http-proxy
-username/password. It is always cached.
-.\"*********************************************************
-.TP
-.B \-\-management-hold
-Start OpenVPN in a hibernating state, until a client
-of the management interface explicitly starts it
-with the
-.B hold release
-command.
-.\"*********************************************************
-.TP
-.B \-\-management-signal
-Send SIGUSR1 signal to OpenVPN if management session disconnects.
-This is useful when you wish to disconnect an OpenVPN session on
-user logoff. For --management-client this option is not needed since
-a disconnect will always generate a SIGTERM.
-.\"*********************************************************
-.TP
-.B \-\-management-log-cache n
-Cache the most recent
-.B n
-lines of log file history for usage
-by the management channel.
-.\"*********************************************************
-.TP
-.B \-\-management-up-down
-Report tunnel up/down events to management interface.
-.B
-.\"*********************************************************
-.TP
-.B \-\-management-client-auth
-Gives management interface client the responsibility
-to authenticate clients after their client certificate
-has been verified. See management-notes.txt in OpenVPN
-distribution for detailed notes.
-.\"*********************************************************
-.TP
-.B \-\-management-client-pf
-Management interface clients must specify a packet
-filter file for each connecting client. See management-notes.txt
-in OpenVPN distribution for detailed notes.
-.\"*********************************************************
-.TP
-.B \-\-management-client-user u
-When the management interface is listening on a unix domain socket,
-only allow connections from user
-.B u.
-.\"*********************************************************
-.TP
-.B \-\-management-client-group g
-When the management interface is listening on a unix domain socket,
-only allow connections from group
-.B g.
-.\"*********************************************************
-.TP
-.B \-\-plugin module-pathname [init-string]
-Load plug-in module from the file
-.B module-pathname,
-passing
-.B init-string
-as an argument
-to the module initialization function. Multiple
-plugin modules may be loaded into one OpenVPN
-process.
-
-For more information and examples on how to build OpenVPN
-plug-in modules, see the README file in the
-.B plugin
-folder of the OpenVPN source distribution.
-
-If you are using an RPM install of OpenVPN, see
-/usr/share/openvpn/plugin. The documentation is
-in
-.B doc
-and the actual plugin modules are in
-.B lib.
-
-Multiple plugin modules can be cascaded, and modules can be
-used in tandem with scripts. The modules will be called by
-OpenVPN in the order that they are declared in the config
-file. If both a plugin and script are configured for the same
-callback, the script will be called last. If the
-return code of the module/script controls an authentication
-function (such as tls-verify, auth-user-pass-verify, or
-client-connect), then
-every module and script must return success (0) in order for
-the connection to be authenticated.
-.\"*********************************************************
-.SS Server Mode
-Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode
-is supported, and can be enabled with the
-.B \-\-mode server
-option. In server mode, OpenVPN will listen on a single
-port for incoming client connections. All client
-connections will be routed through a single tun or tap
-interface. This mode is designed for scalability and should
-be able to support hundreds or even thousands of clients
-on sufficiently fast hardware. SSL/TLS authentication must
-be used in this mode.
-.\"*********************************************************
-.TP
-.B \-\-server network netmask ['nopool']
-A helper directive designed to simplify the configuration
-of OpenVPN's server mode. This directive will set up an
-OpenVPN server which will allocate addresses to clients
-out of the given network/netmask. The server itself
-will take the ".1" address of the given network
-for use as the server-side endpoint of the local
-TUN/TAP interface.
-
-For example,
-.B \-\-server 10.8.0.0 255.255.255.0
-expands as follows:
-
-.nf
-.ft 3
-.in +4
- mode server
- tls-server
- push "topology [topology]"
-
- if dev tun AND (topology == net30 OR topology == p2p):
- ifconfig 10.8.0.1 10.8.0.2
- if !nopool:
- ifconfig-pool 10.8.0.4 10.8.0.251
- route 10.8.0.0 255.255.255.0
- if client-to-client:
- push "route 10.8.0.0 255.255.255.0"
- else if topology == net30:
- push "route 10.8.0.1"
-
- if dev tap OR (dev tun AND topology == subnet):
- ifconfig 10.8.0.1 255.255.255.0
- if !nopool:
- ifconfig-pool 10.8.0.2 10.8.0.254 255.255.255.0
- push "route-gateway 10.8.0.1"
- if route-gateway unset:
- route-gateway 10.8.0.2
-
-.in -4
-.ft
-.fi
-
-Don't use
-.B \-\-server
-if you are ethernet bridging. Use
-.B \-\-server-bridge
-instead.
-.\"*********************************************************
-.TP
-.B \-\-server-bridge gateway netmask pool-start-IP pool-end-IP
-.TP
-.B \-\-server-bridge ['nogw']
-
-A helper directive similar to
-.B \-\-server
-which is designed to simplify the configuration
-of OpenVPN's server mode in ethernet bridging configurations.
-
-If
-.B \-\-server-bridge
-is used without any parameters, it will enable a DHCP-proxy
-mode, where connecting OpenVPN clients will receive an IP
-address for their TAP adapter from the DHCP server running
-on the OpenVPN server-side LAN.
-Note that only clients that support
-the binding of a DHCP client with the TAP adapter (such as
-Windows) can support this mode. The optional
-.B nogw
-flag (advanced) indicates that gateway information should not be
-pushed to the client.
-
-To configure ethernet bridging, you
-must first use your OS's bridging capability
-to bridge the TAP interface with the ethernet
-NIC interface. For example, on Linux this is done
-with the
-.B brctl
-tool, and with Windows XP it is done in the Network
-Connections Panel by selecting the ethernet and
-TAP adapters and right-clicking on "Bridge Connections".
-
-Next you you must manually set the
-IP/netmask on the bridge interface. The
-.B gateway
-and
-.B netmask
-parameters to
-.B \-\-server-bridge
-can be set to either the IP/netmask of the
-bridge interface, or the IP/netmask of the
-default gateway/router on the bridged
-subnet.
-
-Finally, set aside a IP range in the bridged
-subnet,
-denoted by
-.B pool-start-IP
-and
-.B pool-end-IP,
-for OpenVPN to allocate to connecting
-clients.
-
-For example,
-.B server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 10.8.0.254
-expands as follows:
-
-.nf
-.ft 3
-.in +4
-mode server
-tls-server
-
-ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0
-push "route-gateway 10.8.0.4"
-.in -4
-.ft
-.fi
-
-In another example,
-.B \-\-server-bridge
-(without parameters) expands as follows:
-
-.nf
-.ft 3
-.in +4
-mode server
-tls-server
-
-push "route-gateway dhcp"
-.in -4
-.ft
-.fi
-
-Or
-.B \-\-server-bridge nogw
-expands as follows:
-
-.nf
-.ft 3
-.in +4
-mode server
-tls-server
-.in -4
-.ft
-.fi
-.\"*********************************************************
-.TP
-.B \-\-push "option"
-Push a config file option back to the client for remote
-execution. Note that
-.B
-option
-must be enclosed in double quotes (""). The client must specify
-.B \-\-pull
-in its config file. The set of options which can be
-pushed is limited by both feasibility and security.
-Some options such as those which would execute scripts
-are banned, since they would effectively allow a compromised
-server to execute arbitrary code on the client.
-Other options such as TLS or MTU parameters
-cannot be pushed because the client needs to know
-them before the connection to the server can be initiated.
-
-This is a partial list of options which can currently be pushed:
-.B \-\-route, \-\-route-gateway, \-\-route-delay, \-\-redirect-gateway,
-.B \-\-ip-win32, \-\-dhcp-option,
-.B \-\-inactive, \-\-ping, \-\-ping-exit, \-\-ping-restart,
-.B \-\-setenv,
-.B \-\-persist-key, \-\-persist-tun, \-\-echo,
-.B \-\-comp-lzo,
-.B \-\-socket-flags,
-.B \-\-sndbuf, \-\-rcvbuf
-.\"*********************************************************
-.TP
-.B \-\-push-reset
-Don't inherit the global push list for a specific client instance.
-Specify this option in a client-specific context such
-as with a
-.B \-\-client-config-dir
-configuration file. This option will ignore
-.B \-\-push
-options at the global config file level.
-.TP
-.B \-\-push-peer-info
-Push additional information about the client to server. The additional information
-consists of the following data:
-
-IV_VER=<version> -- the client OpenVPN version
-
-IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win] -- the client OS platform
-
-IV_HWADDR=<mac address> -- the MAC address of clients default gateway
-
-IV_LZO_STUB=1 -- if client was built with LZO stub capability
-
-UV_<name>=<value> -- client environment variables whose names start with "UV_"
-.\"*********************************************************
-.TP
-.B \-\-disable
-Disable a particular client (based on the common name)
-from connecting. Don't use this option to disable a client
-due to key or password compromise. Use a CRL (certificate
-revocation list) instead (see the
-.B \-\-crl-verify
-option).
-
-This option must be associated with a specific client instance,
-which means that it must be specified either in a client
-instance config file using
-.B \-\-client-config-dir
-or dynamically generated using a
-.B \-\-client-connect
-script.
-.\"*********************************************************
-.TP
-.B \-\-ifconfig-pool start-IP end-IP [netmask]
-Set aside a pool of subnets to be
-dynamically allocated to connecting clients, similar
-to a DHCP server. For tun-style
-tunnels, each client will be given a /30 subnet (for
-interoperability with Windows clients). For tap-style
-tunnels, individual addresses will be allocated, and the
-optional
-.B netmask
-parameter will also be pushed to clients.
-
-.\"*********************************************************
-.TP
-.B \-\-ifconfig-pool-persist file [seconds]
-Persist/unpersist ifconfig-pool
-data to
-.B file,
-at
-.B seconds
-intervals (default=600), as well as on program startup and
-shutdown.
-
-The goal of this option is to provide a long-term association
-between clients (denoted by their common name) and the virtual
-IP address assigned to them from the ifconfig-pool.
-Maintaining a long-term
-association is good for clients because it allows them
-to effectively use the
-.B \-\-persist-tun
-option.
-
-.B file
-is a comma-delimited ASCII file, formatted as
-<Common-Name>,<IP-address>.
-
-If
-.B seconds
-= 0,
-.B file
-will be treated as read-only. This is useful if
-you would like to treat
-.B file
-as a configuration file.
-
-Note that the entries in this file are treated by OpenVPN as
-suggestions only, based on past associations between
-a common name and IP address. They do not guarantee that the given common
-name will always receive the given IP address. If you want guaranteed
-assignment, use
-.B \-\-ifconfig-push
-.\"*********************************************************
-.TP
-.B \-\-ifconfig-pool-linear
-Modifies the
-.B \-\-ifconfig-pool
-directive to
-allocate individual TUN interface addresses for
-clients rather than /30 subnets. NOTE: This option
-is incompatible with Windows clients.
-
-This option is deprecated, and should be replaced with
-.B \-\-topology p2p
-which is functionally equivalent.
-.\"*********************************************************
-.TP
-.B \-\-ifconfig-push local remote-netmask [alias]
-Push virtual IP endpoints for client tunnel,
-overriding the \-\-ifconfig-pool dynamic allocation.
-
-The parameters
-.B local
-and
-.B remote-netmask
-are set according to the
-.B \-\-ifconfig
-directive which you want to execute on the client machine to
-configure the remote end of the tunnel. Note that the parameters
-.B local
-and
-.B remote-netmask
-are from the perspective of the client, not the server. They may be
-DNS names rather than IP addresses, in which case they will be resolved
-on the server at the time of client connection.
-
-The optional
-.B alias
-parameter may be used in cases where NAT causes the client view
-of its local endpoint to differ from the server view. In this case
-.B local/remote-netmask
-will refer to the server view while
-.B alias/remote-netmask
-will refer to the client view.
-
-This option must be associated with a specific client instance,
-which means that it must be specified either in a client
-instance config file using
-.B \-\-client-config-dir
-or dynamically generated using a
-.B \-\-client-connect
-script.
-
-Remember also to include a
-.B \-\-route
-directive in the main OpenVPN config file which encloses
-.B local,
-so that the kernel will know to route it
-to the server's TUN/TAP interface.
-
-OpenVPN's internal client IP address selection algorithm works as
-follows:
-
-.B 1
-\-\- Use
-.B \-\-client-connect script
-generated file for static IP (first choice).
-.br
-.B 2
-\-\- Use
-.B \-\-client-config-dir
-file for static IP (next choice).
-.br
-.B 3
-\-\- Use
-.B \-\-ifconfig-pool
-allocation for dynamic IP (last choice).
-.br
-.\"*********************************************************
-.TP
-.B \-\-iroute network [netmask]
-Generate an internal route to a specific
-client. The
-.B netmask
-parameter, if omitted, defaults to 255.255.255.255.
-
-This directive can be used to route a fixed subnet from
-the server to a particular client, regardless
-of where the client is connecting from. Remember
-that you must also add the route to the system
-routing table as well (such as by using the
-.B \-\-route
-directive). The reason why two routes are needed
-is that the
-.B \-\-route
-directive routes the packet from the kernel
-to OpenVPN. Once in OpenVPN, the
-.B \-\-iroute
-directive routes to the specific client.
-
-This option must be specified either in a client
-instance config file using
-.B \-\-client-config-dir
-or dynamically generated using a
-.B \-\-client-connect
-script.
-
-The
-.B \-\-iroute
-directive also has an important interaction with
-.B \-\-push
-"route ...".
-.B \-\-iroute
-essentially defines a subnet which is owned by a
-particular client (we will call this client A).
-If you would like other clients to be able to reach A's
-subnet, you can use
-.B \-\-push
-"route ..."
-together with
-.B \-\-client-to-client
-to effect this. In order for all clients to see
-A's subnet, OpenVPN must push this route to all clients
-EXCEPT for A, since the subnet is already owned by A.
-OpenVPN accomplishes this by not
-not pushing a route to a client
-if it matches one of the client's iroutes.
-.\"*********************************************************
-.TP
-.B \-\-client-to-client
-Because the OpenVPN server mode handles multiple clients
-through a single tun or tap interface, it is effectively
-a router. The
-.B \-\-client-to-client
-flag tells OpenVPN to internally route client-to-client
-traffic rather than pushing all client-originating traffic
-to the TUN/TAP interface.
-
-When this option is used, each client will "see" the other
-clients which are currently connected. Otherwise, each
-client will only see the server. Don't use this option
-if you want to firewall tunnel traffic using
-custom, per-client rules.
-.\"*********************************************************
-.TP
-.B \-\-duplicate-cn
-Allow multiple clients with the same common name to concurrently connect.
-In the absence of this option, OpenVPN will disconnect a client instance
-upon connection of a new client having the same common name.
-.\"*********************************************************
-.TP
-.B \-\-client-connect cmd
-Run
-.B command cmd
-on client connection.
-
-.B cmd
-consists of a path to script (or executable program), optionally
-followed by arguments. The path and arguments may be single- or double-quoted
-and/or escaped using a backslash, and should be separated by one or more spaces.
-
-The command is passed the common name
-and IP address of the just-authenticated client
-as environmental variables (see environmental variable section
-below). The command is also passed
-the pathname of a freshly created temporary file as the last argument
-(after any arguments specified in
-.B cmd
-), to be used by the command
-to pass dynamically generated config file directives back to OpenVPN.
-
-If the script wants to generate a dynamic config file
-to be applied on the server when the client connects,
-it should write it to the file named by the last argument.
-
-See the
-.B \-\-client-config-dir
-option below for options which
-can be legally used in a dynamically generated config file.
-
-Note that the return value of
-.B script
-is significant. If
-.B script
-returns a non-zero error status, it will cause the client
-to be disconnected.
-.\"*********************************************************
-.TP
-.B \-\-client-disconnect cmd
-Like
-.B \-\-client-connect
-but called on client instance shutdown. Will not be called
-unless the
-.B \-\-client-connect
-script and plugins (if defined)
-were previously called on this instance with
-successful (0) status returns.
-
-The exception to this rule is if the
-.B \-\-client-disconnect
-command or plugins are cascaded, and at least one client-connect
-function succeeded, then ALL of the client-disconnect functions for
-scripts and plugins will be called on client instance object deletion,
-even in cases where some of the related client-connect functions returned
-an error status.
-
-The
-.B \-\-client-disconnect
-command is passed the same pathname as the corresponding
-.B \-\-client-connect
-command as its last argument. (after any arguments specified in
-.B cmd
-).
-.B
-.\"*********************************************************
-.TP
-.B \-\-client-config-dir dir
-Specify a directory
-.B dir
-for custom client config files. After
-a connecting client has been authenticated, OpenVPN will
-look in this directory for a file having the same name
-as the client's X509 common name. If a matching file
-exists, it will be opened and parsed for client-specific
-configuration options. If no matching file is found, OpenVPN
-will instead try to open and parse a default file called
-"DEFAULT", which may be provided but is not required. Note that
-the configuration files must be readable by the OpenVPN process
-after it has dropped it's root privileges.
-
-This file can specify a fixed IP address for a given
-client using
-.B \-\-ifconfig-push,
-as well as fixed subnets owned by the client using
-.B \-\-iroute.
-
-One of the useful properties of this option is that it
-allows client configuration files to be conveniently
-created, edited, or removed while the server is live,
-without needing to restart the server.
-
-The following
-options are legal in a client-specific context:
-.B \-\-push, \-\-push-reset, \-\-iroute, \-\-ifconfig-push,
-and
-.B \-\-config.
-.\"*********************************************************
-.TP
-.B \-\-ccd-exclusive
-Require, as a
-condition of authentication, that a connecting client has a
-.B \-\-client-config-dir
-file.
-.\"*********************************************************
-.TP
-.B \-\-tmp-dir dir
-Specify a directory
-.B dir
-for temporary files. This directory will be used by
-openvpn processes and script to communicate temporary
-data with openvpn main process. Note that
-the directory must be writable by the OpenVPN process
-after it has dropped it's root privileges.
-
-This directory will be used by in the following cases:
-
-*
-.B \-\-client-connect
-scripts to dynamically generate client-specific
-configuration files.
-
-*
-.B OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY
-plugin hook to return success/failure via auth_control_file
-when using deferred auth method
-
-*
-.B OPENVPN_PLUGIN_ENABLE_PF
-plugin hook to pass filtering rules via pf_file
-.\"*********************************************************
-.TP
-.B \-\-hash-size r v
-Set the size of the real address hash table to
-.B r
-and the virtual address table to
-.B v.
-By default, both tables are sized at 256 buckets.
-.\"*********************************************************
-.TP
-.B \-\-bcast-buffers n
-Allocate
-.B n
-buffers for broadcast datagrams (default=256).
-.\"*********************************************************
-.TP
-.B \-\-tcp-queue-limit n
-Maximum number of output packets queued before TCP (default=64).
-
-When OpenVPN is tunneling data from a TUN/TAP device to a
-remote client over a TCP connection, it is possible that the TUN/TAP device
-might produce data at a faster rate than the TCP connection
-can support. When the number of output packets queued before sending to
-the TCP socket reaches this limit for a given client connection,
-OpenVPN will start to drop outgoing packets directed
-at this client.
-.\"*********************************************************
-.TP
-.B \-\-tcp-nodelay
-This macro sets the TCP_NODELAY socket flag on the server
-as well as pushes it to connecting clients. The TCP_NODELAY
-flag disables the Nagle algorithm on TCP sockets causing
-packets to be transmitted immediately with low latency,
-rather than waiting a short period of time in order
-to aggregate several packets into a larger containing
-packet. In VPN applications over TCP, TCP_NODELAY
-is generally a good latency optimization.
-
-The macro expands as follows:
-
-.nf
-.ft 3
-.in +4
- if mode server:
- socket-flags TCP_NODELAY
- push "socket-flags TCP_NODELAY"
-.in -4
-.ft
-.fi
-.\"*********************************************************
-.TP
-.B \-\-max-clients n
-Limit server to a maximum of
-.B n
-concurrent clients.
-.\"*********************************************************
-.TP
-.B \-\-max-routes-per-client n
-Allow a maximum of
-.B n
-internal routes per client (default=256).
-This is designed to
-help contain DoS attacks where an authenticated client floods the
-server with packets appearing to come from many unique MAC addresses,
-forcing the server to deplete
-virtual memory as its internal routing table expands.
-This directive can be used in a
-.B \-\-client-config-dir
-file or auto-generated by a
-.B \-\-client-connect
-script to override the global value for a particular client.
-
-Note that this
-directive affects OpenVPN's internal routing table, not the
-kernel routing table.
-.\"*********************************************************
-.TP
-.B \-\-stale-routes-check n [t]
-Remove routes haven't had activity for
-.B n
-seconds (i.e. the ageing time).
-
-This check is ran every
-.B t
-seconds (i.e. check interval).
-
-If
-.B t
-is not present it defaults to
-.B n
-
-This option helps to keep the dynamic routing table small.
-See also
-.B \-\-max-routes-per-client
-.\"*********************************************************
-.TP
-.B \-\-connect-freq n sec
-Allow a maximum of
-.B n
-new connections per
-.B sec
-seconds from clients. This is designed to contain DoS attacks which flood
-the server with connection requests using certificates which
-will ultimately fail to authenticate.
-
-This is an imperfect solution however, because in a real
-DoS scenario, legitimate connections might also be refused.
-
-For the best protection against DoS attacks in server mode,
-use
-.B \-\-proto udp
-and
-.B \-\-tls-auth.
-.\"*********************************************************
-.TP
-.B \-\-learn-address cmd
-Run command
-.B cmd
-to validate client virtual addresses or routes.
-
-.B cmd
-consists of a path to script (or executable program), optionally
-followed by arguments. The path and arguments may be single- or double-quoted
-and/or escaped using a backslash, and should be separated by one or more spaces.
-
-Three arguments will be appended to any arguments in
-.B cmd
-as follows:
-
-.B [1] operation \-\-
-"add", "update", or "delete" based on whether or not
-the address is being added to, modified, or deleted from
-OpenVPN's internal routing table.
-.br
-.B [2] address \-\-
-The address being learned or unlearned. This can be
-an IPv4 address such as "198.162.10.14", an IPv4 subnet
-such as "198.162.10.0/24", or an ethernet MAC address (when
-.B \-\-dev tap
-is being used) such as "00:FF:01:02:03:04".
-.br
-.B [3] common name \-\-
-The common name on the certificate associated with the
-client linked to this address. Only present for "add"
-or "update" operations, not "delete".
-
-On "add" or "update" methods, if the script returns
-a failure code (non-zero), OpenVPN will reject the address
-and will not modify its internal routing table.
-
-Normally, the
-.B cmd
-script will use the information provided above to set
-appropriate firewall entries on the VPN TUN/TAP interface.
-Since OpenVPN provides the association between virtual IP
-or MAC address and the client's authenticated common name,
-it allows a user-defined script to configure firewall access
-policies with regard to the client's high-level common name,
-rather than the low level client virtual addresses.
-.\"*********************************************************
-.TP
-.B \-\-auth-user-pass-verify cmd method
-Require the client to provide a username/password (possibly
-in addition to a client certificate) for authentication.
-
-OpenVPN will run
-.B command cmd
-to validate the username/password
-provided by the client.
-
-.B cmd
-consists of a path to script (or executable program), optionally
-followed by arguments. The path and arguments may be single- or double-quoted
-and/or escaped using a backslash, and should be separated by one or more spaces.
-
-If
-.B method
-is set to "via-env", OpenVPN will call
-.B script
-with the environmental variables
-.B username
-and
-.B password
-set to the username/password strings provided by the client.
-Be aware that this method is insecure on some platforms which
-make the environment of a process publicly visible to other
-unprivileged processes.
-
-If
-.B method
-is set to "via-file", OpenVPN will write the username and
-password to the first two lines of a temporary file. The filename
-will be passed as an argument to
-.B script,
-and the file will be automatically deleted by OpenVPN after
-the script returns. The location of the temporary file is
-controlled by the
-.B \-\-tmp-dir
-option, and will default to the current directory if unspecified.
-For security, consider setting
-.B \-\-tmp-dir
-to a volatile storage medium such as
-.B /dev/shm
-(if available) to prevent the username/password file from touching the hard drive.
-
-The script should examine the username
-and password,
-returning a success exit code (0) if the
-client's authentication request is to be accepted, or a failure
-code (1) to reject the client.
-
-This directive is designed to enable a plugin-style interface
-for extending OpenVPN's authentication capabilities.
-
-To protect against a client passing a maliciously formed
-username or password string, the username string must
-consist only of these characters: alphanumeric, underbar
-('_'), dash ('-'), dot ('.'), or at ('@'). The password
-string can consist of any printable characters except for
-CR or LF. Any illegal characters in either the username
-or password string will be converted to underbar ('_').
-
-Care must be taken by any user-defined scripts to avoid
-creating a security vulnerability in the way that these
-strings are handled. Never use these strings in such a way
-that they might be escaped or evaluated by a shell interpreter.
-
-For a sample script that performs PAM authentication, see
-.B sample-scripts/auth-pam.pl
-in the OpenVPN source distribution.
-.\"*********************************************************
-.TP
-.B \-\-opt-verify
-Clients that connect with options that are incompatible
-with those of the server will be disconnected.
-
-Options that will be compared for compatibility include
-dev-type, link-mtu, tun-mtu, proto, tun-ipv6, ifconfig,
-comp-lzo, fragment, keydir, cipher, auth, keysize, secret,
-no-replay, no-iv, tls-auth, key-method, tls-server, and tls-client.
-
-This option requires that
-.B \-\-disable-occ
-NOT be used.
-.\"*********************************************************
-.TP
-.B \-\-auth-user-pass-optional
-Allow connections by clients that do not specify a username/password.
-Normally, when
-.B \-\-auth-user-pass-verify
-or
-.B \-\-management-client-auth
-is specified (or an authentication plugin module), the
-OpenVPN server daemon will require connecting clients to specify a
-username and password. This option makes the submission of a username/password
-by clients optional, passing the responsibility to the user-defined authentication
-module/script to accept or deny the client based on other factors
-(such as the setting of X509 certificate fields). When this option is used,
-and a connecting client does not submit a username/password, the user-defined
-authentication module/script will see the username and password as being set
-to empty strings (""). The authentication module/script MUST have logic
-to detect this condition and respond accordingly.
-.\"*********************************************************
-.TP
-.B \-\-client-cert-not-required
-Don't require client certificate, client will authenticate
-using username/password only. Be aware that using this directive
-is less secure than requiring certificates from all clients.
-
-If you use this directive, the
-entire responsibility of authentication will rest on your
-.B \-\-auth-user-pass-verify
-script, so keep in mind that bugs in your script
-could potentially compromise the security of your VPN.
-
-If you don't use this directive, but you also specify an
-.B \-\-auth-user-pass-verify
-script, then OpenVPN will perform double authentication. The
-client certificate verification AND the
-.B \-\-auth-user-pass-verify
-script will need to succeed in order for a client to be
-authenticated and accepted onto the VPN.
-.\"*********************************************************
-.TP
-.B \-\-username-as-common-name
-For
-.B \-\-auth-user-pass-verify
-authentication, use
-the authenticated username as the common name,
-rather than the common name from the client cert.
-.\"*********************************************************
-.TP
-.B \-\-compat\-names [no\-remapping] (DEPRECATED)
-Until OpenVPN v2.3 the format of the X.509 Subject fields was formatted
-like this:
-.IP
-.B
-/C=US/L=Somewhere/CN=John Doe/emailAddress=john@example.com
-.IP
-In addition the old behaviour was to remap any character other than
-alphanumeric, underscore ('_'), dash ('-'), dot ('.'), and slash ('/') to
-underscore ('_'). The X.509 Subject string as returned by the
-.B tls_id
-environmental variable, could additionally contain colon (':') or equal ('=').
-.IP
-When using the
-.B \-\-compat\-names
-option, this old formatting and remapping will be re-enabled again. This is
-purely implemented for compatibility reasons when using older plug-ins or
-scripts which does not handle the new formatting or UTF-8 characters.
-.IP
-In OpenVPN v2.3 the formatting of these fields changed into a more
-standardised format. It now looks like:
-.IP
-.B
-C=US, L=Somewhere, CN=John Doe, emailAddress=john@example.com
-.IP
-The new default format in OpenVPN v2.3 also does not do the character remapping
-which happened earlier. This new format enables proper support for UTF\-8
-characters in the usernames, X.509 Subject fields and Common Name variables and
-it complies to the RFC 2253, UTF\-8 String Representation of Distinguished
-Names.
-
-The
-.B no\-remapping
-mode flag can be used with the
-.B
-\-\-compat\-names
-option to be compatible with the now deprecated \-\-no\-name\-remapping option.
-It is only available at the server. When this mode flag is used, the Common Name,
-Subject, and username strings are allowed to include any printable character
-including space, but excluding control characters such as tab, newline, and
-carriage-return. no-remapping is only available on the server side.
-
-.B Please note:
-This option is immediately deprecated. It is only implemented
-to make the transition to the new formatting less intrusive. It will be
-removed either in OpenVPN v2.4 or v2.5. So please make sure you use the
-.B \-\-verify-x509-name
-option instead of
-.B \-\-tls-remote
-as soon as possible and update your scripts where necessary.
-.\"*********************************************************
-.TP
-.B \-\-no\-name\-remapping (DEPRECATED)
-The
-.B \-\-no\-name\-remapping
-option is an alias for
-.B \-\-compat\-names\ no\-remapping.
-It ensures compatibility with server configurations using the
-.B \-\-no\-name\-remapping
-option.
-
-.B Please note:
-This option is now deprecated. It will be removed either in OpenVPN v2.4
-or v2.5. So please make sure you support the new X.509 name formatting
-described with the
-.B \-\-compat\-names
-option as soon as possible.
-.\"*********************************************************
-.TP
-.B \-\-port-share host port [dir]
-When run in TCP server mode, share the OpenVPN port with
-another application, such as an HTTPS server. If OpenVPN
-senses a connection to its port which is using a non-OpenVPN
-protocol, it will proxy the connection to the server at
-.B host:port.
-Currently only designed to work with HTTP/HTTPS,
-though it would be theoretically possible to extend to
-other protocols such as ssh.
-
-.B dir
-specifies an optional directory where a temporary file with name N
-containing content C will be dynamically generated for each proxy
-connection, where N is the source IP:port of the client connection
-and C is the source IP:port of the connection to the proxy
-receiver. This directory can be used as a dictionary by
-the proxy receiver to determine the origin of the connection.
-Each generated file will be automatically deleted when the proxied
-connection is torn down.
-
-Not implemented on Windows.
-.\"*********************************************************
-.SS Client Mode
-Use client mode when connecting to an OpenVPN server
-which has
-.B \-\-server, \-\-server-bridge,
-or
-.B \-\-mode server
-in it's configuration.
-.\"*********************************************************
-.TP
-.B \-\-client
-A helper directive designed to simplify the configuration
-of OpenVPN's client mode. This directive is equivalent to:
-
-.nf
-.ft 3
-.in +4
- pull
- tls-client
-.in -4
-.ft
-.fi
-.\"*********************************************************
-.TP
-.B \-\-pull
-This option must be used on a client which is connecting
-to a multi-client server. It indicates to OpenVPN that it
-should accept options pushed by the server, provided they
-are part of the legal set of pushable options (note that the
-.B \-\-pull
-option is implied by
-.B \-\-client
-).
-
-In particular,
-.B \-\-pull
-allows the server to push routes to the client, so you should
-not use
-.B \-\-pull
-or
-.B \-\-client
-in situations where you don't trust the server to have control
-over the client's routing table.
-.\"*********************************************************
-.TP
-.B \-\-auth-user-pass [up]
-Authenticate with server using username/password.
-.B up
-is a file containing username/password on 2 lines (Note: OpenVPN
-will only read passwords from a file if it has been built
-with the \-\-enable-password-save configure option, or on Windows
-by defining ENABLE_PASSWORD_SAVE in win/settings.in).
-
-If
-.B up
-is omitted, username/password will be prompted from the
-console.
-
-The server configuration must specify an
-.B \-\-auth-user-pass-verify
-script to verify the username/password provided by
-the client.
-.\"*********************************************************
-.TP
-.B \-\-auth-retry type
-Controls how OpenVPN responds to username/password verification
-errors such as the client-side response to an AUTH_FAILED message from the server
-or verification failure of the private key password.
-
-Normally used to prevent auth errors from being fatal
-on the client side, and to permit username/password requeries in case
-of error.
-
-An AUTH_FAILED message is generated by the server if the client
-fails
-.B \-\-auth-user-pass
-authentication, or if the server-side
-.B \-\-client-connect
-script returns an error status when the client
-tries to connect.
-
-.B type
-can be one of:
-
-.B none \-\-
-Client will exit with a fatal error (this is the default).
-.br
-.B nointeract \-\-
-Client will retry the connection without requerying for an
-.B \-\-auth-user-pass
-username/password. Use this option for unattended clients.
-.br
-.B interact \-\-
-Client will requery for an
-.B \-\-auth-user-pass
-username/password and/or private key password before attempting a reconnection.
-
-Note that while this option cannot be pushed, it can be controlled
-from the management interface.
-.\"*********************************************************
-.TP
-.B \-\-static\-challenge t e
-Enable static challenge/response protocol using challenge text
-.B t,
-with
-echo flag given by
-.B e
-(0|1).
-
-The echo flag indicates whether or not the user's response
-to the challenge should be echoed.
-
-See management\-notes.txt in the OpenVPN distribution for a
-description of the OpenVPN challenge/response protocol.
-.\"*********************************************************
-.TP
-.B \-\-server-poll-timeout n
-when polling possible remote servers to connect to
-in a round-robin fashion, spend no more than
-.B n
-seconds waiting for a response before trying the next server.
-.\"*********************************************************
-.TP
-.B \-\-explicit-exit-notify [n]
-In UDP client mode or point-to-point mode, send server/peer an exit notification
-if tunnel is restarted or OpenVPN process is exited. In client mode, on
-exit/restart, this
-option will tell the server to immediately close its client instance object
-rather than waiting for a timeout. The
-.B n
-parameter (default=1) controls the maximum number of attempts that the client
-will try to resend the exit notification message. OpenVPN will not send any exit
-notifications unless this option is enabled.
-.\"*********************************************************
-.SS Data Channel Encryption Options:
-These options are meaningful for both Static & TLS-negotiated key modes
-(must be compatible between peers).
-.\"*********************************************************
-.TP
-.B \-\-secret file [direction]
-Enable Static Key encryption mode (non-TLS).
-Use pre-shared secret
-.B file
-which was generated with
-.B \-\-genkey.
-
-The optional
-.B direction
-parameter enables the use of 4 distinct keys
-(HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that
-each data flow direction has a different set of HMAC and cipher keys.
-This has a number of desirable security properties including
-eliminating certain kinds of DoS and message replay attacks.
-
-When the
-.B direction
-parameter is omitted, 2 keys are used bidirectionally, one for HMAC
-and the other for encryption/decryption.
-
-The
-.B direction
-parameter should always be complementary on either side of the connection,
-i.e. one side should use "0" and the other should use "1", or both sides
-should omit it altogether.
-
-The
-.B direction
-parameter requires that
-.B file
-contains a 2048 bit key. While pre-1.5 versions of OpenVPN
-generate 1024 bit key files, any version of OpenVPN which
-supports the
-.B direction
-parameter, will also support 2048 bit key file generation
-using the
-.B \-\-genkey
-option.
-
-Static key encryption mode has certain advantages,
-the primary being ease of configuration.
-
-There are no certificates
-or certificate authorities or complicated negotiation handshakes and protocols.
-The only requirement is that you have a pre-existing secure channel with
-your peer (such as
-.B ssh
-) to initially copy the key. This requirement, along with the
-fact that your key never changes unless you manually generate a new one,
-makes it somewhat less secure than TLS mode (see below). If an attacker
-manages to steal your key, everything that was ever encrypted with
-it is compromised. Contrast that to the perfect forward secrecy features of
-TLS mode (using Diffie Hellman key exchange), where even if an attacker
-was able to steal your private key, he would gain no information to help
-him decrypt past sessions.
-
-Another advantageous aspect of Static Key encryption mode is that
-it is a handshake-free protocol
-without any distinguishing signature or feature
-(such as a header or protocol handshake sequence)
-that would mark the ciphertext packets as being
-generated by OpenVPN. Anyone eavesdropping on the wire
-would see nothing
-but random-looking data.
-.\"*********************************************************
-.TP
-.B \-\-key-direction
-Alternative way of specifying the optional direction parameter for the
-.B \-\-tls-auth
-and
-.B \-\-secret
-options. Useful when using inline files (See section on inline files).
-.\"*********************************************************
-.TP
-.B \-\-auth alg
-Authenticate packets with HMAC using message
-digest algorithm
-.B alg.
-(The default is
-.B SHA1
-).
-HMAC is a commonly used message authentication algorithm (MAC) that uses
-a data string, a secure hash algorithm, and a key, to produce
-a digital signature.
-
-OpenVPN's usage of HMAC is to first encrypt a packet, then HMAC the resulting ciphertext.
-
-In static-key encryption mode, the HMAC key
-is included in the key file generated by
-.B \-\-genkey.
-In TLS mode, the HMAC key is dynamically generated and shared
-between peers via the TLS control channel. If OpenVPN receives a packet with
-a bad HMAC it will drop the packet.
-HMAC usually adds 16 or 20 bytes per packet.
-Set
-.B alg=none
-to disable authentication.
-
-For more information on HMAC see
-.I http://www.cs.ucsd.edu/users/mihir/papers/hmac.html
-.\"*********************************************************
-.TP
-.B \-\-cipher alg
-Encrypt packets with cipher algorithm
-.B alg.
-The default is
-.B BF-CBC,
-an abbreviation for Blowfish in Cipher Block Chaining mode.
-Blowfish has the advantages of being fast, very secure, and allowing key sizes
-of up to 448 bits. Blowfish is designed to be used in situations where
-keys are changed infrequently.
-
-For more information on blowfish, see
-.I http://www.counterpane.com/blowfish.html
-
-To see other ciphers that are available with
-OpenVPN, use the
-.B \-\-show-ciphers
-option.
-
-OpenVPN supports the CBC, CFB, and OFB cipher modes,
-however CBC is recommended and CFB and OFB should
-be considered advanced modes.
-
-Set
-.B alg=none
-to disable encryption.
-.\"*********************************************************
-.TP
-.B \-\-keysize n
-Size of cipher key in bits (optional).
-If unspecified, defaults to cipher-specific default. The
-.B \-\-show-ciphers
-option (see below) shows all available OpenSSL ciphers,
-their default key sizes, and whether the key size can
-be changed. Use care in changing a cipher's default
-key size. Many ciphers have not been extensively
-cryptanalyzed with non-standard key lengths, and a
-larger key may offer no real guarantee of greater
-security, or may even reduce security.
-.\"*********************************************************
-.TP
-.B \-\-prng alg [nsl]
-(Advanced) For PRNG (Pseudo-random number generator),
-use digest algorithm
-.B alg
-(default=sha1), and set
-.B nsl
-(default=16)
-to the size in bytes of the nonce secret length (between 16 and 64).
-
-Set
-.B alg=none
-to disable the PRNG and use the OpenSSL RAND_bytes function
-instead for all of OpenVPN's pseudo-random number needs.
-.\"*********************************************************
-.TP
-.B \-\-engine [engine-name]
-Enable OpenSSL hardware-based crypto engine functionality.
-
-If
-.B engine-name
-is specified,
-use a specific crypto engine. Use the
-.B \-\-show-engines
-standalone option to list the crypto engines which are
-supported by OpenSSL.
-.\"*********************************************************
-.TP
-.B \-\-no-replay
-(Advanced) Disable OpenVPN's protection against replay attacks.
-Don't use this option unless you are prepared to make
-a tradeoff of greater efficiency in exchange for less
-security.
-
-OpenVPN provides datagram replay protection by default.
-
-Replay protection is accomplished
-by tagging each outgoing datagram with an identifier
-that is guaranteed to be unique for the key being used.
-The peer that receives the datagram will check for
-the uniqueness of the identifier. If the identifier
-was already received in a previous datagram, OpenVPN
-will drop the packet. Replay protection is important
-to defeat attacks such as a SYN flood attack, where
-the attacker listens in the wire, intercepts a TCP
-SYN packet (identifying it by the context in which
-it occurs in relation to other packets), then floods
-the receiving peer with copies of this packet.
-
-OpenVPN's replay protection is implemented in slightly
-different ways, depending on the key management mode
-you have selected.
-
-In Static Key mode
-or when using an CFB or OFB mode cipher, OpenVPN uses a
-64 bit unique identifier that combines a time stamp with
-an incrementing sequence number.
-
-When using TLS mode for key exchange and a CBC cipher
-mode, OpenVPN uses only a 32 bit sequence number without
-a time stamp, since OpenVPN can guarantee the uniqueness
-of this value for each key. As in IPSec, if the sequence number is
-close to wrapping back to zero, OpenVPN will trigger
-a new key exchange.
-
-To check for replays, OpenVPN uses
-the
-.I sliding window
-algorithm used
-by IPSec.
-.\"*********************************************************
-.TP
-.B \-\-replay-window n [t]
-Use a replay protection sliding-window of size
-.B n
-and a time window of
-.B t
-seconds.
-
-By default
-.B n
-is 64 (the IPSec default) and
-.B t
-is 15 seconds.
-
-This option is only relevant in UDP mode, i.e.
-when either
-.B \-\-proto udp
-is specifed, or no
-.B \-\-proto
-option is specified.
-
-When OpenVPN tunnels IP packets over UDP, there is the possibility that
-packets might be dropped or delivered out of order. Because OpenVPN, like IPSec,
-is emulating the physical network layer,
-it will accept an out-of-order packet sequence, and
-will deliver such packets in the same order they were received to
-the TCP/IP protocol stack, provided they satisfy several constraints.
-
-.B (a)
-The packet cannot be a replay (unless
-.B \-\-no-replay
-is specified, which disables replay protection altogether).
-
-.B (b)
-If a packet arrives out of order, it will only be accepted if the difference
-between its sequence number and the highest sequence number received
-so far is less than
-.B n.
-
-.B (c)
-If a packet arrives out of order, it will only be accepted if it arrives no later
-than
-.B t
-seconds after any packet containing a higher sequence number.
-
-If you are using a network link with a large pipeline (meaning that
-the product of bandwidth and latency is high), you may want to use
-a larger value for
-.B n.
-Satellite links in particular often require this.
-
-If you run OpenVPN at
-.B \-\-verb 4,
-you will see the message "Replay-window backtrack occurred [x]"
-every time the maximum sequence number backtrack seen thus far
-increases. This can be used to calibrate
-.B n.
-
-There is some controversy on the appropriate method of handling packet
-reordering at the security layer.
-
-Namely, to what extent should the
-security layer protect the encapsulated protocol from attacks which masquerade
-as the kinds of normal packet loss and reordering that occur over IP networks?
-
-The IPSec and OpenVPN approach is to allow packet reordering within a certain
-fixed sequence number window.
-
-OpenVPN adds to the IPSec model by limiting the window size in time as well as
-sequence space.
-
-OpenVPN also adds TCP transport as an option (not offered by IPSec) in which
-case OpenVPN can adopt a very strict attitude towards message deletion and
-reordering: Don't allow it. Since TCP guarantees reliability, any packet
-loss or reordering event can be assumed to be an attack.
-
-In this sense, it could be argued that TCP tunnel transport is preferred when
-tunneling non-IP or UDP application protocols which might be vulnerable to a
-message deletion or reordering attack which falls within the normal
-operational parameters of IP networks.
-
-So I would make the statement that one should never tunnel a non-IP protocol
-or UDP application protocol over UDP, if the protocol might be vulnerable to a
-message deletion or reordering attack that falls within the normal operating
-parameters of what is to be expected from the physical IP layer. The problem
-is easily fixed by simply using TCP as the VPN transport layer.
-.\"*********************************************************
-.TP
-.B \-\-mute-replay-warnings
-Silence the output of replay warnings, which are a common
-false alarm on WiFi networks. This option preserves
-the security of the replay protection code without
-the verbosity associated with warnings about duplicate
-packets.
-.\"*********************************************************
-.TP
-.B \-\-replay-persist file
-Persist replay-protection state across sessions using
-.B file
-to save and reload the state.
-
-This option will strengthen protection against replay attacks,
-especially when you are using OpenVPN in a dynamic context (such
-as with
-.B \-\-inetd)
-when OpenVPN sessions are frequently started and stopped.
-
-This option will keep a disk copy of the current replay protection
-state (i.e. the most recent packet timestamp and sequence number
-received from the remote peer), so that if an OpenVPN session
-is stopped and restarted, it will reject any replays of packets
-which were already received by the prior session.
-
-This option only makes sense when replay protection is enabled
-(the default) and you are using either
-.B \-\-secret
-(shared-secret key mode) or TLS mode with
-.B \-\-tls-auth.
-.\"*********************************************************
-.TP
-.B \-\-no-iv
-(Advanced) Disable OpenVPN's use of IV (cipher initialization vector).
-Don't use this option unless you are prepared to make
-a tradeoff of greater efficiency in exchange for less
-security.
-
-OpenVPN uses an IV by default, and requires it for CFB and
-OFB cipher modes (which are totally insecure without it).
-Using an IV is important for security when multiple
-messages are being encrypted/decrypted with the same key.
-
-IV is implemented differently depending on the cipher mode used.
-
-In CBC mode, OpenVPN uses a pseudo-random IV for each packet.
-
-In CFB/OFB mode, OpenVPN uses a unique sequence number and time stamp
-as the IV. In fact, in CFB/OFB mode, OpenVPN uses a datagram
-space-saving optimization that uses the unique identifier for
-datagram replay protection as the IV.
-.\"*********************************************************
-.TP
-.B \-\-use-prediction-resistance
-Enable prediction resistance on PolarSSL's RNG.
-
-Enabling prediction resistance causes the RNG to reseed in each
-call for random. Reseeding this often can quickly deplete the kernel
-entropy pool.
-
-If you need this option, please consider running a daemon that adds
-entropy to the kernel pool.
-
-Note that this option only works with PolarSSL versions greater
-than 1.1.
-.\"*********************************************************
-.TP
-.B \-\-test-crypto
-Do a self-test of OpenVPN's crypto options by encrypting and
-decrypting test packets using the data channel encryption options
-specified above. This option does not require a peer to function,
-and therefore can be specified without
-.B \-\-dev
-or
-.B \-\-remote.
-
-The typical usage of
-.B \-\-test-crypto
-would be something like this:
-
-.B openvpn \-\-test-crypto \-\-secret key
-
-or
-
-.B openvpn \-\-test-crypto \-\-secret key \-\-verb 9
-
-This option is very useful to test OpenVPN after it has been ported to
-a new platform, or to isolate problems in the compiler, OpenSSL
-crypto library, or OpenVPN's crypto code. Since it is a self-test mode,
-problems with encryption and authentication can be debugged independently
-of network and tunnel issues.
-.\"*********************************************************
-.SS TLS Mode Options:
-TLS mode is the most powerful crypto mode of OpenVPN in both security and flexibility.
-TLS mode works by establishing control and
-data channels which are multiplexed over a single TCP/UDP port. OpenVPN initiates
-a TLS session over the control channel and uses it to exchange cipher
-and HMAC keys to protect the data channel. TLS mode uses a robust reliability
-layer over the UDP connection for all control channel communication, while
-the data channel, over which encrypted tunnel data passes, is forwarded without
-any mediation. The result is the best of both worlds: a fast data channel
-that forwards over UDP with only the overhead of encrypt,
-decrypt, and HMAC functions,
-and a control channel that provides all of the security features of TLS,
-including certificate-based authentication and Diffie Hellman forward secrecy.
-
-To use TLS mode, each peer that runs OpenVPN should have its own local
-certificate/key pair (
-.B \-\-cert
-and
-.B \-\-key
-), signed by the root certificate which is specified
-in
-.B \-\-ca.
-
-When two OpenVPN peers connect, each presents its local certificate to the
-other. Each peer will then check that its partner peer presented a
-certificate which was signed by the master root certificate as specified in
-.B \-\-ca.
-
-If that check on both peers succeeds, then the TLS negotiation
-will succeed, both OpenVPN
-peers will exchange temporary session keys, and the tunnel will begin
-passing data.
-
-The OpenVPN distribution contains a set of scripts for
-managing RSA certificates & keys,
-located in the
-.I easy-rsa
-subdirectory.
-
-The easy-rsa package is also rendered in web form here:
-.I http://openvpn.net/easyrsa.html
-.\"*********************************************************
-.TP
-.B \-\-tls-server
-Enable TLS and assume server role during TLS handshake. Note that
-OpenVPN is designed as a peer-to-peer application. The designation
-of client or server is only for the purpose of negotiating the TLS
-control channel.
-.\"*********************************************************
-.TP
-.B \-\-tls-client
-Enable TLS and assume client role during TLS handshake.
-.\"*********************************************************
-.TP
-.B \-\-ca file
-Certificate authority (CA) file in .pem format, also referred to as the
-.I root
-certificate. This file can have multiple
-certificates in .pem format, concatenated together. You can construct your own
-certificate authority certificate and private key by using a command such as:
-
-.B openssl req -nodes -new -x509 -keyout ca.key -out ca.crt
-
-Then edit your openssl.cnf file and edit the
-.B certificate
-variable to point to your new root certificate
-.B ca.crt.
-
-For testing purposes only, the OpenVPN distribution includes a sample
-CA certificate (ca.crt).
-Of course you should never use
-the test certificates and test keys distributed with OpenVPN in a
-production environment, since by virtue of the fact that
-they are distributed with OpenVPN, they are totally insecure.
-.\"*********************************************************
-.TP
-.B \-\-capath dir
-Directory containing trusted certificates (CAs and CRLs).
-Available with OpenSSL version >= 0.9.7 dev.
-Not available with PolarSSL.
-.\"*********************************************************
-.TP
-.B \-\-dh file
-File containing Diffie Hellman parameters
-in .pem format (required for
-.B \-\-tls-server
-only).
-
-Set
-.B file=none
-to disable Diffie Hellman key exchange (and use ECDH only). Note that this
-requires peers to be using an SSL library that supports ECDH TLS cipher suites
-(e.g. OpenSSL 1.0.1+, or PolarSSL 1.3+).
-
-Use
-.B openssl dhparam -out dh2048.pem 2048
-to generate 2048-bit DH parameters. Diffie Hellman parameters may be considered
-public.
-.\"*********************************************************
-.TP
-.B \-\-ecdh-curve name
-Specify the curve to use for elliptic curve Diffie Hellman. Available
-curves can be listed with
-.B \-\-show-curves
-. The specified curve will only be used for ECDH TLS-ciphers.
-.\"*********************************************************
-.TP
-.B \-\-cert file
-Local peer's signed certificate in .pem format \-\- must be signed
-by a certificate authority whose certificate is in
-.B \-\-ca file.
-Each peer in an OpenVPN link running in TLS mode should have its own
-certificate and private key file. In addition, each certificate should
-have been signed by the key of a certificate
-authority whose public key resides in the
-.B \-\-ca
-certificate authority file.
-You can easily make your own certificate authority (see above) or pay money
-to use a commercial service such as thawte.com (in which case you will be
-helping to finance the world's second space tourist :).
-To generate a certificate,
-you can use a command such as:
-
-.B openssl req -nodes -new -keyout mycert.key -out mycert.csr
-
-If your certificate authority private key lives on another machine, copy
-the certificate signing request (mycert.csr) to this other machine (this can
-be done over an insecure channel such as email). Now sign the certificate
-with a command such as:
-
-.B openssl ca -out mycert.crt -in mycert.csr
-
-Now copy the certificate (mycert.crt)
-back to the peer which initially generated the .csr file (this
-can be over a public medium).
-Note that the
-.B openssl ca
-command reads the location of the certificate authority key from its
-configuration file such as
-.B /usr/share/ssl/openssl.cnf
-\-\- note also
-that for certificate authority functions, you must set up the files
-.B index.txt
-(may be empty) and
-.B serial
-(initialize to
-.B
-01
-).
-.\"*********************************************************
-.TP
-.B \-\-extra-certs file
-Specify a
-.B file
-containing one or more PEM certs (concatenated together)
-that complete the
-local certificate chain.
-
-This option is useful for "split" CAs, where the CA for server
-certs is different than the CA for client certs. Putting certs
-in this file allows them to be used to complete the local
-certificate chain without trusting them to verify the peer-submitted
-certificate, as would be the case if the certs were placed in the
-.B ca
-file.
-.\"*********************************************************
-.TP
-.B \-\-key file
-Local peer's private key in .pem format. Use the private key which was generated
-when you built your peer's certificate (see
-.B -cert file
-above).
-.\"*********************************************************
-.TP
-.B \-\-tls-version-min version ['or-highest']
-Sets the minimum
-TLS version we will accept from the peer (default is "1.0").
-Examples for version
-include "1.0", "1.1", or "1.2". If 'or-highest' is specified
-and version is not recognized, we will only accept the highest TLS
-version supported by the local SSL implementation.
-.\"*********************************************************
-.TP
-.B \-\-tls-version-max version
-Set the maximum TLS version we will use (default is the highest version
-supported). Examples for version include "1.0", "1.1", or "1.2".
-.\"*********************************************************
-.TP
-.B \-\-pkcs12 file
-Specify a PKCS #12 file containing local private key,
-local certificate, and root CA certificate.
-This option can be used instead of
-.B \-\-ca, \-\-cert,
-and
-.B \-\-key.
-Not available with PolarSSL.
-.\"*********************************************************
-.TP
-.B \-\-verify-hash hash
-Specify SHA1 fingerprint for level-1 cert. The level-1 cert is the
-CA (or intermediate cert) that signs the leaf certificate, and is
-one removed from the leaf certificate in the direction of the root.
-When accepting a connection from a peer, the level-1 cert
-fingerprint must match
-.B hash
-or certificate verification will fail. Hash is specified
-as XX:XX:... For example: AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16
-.\"*********************************************************
-.TP
-.B \-\-pkcs11-cert-private [0|1]...
-Set if access to certificate object should be performed after login.
-Every provider has its own setting.
-.\"*********************************************************
-.TP
-.B \-\-pkcs11-id name
-Specify the serialized certificate id to be used. The id can be gotten
-by the standalone
-.B \-\-show-pkcs11-ids
-option.
-.\"*********************************************************
-.TP
-.B \-\-pkcs11-id-management
-Acquire PKCS#11 id from management interface. In this case a NEED-STR 'pkcs11-id-request'
-real-time message will be triggered, application may use pkcs11-id-count command to
-retrieve available number of certificates, and pkcs11-id-get command to retrieve certificate
-id and certificate body.
-.\"*********************************************************
-.TP
-.B \-\-pkcs11-pin-cache seconds
-Specify how many seconds the PIN can be cached, the default is until the token is removed.
-.\"*********************************************************
-.TP
-.B \-\-pkcs11-protected-authentication [0|1]...
-Use PKCS#11 protected authentication path, useful for biometric and external
-keypad devices.
-Every provider has its own setting.
-.\"*********************************************************
-.TP
-.B \-\-pkcs11-providers provider...
-Specify a RSA Security Inc. PKCS #11 Cryptographic Token Interface (Cryptoki) providers
-to load.
-This option can be used instead of
-.B \-\-cert, \-\-key,
-and
-.B \-\-pkcs12.
-
-If p11-kit is present on the system, its
-.B p11-kit-proxy.so
-module will be loaded by default if either the
-.B \-\-pkcs11\-id
-or
-.B \-\-pkcs11\-id\-management
-options are specified without
-.B \-\-pkcs11\-provider
-being given.
-.\"*********************************************************
-.TP
-.B \-\-pkcs11-private-mode mode...
-Specify which method to use in order to perform private key operations.
-A different mode can be specified for each provider.
-Mode is encoded as hex number, and can be a mask one of the following:
-
-.B 0
-(default) \-\- Try to determine automatically.
-.br
-.B 1
-\-\- Use sign.
-.br
-.B 2
-\-\- Use sign recover.
-.br
-.B 4
-\-\- Use decrypt.
-.br
-.B 8
-\-\- Use unwrap.
-.br
-.\"*********************************************************
-.TP
-.B \-\-cryptoapicert select-string
-Load the certificate and private key from the
-Windows Certificate System Store (Windows/OpenSSL Only).
-
-Use this option instead of
-.B \-\-cert
-and
-.B \-\-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:
-
-.B cryptoapicert
-"SUBJ:Peter Runestig"
-
-To select a certificate, based on certificate's thumbprint:
-
-.B cryptoapicert
-"THUMB:f6 49 24 41 01 b4 ..."
-
-The thumbprint hex string can easily be copy-and-pasted from the Windows
-Certificate Store GUI.
-
-.\"*********************************************************
-.TP
-.B \-\-key-method m
-Use data channel key negotiation method
-.B m.
-The key method must match on both sides of the connection.
-
-After OpenVPN negotiates a TLS session, a new set of keys
-for protecting the tunnel data channel is generated and
-exchanged over the TLS session.
-
-In method 1 (the default for OpenVPN 1.x), both sides generate
-random encrypt and HMAC-send keys which are forwarded to
-the other host over the TLS channel.
-
-In method 2, (the default for OpenVPN 2.0)
-the client generates a random key. Both client
-and server also generate some random seed material. All key source
-material is exchanged over the TLS channel. The actual
-keys are generated using the TLS PRF function, taking source
-entropy from both client and server. Method 2 is designed to
-closely parallel the key generation process used by TLS 1.0.
-
-Note that in TLS mode, two separate levels
-of keying occur:
-
-(1) The TLS connection is initially negotiated, with both sides
-of the connection producing certificates and verifying the certificate
-(or other authentication info provided) of
-the other side. The
-.B \-\-key-method
-parameter has no effect on this process.
-
-(2) After the TLS connection is established, the tunnel session keys are
-separately negotiated over the existing secure TLS channel. Here,
-.B \-\-key-method
-determines the derivation of the tunnel session keys.
-.\"*********************************************************
-.TP
-.B \-\-tls-cipher l
-A list
-.B l
-of allowable TLS ciphers delimited by a colon (":").
-If you require a high level of security,
-you may want to set this parameter manually, to prevent a
-version rollback attack where a man-in-the-middle attacker tries
-to force two peers to negotiate to the lowest level
-of security they both support.
-Use
-.B \-\-show-tls
-to see a list of supported TLS ciphers.
-
-The default for --tls-cipher is to use PolarSSL's default cipher list
-when using PolarSSL or "DEFAULT:!EXP:!PSK:!SRP:!kRSA" when using OpenSSL.
-.\"*********************************************************
-.TP
-.B \-\-tls-timeout n
-Packet retransmit timeout on TLS control channel
-if no acknowledgment from remote within
-.B n
-seconds (default=2). When OpenVPN sends a control
-packet to its peer, it will expect to receive an
-acknowledgement within
-.B n
-seconds or it will retransmit the packet, subject
-to a TCP-like exponential backoff algorithm. This parameter
-only applies to control channel packets. Data channel
-packets (which carry encrypted tunnel data) are never
-acknowledged, sequenced, or retransmitted by OpenVPN because
-the higher level network protocols running on top of the tunnel
-such as TCP expect this role to be left to them.
-.\"*********************************************************
-.TP
-.B \-\-reneg-bytes n
-Renegotiate data channel key after
-.B n
-bytes sent or received (disabled by default).
-OpenVPN allows the lifetime of a key
-to be expressed as a number of bytes encrypted/decrypted, a number of packets, or
-a number of seconds. A key renegotiation will be forced
-if any of these three criteria are met by either peer.
-.\"*********************************************************
-.TP
-.B \-\-reneg-pkts n
-Renegotiate data channel key after
-.B n
-packets sent and received (disabled by default).
-.\"*********************************************************
-.TP
-.B \-\-reneg-sec n
-Renegotiate data channel key after
-.B n
-seconds (default=3600).
-
-When using dual-factor authentication, note that this default value may
-cause the end user to be challenged to reauthorize once per hour.
-
-Also, keep in mind that this option can be used on both the client and server,
-and whichever uses the lower value will be the one to trigger the renegotiation.
-A common mistake is to set
-.B \-\-reneg-sec
-to a higher value on either the client or server, while the other side of the connection
-is still using the default value of 3600 seconds, meaning that the renegotiation will
-still occur once per 3600 seconds. The solution is to increase \-\-reneg-sec on both the
-client and server, or set it to 0 on one side of the connection (to disable), and to
-your chosen value on the other side.
-.\"*********************************************************
-.TP
-.B \-\-hand-window n
-Handshake Window \-\- the TLS-based key exchange must finalize within
-.B n
-seconds
-of handshake initiation by any peer (default = 60 seconds).
-If the handshake fails
-we will attempt to reset our connection with our peer and try again.
-Even in the event of handshake failure we will still use
-our expiring key for up to
-.B \-\-tran-window
-seconds to maintain continuity of transmission of tunnel
-data.
-.\"*********************************************************
-.TP
-.B \-\-tran-window n
-Transition window \-\- our old key can live this many seconds
-after a new a key renegotiation begins (default = 3600 seconds).
-This feature allows for a graceful transition from old to new
-key, and removes the key renegotiation sequence from the critical
-path of tunnel data forwarding.
-.\"*********************************************************
-.TP
-.B \-\-single-session
-After initially connecting to a remote peer, disallow any new connections.
-Using this
-option means that a remote peer cannot connect, disconnect, and then
-reconnect.
-
-If the daemon is reset by a signal or
-.B \-\-ping-restart,
-it will allow one new connection.
-
-.B \-\-single-session
-can be used with
-.B \-\-ping-exit
-or
-.B \-\-inactive
-to create a single dynamic session that will exit when finished.
-.\"*********************************************************
-.TP
-.B \-\-tls-exit
-Exit on TLS negotiation failure.
-.\"*********************************************************
-.TP
-.B \-\-tls-auth file [direction]
-Add an additional layer of HMAC authentication on top of the TLS
-control channel to protect against DoS attacks.
-
-In a nutshell,
-.B \-\-tls-auth
-enables a kind of "HMAC firewall" on OpenVPN's TCP/UDP port,
-where TLS control channel packets
-bearing an incorrect HMAC signature can be dropped immediately without
-response.
-
-.B file
-(required) is a file in OpenVPN static key format which can be generated by
-.B \-\-genkey
-
-Older versions (up to 2.3) supported a freeform passphrase file.
-This is no longer supported in newer versions (2.4+).
-
-See the
-.B \-\-secret
-option for more information on the optional
-.B direction
-parameter.
-
-.B \-\-tls-auth
-is recommended when you are running OpenVPN in a mode where
-it is listening for packets from any IP address, such as when
-.B \-\-remote
-is not specified, or
-.B \-\-remote
-is specified with
-.B \-\-float.
-
-The rationale for
-this feature is as follows. TLS requires a multi-packet exchange
-before it is able to authenticate a peer. During this time
-before authentication, OpenVPN is allocating resources (memory
-and CPU) to this potential peer. The potential peer is also
-exposing many parts of OpenVPN and the OpenSSL library to the packets
-it is sending. Most successful network attacks today seek
-to either exploit bugs in programs (such as buffer overflow attacks) or
-force a program to consume so many resources that it becomes unusable.
-Of course the first line of defense is always to produce clean,
-well-audited code. OpenVPN has been written with buffer overflow
-attack prevention as a top priority.
-But as history has shown, many of the most widely used
-network applications have, from time to time,
-fallen to buffer overflow attacks.
-
-So as a second line of defense, OpenVPN offers
-this special layer of authentication on top of the TLS control channel so that
-every packet on the control channel is authenticated by an
-HMAC signature and a unique ID for replay protection.
-This signature will also help protect against DoS (Denial of Service) attacks.
-An important rule of thumb in reducing vulnerability to DoS attacks is to
-minimize the amount of resources a potential, but as yet unauthenticated,
-client is able to consume.
-
-.B \-\-tls-auth
-does this by signing every TLS control channel packet with an HMAC signature,
-including packets which are sent before the TLS level has had a chance
-to authenticate the peer.
-The result is that packets without
-the correct signature can be dropped immediately upon reception,
-before they have a chance to consume additional system resources
-such as by initiating a TLS handshake.
-.B \-\-tls-auth
-can be strengthened by adding the
-.B \-\-replay-persist
-option which will keep OpenVPN's replay protection state
-in a file so that it is not lost across restarts.
-
-It should be emphasized that this feature is optional and that the
-passphrase/key file used with
-.B \-\-tls-auth
-gives a peer nothing more than the power to initiate a TLS
-handshake. It is not used to encrypt or authenticate any tunnel data.
-.\"*********************************************************
-.TP
-.B \-\-askpass [file]
-Get certificate password from console or
-.B file
-before we daemonize.
-
-For the extremely
-security conscious, it is possible to protect your private key with
-a password. Of course this means that every time the OpenVPN
-daemon is started you must be there to type the password. The
-.B \-\-askpass
-option allows you to start OpenVPN from the command line. It will
-query you for a password before it daemonizes. To protect a private
-key with a password you should omit the
-.B -nodes
-option when you use the
-.B openssl
-command line tool to manage certificates and private keys.
-
-If
-.B file
-is specified, read the password from the first line of
-.B file.
-Keep in mind that storing your password in a file
-to a certain extent invalidates the extra security provided by
-using an encrypted key (Note: OpenVPN
-will only read passwords from a file if it has been built
-with the \-\-enable-password-save configure option, or on Windows
-by defining ENABLE_PASSWORD_SAVE in win/settings.in).
-.\"*********************************************************
-.TP
-.B \-\-auth-nocache
-Don't cache
-.B \-\-askpass
-or
-.B \-\-auth-user-pass
-username/passwords in virtual memory.
-
-If specified, this directive will cause OpenVPN to immediately
-forget username/password inputs after they are used. As a result,
-when OpenVPN needs a username/password, it will prompt for input
-from stdin, which may be multiple times during the duration of an
-OpenVPN session.
-
-This directive does not affect the
-.B \-\-http-proxy
-username/password. It is always cached.
-.\"*********************************************************
-.TP
-.B \-\-tls-verify cmd
-Run command
-.B cmd
-to verify the X509 name of a
-pending TLS connection that has otherwise passed all other
-tests of certification (except for revocation via
-.B \-\-crl-verify
-directive; the revocation test occurs after the
-.B \-\-tls-verify
-test).
-
-.B cmd
-should return 0 to allow the TLS handshake to proceed, or 1 to fail.
-
-.B cmd
-consists of a path to script (or executable program), optionally
-followed by arguments. The path and arguments may be single- or double-quoted
-and/or escaped using a backslash, and should be separated by one or more spaces.
-
-When
-.B cmd
-is executed two arguments are appended after any arguments specified in
-.B cmd
-, as follows:
-
-.B cmd certificate_depth subject
-
-These arguments are, respectively, the current certificate depth and
-the X509 common name (cn) of the peer.
-
-This feature is useful if the peer you want to trust has a certificate
-which was signed by a certificate authority who also signed many
-other certificates, where you don't necessarily want to trust all of them,
-but rather be selective about which
-peer certificate you will accept. This feature allows you to write a script
-which will test the X509 name on a certificate and decide whether or
-not it should be accepted. For a simple perl script which will test
-the common name field on the certificate, see the file
-.B verify-cn
-in the OpenVPN distribution.
-
-See the "Environmental Variables" section below for
-additional parameters passed as environmental variables.
-.\"*********************************************************
-.TP
-.B \-\-tls-export-cert directory
-Store the certificates the clients uses upon connection to this
-directory. This will be done before \-\-tls-verify is called. The
-certificates will use a temporary name and will be deleted when
-the tls-verify script returns. The file name used for the certificate
-is available via the peer_cert environment variable.
-.\"*********************************************************
-.TP
-.B \-\-x509-username-field [ext:\]fieldname
-Field in the X.509 certificate subject to be used as the username (default=CN).
-Typically, this option is specified with
-.B fieldname
-as either of the following:
-
-.B \-\-x509-username-field
-emailAddress
-.br
-.B \-\-x509-username-field ext:\fRsubjectAltName
-
-The first example uses the value of the "emailAddress" attribute in the
-certificate's Subject field as the username. The second example uses
-the
-.B ext:
-prefix to signify that the X.509 extension
-.B fieldname
-"subjectAltName" be searched for an rfc822Name (email) field to be used
-as the username. In cases where there are multiple email addresses
-in
-.B ext:fieldname\fR,
-the last occurrence is chosen.
-
-When this option is used, the
-.B \-\-verify-x509-name
-option will match against the chosen
-.B fieldname
-instead of the Common Name.
-
-.B Please note:
-This option has a feature which will convert an all-lowercase
-.B fieldname
-to uppercase characters, e.g., ou -> OU. A mixed-case
-.B fieldname
-or one having the
-.B ext:
-prefix will be left as-is. This automatic upcasing feature
-is deprecated and will be removed in a future release.
-.\"*********************************************************
-.TP
-.B \-\-tls-remote name (DEPRECATED)
-Accept connections only from a host with X509 name
-or common name equal to
-.B name.
-The remote host must also pass all other tests
-of verification.
-
-.B NOTE:
-Because tls-remote may test against a common name prefix,
-only use this option when you are using OpenVPN with a custom CA
-certificate that is under your control.
-Never use this option when your client certificates are signed by
-a third party, such as a commercial web CA.
-
-Name can also be a common name prefix, for example if you
-want a client to only accept connections to "Server-1",
-"Server-2", etc., you can simply use
-.B \-\-tls-remote Server
-
-Using a common name prefix is a useful alternative to managing
-a CRL (Certificate Revocation List) on the client, since it allows the client
-to refuse all certificates except for those associated
-with designated servers.
-
-.B \-\-tls-remote
-is a useful replacement for the
-.B \-\-tls-verify
-option to verify the remote host, because
-.B \-\-tls-remote
-works in a
-.B \-\-chroot
-environment too.
-
-.B Please also note:
-This option is now deprecated. It will be removed either in OpenVPN v2.4
-or v2.5. So please make sure you support the new X.509 name formatting
-described with the
-.B \-\-compat-names
-option as soon as possible by updating your configurations to use
-.B \-\-verify-x509-name
-instead.
-.\"*********************************************************
-.TP
-.B \-\-verify-x509-name name type
-Accept connections only if a host's X.509 name is equal to
-.B name.
-The remote host must also pass all other tests of verification.
-
-Which X.509 name is compared to
-.B name
-depends on the setting of type.
-.B type
-can be "subject" to match the complete subject DN (default),
-"name" to match a subject RDN or "name-prefix" to match a subject RDN prefix.
-Which RDN is verified as name depends on the
-.B \-\-x509-username-field
-option. But it defaults to the common name (CN), e.g. a certificate with a
-subject DN "C=KG, ST=NA, L=Bishkek, CN=Server-1" would be matched by:
-
-.B \-\-verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1'
-and
-.B \-\-verify-x509-name Server-1 name
-or you could use
-.B \-\-verify-x509-name Server- name-prefix
-if you want a client to only accept connections to "Server-1", "Server-2", etc.
-
-.B \-\-verify-x509-name
-is a useful replacement for the
-.B \-\-tls-verify
-option to verify the remote host, because
-.B \-\-verify-x509-name
-works in a
-.B \-\-chroot
-environment without any dependencies.
-
-Using a name prefix is a useful alternative to managing
-a CRL (Certificate Revocation List) on the client, since it allows the client
-to refuse all certificates except for those associated
-with designated servers.
-
-.B NOTE:
-Test against a name prefix only when you are using OpenVPN with
-a custom CA certificate that is under your control.
-Never use this option with type "name-prefix" when your client certificates
-are signed by a third party, such as a commercial web CA.
-.\"*********************************************************
-.TP
-.B \-\-x509-track attribute
-Save peer X509
-.B attribute
-value in environment for use by plugins and management interface.
-Prepend a '+' to
-.B attribute
-to save values from full cert chain. Values will be encoded
-as X509_<depth>_<attribute>=<value>. Multiple
-.B \-\-x509-track
-options can be defined to track multiple attributes.
-Not available with PolarSSL.
-.\"*********************************************************
-.TP
-.B \-\-ns-cert-type client|server
-Require that peer certificate was signed with an explicit
-.B nsCertType
-designation of "client" or "server".
-
-This is a useful security option for clients, to ensure that
-the host they connect with is a designated server.
-
-See the easy-rsa/build-key-server script for an example
-of how to generate a certificate with the
-.B nsCertType
-field set to "server".
-
-If the server certificate's nsCertType field is set
-to "server", then the clients can verify this with
-.B \-\-ns-cert-type server.
-
-This is an important security precaution to protect against
-a man-in-the-middle attack where an authorized client
-attempts to connect to another client by impersonating the server.
-The attack is easily prevented by having clients verify
-the server certificate using any one of
-.B \-\-ns-cert-type, \-\-verify-x509-name,
-or
-.B \-\-tls-verify.
-.\"*********************************************************
-.TP
-.B \-\-remote-cert-ku v...
-Require that peer certificate was signed with an explicit
-.B key usage.
-
-This is a useful security option for clients, to ensure that
-the host they connect to is a designated server.
-
-The key usage should be encoded in hex, more than one key
-usage can be specified.
-.\"*********************************************************
-.TP
-.B \-\-remote-cert-eku oid
-Require that peer certificate was signed with an explicit
-.B extended key usage.
-
-This is a useful security option for clients, to ensure that
-the host they connect to is a designated server.
-
-The extended key usage should be encoded in oid notation, or
-OpenSSL symbolic representation.
-.\"*********************************************************
-.TP
-.B \-\-remote-cert-tls client|server
-Require that peer certificate was signed with an explicit
-.B key usage
-and
-.B extended key usage
-based on RFC3280 TLS rules.
-
-This is a useful security option for clients, to ensure that
-the host they connect to is a designated server.
-
-The
-.B \-\-remote-cert-tls client
-option is equivalent to
-.B
-\-\-remote-cert-ku 80 08 88 \-\-remote-cert-eku "TLS Web Client Authentication"
-
-The key usage is digitalSignature and/or keyAgreement.
-
-The
-.B \-\-remote-cert-tls server
-option is equivalent to
-.B
-\-\-remote-cert-ku a0 88 \-\-remote-cert-eku "TLS Web Server Authentication"
-
-The key usage is digitalSignature and ( keyEncipherment or keyAgreement ).
-
-This is an important security precaution to protect against
-a man-in-the-middle attack where an authorized client
-attempts to connect to another client by impersonating the server.
-The attack is easily prevented by having clients verify
-the server certificate using any one of
-.B \-\-remote-cert-tls, \-\-verify-x509-name,
-or
-.B \-\-tls-verify.
-.\"*********************************************************
-.TP
-.B \-\-crl-verify crl ['dir']
-Check peer certificate against the file
-.B crl
-in PEM format.
-
-A CRL (certificate revocation list) is used when a particular key is
-compromised but when the overall PKI is still intact.
-
-Suppose you had a PKI consisting of a CA, root certificate, and a number of
-client certificates. Suppose a laptop computer containing a client key and
-certificate was stolen. By adding the stolen certificate to the CRL file,
-you could reject any connection which attempts to use it, while preserving the
-overall integrity of the PKI.
-
-The only time when it would be necessary to rebuild the entire PKI from scratch would be
-if the root certificate key itself was compromised.
-
-If the optional
-.B dir
-flag is specified, enable a different mode where
-.B crl
-is a directory containing files named as revoked serial numbers
-(the files may be empty, the contents are never read). If a client
-requests a connection, where the client certificate serial number
-(decimal string) is the name of a file present in the directory,
-it will be rejected.
-.\"*********************************************************
-.SS SSL Library information:
-.\"*********************************************************
-.TP
-.B \-\-show-ciphers
-(Standalone)
-Show all cipher algorithms to use with the
-.B \-\-cipher
-option.
-.\"*********************************************************
-.TP
-.B \-\-show-digests
-(Standalone)
-Show all message digest algorithms to use with the
-.B \-\-auth
-option.
-.\"*********************************************************
-.TP
-.B \-\-show-tls
-(Standalone)
-Show all TLS ciphers (TLS used only as a control channel). The TLS
-ciphers will be sorted from highest preference (most secure) to
-lowest.
-.\"*********************************************************
-.TP
-.B \-\-show-engines
-(Standalone)
-Show currently available hardware-based crypto acceleration
-engines supported by the OpenSSL library.
-.\"*********************************************************
-.TP
-.B \-\-show-curves
-(Standalone)
-Show all available elliptic curves to use with the
-.B \-\-ecdh-curve
-option.
-.\"*********************************************************
-.SS Generate a random key:
-Used only for non-TLS static key encryption mode.
-.\"*********************************************************
-.TP
-.B \-\-genkey
-(Standalone)
-Generate a random key to be used as a shared secret,
-for use with the
-.B \-\-secret
-option. This file must be shared with the
-peer over a pre-existing secure channel such as
-.BR scp (1)
-.
-.\"*********************************************************
-.TP
-.B \-\-secret file
-Write key to
-.B file.
-.\"*********************************************************
-.SS TUN/TAP persistent tunnel config mode:
-Available with linux 2.4.7+. These options comprise a standalone mode
-of OpenVPN which can be used to create and delete persistent tunnels.
-.\"*********************************************************
-.TP
-.B \-\-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
-.B \-\-up
-and
-.B \-\-down
-scripts to run the appropriate
-.BR ifconfig (8)
-and
-.BR 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
-.B \-\-ipchange
-option above).
-
-One disadvantage of persistent tunnels is that it is harder to automatically
-configure their MTU value (see
-.B \-\-link-mtu
-and
-.B \-\-tun-mtu
-above).
-
-On some platforms such as Windows, TAP-Win32 tunnels are persistent by
-default.
-.\"*********************************************************
-.TP
-.B \-\-rmtun
-(Standalone)
-Remove a persistent tunnel.
-.\"*********************************************************
-.TP
-.B \-\-dev tunX | tapX
-TUN/TAP device
-.\"*********************************************************
-.TP
-.B \-\-user user
-Optional user to be owner of this tunnel.
-.\"*********************************************************
-.TP
-.B \-\-group group
-Optional group to be owner of this tunnel.
-.\"*********************************************************
-.SS Windows-Specific Options:
-.\"*********************************************************
-.TP
-.B \-\-win-sys path
-Set the Windows system directory pathname to use when looking for system
-executables such as
-.B route.exe
-and
-.B netsh.exe.
-By default, if this directive is
-not specified, OpenVPN will use the SystemRoot environment variable.
-
-This option have changed behaviour in OpenVPN 2.3. Earlier you had to
-define
-.B --win-sys env
-to use the SystemRoot environment variable, otherwise it defaulted to C:\\WINDOWS.
-It is not needed to use the
-.B env
-keyword any more, and it will just be ignored. A warning is logged when this
-is found in the configuration file.
-.\"*********************************************************
-.TP
-.B \-\-ip-win32 method
-When using
-.B \-\-ifconfig
-on Windows, set the TAP-Win32 adapter
-IP address and netmask using
-.B method.
-Don't use this option unless you are also using
-.B \-\-ifconfig.
-
-.B 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.
-
-.B 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
-.B \-\-dev tap
-mode, OpenVPN will
-take the normally unused first address in the subnet. For example,
-if your subnet is 192.168.4.0 netmask 255.255.255.0, then
-OpenVPN will take the IP address 192.168.4.0 to use as the
-virtual DHCP server address. In
-.B \-\-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 > -256 and < 256 and which defaults to 0.
-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
-.B 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
-.B 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.
-
-.B 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.
-
-.B 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."
-
-.B adaptive \-\-
-(Default) Try
-.B dynamic
-method initially and fail over to
-.B 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
-.B 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
-.B adaptive
-mode to use
-.B netsh
-immediately, rather than trying
-.B dynamic
-first. To "unstick" the
-.B adaptive
-mode from using
-.B netsh,
-run OpenVPN at least once using the
-.B dynamic
-mode to restore the TAP-Win32 adapter TCP/IP properties
-to a DHCP configuration.
-.\"*********************************************************
-.TP
-.B \-\-route-method m
-Which method
-.B m
-to use for adding routes on Windows?
-
-.B adaptive
-(default) \-\- Try IP helper API first. If that fails, fall
-back to the route.exe shell command.
-.br
-.B ipapi
-\-\- Use IP helper API.
-.br
-.B exe
-\-\- Call the route.exe shell command.
-.\"*********************************************************
-.TP
-.B \-\-dhcp-option type [parm]
-Set extended TAP-Win32 TCP/IP properties, must
-be used with
-.B \-\-ip-win32 dynamic
-or
-.B \-\-ip-win32 adaptive.
-This option can be used to set additional TCP/IP properties
-on the TAP-Win32 adapter, and is particularly useful for
-configuring an OpenVPN client to access a Samba server
-across the VPN.
-
-.B DOMAIN name \-\-
-Set Connection-specific DNS Suffix.
-
-.B DNS addr \-\-
-Set primary domain name server address. Repeat
-this option to set secondary DNS server addresses.
-
-.B WINS addr \-\-
-Set primary WINS server address (NetBIOS over TCP/IP Name Server).
-Repeat this option to set secondary WINS server addresses.
-
-.B NBDD addr \-\-
-Set primary NBDD server address (NetBIOS over TCP/IP Datagram Distribution Server)
-Repeat this option
-to set secondary NBDD server addresses.
-
-.B NTP addr \-\-
-Set primary NTP server address (Network Time Protocol).
-Repeat this option
-to set secondary NTP server addresses.
-
-.B NBT type \-\-
-Set NetBIOS over TCP/IP Node type. Possible options:
-.B 1
-= b-node (broadcasts),
-.B 2
-= p-node (point-to-point
-name queries to a WINS server),
-.B 4
-= m-node (broadcast
-then query name server), and
-.B 8
-= h-node (query name server, then broadcast).
-
-.B 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)
-
-.B DISABLE-NBT \-\-
-Disable Netbios-over-TCP/IP.
-
-Note that if
-.B \-\-dhcp-option
-is pushed via
-.B \-\-push
-to a non-windows client, the option will be saved in the client's
-environment before the up script is called, under
-the name "foreign_option_{n}".
-.\"*********************************************************
-.TP
-.B \-\-tap-sleep n
-Cause OpenVPN to sleep for
-.B 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
-.B \-\-ifconfig
-and
-.B \-\-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.
-.\"*********************************************************
-.TP
-.B \-\-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.
-.\"*********************************************************
-.TP
-.B \-\-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.
-.\"*********************************************************
-.TP
-.B \-\-dhcp-release
-Ask Windows to release the TAP adapter lease on shutdown.
-This option has the same caveats as
-.B \-\-dhcp-renew
-above.
-.\"*********************************************************
-.TP
-.B \-\-register-dns
-Run net stop dnscache, net start dnscache, ipconfig /flushdns
-and ipconfig /registerdns on connection initiation.
-This is known to kick Windows into
-recognizing pushed DNS servers.
-.\"*********************************************************
-.TP
-.B \-\-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.
-.\"*********************************************************
-.TP
-.B \-\-service exit-event [0|1]
-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. 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.
-
-.B 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
-.B exit-event
-and normally defaults to 0.
-
-Multiple OpenVPN processes can be simultaneously executed with the same
-.B exit-event
-parameter. In any case, the controlling process can signal
-.B exit-event,
-causing all such OpenVPN processes to exit.
-
-When executing an OpenVPN process using the
-.B \-\-service
-directive, OpenVPN will probably not have a console
-window to output status/error
-messages, therefore it is useful to use
-.B \-\-log
-or
-.B \-\-log-append
-to write these messages to a file.
-.\"*********************************************************
-.TP
-.B \-\-show-adapters
-(Standalone)
-Show available TAP-Win32 adapters which can be selected using the
-.B \-\-dev-node
-option. On non-Windows systems, the
-.BR ifconfig (8)
-command provides similar functionality.
-.\"*********************************************************
-.TP
-.B \-\-allow-nonadmin [TAP-adapter]
-(Standalone)
-Set
-.B TAP-adapter
-to allow access from non-administrative accounts. If
-.B 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.
-.\"*********************************************************
-.TP
-.B \-\-show-valid-subnets
-(Standalone)
-Show valid subnets for
-.B \-\-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).
-.\"*********************************************************
-.TP
-.B \-\-show-net
-(Standalone)
-Show OpenVPN's view of the system routing table and network
-adapter list.
-.\"*********************************************************
-.SS PKCS#11 Standalone Options:
-.\"*********************************************************
-.TP
-.B \-\-show-pkcs11-ids [provider] [cert_private]
-(Standalone)
-Show PKCS#11 token object list. Specify cert_private as 1
-if certificates are stored as private objects.
-
-If p11-kit is present on the system, the
-.B provider
-argument is optional; if omitted the default
-.B p11-kit-proxy.so
-module will be queried.
-
-.B \-\-verb
-option can be used BEFORE this option to produce debugging information.
-.\"*********************************************************
-.SS IPv6 Related Options
-.\"*********************************************************
-The following options exist to support IPv6 tunneling in peer-to-peer
-and client-server mode. All options are modeled after their IPv4
-counterparts, so more detailed explanations given there apply here
-as well (except for
-.B \-\-topology
-, which has no effect on IPv6).
-.TP
-.B --ifconfig-ipv6 ipv6addr/bits ipv6remote
-configure IPv6 address
-.B ipv6addr/bits
-on the ``tun'' device. The second parameter is used as route target for
-.B --route-ipv6
-if no gateway is specified.
-.TP
-.B --route-ipv6 ipv6addr/bits [gateway] [metric]
-setup IPv6 routing in the system to send the specified IPv6 network
-into OpenVPN's ``tun''. The gateway parameter is only used for
-IPv6 routes across ``tap'' devices, and if missing, the ``ipv6remote''
-field from
-.B --ifconfig-ipv6
-is used.
-.TP
-.B --server-ipv6 ipv6addr/bits
-convenience-function to enable a number of IPv6 related options at
-once, namely
-.B --ifconfig-ipv6, --ifconfig-ipv6-pool, --tun-ipv6
-and
-.B --push tun-ipv6
-Is only accepted if ``--mode server'' or ``--server'' is set.
-.TP
-.B --ifconfig-ipv6-pool ipv6addr/bits
-Specify an IPv6 address pool for dynamic assignment to clients. The
-pool starts at
-.B ipv6addr
-and increments by +1 for every new client (linear mode). The
-.B /bits
-setting controls the size of the pool. Due to implementation details,
-the pool size must be between /64 and /112.
-.TP
-.B --ifconfig-ipv6-push ipv6addr/bits ipv6remote
-for ccd/ per-client static IPv6 interface configuration, see
-.B --client-config-dir
-and
-.B --ifconfig-push
-for more details.
-.TP
-.B --iroute-ipv6 ipv6addr/bits
-for ccd/ per-client static IPv6 route configuration, see
-.B --iroute
-for more details how to setup and use this, and how
-.B --iroute
-and
-.B --route
-interact.
-
-.\"*********************************************************
-.SH SCRIPTING AND ENVIRONMENTAL VARIABLES
-OpenVPN exports a series
-of environmental variables for use by user-defined scripts.
-.\"*********************************************************
-.SS Script Order of Execution
-.\"*********************************************************
-.TP
-.B \-\-up
-Executed after TCP/UDP socket bind and TUN/TAP open.
-.\"*********************************************************
-.TP
-.B \-\-tls-verify
-Executed when we have a still untrusted remote peer.
-.\"*********************************************************
-.TP
-.B \-\-ipchange
-Executed after connection authentication, or remote IP address change.
-.\"*********************************************************
-.TP
-.B \-\-client-connect
-Executed in
-.B \-\-mode server
-mode immediately after client authentication.
-.\"*********************************************************
-.TP
-.B \-\-route-up
-Executed after connection authentication, either
-immediately after, or some number of seconds after
-as defined by the
-.B \-\-route-delay
-option.
-.\"*********************************************************
-.TP
-.B \-\-route-pre-down
-Executed right before the routes are removed.
-.\"*********************************************************
-.TP
-.B \-\-client-disconnect
-Executed in
-.B \-\-mode server
-mode on client instance shutdown.
-.\"*********************************************************
-.TP
-.B \-\-down
-Executed after TCP/UDP and TUN/TAP close.
-.\"*********************************************************
-.TP
-.B \-\-learn-address
-Executed in
-.B \-\-mode server
-mode whenever an IPv4 address/route or MAC address is added to OpenVPN's
-internal routing table.
-.\"*********************************************************
-.TP
-.B \-\-auth-user-pass-verify
-Executed in
-.B \-\-mode server
-mode on new client connections, when the client is
-still untrusted.
-.\"*********************************************************
-.SS String Types and Remapping
-In certain cases, OpenVPN will perform remapping of characters
-in strings. Essentially, any characters outside the set of
-permitted characters for each string type will be converted
-to underbar ('_').
-
-.B Q:
-Why is string remapping necessary?
-
-.B A:
-It's an important security feature to prevent the malicious coding of
-strings from untrusted sources to be passed as parameters to scripts,
-saved in the environment, used as a common name, translated to a filename,
-etc.
-
-.B Q:
-Can string remapping be disabled?
-
-.B A:
-Yes, by using the
-.B \-\-no-name-remapping
-option, however this should be considered an advanced option.
-
-Here is a brief rundown of OpenVPN's current string types and the
-permitted character class for each string:
-
-.B X509 Names:
-Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), at
-('@'), colon (':'), slash ('/'), and equal ('='). Alphanumeric is defined
-as a character which will cause the C library isalnum() function to return
-true.
-
-.B Common Names:
-Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), and at
-('@').
-
-.B \-\-auth-user-pass username:
-Same as Common Name, with one exception: starting with OpenVPN 2.0.1,
-the username is passed to the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin in its raw form,
-without string remapping.
-
-.B \-\-auth-user-pass password:
-Any "printable" character except CR or LF.
-Printable is defined to be a character which will cause the C library
-isprint() function to return true.
-
-.B \-\-client-config-dir filename as derived from common name or username:
-Alphanumeric, underbar ('_'), dash ('-'), and dot ('.') except for "." or
-".." as standalone strings. As of 2.0.1-rc6, the at ('@') character has
-been added as well for compatibility with the common name character class.
-
-.B Environmental variable names:
-Alphanumeric or underbar ('_').
-
-.B Environmental variable values:
-Any printable character.
-
-For all cases, characters in a string which are not members of the legal
-character class for that string type will be remapped to underbar ('_').
-.\"*********************************************************
-.SS Environmental Variables
-Once set, a variable is persisted
-indefinitely until it is reset by a new value or a restart,
-
-As of OpenVPN 2.0-beta12, in server mode, environmental
-variables set by OpenVPN
-are scoped according to the client objects
-they are
-associated with, so there should not be any issues with
-scripts having access to stale, previously set variables
-which refer to different client instances.
-.\"*********************************************************
-.TP
-.B bytes_received
-Total number of bytes received from client during VPN session.
-Set prior to execution of the
-.B \-\-client-disconnect
-script.
-.\"*********************************************************
-.TP
-.B bytes_sent
-Total number of bytes sent to client during VPN session.
-Set prior to execution of the
-.B \-\-client-disconnect
-script.
-.\"*********************************************************
-.TP
-.B common_name
-The X509 common name of an authenticated client.
-Set prior to execution of
-.B \-\-client-connect, \-\-client-disconnect,
-and
-.B \-\-auth-user-pass-verify
-scripts.
-.\"*********************************************************
-.TP
-.B config
-Name of first
-.B \-\-config
-file.
-Set on program initiation and reset on SIGHUP.
-.\"*********************************************************
-.TP
-.B daemon
-Set to "1" if the
-.B \-\-daemon
-directive is specified, or "0" otherwise.
-Set on program initiation and reset on SIGHUP.
-.\"*********************************************************
-.TP
-.B daemon_log_redirect
-Set to "1" if the
-.B \-\-log
-or
-.B \-\-log-append
-directives are specified, or "0" otherwise.
-Set on program initiation and reset on SIGHUP.
-.\"*********************************************************
-.TP
-.B dev
-The actual name of the TUN/TAP device, including
-a unit number if it exists.
-Set prior to
-.B \-\-up
-or
-.B \-\-down
-script execution.
-.\"*********************************************************
-.TP
-.B foreign_option_{n}
-An option pushed via
-.B \-\-push
-to a client which does not natively support it,
-such as
-.B \-\-dhcp-option
-on a non-Windows system, will be recorded to this
-environmental variable sequence prior to
-.B \-\-up
-script execution.
-.\"*********************************************************
-.TP
-.B ifconfig_broadcast
-The broadcast address for the virtual
-ethernet segment which is derived from the
-.B \-\-ifconfig
-option when
-.B \-\-dev tap
-is used.
-Set prior to OpenVPN calling the
-.I ifconfig
-or
-.I netsh
-(windows version of ifconfig) commands which
-normally occurs prior to
-.B \-\-up
-script execution.
-.\"*********************************************************
-.TP
-.B ifconfig_ipv6_local
-The local VPN endpoint IPv6 address specified in the
-.B \-\-ifconfig-ipv6
-option (first parameter).
-Set prior to OpenVPN calling the
-.I ifconfig
-or
-.I netsh
-(windows version of ifconfig) commands which
-normally occurs prior to
-.B \-\-up
-script execution.
-.\"*********************************************************
-.TP
-.B ifconfig_ipv6_netbits
-The prefix length of the IPv6 network on the VPN interface. Derived from
-the /nnn parameter of the IPv6 address in the
-.B \-\-ifconfig-ipv6
-option (first parameter).
-Set prior to OpenVPN calling the
-.I ifconfig
-or
-.I netsh
-(windows version of ifconfig) commands which
-normally occurs prior to
-.B \-\-up
-script execution.
-.\"*********************************************************
-.TP
-.B ifconfig_ipv6_remote
-The remote VPN endpoint IPv6 address specified in the
-.B \-\-ifconfig-ipv6
-option (second parameter).
-Set prior to OpenVPN calling the
-.I ifconfig
-or
-.I netsh
-(windows version of ifconfig) commands which
-normally occurs prior to
-.B \-\-up
-script execution.
-.\"*********************************************************
-.TP
-.B ifconfig_local
-The local VPN endpoint IP address specified in the
-.B \-\-ifconfig
-option (first parameter).
-Set prior to OpenVPN calling the
-.I ifconfig
-or
-.I netsh
-(windows version of ifconfig) commands which
-normally occurs prior to
-.B \-\-up
-script execution.
-.\"*********************************************************
-.TP
-.B ifconfig_remote
-The remote VPN endpoint IP address specified in the
-.B \-\-ifconfig
-option (second parameter) when
-.B \-\-dev tun
-is used.
-Set prior to OpenVPN calling the
-.I ifconfig
-or
-.I netsh
-(windows version of ifconfig) commands which
-normally occurs prior to
-.B \-\-up
-script execution.
-.\"*********************************************************
-.TP
-.B ifconfig_netmask
-The subnet mask of the virtual ethernet segment
-that is specified as the second parameter to
-.B \-\-ifconfig
-when
-.B \-\-dev tap
-is being used.
-Set prior to OpenVPN calling the
-.I ifconfig
-or
-.I netsh
-(windows version of ifconfig) commands which
-normally occurs prior to
-.B \-\-up
-script execution.
-.\"*********************************************************
-.TP
-.B ifconfig_pool_local_ip
-The local
-virtual IP address for the TUN/TAP tunnel taken from an
-.B \-\-ifconfig-push
-directive if specified, or otherwise from
-the ifconfig pool (controlled by the
-.B \-\-ifconfig-pool
-config file directive).
-Only set for
-.B \-\-dev tun
-tunnels.
-This option is set on the server prior to execution
-of the
-.B \-\-client-connect
-and
-.B \-\-client-disconnect
-scripts.
-.\"*********************************************************
-.TP
-.B ifconfig_pool_netmask
-The
-virtual IP netmask for the TUN/TAP tunnel taken from an
-.B \-\-ifconfig-push
-directive if specified, or otherwise from
-the ifconfig pool (controlled by the
-.B \-\-ifconfig-pool
-config file directive).
-Only set for
-.B \-\-dev tap
-tunnels.
-This option is set on the server prior to execution
-of the
-.B \-\-client-connect
-and
-.B \-\-client-disconnect
-scripts.
-.\"*********************************************************
-.TP
-.B ifconfig_pool_remote_ip
-The remote
-virtual IP address for the TUN/TAP tunnel taken from an
-.B \-\-ifconfig-push
-directive if specified, or otherwise from
-the ifconfig pool (controlled by the
-.B \-\-ifconfig-pool
-config file directive).
-This option is set on the server prior to execution
-of the
-.B \-\-client-connect
-and
-.B \-\-client-disconnect
-scripts.
-.\"*********************************************************
-.TP
-.B link_mtu
-The maximum packet size (not including the IP header)
-of tunnel data in UDP tunnel transport mode.
-Set prior to
-.B \-\-up
-or
-.B \-\-down
-script execution.
-.\"*********************************************************
-.TP
-.B local
-The
-.B \-\-local
-parameter.
-Set on program initiation and reset on SIGHUP.
-.\"*********************************************************
-.TP
-.B local_port
-The local port number or name, specified by
-.B \-\-port
-or
-.B \-\-lport.
-Set on program initiation and reset on SIGHUP.
-.\"*********************************************************
-.TP
-.B password
-The password provided by a connecting client.
-Set prior to
-.B \-\-auth-user-pass-verify
-script execution only when the
-.B via-env
-modifier is specified, and deleted from the environment
-after the script returns.
-.\"*********************************************************
-.TP
-.B proto
-The
-.B \-\-proto
-parameter.
-Set on program initiation and reset on SIGHUP.
-.\"*********************************************************
-.TP
-.B remote_{n}
-The
-.B \-\-remote
-parameter.
-Set on program initiation and reset on SIGHUP.
-.\"*********************************************************
-.TP
-.B remote_port_{n}
-The remote port number, specified by
-.B \-\-port
-or
-.B \-\-rport.
-Set on program initiation and reset on SIGHUP.
-.\"*********************************************************
-.TP
-.B route_net_gateway
-The pre-existing default IP gateway in the system routing
-table.
-Set prior to
-.B \-\-up
-script execution.
-.\"*********************************************************
-.TP
-.B route_vpn_gateway
-The default gateway used by
-.B \-\-route
-options, as specified in either the
-.B \-\-route-gateway
-option or the second parameter to
-.B \-\-ifconfig
-when
-.B \-\-dev tun
-is specified.
-Set prior to
-.B \-\-up
-script execution.
-.\"*********************************************************
-.TP
-.B route_{parm}_{n}
-A set of variables which define each route to be added, and
-are set prior to
-.B \-\-up
-script execution.
-
-.B parm
-will be one of "network", "netmask", "gateway", or "metric".
-
-.B n
-is the OpenVPN route number, starting from 1.
-
-If the network or gateway are resolvable DNS names,
-their IP address translations will be recorded rather
-than their names as denoted on the command line
-or configuration file.
-.\"*********************************************************
-.TP
-.B route_ipv6_{parm}_{n}
-A set of variables which define each IPv6 route to be added, and
-are set prior to
-.B \-\-up
-script execution.
-
-.B parm
-will be one of "network" or "gateway" ("netmask" is contained as "/nnn"
-in the route_ipv6_network_{n}, unlike IPv4 where it is passed in a separate
-environment variable).
-
-.B n
-is the OpenVPN route number, starting from 1.
-
-If the network or gateway are resolvable DNS names,
-their IP address translations will be recorded rather
-than their names as denoted on the command line
-or configuration file.
-.\"*********************************************************
-.TP
-.B peer_cert
-Temporary file name containing the client certificate upon
-connection. Useful in conjunction with --tls-verify
-.\"*********************************************************
-.TP
-.B script_context
-Set to "init" or "restart" prior to up/down script execution.
-For more information, see
-documentation for
-.B \-\-up.
-.\"*********************************************************
-.TP
-.B script_type
-Prior to execution of any script, this variable is set to the type of
-script being run. It can be one of the following:
-.B up, down, ipchange, route-up, tls-verify, auth-user-pass-verify,
-.B client-connect, client-disconnect,
-or
-.B learn-address.
-Set prior to execution of any script.
-.\"*********************************************************
-.TP
-.B signal
-The reason for exit or restart. Can be one of
-.B sigusr1, sighup, sigterm, sigint, inactive
-(controlled by
-.B \-\-inactive
-option),
-.B ping-exit
-(controlled by
-.B \-\-ping-exit
-option),
-.B ping-restart
-(controlled by
-.B \-\-ping-restart
-option),
-.B connection-reset
-(triggered on TCP connection reset),
-.B error,
-or
-.B unknown
-(unknown signal). This variable is set just prior to down script execution.
-.\"*********************************************************
-.TP
-.B time_ascii
-Client connection timestamp, formatted as a human-readable
-time string.
-Set prior to execution of the
-.B \-\-client-connect
-script.
-.\"*********************************************************
-.TP
-.B time_duration
-The duration (in seconds) of the client session which is now
-disconnecting.
-Set prior to execution of the
-.B \-\-client-disconnect
-script.
-.\"*********************************************************
-.TP
-.B time_unix
-Client connection timestamp, formatted as a unix integer
-date/time value.
-Set prior to execution of the
-.B \-\-client-connect
-script.
-.\"*********************************************************
-.TP
-.B tls_digest_{n}
-Contains the certificate SHA1 fingerprint/digest hash value,
-where
-.B n
-is the verification level. Only set for TLS connections. Set prior
-to execution of
-.B \-\-tls-verify
-script.
-.\"*********************************************************
-.TP
-.B tls_id_{n}
-A series of certificate fields from the remote peer,
-where
-.B n
-is the verification level. Only set for TLS connections. Set prior
-to execution of
-.B \-\-tls-verify
-script.
-.\"*********************************************************
-.TP
-.B tls_serial_{n}
-The serial number of the certificate from the remote peer,
-where
-.B n
-is the verification level. Only set for TLS connections. Set prior
-to execution of
-.B \-\-tls-verify
-script. This is in the form of a decimal string like "933971680", which is
-suitable for doing serial-based OCSP queries (with OpenSSL, do not
-prepend "0x" to the string) If something goes wrong while reading
-the value from the certificate it will be an empty string, so your
-code should check that.
-See the contrib/OCSP_check/OCSP_check.sh script for an example.
-.\"*********************************************************
-.TP
-.B tls_serial_hex_{n}
-Like
-.B tls_serial_{n}\fR,
-but in hex form (e.g. "12:34:56:78:9A").
-.\"*********************************************************
-.TP
-.B tun_mtu
-The MTU of the TUN/TAP device.
-Set prior to
-.B \-\-up
-or
-.B \-\-down
-script execution.
-.\"*********************************************************
-.TP
-.B trusted_ip (or trusted_ip6)
-Actual IP address of connecting client or peer which has been authenticated.
-Set prior to execution of
-.B \-\-ipchange, \-\-client-connect,
-and
-.B \-\-client-disconnect
-scripts.
-If using ipv6 endpoints (udp6, tcp6),
-.B trusted_ip6
-will be set instead.
-.\"*********************************************************
-.TP
-.B trusted_port
-Actual port number of connecting client or peer which has been authenticated.
-Set prior to execution of
-.B \-\-ipchange, \-\-client-connect,
-and
-.B \-\-client-disconnect
-scripts.
-.\"*********************************************************
-.TP
-.B untrusted_ip (or untrusted_ip6)
-Actual IP address of connecting client or peer which has not been authenticated
-yet. Sometimes used to
-.B nmap
-the connecting host in a
-.B \-\-tls-verify
-script to ensure it is firewalled properly.
-Set prior to execution of
-.B \-\-tls-verify
-and
-.B \-\-auth-user-pass-verify
-scripts.
-If using ipv6 endpoints (udp6, tcp6),
-.B untrusted_ip6
-will be set instead.
-.\"*********************************************************
-.TP
-.B untrusted_port
-Actual port number of connecting client or peer which has not been authenticated
-yet.
-Set prior to execution of
-.B \-\-tls-verify
-and
-.B \-\-auth-user-pass-verify
-scripts.
-.\"*********************************************************
-.TP
-.B username
-The username provided by a connecting client.
-Set prior to
-.B \-\-auth-user-pass-verify
-script execution only when the
-.B via-env
-modifier is specified.
-.\"*********************************************************
-.TP
-.B X509_{n}_{subject_field}
-An X509 subject field from the remote peer certificate,
-where
-.B n
-is the verification level. Only set for TLS connections. Set prior
-to execution of
-.B \-\-tls-verify
-script. This variable is similar to
-.B tls_id_{n}
-except the component X509 subject fields are broken out, and
-no string remapping occurs on these field values (except for remapping
-of control characters to "_").
-For example, the following variables would be set on the
-OpenVPN server using the sample client certificate
-in sample-keys (client.crt).
-Note that the verification level is 0 for the client certificate
-and 1 for the CA certificate.
-
-.nf
-.ft 3
-.in +4
-X509_0_emailAddress=me@myhost.mydomain
-X509_0_CN=Test-Client
-X509_0_O=OpenVPN-TEST
-X509_0_ST=NA
-X509_0_C=KG
-X509_1_emailAddress=me@myhost.mydomain
-X509_1_O=OpenVPN-TEST
-X509_1_L=BISHKEK
-X509_1_ST=NA
-X509_1_C=KG
-.in -4
-.ft
-.fi
-.\"*********************************************************
-.SH INLINE FILE SUPPORT
-OpenVPN allows including files in the main configuration for the
-.B \-\-ca, \-\-cert, \-\-dh, \-\-extra-certs, \-\-key, \-\-pkcs12, \-\-secret
-and
-.B \-\-tls-auth
-options.
-
-Each inline file started by the line
-.B <option>
-and ended by the line
-.B </option>
-
-Here is an example of an inline file usage
-
-.nf
-.ft 3
-.in +4
-<cert>
------BEGIN CERTIFICATE-----
-[...]
------END CERTIFICATE-----
-</cert>
-.in -4
-.ft
-.fi
-
-When using the inline file feature with
-.B \-\-pkcs12
-the inline file has to be base64 encoded. Encoding of a .p12 file into base64 can be done for example with OpenSSL by running
-.B openssl base64 -in input.p12
-
-.SH SIGNALS
-.TP
-.B SIGHUP
-Cause OpenVPN to close all TUN/TAP and
-network connections,
-restart, re-read the configuration file (if any),
-and reopen TUN/TAP and network connections.
-.\"*********************************************************
-.TP
-.B SIGUSR1
-Like
-.B SIGHUP,
-except don't re-read configuration file, and possibly don't close and reopen TUN/TAP
-device, re-read key files, preserve local IP address/port, or preserve most recently authenticated
-remote IP address/port based on
-.B \-\-persist-tun, \-\-persist-key, \-\-persist-local-ip,
-and
-.B \-\-persist-remote-ip
-options respectively (see above).
-
-This signal may also be internally generated by a timeout condition, governed
-by the
-.B \-\-ping-restart
-option.
-
-This signal, when combined with
-.B \-\-persist-remote-ip,
-may be
-sent when the underlying parameters of the host's network interface change
-such as when the host is a DHCP client and is assigned a new IP address.
-See
-.B \-\-ipchange
-above for more information.
-.\"*********************************************************
-.TP
-.B SIGUSR2
-Causes OpenVPN to display its current statistics (to the syslog
-file if
-.B \-\-daemon
-is used, or stdout otherwise).
-.\"*********************************************************
-.TP
-.B SIGINT, SIGTERM
-Causes OpenVPN to exit gracefully.
-.\"*********************************************************
-.SH TUN/TAP DRIVER SETUP
-If you are running Linux 2.4.7 or higher, you probably have the TUN/TAP driver
-already installed. If so, there are still a few things you need to do:
-
-Make device:
-.B mknod /dev/net/tun c 10 200
-
-Load driver:
-.B modprobe tun
-.\"*********************************************************
-.SH EXAMPLES
-Prior to running these examples, you should have OpenVPN installed on two
-machines with network connectivity between them. If you have not
-yet installed OpenVPN, consult the INSTALL file included in the OpenVPN
-distribution.
-.\"*********************************************************
-.SS TUN/TAP Setup:
-If you are using Linux 2.4 or higher,
-make the tun device node and load the tun module:
-.IP
-.B mknod /dev/net/tun c 10 200
-.LP
-.IP
-.B modprobe tun
-.LP
-If you installed from RPM, the
-.B mknod
-step may be omitted, because the RPM install does that for you.
-
-Only Linux 2.4 and newer are supported.
-
-For other platforms, consult the INSTALL file at
-.I http://openvpn.net/install.html
-for more information.
-.\"*********************************************************
-.SS Firewall Setup:
-If firewalls exist between
-the two machines, they should be set to forward UDP port 1194
-in both directions. If you do not have control over the firewalls
-between the two machines, you may still be able to use OpenVPN by adding
-.B \-\-ping 15
-to each of the
-.B openvpn
-commands used below in the examples (this will cause each peer to send out
-a UDP ping to its remote peer once every 15 seconds which will cause many
-stateful firewalls to forward packets in both directions
-without an explicit firewall rule).
-
-If you are using a Linux iptables-based firewall, you may need to enter
-the following command to allow incoming packets on the TUN device:
-.IP
-.B iptables -A INPUT -i tun+ -j ACCEPT
-.LP
-See the firewalls section below for more information on configuring firewalls
-for use with OpenVPN.
-.\"*********************************************************
-.SS VPN Address Setup:
-For purposes
-of our example, our two machines will be called
-.B may.kg
-and
-.B june.kg.
-If you are constructing a VPN over the internet, then replace
-.B may.kg
-and
-.B june.kg
-with the internet hostname or IP address that each machine will use
-to contact the other over the internet.
-
-Now we will choose the tunnel endpoints. Tunnel endpoints are
-private IP addresses that only have meaning in the context of
-the VPN. Each machine will use the tunnel endpoint of the other
-machine to access it over the VPN. In our example,
-the tunnel endpoint for may.kg
-will be 10.4.0.1 and for june.kg, 10.4.0.2.
-
-Once the VPN is established, you have essentially
-created a secure alternate path between the two hosts
-which is addressed by using the tunnel endpoints. You can
-control which network
-traffic passes between the hosts
-(a) over the VPN or (b) independently of the VPN, by choosing whether to use
-(a) the VPN endpoint address or (b) the public internet address,
-to access the remote host. For example if you are on may.kg and you wish to connect to june.kg
-via
-.B ssh
-without using the VPN (since
-.B ssh
-has its own built-in security) you would use the command
-.B ssh june.kg.
-However in the same scenario, you could also use the command
-.B telnet 10.4.0.2
-to create a telnet session with june.kg over the VPN, that would
-use the VPN to secure the session rather than
-.B ssh.
-
-You can use any address you wish for the
-tunnel endpoints
-but make sure that they are private addresses
-(such as those that begin with 10 or 192.168) and that they are
-not part of any existing subnet on the networks of
-either peer, unless you are bridging. If you use an address that is part of
-your local subnet for either of the tunnel endpoints,
-you will get a weird feedback loop.
-.\"*********************************************************
-.SS Example 1: A simple tunnel without security
-.LP
-On may:
-.IP
-.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9
-.LP
-On june:
-.IP
-.B openvpn \-\-remote may.kg \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9
-.LP
-Now verify the tunnel is working by pinging across the tunnel.
-.LP
-On may:
-.IP
-.B ping 10.4.0.2
-.LP
-On june:
-.IP
-.B ping 10.4.0.1
-.LP
-The
-.B \-\-verb 9
-option will produce verbose output, similar to the
-.BR tcpdump (8)
-program. Omit the
-.B \-\-verb 9
-option to have OpenVPN run quietly.
-.\"*********************************************************
-.SS Example 2: A tunnel with static-key security (i.e. using a pre-shared secret)
-First build a static key on may.
-.IP
-.B openvpn \-\-genkey \-\-secret key
-.LP
-This command will build a random key file called
-.B key
-(in ascii format).
-Now copy
-.B key
-to june over a secure medium such as by
-using the
-.BR scp (1)
-program.
-.LP
-On may:
-.IP
-.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \-\-secret key
-.LP
-On june:
-.IP
-.B openvpn \-\-remote may.kg \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \-\-secret key
-.LP
-Now verify the tunnel is working by pinging across the tunnel.
-.LP
-On may:
-.IP
-.B ping 10.4.0.2
-.LP
-On june:
-.IP
-.B ping 10.4.0.1
-.\"*********************************************************
-.SS Example 3: A tunnel with full TLS-based security
-For this test, we will designate
-.B may
-as the TLS client and
-.B june
-as the TLS server.
-.I Note that client or server designation only has meaning for the TLS subsystem. It has no bearing on OpenVPN's peer-to-peer, UDP-based communication model.
-
-First, build a separate certificate/key pair
-for both may and june (see above where
-.B \-\-cert
-is discussed for more info). Then construct
-Diffie Hellman parameters (see above where
-.B \-\-dh
-is discussed for more info). You can also use the
-included test files client.crt, client.key,
-server.crt, server.key and ca.crt.
-The .crt files are certificates/public-keys, the .key
-files are private keys, and ca.crt is a certification
-authority who has signed both
-client.crt and server.crt. For Diffie Hellman
-parameters you can use the included file dh1024.pem.
-.I Note that all client, server, and certificate authority certificates and keys included in the OpenVPN distribution are totally insecure and should be used for testing only.
-.LP
-On may:
-.IP
-.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-tls-client \-\-ca ca.crt \-\-cert client.crt \-\-key client.key \-\-reneg-sec 60 \-\-verb 5
-.LP
-On june:
-.IP
-.B openvpn \-\-remote may.kg \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-tls-server \-\-dh dh1024.pem \-\-ca ca.crt \-\-cert server.crt \-\-key server.key \-\-reneg-sec 60 \-\-verb 5
-.LP
-Now verify the tunnel is working by pinging across the tunnel.
-.LP
-On may:
-.IP
-.B ping 10.4.0.2
-.LP
-On june:
-.IP
-.B ping 10.4.0.1
-.LP
-Notice the
-.B \-\-reneg-sec 60
-option we used above. That tells OpenVPN to renegotiate
-the data channel keys every minute.
-Since we used
-.B \-\-verb 5
-above, you will see status information on each new key negotiation.
-
-For production operations, a key renegotiation interval of 60 seconds
-is probably too frequent. Omit the
-.B \-\-reneg-sec 60
-option to use OpenVPN's default key renegotiation interval of one hour.
-.\"*********************************************************
-.SS Routing:
-Assuming you can ping across the tunnel,
-the next step is to route a real subnet over
-the secure tunnel. Suppose that may and june have two network
-interfaces each, one connected
-to the internet, and the other to a private
-network. Our goal is to securely connect
-both private networks. We will assume that may's private subnet
-is 10.0.0.0/24 and june's is 10.0.1.0/24.
-.LP
-First, ensure that IP forwarding is enabled on both peers.
-On Linux, enable routing:
-.IP
-.B echo 1 > /proc/sys/net/ipv4/ip_forward
-.LP
-and enable TUN packet forwarding through the firewall:
-.IP
-.B iptables -A FORWARD -i tun+ -j ACCEPT
-.LP
-On may:
-.IP
-.B route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
-.LP
-On june:
-.IP
-.B route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
-.LP
-Now any machine on the 10.0.0.0/24 subnet can
-access any machine on the 10.0.1.0/24 subnet
-over the secure tunnel (or vice versa).
-
-In a production environment, you could put the route command(s)
-in a script and execute with the
-.B \-\-up
-option.
-.\"*********************************************************
-.SH FIREWALLS
-OpenVPN's usage of a single UDP port makes it fairly firewall-friendly.
-You should add an entry to your firewall rules to allow incoming OpenVPN
-packets. On Linux 2.4+:
-.IP
-.B iptables -A INPUT -p udp -s 1.2.3.4 \-\-dport 1194 -j ACCEPT
-.LP
-This will allow incoming packets on UDP port 1194 (OpenVPN's default UDP port)
-from an OpenVPN peer at 1.2.3.4.
-
-If you are using HMAC-based packet authentication (the default in any of
-OpenVPN's secure modes), having the firewall filter on source
-address can be considered optional, since HMAC packet authentication
-is a much more secure method of verifying the authenticity of
-a packet source. In that case:
-.IP
-.B iptables -A INPUT -p udp \-\-dport 1194 -j ACCEPT
-.LP
-would be adequate and would not render the host inflexible with
-respect to its peer having a dynamic IP address.
-
-OpenVPN also works well on stateful firewalls. In some cases, you may
-not need to add any static rules to the firewall list if you are
-using a stateful firewall that knows how to track UDP connections.
-If you specify
-.B \-\-ping n,
-OpenVPN will be guaranteed
-to send a packet to its peer at least once every
-.B n
-seconds. If
-.B n
-is less than the stateful firewall connection timeout, you can
-maintain an OpenVPN connection indefinitely without explicit
-firewall rules.
-
-You should also add firewall rules to allow incoming IP traffic on
-TUN or TAP devices such as:
-.IP
-.B iptables -A INPUT -i tun+ -j ACCEPT
-.LP
-to allow input packets from tun devices,
-.IP
-.B iptables -A FORWARD -i tun+ -j ACCEPT
-.LP
-to allow input packets from tun devices to be forwarded to
-other hosts on the local network,
-.IP
-.B iptables -A INPUT -i tap+ -j ACCEPT
-.LP
-to allow input packets from tap devices, and
-.IP
-.B iptables -A FORWARD -i tap+ -j ACCEPT
-.LP
-to allow input packets from tap devices to be forwarded to
-other hosts on the local network.
-
-These rules are secure if you use packet authentication,
-since no incoming packets will arrive on a TUN or TAP
-virtual device
-unless they first pass an HMAC authentication test.
-.\"*********************************************************
-.SH FAQ
-.I http://openvpn.net/faq.html
-.\"*********************************************************
-.SH HOWTO
-For a more comprehensive guide to setting up OpenVPN
-in a production setting, see the OpenVPN HOWTO at
-.I http://openvpn.net/howto.html
-.\"*********************************************************
-.SH PROTOCOL
-For a description of OpenVPN's underlying protocol,
-see
-.I http://openvpn.net/security.html
-.\"*********************************************************
-.SH WEB
-OpenVPN's web site is at
-.I http://openvpn.net/
-
-Go here to download the latest version of OpenVPN, subscribe
-to the mailing lists, read the mailing list
-archives, or browse the SVN repository.
-.\"*********************************************************
-.SH BUGS
-Report all bugs to the OpenVPN team <info@openvpn.net>.
-.\"*********************************************************
-.SH "SEE ALSO"
-.BR dhcpcd (8),
-.BR ifconfig (8),
-.BR openssl (1),
-.BR route (8),
-.BR scp (1)
-.BR ssh (1)
-.\"*********************************************************
-.SH NOTES
-.LP
-This product includes software developed by the
-OpenSSL Project (
-.I http://www.openssl.org/
-)
-
-For more information on the TLS protocol, see
-.I http://www.ietf.org/rfc/rfc2246.txt
-
-For more information on the LZO real-time compression library see
-.I http://www.oberhumer.com/opensource/lzo/
-.\"*********************************************************
-.SH COPYRIGHT
-Copyright (C) 2002-2010 OpenVPN Technologies, Inc. This program is free software;
-you can redistribute it and/or modify
-it under the terms of the GNU General Public License version 2
-as published by the Free Software Foundation.
-.\"*********************************************************
-.SH AUTHORS
-James Yonan <jim@yonan.net>