diff options
| author | Parménides GV <parmegv@sdf.org> | 2014-04-08 12:04:17 +0200 |
|---|---|---|
| committer | Parménides GV <parmegv@sdf.org> | 2014-04-08 12:04:17 +0200 |
| commit | 3c3421afd8f74a3aa8d1011de07a8c18f9549210 (patch) | |
| tree | 49d52344661c23d7268b8ea69466a1cfef04bf8b /bitmask_android/openvpn/doc | |
| parent | 5fc5d37330d3535a0f421632694d1e7918fc22d7 (diff) | |
Rename app->bitmask_android
This way, gradle commands generate apks correctly named.
Diffstat (limited to 'bitmask_android/openvpn/doc')
20 files changed, 9468 insertions, 0 deletions
diff --git a/bitmask_android/openvpn/doc/Makefile.am b/bitmask_android/openvpn/doc/Makefile.am new file mode 100644 index 00000000..d33e1edd --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/README.plugins b/bitmask_android/openvpn/doc/README.plugins new file mode 100644 index 00000000..6e490c5a --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_compression.h b/bitmask_android/openvpn/doc/doxygen/doc_compression.h new file mode 100644 index 00000000..bdc4a7ed --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_control_processor.h b/bitmask_android/openvpn/doc/doxygen/doc_control_processor.h new file mode 100644 index 00000000..072dc372 --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_control_tls.h b/bitmask_android/openvpn/doc/doxygen/doc_control_tls.h new file mode 100644 index 00000000..aba55f77 --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_data_control.h b/bitmask_android/openvpn/doc/doxygen/doc_data_control.h new file mode 100644 index 00000000..d0f65ba3 --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_data_crypto.h b/bitmask_android/openvpn/doc/doxygen/doc_data_crypto.h new file mode 100644 index 00000000..ee72b8cd --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_eventloop.h b/bitmask_android/openvpn/doc/doxygen/doc_eventloop.h new file mode 100644 index 00000000..a860db68 --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_external_multiplexer.h b/bitmask_android/openvpn/doc/doxygen/doc_external_multiplexer.h new file mode 100644 index 00000000..76532557 --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_fragmentation.h b/bitmask_android/openvpn/doc/doxygen/doc_fragmentation.h new file mode 100644 index 00000000..ef34cdb2 --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_internal_multiplexer.h b/bitmask_android/openvpn/doc/doxygen/doc_internal_multiplexer.h new file mode 100644 index 00000000..5142dd0d --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_key_generation.h b/bitmask_android/openvpn/doc/doxygen/doc_key_generation.h new file mode 100644 index 00000000..903a4652 --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_mainpage.h b/bitmask_android/openvpn/doc/doxygen/doc_mainpage.h new file mode 100644 index 00000000..821b2e87 --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_memory_management.h b/bitmask_android/openvpn/doc/doxygen/doc_memory_management.h new file mode 100644 index 00000000..f948783e --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_protocol_overview.h b/bitmask_android/openvpn/doc/doxygen/doc_protocol_overview.h new file mode 100644 index 00000000..26fed331 --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_reliable.h b/bitmask_android/openvpn/doc/doxygen/doc_reliable.h new file mode 100644 index 00000000..5264906a --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/doc_tunnel_state.h b/bitmask_android/openvpn/doc/doxygen/doc_tunnel_state.h new file mode 100644 index 00000000..6c93e71b --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/doxygen/openvpn.doxyfile b/bitmask_android/openvpn/doc/doxygen/openvpn.doxyfile new file mode 100644 index 00000000..5d87172c --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/management-notes.txt b/bitmask_android/openvpn/doc/management-notes.txt new file mode 100644 index 00000000..ef39b855 --- /dev/null +++ b/bitmask_android/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/bitmask_android/openvpn/doc/openvpn.8 b/bitmask_android/openvpn/doc/openvpn.8 new file mode 100644 index 00000000..d66bd665 --- /dev/null +++ b/bitmask_android/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> |