summaryrefslogtreecommitdiff
path: root/app/openvpn/doc
diff options
context:
space:
mode:
authorParménides GV <parmegv@sdf.org>2014-04-09 16:03:55 +0200
committerParménides GV <parmegv@sdf.org>2014-04-09 16:07:34 +0200
commit1684c8f398922065a97e7da4dac4ac6a33cc5218 (patch)
tree76a4b11ae0d7b217c088f3c2b8fc7e69a7b8ae0d /app/openvpn/doc
parentb9a2b085a8f508cd09e2639c70be845c992c4a3e (diff)
Back to the standard "app" module.
This return to "app" instead of "bitmask_android" is due to this reading: https://developer.android.com/sdk/installing/studio-build.html#projectStructure I'll have to tweak the final apk name in build.gradle.
Diffstat (limited to 'app/openvpn/doc')
-rw-r--r--app/openvpn/doc/Makefile.am31
-rw-r--r--app/openvpn/doc/README.plugins47
-rw-r--r--app/openvpn/doc/doxygen/doc_compression.h92
-rw-r--r--app/openvpn/doc/doxygen/doc_control_processor.h189
-rw-r--r--app/openvpn/doc/doxygen/doc_control_tls.h105
-rw-r--r--app/openvpn/doc/doxygen/doc_data_control.h103
-rw-r--r--app/openvpn/doc/doxygen/doc_data_crypto.h75
-rw-r--r--app/openvpn/doc/doxygen/doc_eventloop.h67
-rw-r--r--app/openvpn/doc/doxygen/doc_external_multiplexer.h46
-rw-r--r--app/openvpn/doc/doxygen/doc_fragmentation.h96
-rw-r--r--app/openvpn/doc/doxygen/doc_internal_multiplexer.h44
-rw-r--r--app/openvpn/doc/doxygen/doc_key_generation.h153
-rw-r--r--app/openvpn/doc/doxygen/doc_mainpage.h162
-rw-r--r--app/openvpn/doc/doxygen/doc_memory_management.h99
-rw-r--r--app/openvpn/doc/doxygen/doc_protocol_overview.h199
-rw-r--r--app/openvpn/doc/doxygen/doc_reliable.h49
-rw-r--r--app/openvpn/doc/doxygen/doc_tunnel_state.h155
-rw-r--r--app/openvpn/doc/doxygen/openvpn.doxyfile279
-rw-r--r--app/openvpn/doc/management-notes.txt1039
-rw-r--r--app/openvpn/doc/openvpn.86438
20 files changed, 9468 insertions, 0 deletions
diff --git a/app/openvpn/doc/Makefile.am b/app/openvpn/doc/Makefile.am
new file mode 100644
index 00000000..d33e1edd
--- /dev/null
+++ b/app/openvpn/doc/Makefile.am
@@ -0,0 +1,31 @@
+#
+# 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/app/openvpn/doc/README.plugins b/app/openvpn/doc/README.plugins
new file mode 100644
index 00000000..6e490c5a
--- /dev/null
+++ b/app/openvpn/doc/README.plugins
@@ -0,0 +1,47 @@
+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/app/openvpn/doc/doxygen/doc_compression.h b/app/openvpn/doc/doxygen/doc_compression.h
new file mode 100644
index 00000000..bdc4a7ed
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_compression.h
@@ -0,0 +1,92 @@
+/*
+ * 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/app/openvpn/doc/doxygen/doc_control_processor.h b/app/openvpn/doc/doxygen/doc_control_processor.h
new file mode 100644
index 00000000..072dc372
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_control_processor.h
@@ -0,0 +1,189 @@
+/*
+ * 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/app/openvpn/doc/doxygen/doc_control_tls.h b/app/openvpn/doc/doxygen/doc_control_tls.h
new file mode 100644
index 00000000..aba55f77
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_control_tls.h
@@ -0,0 +1,105 @@
+/*
+ * 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/app/openvpn/doc/doxygen/doc_data_control.h b/app/openvpn/doc/doxygen/doc_data_control.h
new file mode 100644
index 00000000..d0f65ba3
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_data_control.h
@@ -0,0 +1,103 @@
+/*
+ * 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/app/openvpn/doc/doxygen/doc_data_crypto.h b/app/openvpn/doc/doxygen/doc_data_crypto.h
new file mode 100644
index 00000000..ee72b8cd
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_data_crypto.h
@@ -0,0 +1,75 @@
+/*
+ * 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 and \c ENABLE_SSL preprocessor macros. 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
+ * OpenSSL library. More precisely, it uses the OpenSSL library's \c
+ * EVP_Cipher* and \c HMAC_* set of functions to perform cryptographic
+ * operations on data channel packets.
+ */
diff --git a/app/openvpn/doc/doxygen/doc_eventloop.h b/app/openvpn/doc/doxygen/doc_eventloop.h
new file mode 100644
index 00000000..a860db68
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_eventloop.h
@@ -0,0 +1,67 @@
+/*
+ * 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/app/openvpn/doc/doxygen/doc_external_multiplexer.h b/app/openvpn/doc/doxygen/doc_external_multiplexer.h
new file mode 100644
index 00000000..76532557
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_external_multiplexer.h
@@ -0,0 +1,46 @@
+/*
+ * 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/app/openvpn/doc/doxygen/doc_fragmentation.h b/app/openvpn/doc/doxygen/doc_fragmentation.h
new file mode 100644
index 00000000..ef34cdb2
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_fragmentation.h
@@ -0,0 +1,96 @@
+/*
+ * 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/app/openvpn/doc/doxygen/doc_internal_multiplexer.h b/app/openvpn/doc/doxygen/doc_internal_multiplexer.h
new file mode 100644
index 00000000..5142dd0d
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_internal_multiplexer.h
@@ -0,0 +1,44 @@
+/*
+ * 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/app/openvpn/doc/doxygen/doc_key_generation.h b/app/openvpn/doc/doxygen/doc_key_generation.h
new file mode 100644
index 00000000..903a4652
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_key_generation.h
@@ -0,0 +1,153 @@
+/*
+ * 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/app/openvpn/doc/doxygen/doc_mainpage.h b/app/openvpn/doc/doxygen/doc_mainpage.h
new file mode 100644
index 00000000..821b2e87
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_mainpage.h
@@ -0,0 +1,162 @@
+/*
+ * 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 v2.1 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/app/openvpn/doc/doxygen/doc_memory_management.h b/app/openvpn/doc/doxygen/doc_memory_management.h
new file mode 100644
index 00000000..f948783e
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_memory_management.h
@@ -0,0 +1,99 @@
+/*
+ * 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/app/openvpn/doc/doxygen/doc_protocol_overview.h b/app/openvpn/doc/doxygen/doc_protocol_overview.h
new file mode 100644
index 00000000..26fed331
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_protocol_overview.h
@@ -0,0 +1,199 @@
+/*
+ * 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 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:
+ * - \c P_CONTROL_HARD_RESET_CLIENT_V1 -- %Key method 1, initial %key
+ * from client, forget previous state.
+ * - \c P_CONTROL_HARD_RESET_SERVER_V1 -- %Key method 1, initial %key
+ * from server, forget previous state.
+ * - \c P_CONTROL_HARD_RESET_CLIENT_V2 -- %Key method 2, initial %key
+ * from client, forget previous state.
+ * - \c P_CONTROL_HARD_RESET_SERVER_V2 -- %Key method 2, initial %key
+ * from server, forget previous state.
+ * - \c 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.
+ * - \c P_CONTROL_V1 -- Control channel packet (usually TLS
+ * ciphertext).
+ * - \c P_ACK_V1 -- Acknowledgement for control channel packets
+ * received.
+ * - Data channel messages:
+ * - \c P_DATA_V1 -- Data channel packet containing 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()
+ * OpenSSL 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
+ *
+ * @subsection network_protocol_data_ciphertext Structure of ciphertext data channel messages
+ *
+ * The P_DATA_* payload represents encrypted, encapsulated tunnel packets
+ * which tend to be either IP packets or Ethernet frames. This is
+ * essentially the "payload" of the VPN.
+ *
+ * Data channel packets in ciphertext form consist of the following parts:
+ * - HMAC of ciphertext IV + ciphertext (if not disabled by \c --auth
+ * none).
+ * - Ciphertext IV (size is cipher-dependent, if not disabled by \c
+ * --no-iv).
+ * - Tunnel packet ciphertext.
+ *
+ * @subsection network_protocol_data_plaintext Structure of plaintext data channel messages
+ *
+ * Data channel packets in plaintext form consist of the following parts:
+ * - packet-id (4 or 8 bytes, if not disabled by --no-replay).
+ * - In TLS mode, 4 bytes are used because the implementation can
+ * force a TLS renegotation before \c 2^32 packets are sent.
+ * - In pre-shared %key mode, 8 bytes are used (sequence number and \c
+ * time_t value) to allow long-term %key usage without packet-id
+ * collisions.
+ * - User plaintext (n bytes).
+ */
diff --git a/app/openvpn/doc/doxygen/doc_reliable.h b/app/openvpn/doc/doxygen/doc_reliable.h
new file mode 100644
index 00000000..5264906a
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_reliable.h
@@ -0,0 +1,49 @@
+/*
+ * 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/app/openvpn/doc/doxygen/doc_tunnel_state.h b/app/openvpn/doc/doxygen/doc_tunnel_state.h
new file mode 100644
index 00000000..6c93e71b
--- /dev/null
+++ b/app/openvpn/doc/doxygen/doc_tunnel_state.h
@@ -0,0 +1,155 @@
+/*
+ * 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/app/openvpn/doc/doxygen/openvpn.doxyfile b/app/openvpn/doc/doxygen/openvpn.doxyfile
new file mode 100644
index 00000000..5d87172c
--- /dev/null
+++ b/app/openvpn/doc/doxygen/openvpn.doxyfile
@@ -0,0 +1,279 @@
+# 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 USE_CRYPTO USE_SSL 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/app/openvpn/doc/management-notes.txt b/app/openvpn/doc/management-notes.txt
new file mode 100644
index 00000000..ef39b855
--- /dev/null
+++ b/app/openvpn/doc/management-notes.txt
@@ -0,0 +1,1039 @@
+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/app/openvpn/doc/openvpn.8 b/app/openvpn/doc/openvpn.8
new file mode 100644
index 00000000..d66bd665
--- /dev/null
+++ b/app/openvpn/doc/openvpn.8
@@ -0,0 +1,6438 @@
+.\" 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".
+
+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
+Add a random string (6 characters) to first DNS label of 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 float,
+.B http-proxy,
+.B http-proxy-option,
+.B http-proxy-retry,
+.B http-proxy-timeout,
+.B local,
+.B lport,
+.B nobind,
+.B port,
+.B proto,
+.B remote,
+.B rport,
+.B socks-proxy, and
+.B socks-proxy-retry.
+
+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.
+.\"*********************************************************
+.TP
+.B \-\-socks-proxy server [port]
+Connect to remote host through a Socks5 proxy at address
+.B server
+and port
+.B port
+(default=1080).
+.\"*********************************************************
+.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
+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.
+.\"*********************************************************
+.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.
+
+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 \-\-max-routes n
+Allow a maximum number of n
+.B \-\-route
+options to be specified, either in the local configuration file,
+or pulled from an OpenVPN server. By default, n=100.
+.\"*********************************************************
+.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.
+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 dectected 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.
+.\"*********************************************************
+.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 \-\-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.
+.\"*********************************************************
+.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 \-\-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 can be used when
+OpenVPN has been configured to listen on all interfaces, and will
+attempt to bind client sessions to the interface on which packets
+are being received, so that outgoing packets will be sent out
+of the same interface. Note that this option is only relevant for
+UDP servers and currently is only implemented on Linux.
+
+Note: clients connecting to a
+.B \-\-multihome
+server should always use the
+.B \-\-nobind
+option.
+.\"*********************************************************
+.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 \-\-comp-lzo [mode]
+Use fast LZO compression \-\- may add up to 1 byte per
+packet for incompressible data.
+.B mode
+may be "yes", "no", or "adaptive" (default).
+
+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 uncompressible
+(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).
+.\"*********************************************************
+.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
+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"
+.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]
+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 behavivour 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.
+
+As a backwards compatibility for the removed \-\-no\-name\-remapping feature in
+older OpenVPN versions, the
+.B no\-remapping
+mode flag can be used with the
+.B
+\-\-compat\-names
+option.
+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. It ensures
+compatibility with the
+.B \-\-no\-name\-remapping
+option of OpenVPN versions before v2.3.
+
+.B Please note:
+This option will not be around for a long time. 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 start
+the process to support the new formatting 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). Use
+
+.B openssl dhparam -out dh1024.pem 1024
+
+to generate your own, or use the existing dh1024.pem file
+included with the OpenVPN distribution. Diffie Hellman parameters
+may be considered public.
+.\"*********************************************************
+.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 \-\-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.
+.\"*********************************************************
+.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 determind 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.
+.\"*********************************************************
+.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 key file which can be in one of two formats:
+
+.B (1)
+An OpenVPN static key file generated by
+.B \-\-genkey
+(required if
+.B direction
+parameter is used).
+
+.B (2)
+A freeform passphrase file. In this case the HMAC key will
+be derived by taking a secure hash of this file, similar to
+the
+.BR md5sum (1)
+or
+.BR sha1sum (1)
+commands.
+
+OpenVPN will first try format (1), and if the file fails to parse as
+a static key file, format (2) will be used.
+
+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 fieldname
+Field in x509 certificate subject to be used as username (default=CN).
+.B Fieldname
+will be uppercased before matching. When this option is used, the
+--tls-remote option will match against the chosen fieldname instead
+of the CN.
+.\"*********************************************************
+.TP
+.B \-\-tls-remote name
+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.
+.\"*********************************************************
+.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, \-\-tls-remote,
+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, \-\-tls-remote,
+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.
+.\"*********************************************************
+.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.
+
+.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. As of now, this is just very basic
+documentation of the IPv6-related options. More documentation can be
+found on http://www.greenie.net/ipv6/openvpn.html.
+.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'' device
+.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.
+.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_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 hex string like "37AB46E0", which is
+suitable for doing serial-based OCSP queries (with OpenSSL, you have
+to 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 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>