diff options
Diffstat (limited to 'app/openvpn/doc')
20 files changed, 0 insertions, 9468 deletions
diff --git a/app/openvpn/doc/Makefile.am b/app/openvpn/doc/Makefile.am deleted file mode 100644 index d33e1edd..00000000 --- a/app/openvpn/doc/Makefile.am +++ /dev/null @@ -1,31 +0,0 @@ -# -# OpenVPN -- An application to securely tunnel IP networks -# over a single UDP port, with support for SSL/TLS-based -# session authentication and key exchange, -# packet encryption, packet authentication, and -# packet compression. -# -# Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net> -# Copyright (C) 2006-2012 Alon Bar-Lev <alon.barlev@gmail.com> -# - -MAINTAINERCLEANFILES = \ - $(srcdir)/Makefile.in - -CLEANFILES = openvpn.8.html - -dist_doc_DATA = \ - management-notes.txt - -dist_noinst_DATA = \ - README.plugins - -if WIN32 -dist_noinst_DATA += openvpn.8 -nodist_html_DATA = openvpn.8.html -openvpn.8.html: $(srcdir)/openvpn.8 - $(MAN2HTML) < $(srcdir)/openvpn.8 > openvpn.8.html -else -dist_man_MANS = openvpn.8 -endif - diff --git a/app/openvpn/doc/README.plugins b/app/openvpn/doc/README.plugins deleted file mode 100644 index 6e490c5a..00000000 --- a/app/openvpn/doc/README.plugins +++ /dev/null @@ -1,47 +0,0 @@ -OpenVPN Plugins ---------------- - -Starting with OpenVPN 2.0-beta17, compiled plugin modules are -supported on any *nix OS which includes libdl or on Windows. -One or more modules may be loaded into OpenVPN using -the --plugin directive, and each plugin module is capable of -intercepting any of the script callbacks which OpenVPN supports: - -(1) up -(2) down -(3) route-up -(4) ipchange -(5) tls-verify -(6) auth-user-pass-verify -(7) client-connect -(8) client-disconnect -(9) learn-address - -See the openvpn-plugin.h file in the top-level directory of the -OpenVPN source distribution for more detailed information -on the plugin interface. - -Included Plugins ----------------- - -auth-pam -- Authenticate using PAM and a split privilege - execution model which functions even if - root privileges or the execution environment - have been altered with --user/--group/--chroot. - Tested on Linux only. - -down-root -- Enable the running of down scripts with root privileges - even if --user/--group/--chroot have been used - to drop root privileges or change the execution - environment. Not applicable on Windows. - -examples -- A simple example that demonstrates a portable - plugin, i.e. one which can be built for *nix - or Windows from the same source. - -Building Plugins ----------------- - -cd to the top-level directory of a plugin, and use the -"make" command to build it. The examples plugin is -built using a build script, not a makefile. diff --git a/app/openvpn/doc/doxygen/doc_compression.h b/app/openvpn/doc/doxygen/doc_compression.h deleted file mode 100644 index bdc4a7ed..00000000 --- a/app/openvpn/doc/doxygen/doc_compression.h +++ /dev/null @@ -1,92 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file Data Channel Compression module documentation file. - */ - -/** - * @defgroup compression Data Channel Compression module - * - * This module offers compression of data channel packets. - * - * @par State structures - * The Data Channel Compression module stores its internal state in a \c - * lzo_compress_workspace structure. This state includes flags which - * control the module's behavior and preallocated working memory. One - * such structure is present for each VPN tunnel, and is stored in the \c - * context.c2.lzo_compwork of the \c context associated with that VPN - * tunnel. - * - * @par Initialization and cleanup - * Every time a new \c lzo_compress_workspace is needed, it must be - * initialized using the \c lzo_compress_init() function. Similarly, - * every time a \c lzo_compress_workspace is no longer needed, it must be - * cleaned up using the \c lzo_compress_uninit() function. These - * functions take care of the allocation and freeing of internal working - * memory, but not of the \c lzo_compress_workspace structures themselves. - * - * @par - * Because of the one-to-one relationship between \c - * lzo_compress_workspace structures and VPN tunnels, the above-mentioned - * initialization and cleanup functions are called directly from the \c - * init_instance() and \c close_instance() functions, which control the - * initialization and cleanup of VPN tunnel instances and their associated - * \c context structures. - * - * @par Packet processing functions - * This module receives data channel packets from the \link data_control - * Data Channel Control module\endlink and processes them according to the - * settings of the packet's VPN tunnel. The \link data_control Data - * Channel Control module\endlink uses the following interface functions: - * - For packets which will be sent to a remote OpenVPN peer: \c - * lzo_compress() - * - For packets which have been received from a remote OpenVPN peer: \c - * lzo_decompress() - * - * @par Settings that control this module's activity - * Whether or not the Data Channel Compression module is active depends on - * the compile-time \c ENABLE_LZO preprocessor macro and the runtime flags - * stored in \c lzo_compress_workspace.flags of the associated VPN tunnel. - * The latter are initialized from \c options.lzo, which gets its value - * from the process's configuration sources, such as its configuration - * file or command line %options. - * - * @par Adaptive compression - * The compression module supports adaptive compression. If this feature - * is enabled, the compression routines monitor their own performance and - * turn compression on or off depending on whether it is leading to - * significantly reduced payload size. - * - * @par Compression algorithms - * This module uses the Lempel-Ziv-Oberhumer (LZO) compression algorithms. - * These offer lossless compression and are designed for high-performance - * decompression. This module uses the external \c lzo library's - * implementation of the algorithms. - * - * @par - * For more information on the LZO library, see:\n - * http://www.oberhumer.com/opensource/lzo/ - */ diff --git a/app/openvpn/doc/doxygen/doc_control_processor.h b/app/openvpn/doc/doxygen/doc_control_processor.h deleted file mode 100644 index 072dc372..00000000 --- a/app/openvpn/doc/doxygen/doc_control_processor.h +++ /dev/null @@ -1,189 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file - * Control Channel Processor module documentation file. - */ - -/** - * @defgroup control_processor Control Channel Processor module - * - * This module controls the setup and maintenance of VPN tunnels and the - * associated security parameters. - * - * @par This module's role - * The Control Channel Processor module lies at the core of OpenVPN's - * activities. It handles the setup of new VPN tunnels, the negotiation - * of data channel security parameters, the managing of active VPN - * tunnels, and finally the cleanup of expired VPN tunnels. - * - * @par State structures - * A large amount of VPN tunnel state information must be stored within an - * OpenVPN process. A wide variety of container structures are used by - * this module for that purpose. Several of these structures are listed - * below, and the function of the first three VPN tunnel state containers - * is described in more detail later. - * - VPN tunnel state containers: - * - \c tls_multi, security parameter state for a single VPN tunnel. - * Contains three instances of the \c tls_session structure. - * - \c tls_session, security parameter state of a single session - * within a VPN tunnel. Contains two instances of the \c key_state - * structure. - * - \c key_state, security parameter state of one TLS and data - * channel %key set. - * - Data channel security parameter containers: - * - \c key_ctx_bi, container for two sets of OpenSSL cipher and/or - * HMAC context (both directions). Contains two instances of the \c - * key_ctx structure. - * - \c key_ctx, container for one set of OpenSSL cipher and/or HMAC - * context (one directions. - * - Key material containers: - * - \c key2, container for two sets of cipher and/or HMAC %key - * material (both directions). Contains two instances of the \c key - * structure. - * - \c key, container for one set of cipher and/or HMAC %key material - * (one direction). - * - \c key_direction_state, ordering of %key material within the \c - * key2.key array. - * - Key method 2 random material containers: - * - \c key_source2, container for both halves of random material used - * for %key method 2. Contains two instances of the \c key_source - * structure. - * - \c key_source, container for one half of random material used for - * %key method 2. - * - * @par The life of a \c tls_multi object - * A \c tls_multi structure contains all the security parameter state - * information related to the control and data channels of one VPN tunnel. - * Its life cycle can be summarized as follows: - * -# Initialization: \c tls_multi_init() and \c - * tls_multi_init_finalize(), which are called (indirectly) from \c - * init_instance() when initializing a new \c context structure. - * - Initializes a \c tls_multi structure. - * - Allocates the three \c tls_session objects contained by the \c - * tls_multi structure, and initializes as appropriate. - * -# Management: \c tls_multi_process() and \c tls_pre_decrypt() - * - If a new session is initiated by the remote peer, then \c - * tls_pre_decrypt() starts the new session negotiation in the - * un-trusted \c tls_session. - * - If the, as yet, un-trusted \c tls_session authenticates - * successfully, then \c tls_multi_process() moves it so as to be - * the active \c tls_session. - * - If an error occurs during processing of a \c key_state object, - * then \c tls_multi_process() cleans up and initializes the - * associated \c tls_session object. If the error occurred in the - * active \c key_state of the active \c tls_session and the - * lame-duck \c key_state of that \c tls_session has not yet - * expired, it is preserved as fallback. - * -# Cleanup: \c tls_multi_free(), which is called (indirectly) from \c - * close_instance() when cleaning up a \c context structure. - * - Cleans up a \c tls_multi structure. - * - Cleans up the three \c tls_session objects contained by the \c - * tls_multi structure. - * - * @par The life of a \c tls_session object - * A \c tls_session structure contains the state information related to an - * active and a lame-duck \c key_state. Its life cycle can be summarized - * as follows: - * -# Initialization: \c tls_session_init() - * - Initializes a \c tls_session structure. - * - Initializes the primary \c key_state by calling \c - * key_state_init(). - * -# Renegotiation: \c key_state_soft_reset() - * - Cleans up the old lame-duck \c key_state by calling \c - * key_state_free(). - * - Moves the old primary \c key_state to be the new lame-duck \c - * key_state. - * - Initializes a new primary \c key_state by calling \c - * key_state_init(). - * -# Cleanup: \c tls_session_free() - * - Cleans up a \c tls_session structure. - * - Cleans up all \c key_state objects associated with the session by - * calling \c key_state_free() for each. - * - * @par The life of a \c key_state object - * A \c key_state structure represents one control and data channel %key - * set. It contains an OpenSSL TLS object that encapsulates the control - * channel, and the data channel security parameters needed by the \link - * data_crypto Data Channel Crypto module\endlink to perform cryptographic - * operations on data channel packets. Its life cycle can be summarized - * as follows: - * -# Initialization: \c key_state_init() - * - Initializes a \c key_state structure. - * - Creates a new OpenSSL TLS object to encapsulate this new control - * channel session. - * - Sets \c key_state.state to \c S_INITIAL. - * - Allocates several internal buffers. - * - Initializes new reliability layer structures for this key set. - * -# Negotiation: \c tls_process() - * - The OpenSSL TLS object negotiates a TLS session between itself - * and the remote peer's TLS object. - * - Key material is generated and exchanged through the TLS session - * between OpenVPN peers. - * - Both peers initialize their data channel cipher and HMAC key - * contexts. - * - On successful negotiation, the \c key_state.state will progress - * from \c S_INITIAL to \c S_ACTIVE and \c S_NORMAL. - * -# Active tunneling: \link data_crypto Data Channel Crypto - * module\endlink - * - Data channel packet to be sent to a remote OpenVPN peer: - * - \c tls_pre_encrypt() loads the security parameters from the \c - * key_state into a \c crypto_options structure. - * - \c openvpn_encrypt() uses the \c crypto_options to an encrypt - * and HMAC sign the data channel packet. - * - Data channel packet received from a remote OpenVPN peer: - * - \c tls_pre_decrypt() loads the security parameters from the \c - * key_state into a \c crypto_options structure. - * - \c openvpn_encrypt() uses the \c crypto_options to - * authenticate and decrypt the data channel packet. - * -# Cleanup: \c key_state_free() - * - Cleans up a \c key_state structure together with its OpenSSL TLS - * object, key material, internal buffers, and reliability layer - * structures. - * - * @par Control functions - * The following two functions drive the Control Channel Processor's - * activities. - * - \c tls_multi_process(), iterates through the \c tls_session objects - * within a given \c tls_multi of a VPN tunnel, and calls \c - * tls_process() for each \c tls_session which is being set up, is - * already active, or is busy expiring. - * - \c tls_process(), performs the Control Channel Processor module's - * core handling of received control channel messages, and generates - * appropriate messages to be sent. - * - * @par Functions which control data channel key generation - * - Key method 1 key exchange functions: - * - \c key_method_1_write(), generates and processes key material to - * be sent to the remote OpenVPN peer. - * - \c key_method_1_read(), processes key material received from the - * remote OpenVPN peer. - * - Key method 2 key exchange functions: - * - \c key_method_2_write(), generates and processes key material to - * be sent to the remote OpenVPN peer. - * - \c key_method_2_read(), processes key material received from the - * remote OpenVPN peer. - */ diff --git a/app/openvpn/doc/doxygen/doc_control_tls.h b/app/openvpn/doc/doxygen/doc_control_tls.h deleted file mode 100644 index aba55f77..00000000 --- a/app/openvpn/doc/doxygen/doc_control_tls.h +++ /dev/null @@ -1,105 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file - * Control Channel TLS module documentation file. - */ - -/** - * @defgroup control_tls Control Channel TLS module - * - * This module provides secure encapsulation of control channel messages - * exchanged between OpenVPN peers. - * - * The Control Channel TLS module uses the Transport Layer Security (TLS) - * protocol to provide an encrypted communication channel between the - * local OpenVPN process and a remote peer. This protocol simultaneously - * offers certificate-based authentication of the communicating parties. - * - * @par This module's roles - * The Control Channel TLS module is essential for the security of any - * OpenVPN-based system. On the one hand, it performs the security - * operations necessary to protect control channel messages exchanged - * between OpenVPN peers. On the other hand, before the control and data - * channels are even setup, it controls the exchange of certificates and - * verification of the remote's identity during negotiation of VPN - * tunnels. - * - * @par - * The former role is described below. The latter is described in the - * documentation for the \c verify_callback() function. - * - * @par - * In other words, this module takes care of the confidentiality and - * integrity of data channel communications, and the authentication of - * both the communicating parties and the control channel messages - * exchanged. - * - * @par Initialization and cleanup - * Because of the one-to-one relationship between control channel TLS - * state and \c key_state structures, the initialization and cleanup of an - * instance of the Control Channel TLS module's state happens within the - * \c key_state_init() and \c key_state_free() functions. In other words, - * each \c key_state object contains exactly one OpenSSL SSL-BIO object, - * which is initialized and cleaned up together with the rest of the \c - * key_state object. - * - * @par Packet processing functions - * This object behaves somewhat like a black box with a ciphertext and a - * plaintext I/O port. Its interaction with OpenVPN's control channel - * during operation takes place within the \c tls_process() function of - * the \link control_processor Control Channel Processor\endlink. The - * following functions are available for processing packets: - * - If ciphertext received from the remote peer is available in the \link - * reliable Reliability Layer\endlink: - * - Insert it into the ciphertext-side of the SSL-BIO. - * - Use function: \c key_state_write_ciphertext() - * - If ciphertext can be extracted from the ciphertext-side of the - * SSL-BIO: - * - Pass it to the \link reliable Reliability Layer\endlink for sending - * to the remote peer. - * - Use function: \c key_state_read_ciphertext() - * - If plaintext can be extracted from the plaintext-side of the SSL-BIO: - * - Pass it on to the \link control_processor Control Channel - * Processor\endlink for local processing. - * - Use function: \c key_state_read_plaintext() - * - If plaintext from the \link control_processor Control Channel - * Processor\endlink is available to be sent to the remote peer: - * - Insert it into the plaintext-side of the SSL-BIO. - * - Use function: \c key_state_write_plaintext() or \c - * key_state_write_plaintext_const() - * - * @par Transport Layer Security protocol implementation - * This module uses the OpenSSL library's implementation of the TLS - * protocol in the form of an OpenSSL SSL-BIO object. - * - * @par - * For more information on the OpenSSL library's BIO objects, please see: - * - OpenSSL's generic BIO objects: - * http://www.openssl.org/docs/crypto/bio.html - * - OpenSSL's SSL-BIO object: - * http://www.openssl.org/docs/crypto/BIO_f_ssl.html - */ diff --git a/app/openvpn/doc/doxygen/doc_data_control.h b/app/openvpn/doc/doxygen/doc_data_control.h deleted file mode 100644 index d0f65ba3..00000000 --- a/app/openvpn/doc/doxygen/doc_data_control.h +++ /dev/null @@ -1,103 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file - * Data Channel Control module documentation file. - */ - -/** - * @defgroup data_control Data Channel Control module - * - * This module controls the processing of packets as they pass through the - * data channel. - * - * The Data Channel Control module controls the processing of packets as - * they pass through the data channel. The processing includes packet - * compression, fragmentation, and the performing of security operations - * on the packets. This module does not do the processing itself, but - * passes the packet to other data channel modules to perform the - * appropriate actions. - * - * Packets can travel in two directions through the data channel. They - * can be going to a remote destination which is reachable through a VPN - * tunnel, in which case this module prepares them to be sent out through - * a VPN tunnel. On the other hand, they can have been received through a - * VPN tunnel from a remote OpenVPN peer, in which case this module - * retrieves the packet in its original form as it was before entering the - * VPN tunnel on the remote OpenVPN peer. How this module processes - * packets traveling in the two directions is discussed in more detail - * below. - * - * @par Packets to be sent to a remote OpenVPN peer - * This module's main function for processing packets traveling in this - * direction is \c encrypt_sign(), which performs the following processing - * steps: - * - Call the \link compression Data Channel Compression module\endlink to - * perform packet compression if necessary. - * - Call the \link fragmentation Data Channel Fragmentation - * module\endlink to perform packet fragmentation if necessary. - * - Call the \link data_crypto Data Channel Crypto module\endlink to - * perform the required security operations. - * - * @par - * See the \c encrypt_sign() documentation for details of these - * interactions. - * - * @par - * After the above processing is complete, the packet is ready to be sent - * to a remote OpenVPN peer as a VPN tunnel packet. The actual sending of - * the packet is handled by the \link external_multiplexer External - * Multiplexer\endlink. - * - * @par Packets received from a remote OpenVPN peer - * The function that controls how packets traveling in this direction are - * processed is \c process_incoming_link(). That function, however, also - * performs some of the tasks required for the \link external_multiplexer - * External Multiplexer\endlink and is therefore listed as part of that - * module, instead of here. - * - * @par - * After the \c process_incoming_link() function has determined that a - * received packet is a data channel packet, it performs the following - * processing steps: - * - Call the \link data_crypto Data Channel Crypto module\endlink to - * perform the required security operations. - * - Call the \link fragmentation Data Channel Fragmentation - * module\endlink to perform packet reassembly if necessary. - * - Call the \link compression Data Channel Compression module\endlink to - * perform packet decompression if necessary. - * - * @par - * See the \c process_incoming_link() documentation for details of these - * interactions. - * - * @par - * After the above processing is complete, the packet is in its original - * form again as it was received by the remote OpenVPN peer. It can now - * be routed further to its final destination. If that destination is a - * locally reachable host, then the \link internal_multiplexer Internal - * Multiplexer\endlink will send it there. - */ diff --git a/app/openvpn/doc/doxygen/doc_data_crypto.h b/app/openvpn/doc/doxygen/doc_data_crypto.h deleted file mode 100644 index ee72b8cd..00000000 --- a/app/openvpn/doc/doxygen/doc_data_crypto.h +++ /dev/null @@ -1,75 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file - * Data Channel Crypto module documentation file. - */ - -/** - * @addtogroup data_crypto Data Channel Crypto module - * - * The Data Channel Crypto Module performs cryptographic operations on - * data channel packets. - * - * @par Security parameters - * This module is merely the user of a VPN tunnel's security parameters. - * It does not perform the negotiation and setup of the security - * parameters, nor the %key generation involved. These actions are done - * by the \link control_processor Control Channel Processor\endlink. This - * module receives the appropriate security parameters from that module in - * the form of a \c crypto_options structure when they are necessary for - * processing a packet. - * - * @par Packet processing functions - * This module receives data channel packets from the \link data_control - * Data Channel Control module\endlink and processes them according to the - * security parameters of the packet's VPN tunnel. The \link data_control - * Data Channel Control module\endlink uses the following interface - * functions: - * - For packets which will be sent to a remote OpenVPN peer: - * - \c tls_pre_encrypt() - * - \c openvpn_encrypt() - * - \c tls_post_encrypt() - * - For packets which have been received from a remote OpenVPN peer: - * - \c tls_pre_decrypt() (documented as part of the \link - * external_multiplexer External Multiplexer\endlink) - * - \c openvpn_decrypt() - * - * @par Settings that control this module's activity - * Whether or not the Data Channel Crypto module is active depends on the - * compile-time \c ENABLE_CRYPTO and \c ENABLE_SSL preprocessor macros. How it - * processes packets received from the \link data_control Data Channel - * Control module\endlink at runtime depends on the associated \c - * crypto_options structure. To perform cryptographic operations, the \c - * crypto_options.key_ctx_bi must contain the correct cipher and HMAC - * security parameters for the direction the packet is traveling in. - * - * @par Crypto algorithms - * This module uses the crypto algorithm implementations of the external - * OpenSSL library. More precisely, it uses the OpenSSL library's \c - * EVP_Cipher* and \c HMAC_* set of functions to perform cryptographic - * operations on data channel packets. - */ diff --git a/app/openvpn/doc/doxygen/doc_eventloop.h b/app/openvpn/doc/doxygen/doc_eventloop.h deleted file mode 100644 index a860db68..00000000 --- a/app/openvpn/doc/doxygen/doc_eventloop.h +++ /dev/null @@ -1,67 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file - * Main Event Loop module documentation file. - */ - -/** - * @defgroup eventloop Main Event Loop module - * - * This main event loop module drives the packet processing of OpenVPN. - * - * OpenVPN is an event driven system. Its activities are driven by a main - * event loop, which repeatedly waits for one of several predefined events - * to occur, and then calls the appropriate module to handle the event. - * The major types of network events that OpenVPN processes are: - * - A packet can be read from the external network interface. - * - The main event loop activates the \link external_multiplexer - * External Multiplexer\endlink to read and process the packet. - * - A packet can be read from the virtual tun/tap network interface. - * - The main event loop activates the \link internal_multiplexer - * Internal Multiplexer\endlink to read and process the packet. - * - If a packet is ready to be sent out as a VPN tunnel packet: the - * external network interface can be written to. - * - The main event loop activates the \link external_multiplexer - * External Multiplexer\endlink to send the packet. - * - If a packet is ready to be sent to a locally reachable destination: - * the virtual tun/tap network interface can be written to. - * - The main event loop activates the \link internal_multiplexer - * Internal Multiplexer\endlink to send the packet. - * - * Beside these external events, OpenVPN also processes other types of - * internal events. These include scheduled events, such as resending of - * non-acknowledged control channel messages. - * - * @par Main event loop implementations - * - * Depending on the mode in which OpenVPN is running, a different main - * event loop function is called to drive the event processing. The - * following implementations are available: - * - Client mode using UDP or TCP: \c tunnel_point_to_point() - * - Server mode using UDP: \c tunnel_server_udp_single_threaded() - * - Server mode using TCP: \c tunnel_server_tcp() - */ diff --git a/app/openvpn/doc/doxygen/doc_external_multiplexer.h b/app/openvpn/doc/doxygen/doc_external_multiplexer.h deleted file mode 100644 index 76532557..00000000 --- a/app/openvpn/doc/doxygen/doc_external_multiplexer.h +++ /dev/null @@ -1,46 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file - * External Multiplexer module documentation file. - */ - -/** - * @addtogroup external_multiplexer External Multiplexer module - * - * The External Multiplexer is the link between the external network - * interface and the other OpenVPN modules. It reads packets from the - * external network interface, determines which remote OpenVPN peer and - * VPN tunnel they are associated with, and whether they are data channel - * or control channel packets. It then passes the packets on to the - * appropriate processing module. - * - * This module also handles packets traveling in the reverse direction, - * which have been generated by the local control channel or which have - * already been processed by the \link data_control Data Channel Control - * module\endlink and are destined for a remote host reachable through a - * VPN tunnel. - */ diff --git a/app/openvpn/doc/doxygen/doc_fragmentation.h b/app/openvpn/doc/doxygen/doc_fragmentation.h deleted file mode 100644 index ef34cdb2..00000000 --- a/app/openvpn/doc/doxygen/doc_fragmentation.h +++ /dev/null @@ -1,96 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file - * Data Channel Fragmentation module documentation file. - */ - -/** - * @defgroup fragmentation Data Channel Fragmentation module - * - * The Data Channel Fragmentation module offers fragmentation of data - * channel packets. - * - * @par State structures - * The Data Channel Fragmentation module stores its internal state in a \c - * fragment_master structure. One such structure is present for each VPN - * tunnel, and is stored in \c context.c2.fragment of the \c context - * associated with that VPN tunnel. - * - * @par - * The \c fragment_master structure contains one \c fragment_list - * structure \c fragment_master.incoming. This is a list of \c fragment - * structures, each of which can store the parts of one fragmented packet - * while it is being reassembled. The \c fragment_master structure also - * contains one \c buffer called \c fragment_master.outgoing, in which a - * data channel large packet to be sent to a remote OpenVPN peer can be - * broken up into parts to be sent one by one. - * - * @par Initialization and cleanup - * Every time a new \c fragment_master is needed, it must be allocated and - * initialized by the \c fragment_init() function. Similarly, every time - * a \c fragment_master is no longer needed, it must be cleaned up using - * the \c fragment_free() function. These functions take care of the - * allocation and freeing of the \c fragment_master structure itself and - * all internal memory required for the use of that structure. Note that - * this behavior is different from that displayed by the \link compression - * Data Channel Compression module\endlink. - * - * @par - * Because of the one-to-one relationship between \c fragment_master - * structures and VPN tunnels, the above-mentioned initialization and - * cleanup functions are called directly from the \c init_instance() and - * \c close_instance() functions, which control the initialization and - * cleanup of VPN tunnel instances and their associated \c context - * structures. - * - * @par Packet processing functions - * This module receives data channel packets from the \link data_control - * Data Channel Control module\endlink and processes them according to the - * settings of the packet's VPN tunnel. The \link data_control Data - * Channel Control module\endlink uses the following interface functions: - * - For packets which will be sent to a remote OpenVPN peer: \c - * fragment_outgoing() \n This function inspects data channel packets as - * they are being made ready to be sent as VPN tunnel packets to a - * remote OpenVPN peer. If a packet's size is larger than its - * destination VPN tunnel's maximum transmission unit (MTU), then this - * module breaks that packet up into smaller parts, each of which is - * smaller than or equal to the VPN tunnel's MTU. See \c - * fragment_outgoing() for details. - * - For packets which have been received from a remote OpenVPN peer: \c - * fragment_incoming() \n This function inspects data channel packets - * that have been received from a remote OpenVPN peer through a VPN - * tunnel. It reads the fragmentation header of the packet, and - * depending on its value performs the appropriate action. See \c - * fragment_incoming() for details. - * - * @par Settings that control this module's activity - * Whether the Data Channel Fragmentation module is active or not depends - * on the compile-time \c ENABLE_FRAGMENT preprocessor macro and the - * runtime flag \c options.fragment, which gets its value from the - * process's configuration sources, such as the configuration file and - * commandline %options. - */ diff --git a/app/openvpn/doc/doxygen/doc_internal_multiplexer.h b/app/openvpn/doc/doxygen/doc_internal_multiplexer.h deleted file mode 100644 index 5142dd0d..00000000 --- a/app/openvpn/doc/doxygen/doc_internal_multiplexer.h +++ /dev/null @@ -1,44 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file - * Internal Multiplexer module documentation file. - */ - -/** - * @addtogroup internal_multiplexer Internal Multiplexer module - * - * The Internal Multiplexer is the link between the virtual tun/tap - * network interface and the \link data_control Data Channel Control - * module\endlink. It reads packets from the virtual network interface, - * determines for which remote OpenVPN peer they are destined, and then - * passes the packets on to the Data Channel Control module together with - * information about their destination VPN tunnel instance. - * - * This module also handles packets traveling in the reverse direction, - * which have already been processed by the Data Channel Control module - * and are destined for a locally reachable host. - */ diff --git a/app/openvpn/doc/doxygen/doc_key_generation.h b/app/openvpn/doc/doxygen/doc_key_generation.h deleted file mode 100644 index 903a4652..00000000 --- a/app/openvpn/doc/doxygen/doc_key_generation.h +++ /dev/null @@ -1,153 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file - * Key generation documentation file. - */ - -/** - * @page key_generation Data channel %key generation - * - * This section describes how OpenVPN peers generate and exchange %key - * material necessary for the security operations performed on data - * channel packets. - * - * The %key generation and exchange process between OpenVPN client and - * server occurs every time data channel security parameters are - * negotiated, for example during the initial setup of a VPN tunnel or - * when the active security parameters expire. In source code terms, this - * is when a new key_state structure is initialized. - * - * @section key_generation_method Key methods - * - * OpenVPN supports two different ways of generating and exchanging %key - * material between client and server. These are known as %key method 1 - * and %key method 2. %Key method 2 is the recommended method. Both are - * explained below. - * - * @subsection key_generation_method_1 Key method 1 - * - * -# Each host generates its own random material. - * -# Each host uses its locally generated random material as %key data - * for encrypting and signing packets sent to the remote peer. - * -# Each host then sends its random material to the remote peer, so that - * the remote peer can use that %key data for authenticating and - * decrypting received packets. - * - * @subsection key_generation_method_2 Key method 2 - * - * -# The client generates random material in the following amounts: - * - Pre-master secret: 48 bytes - * - Client's PRF seed for master secret: 32 bytes - * - Client's PRF seed for %key expansion: 32 bytes - * -# The client sends its share of random material to the server. - * -# The server generates random material in the following amounts: - * - Server's PRF seed for master secret: 32 bytes - * - Server's PRF seed for %key expansion: 32 bytes - * -# The server computes the %key expansion using its own and the - * client's random material. - * -# The server sends its share of random material to the client. - * -# The client computes the %key expansion using its own and the - * server's random material. - * - * %Key method 2 %key expansion is performed by the \c - * generate_key_expansion() function. Please refer to its source code for - * details of the %key expansion process. - * - * @subsection key_generation_random Source of random material - * - * OpenVPN uses the either the OpenSSL library or the PolarSSL library as its - * source of random material. - * - * In OpenSSL, the \c RAND_bytes() function is called - * to supply cryptographically strong pseudo-random data. The following links - * contain more information on this subject: - * - For OpenSSL's \c RAND_bytes() function: - * http://www.openssl.org/docs/crypto/RAND_bytes.html - * - For OpenSSL's pseudo-random number generating system: - * http://www.openssl.org/docs/crypto/rand.html - * - For OpenSSL's support for external crypto modules: - * http://www.openssl.org/docs/crypto/engine.html - * - * In PolarSSL, the Havege random number generator is used. For details, see - * the PolarSSL documentation. - * - * @section key_generation_exchange Key exchange: - * - * The %key exchange process is initiated by the OpenVPN process running - * in client mode. After the initial three-way handshake has successfully - * completed, the client sends its share of random material to the server, - * after which the server responds with its part. This process is - * depicted below: - * -@verbatim - Client Client Server Server - State Action Action State ----------- -------------------- -------------------- ---------- - - ... waiting until three-way handshake complete ... -S_START S_START - key_method_?_write() - send to server --> --> --> --> receive from client -S_SENT_KEY key_method_?_read() - S_GOT_KEY - key_method_?_write() - receive from server <-- <-- <-- <-- send to client - key_method_?_read() S_SENT_KEY -S_GOT_KEY - ... waiting until control channel fully synchronized ... -S_ACTIVE S_ACTIVE -@endverbatim - * - * For more information about the client and server state values, see the - * \link control_processor Control Channel Processor module\endlink. - * - * Depending on which %key method is used, the \c ? in the function names - * of the diagram above is a \c 1 or a \c 2. For example, if %key method - * 2 is used, that %key exchange would be started by the client calling \c - * key_method_2_write(). These functions are called from the \link - * control_processor Control Channel Processor module's\endlink \c - * tls_process() function and control the %key generation and exchange - * process as follows: - * - %Key method 1: - * - \c key_method_1_write(): generate random material locally, and load - * as "sending" keys. - * - \c key_method_1_read(): read random material received from remote - * peer, and load as "receiving" keys. - * - %Key method 2: - * - \c key_method_2_write(): generate random material locally, and if - * in server mode generate %key expansion. - * - \c key_method_2_read(): read random material received from remote - * peer, and if in client mode generate %key expansion. - * - * @subsection key_generation_encapsulation Transmission of key material - * - * The OpenVPN client and server communicate with each other through their - * control channel. This means that all of the data transmitted over the - * network, such as random material for %key generation, is encapsulated - * in a TLS layer. For more details, see the \link control_tls Control - * Channel TLS module\endlink documentation. - */ diff --git a/app/openvpn/doc/doxygen/doc_mainpage.h b/app/openvpn/doc/doxygen/doc_mainpage.h deleted file mode 100644 index 821b2e87..00000000 --- a/app/openvpn/doc/doxygen/doc_mainpage.h +++ /dev/null @@ -1,162 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file - * Main page documentation file. - */ - -/** - * @mainpage OpenVPN v2.1 source code documentation - * - * This documentation describes the internal structure of OpenVPN. It was - * automatically generated from specially formatted comment blocks in - * OpenVPN's source code using Doxygen. (See - * http://www.stack.nl/~dimitri/doxygen/ for more information on Doxygen) - * - * The \ref mainpage_modules "Modules section" below gives an introduction - * into the high-level module concepts used throughout this documentation. - * The \ref mainpage_relatedpages "Related Pages section" below describes - * various special subjects related to OpenVPN's implementation which are - * discussed in the related pages section. - * - * @section mainpage_modules Modules - * - * For the purpose of describing the internal structure of OpenVPN, this - * documentation and the underlying source code has been broken up into a - * number of conceptually well-defined parts, known as modules. Each - * module plays a specific role within the OpenVPN process, and in most - * cases each module has a clear interfacing strategy for interacting with - * other modules. - * - * The following modules have been defined: - * - Driver module: - * - The \link eventloop Main Event Loop\endlink: this module drives the - * event handling of OpenVPN. It implements various types of - * select-loop which wait until an event happens, and then delegate - * the handling of that event to the appropriate module. - * - Network interface modules: - * - The \link external_multiplexer External Multiplexer\endlink: this - * module sends and receives packets to and from remote OpenVPN peers - * over the external network interface. It also takes care of - * demultiplexing received packets to their appropriate VPN tunnel and - * splitting control channel and data channel packets. - * - The \link internal_multiplexer Internal Multiplexer\endlink: this - * module sends and receives packets to and from locally reachable - * posts over the virtual tun/tap network interface. It also takes - * care of determining through which VPN tunnel a received packet must - * be sent to reach its destination. - * - Control channel modules: - * - The \link reliable Reliability Layer\endlink: this module offers a - * %reliable and sequential transport layer for control channel - * messages. - * - The \link control_tls Control Channel TLS module\endlink: this - * module offers a secure encapsulation of control channel messages - * using the TLS protocol. - * - The \link control_processor Control Channel Processor\endlink: his - * module manages the setup, maintenance, and shut down of VPN - * tunnels. - * - Data channel modules: - * - The \link data_control Data Channel Control module\endlink: this - * module controls the processing of data channel packets and, - * depending on the settings of the packet's VPN tunnel, passes the - * packet to the three modules below for handling. - * - The \link data_crypto Data Channel Crypto module\endlink: this - * module performs security operations on data channel packets. - * - The \link fragmentation Data Channel Fragmentation module\endlink: - * this module offers fragmentation of data channel packets larger - * than the VPN tunnel's MTU. - * - The \link compression Data Channel Compression module\endlink: this - * module offers compression of data channel packets. - * - * @subsection mainpage_modules_example Example event: receiving a packet - * - * OpenVPN handles many types of events during operation. These include - * external events, such as network traffic being received, and internal - * events, such as a %key session timing out causing renegotiation. An - * example event, receiving a packet over the network, is described here - * together with which modules play what roles: - * -# The \link eventloop Main Event Loop\endlink detects that a packet - * can be read from the external or the virtual tun/tap network - * interface. - * -# The \link eventloop Main Event Loop\endlink calls the \link - * external_multiplexer External Multiplexer\endlink or \link - * internal_multiplexer Internal Multiplexer\endlink to read and - * process the packet. - * -# The multiplexer module determines the type of packet and its - * destination, and passes the packet on to the appropriate handling - * module: - * - A control channel packet received by the \link - * external_multiplexer External Multiplexer\endlink is passed on - * through the \link reliable Reliability Layer\endlink and the \link - * control_tls Control Channel TLS module\endlink to the \link - * control_processor Control Channel Processor\endlink. - * - A data channel packet received by either multiplexer module is - * passed on to the \link data_control Data Channel Control - * module\endlink. - * -# The packet is processed by the appropriate control channel or data - * channel modules. - * -# If, after processing the packet, a resulting packet is generated - * that needs to be sent to a local or remote destination, it is given - * to the \link external_multiplexer External Multiplexer\endlink or - * \link internal_multiplexer Internal Multiplexer\endlink for sending. - * -# If a packet is waiting to be sent by either multiplexer module and - * the \link eventloop Main Event Loop\endlink detects that data can be - * written to the associated network interface, it calls the - * multiplexer module to send the packet. - * - * @section mainpage_relatedpages Related pages - * - * This documentation includes a number of descriptions of various aspects - * of OpenVPN and its implementation. These are not directly related to - * one module, function, or data structure, and are therefore listed - * separately under "Related Pages". - * - * @subsection mainpage_relatedpages_key_generation Data channel key generation - * - * The @ref key_generation "Data channel key generation" related page - * describes how, during VPN tunnel setup and renegotiation, OpenVPN peers - * generate and exchange the %key material required for the symmetric - * encryption/decryption and HMAC signing/verifying security operations - * performed on data channel packets. - * - * @subsection mainpage_relatedpages_tunnel_state VPN tunnel state - * - * The @ref tunnel_state "Structure of VPN tunnel state storage" related - * page describes how an OpenVPN process manages the state information - * associated with its active VPN tunnels. - * - * @subsection mainpage_relatedpages_network_protocol Network protocol - * - * The @ref network_protocol "Network protocol" related page describes the - * format and content of VPN tunnel packets exchanged between OpenVPN - * peers. - * - * @subsection mainpage_relatedpages_memory_management Memory management - * - * The @ref memory_management "Memory management strategies" related page - * gives a brief introduction into OpenVPN's memory %buffer library and - * garbage collection facilities. - */ diff --git a/app/openvpn/doc/doxygen/doc_memory_management.h b/app/openvpn/doc/doxygen/doc_memory_management.h deleted file mode 100644 index f948783e..00000000 --- a/app/openvpn/doc/doxygen/doc_memory_management.h +++ /dev/null @@ -1,99 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file - * Memory management strategies documentation file. - */ - -/** - * @page memory_management OpenVPN's memory management strategies - * - * This section describes several implementation details relating to - * OpenVPN's memory management strategies. - * - * During operation, the OpenVPN process performs all kinds of operations - * on blocks of data. Receiving packets, encrypting content, prepending - * headers, etc. To make the programmer's job easier and to decrease the - * likelihood of memory-related bugs, OpenVPN uses its own memory %buffer - * library and garbage collection facilities. These are described in - * brief here. - * - * @section memory_management_buffer The buffer structure - * - * The \c buffer structure is a wrapper around a block of dynamically - * allocated memory which keeps track of the block's capacity \c - * buffer.capacity and location in memory \c buffer.data. This structure - * supports efficient prepending and appending within the allocated memory - * through the use of offset \c buffer.offset and length \c buffer.len - * fields. See the \c buffer documentation for more details on the - * structure itself. - * - * OpenVPN's %buffer library, implemented in the \c buffer.h and \c - * buffer.c files, contains many utility functions for working with \c - * buffer structures. These functions facilitate common operations, such - * as allocating, freeing, reading and writing to \c buffer structures, - * and even offer several more advanced operations, such as string - * matching and creating sub-buffers. - * - * Not only do these utility functions make working with \c buffer - * structures easy, they also perform extensive error checking. Each - * function, where necessary, checks whether enough space is available - * before performing its actions. This minimizes the chance of bugs - * leading to %buffer overflows and other vulnerabilities. - * - * @section memory_management_frame The frame structure - * - * The \c frame structure keeps track of the maximum allowed packet - * geometries of a network connection. - * - * It is used, for example, to determine the size of \c buffer structures - * in which to store data channel packets. This is done by having each - * data channel processing module register the maximum amount of extra - * space it will need for header prepending and content expansion in the - * \c frame structure. Once these parameters are known, \c buffer - * structures can be allocated, based on the \c frame parameters, so that - * they are large enough to allow efficient prepending of headers and - * processing of content. - * - * @section memory_management_garbage Garbage collection - * - * OpenVPN has many sizable functions which perform various actions - * depending on their %context. This makes it difficult to know in advance - * exactly how much memory must be allocated. The garbage collection - * facilities are used to keep track of dynamic allocations, thereby - * allowing easy collective freeing of the allocated memory. - * - * The garbage collection system is implemented by the \c gc_arena and \c - * gc_entry structures. The arena represents a garbage collecting unit, - * and contains a linked list of entries. Each entry represents one block - * of dynamically allocated memory. - * - * The garbage collection system also contains various utility functions - * for working with the garbage collection structures. These include - * functions for initializing new arenas, allocating memory of a given - * size and registering the allocation in an arena, and freeing all the - * allocated memory associated with an arena. - */ diff --git a/app/openvpn/doc/doxygen/doc_protocol_overview.h b/app/openvpn/doc/doxygen/doc_protocol_overview.h deleted file mode 100644 index 26fed331..00000000 --- a/app/openvpn/doc/doxygen/doc_protocol_overview.h +++ /dev/null @@ -1,199 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file Network protocol overview documentation file. - */ - -/** - * @page network_protocol OpenVPN's network protocol - * - * Description of packet structure in OpenVPN's network protocol. - * - * This document describes the structure of packets exchanged between - * OpenVPN peers. It is based on the protocol description in the \c ssl.h - * file. - * - * @section network_protocol_external Outer structure of packets exchanged between OpenVPN peers - * - * VPN tunnel packets are transported between OpenVPN peers using the UDP - * or TCP protocols. Their structure is described below. - * - * @subsection network_protocol_external_structure External packet structure - * - * - packet length (16 bits, unsigned) [TCP-mode only]: always sent as - * plain text. Since TCP is a stream protocol, this packet length - * defines the packetization of the stream. - * - packet opcode and key_id (8 bits) [TLS-mode only]: - * - package message type (high 5 bits) - * - key_id (low 3 bits): the key_id refers to an already negotiated - * TLS session. OpenVPN seamlessly renegotiates the TLS session by - * using a new key_id for the new session. Overlap (controlled by - * user definable parameters) between old and new TLS sessions is - * allowed, providing a seamless transition during tunnel operation. - * - payload (n bytes) - * - * @subsection network_protocol_external_types Message types - * - * The type of a VPN tunnel packet is indicated by its opcode. The - * following describes the various opcodes available. - * - * - Control channel messages: - * - \c P_CONTROL_HARD_RESET_CLIENT_V1 -- %Key method 1, initial %key - * from client, forget previous state. - * - \c P_CONTROL_HARD_RESET_SERVER_V1 -- %Key method 1, initial %key - * from server, forget previous state. - * - \c P_CONTROL_HARD_RESET_CLIENT_V2 -- %Key method 2, initial %key - * from client, forget previous state. - * - \c P_CONTROL_HARD_RESET_SERVER_V2 -- %Key method 2, initial %key - * from server, forget previous state. - * - \c P_CONTROL_SOFT_RESET_V1 -- New %key, with a graceful - * transition from old to new %key in the sense that a transition - * window exists where both the old or new key_id can be used. - * - \c P_CONTROL_V1 -- Control channel packet (usually TLS - * ciphertext). - * - \c P_ACK_V1 -- Acknowledgement for control channel packets - * received. - * - Data channel messages: - * - \c P_DATA_V1 -- Data channel packet containing data channel - * ciphertext. - * - * @subsection network_protocol_external_key_id Session IDs and Key IDs - * - * OpenVPN uses two different forms of packet identifiers: - * - The first form is 64 bits and is used for all control channel - * messages. This form is referred to as a \c session_id. - * - Data channel messages on the other hand use a shortened form of 3 - * bits for efficiency reasons since the vast majority of OpenVPN - * packets in an active tunnel will be data channel messages. This - * form is referred to as a \c key_id. - * - * The control and data channels use independent packet-id sequences, - * because the data channel is an unreliable channel while the control - * channel is a %reliable channel. Each use their own independent HMAC - * keys. - * - * @subsection network_protocol_external_reliable Control channel reliability layer - * - * Control channel messages (\c P_CONTROL_* and \c P_ACK_* message types) - * are TLS ciphertext packets which have been encapsulated inside of a - * reliability layer. The reliability layer is implemented as a - * straightforward acknowledge and retransmit model. - * - * Acknowledgments of received messages can be encoded in either the - * dedicated \c P_ACK_* record or they can be prepended to a \c - * P_CONTROL_* message. - * - * See the \link reliable Reliability Layer\endlink module for a detailed - * description. - * - * @section network_protocol_control Structure of control channel messages - * - * @subsection network_protocol_control_ciphertext Structure of ciphertext control channel messages - * - * Control channel packets in ciphertext form consist of the following - * parts: - * - * - local \c session_id (random 64 bit value to identify TLS session). - * - HMAC signature of entire encapsulation header for HMAC firewall - * [only if \c --tls-auth is specified] (usually 16 or 20 bytes). - * - packet-id for replay protection (4 or 8 bytes, includes sequence - * number and optional \c time_t timestamp). - * - acknowledgment packet-id array length (1 byte). - * - acknowledgment packet-id array (if length > 0). - * - acknowledgment remote session-id (if length > 0). - * - packet-id of this message (4 bytes). - * - TLS payload ciphertext (n bytes) (only for \c P_CONTROL_V1). - * - * Note that when \c --tls-auth is used, all message types are protected - * with an HMAC signature, even the initial packets of the TLS handshake. - * This makes it easy for OpenVPN to throw away bogus packets quickly, - * without wasting resources on attempting a TLS handshake which will - * ultimately fail. - * - * @subsection network_protocol_control_key_methods Control channel key methods and - * - * Once the TLS session has been initialized and authenticated, the TLS - * channel is used to exchange random %key material for bidirectional - * cipher and HMAC keys which will be used to secure data channel packets. - * OpenVPN currently implements two %key methods. %Key method 1 directly - * derives keys using random bits obtained from the \c RAND_bytes() - * OpenSSL function. %Key method 2 mixes random %key material from both - * sides of the connection using the TLS PRF mixing function. %Key method - * 2 is the preferred method and is the default for OpenVPN 2.0. - * - * The @ref key_generation "Data channel key generation" related page - * describes the %key methods in more detail. - * - * @subsection network_protocol_control_plaintext Structure of plaintext control channel messages - * - * - %Key method 1: - * - Cipher %key length in bytes (1 byte). - * - Cipher %key (n bytes). - * - HMAC %key length in bytes (1 byte). - * - HMAC %key (n bytes). - * - %Options string (n bytes, null terminated, client/server %options - * string should match). - * - %Key method 2: - * - Literal 0 (4 bytes). - * - %Key method (1 byte). - * - \c key_source structure (\c key_source.pre_master only defined - * for client -> server). - * - %Options string length, including null (2 bytes). - * - %Options string (n bytes, null terminated, client/server %options - * string must match). - * - [The username/password data below is optional, record can end at - * this point.] - * - Username string length, including null (2 bytes). - * - Username string (n bytes, null terminated). - * - Password string length, including null (2 bytes). - * - Password string (n bytes, null terminated). - * - * @section network_protocol_data Structure of data channel messages - * - * @subsection network_protocol_data_ciphertext Structure of ciphertext data channel messages - * - * The P_DATA_* payload represents encrypted, encapsulated tunnel packets - * which tend to be either IP packets or Ethernet frames. This is - * essentially the "payload" of the VPN. - * - * Data channel packets in ciphertext form consist of the following parts: - * - HMAC of ciphertext IV + ciphertext (if not disabled by \c --auth - * none). - * - Ciphertext IV (size is cipher-dependent, if not disabled by \c - * --no-iv). - * - Tunnel packet ciphertext. - * - * @subsection network_protocol_data_plaintext Structure of plaintext data channel messages - * - * Data channel packets in plaintext form consist of the following parts: - * - packet-id (4 or 8 bytes, if not disabled by --no-replay). - * - In TLS mode, 4 bytes are used because the implementation can - * force a TLS renegotation before \c 2^32 packets are sent. - * - In pre-shared %key mode, 8 bytes are used (sequence number and \c - * time_t value) to allow long-term %key usage without packet-id - * collisions. - * - User plaintext (n bytes). - */ diff --git a/app/openvpn/doc/doxygen/doc_reliable.h b/app/openvpn/doc/doxygen/doc_reliable.h deleted file mode 100644 index 5264906a..00000000 --- a/app/openvpn/doc/doxygen/doc_reliable.h +++ /dev/null @@ -1,49 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file - * Reliability Layer module documentation file. - */ - -/** - * @defgroup reliable Reliability Layer module - * - * The Reliability Layer is part of OpenVPN's control channel. It - * provides a reliable and sequential transport mechanism for control - * channel messages between OpenVPN peers. This module forms the - * interface between the \link external_multiplexer External - * Multiplexer\endlink and the \link control_tls Control Channel TLS - * module\endlink. - * - * @par UDP or TCP as VPN tunnel transport - * - * This is especially important when OpenVPN is configured to communicate - * over UDP, because UDP does not offer a reliable and sequential - * transport. OpenVPN endpoints can also communicate over TCP which does - * provide a reliable and sequential transport. In both cases, using UDP - * or TCP as an external transport, the internal Reliability Layer is - * active. - */ diff --git a/app/openvpn/doc/doxygen/doc_tunnel_state.h b/app/openvpn/doc/doxygen/doc_tunnel_state.h deleted file mode 100644 index 6c93e71b..00000000 --- a/app/openvpn/doc/doxygen/doc_tunnel_state.h +++ /dev/null @@ -1,155 +0,0 @@ -/* - * OpenVPN -- An application to securely tunnel IP networks - * over a single TCP/UDP port, with support for SSL/TLS-based - * session authentication and key exchange, - * packet encryption, packet authentication, and - * packet compression. - * - * Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com> - * - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License version 2 - * as published by the Free Software Foundation. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program (see the file COPYING included with this - * distribution); if not, write to the Free Software Foundation, Inc., - * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - -/** - * @file - * VPN tunnel state documentation file. - */ - -/** - * @page tunnel_state Structure of the VPN tunnel state storage - * - * This section describes how OpenVPN stores its VPN tunnel state during - * operation. - * - * OpenVPN uses several data structures as storage containers for state - * information of active VPN tunnels. These are described in this - * section, together with a little bit of history to help understand the - * origin of the current architecture. - * - * Whether an OpenVPN process is running in client-mode or server-mode - * determines whether it can support only one or multiple simultaneously - * active VPN tunnels. This consequently also determines how the - * associated state information is wrapped up internally. This section - * gives an overview of the differences. - * - * @section tunnel_state_history Historic developments - * - * In the old v1.x series, an OpenVPN process managed only one single VPN - * tunnel. This allowed the VPN tunnel state to be stored together with - * process-global information in one single \c context structure. - * - * This changed, however, in the v2.x series, as new OpenVPN versions - * running in server-mode can support multiple simultaneously active VPN - * tunnels. This necessitated a redesign of the VPN tunnel state - * container structures, and modification of the \link - * external_multiplexer External Multiplexer\endlink and \link - * internal_multiplexer Internal Multiplexer\endlink systems. The - * majority of these changes are only relevant for OpenVPN processes - * running in server-mode, and the client-mode structure has remained very - * similar to the v1.x single-tunnel form. - * - * @section tunnel_state_client Client-mode state - * - * An OpenVPN process running in client-mode can manage at most one single - * VPN tunnel at any one time. The state information for a client's VPN - * tunnel is stored in a \c context structure. - * - * The \c context structure is created in the \c main() function. That is - * also where process-wide initialization takes place, such as parsing - * command line %options and reading configuration files. The \c context - * is then passed to \c tunnel_point_to_point() which drives OpenVPN's - * main event processing loop. These functions are both part of the \link - * eventloop Main Event Loop\endlink module. - * - * @subsection tunnel_state_client_init Initialization and cleanup - * - * Because there is only one \c context structure present, it can be - * initialized and cleaned up from the client's main event processing - * function. Before the \c tunnel_point_to_point() function enters its - * event loop, it calls \c init_instance_handle_signals() which calls \c - * init_instance() to initialize the single \c context structure. After - * the event loop stops, it calls \c close_instance() to clean up the \c - * context. - * - * @subsection tunnel_state_client_event Event processing - * - * When the main event processing loop activates the external or internal - * multiplexer to handle a network event, it is not necessary to determine - * which VPN tunnel the event is associated with, because there is only - * one VPN tunnel active. - * - * @section tunnel_state_server Server-mode state - * - * An OpenVPN process running in server-mode can manage multiple - * simultaneously active VPN tunnels. For every VPN tunnel active, in - * other words for every OpenVPN client which is connected to a server, - * the OpenVPN server has one \c context structure in which it stores that - * particular VPN tunnel's state information. - * - * @subsection tunnel_state_server_multi Multi_context and multi_instance structures - * - * To support multiple \c context structures, each is wrapped in a \c - * multi_instance structure, and all the \c multi_instance structures are - * registered in one single \c multi_context structure. The \link - * external_multiplexer External Multiplexer\endlink and \link - * internal_multiplexer Internal Multiplexer\endlink then use the \c - * multi_context to retrieve the correct \c multi_instance and \c context - * associated with a given network address. - * - * @subsection tunnel_state_server_init Startup and initialization - * - * An OpenVPN process running in server-mode starts in the same \c main() - * function as it would in client-mode. The same process-wide - * initialization is performed, and the resulting state and configuration - * is stored in a \c context structure. The server-mode and client-mode - * processes diverge when the \c main() function calls one of \c - * tunnel_point_to_point() or \c tunnel_server(). - * - * In server-mode, \c main() calls the \c tunnel_server() function, which - * transfers control to \c tunnel_server_udp_single_threaded() or \c - * tunnel_server_tcp() depending on the external transport protocol. - * - * These functions receive the \c context created in \c main(). This - * object has a special status in server-mode, as it does not represent an - * active VPN tunnel, but does contain process-wide configuration - * parameters. In the source code, it is often stored in "top" variables. - * To distinguish this object from other instances of the same type, its - * \c context.mode value is set to \c CM_TOP. Other \c context objects, - * which do represent active VPN tunnels, have a \c context.mode set to \c - * CM_CHILD_UDP or \c CM_CHILD_TCP, depending on the external transport - * protocol. - * - * Both \c tunnel_server_udp_single_threaded() and \c tunnel_server_tcp() - * perform similar initialization. In either case, a \c multi_context - * structure is created, and it is initialized according to the - * configuration stored in the top \c context by the \c multi_init() and - * \c multi_top_init() functions. - * - * @subsection tunnel_state_server_tunnels Creating and destroying VPN tunnels - * - * When an OpenVPN client makes a new connection to a server, the server - * creates a new \c context and \c multi_instance. The latter is - * registered in the \c multi_context, which makes it possible for the - * external and internal multiplexers to retrieve the correct \c - * multi_instance and \c context when a network event occurs. - * - * @subsection tunnel_state_server_cleanup Final cleanup - * - * After the main event loop exits, both \c - * tunnel_server_udp_single_threaded() and \c tunnel_server_tcp() perform - * similar cleanup. They call \c multi_uninit() followed by \c - * multi_top_free() to clean up the \c multi_context structure. - */ diff --git a/app/openvpn/doc/doxygen/openvpn.doxyfile b/app/openvpn/doc/doxygen/openvpn.doxyfile deleted file mode 100644 index 5d87172c..00000000 --- a/app/openvpn/doc/doxygen/openvpn.doxyfile +++ /dev/null @@ -1,279 +0,0 @@ -# Doxyfile 1.5.5 - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- -DOXYFILE_ENCODING = UTF-8 -PROJECT_NAME = "OpenVPN" -PROJECT_NUMBER = -OUTPUT_DIRECTORY = doxygen -CREATE_SUBDIRS = NO -OUTPUT_LANGUAGE = English -BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = YES -ABBREVIATE_BRIEF = "The $name class" \ - "The $name widget" \ - "The $name file" \ - is \ - provides \ - specifies \ - contains \ - represents \ - a \ - an \ - the -ALWAYS_DETAILED_SEC = NO -INLINE_INHERITED_MEMB = NO -FULL_PATH_NAMES = YES -STRIP_FROM_PATH = "" -STRIP_FROM_INC_PATH = -SHORT_NAMES = NO -JAVADOC_AUTOBRIEF = YES # NO -QT_AUTOBRIEF = NO -MULTILINE_CPP_IS_BRIEF = NO -DETAILS_AT_TOP = NO -INHERIT_DOCS = YES -SEPARATE_MEMBER_PAGES = NO -TAB_SIZE = 8 -ALIASES = -OPTIMIZE_OUTPUT_FOR_C = YES -OPTIMIZE_OUTPUT_JAVA = NO -OPTIMIZE_FOR_FORTRAN = NO -OPTIMIZE_OUTPUT_VHDL = NO -BUILTIN_STL_SUPPORT = NO -CPP_CLI_SUPPORT = NO -SIP_SUPPORT = NO -DISTRIBUTE_GROUP_DOC = NO -SUBGROUPING = YES -TYPEDEF_HIDES_STRUCT = NO -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- -EXTRACT_ALL = YES -EXTRACT_PRIVATE = YES -EXTRACT_STATIC = YES -EXTRACT_LOCAL_CLASSES = YES -EXTRACT_LOCAL_METHODS = YES -EXTRACT_ANON_NSPACES = YES -HIDE_UNDOC_MEMBERS = NO -HIDE_UNDOC_CLASSES = NO -HIDE_FRIEND_COMPOUNDS = NO -HIDE_IN_BODY_DOCS = NO -INTERNAL_DOCS = NO -CASE_SENSE_NAMES = NO -HIDE_SCOPE_NAMES = NO -SHOW_INCLUDE_FILES = YES -INLINE_INFO = YES -SORT_MEMBER_DOCS = YES -SORT_BRIEF_DOCS = NO -SORT_GROUP_NAMES = NO -SORT_BY_SCOPE_NAME = NO -GENERATE_TODOLIST = YES -GENERATE_TESTLIST = YES -GENERATE_BUGLIST = YES -GENERATE_DEPRECATEDLIST= YES -ENABLED_SECTIONS = -MAX_INITIALIZER_LINES = 30 -SHOW_USED_FILES = YES -SHOW_DIRECTORIES = NO -FILE_VERSION_FILTER = -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- -QUIET = NO -WARNINGS = YES -WARN_IF_UNDOCUMENTED = YES -WARN_IF_DOC_ERROR = YES -WARN_NO_PARAMDOC = NO -WARN_FORMAT = "$file:$line: $text" -WARN_LOGFILE = -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- -INPUT = . -INPUT_ENCODING = UTF-8 -FILE_PATTERNS = *.c \ - *.cc \ - *.cxx \ - *.cpp \ - *.c++ \ - *.d \ - *.java \ - *.ii \ - *.ixx \ - *.ipp \ - *.i++ \ - *.inl \ - *.h \ - *.hh \ - *.hxx \ - *.hpp \ - *.h++ \ - *.idl \ - *.odl \ - *.cs \ - *.php \ - *.php3 \ - *.inc \ - *.m \ - *.mm \ - *.dox \ - *.py \ - *.f90 \ - *.f \ - *.vhd \ - *.vhdl -RECURSIVE = YES -EXCLUDE = -EXCLUDE_SYMLINKS = NO -EXCLUDE_PATTERNS = -EXCLUDE_SYMBOLS = -EXAMPLE_PATH = -EXAMPLE_PATTERNS = * -EXAMPLE_RECURSIVE = NO -IMAGE_PATH = -INPUT_FILTER = -FILTER_PATTERNS = -FILTER_SOURCE_FILES = NO -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- -SOURCE_BROWSER = YES -INLINE_SOURCES = NO -STRIP_CODE_COMMENTS = YES -REFERENCED_BY_RELATION = YES -REFERENCES_RELATION = YES -REFERENCES_LINK_SOURCE = YES -USE_HTAGS = NO -VERBATIM_HEADERS = YES -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- -ALPHABETICAL_INDEX = NO -COLS_IN_ALPHA_INDEX = 5 -IGNORE_PREFIX = -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- -GENERATE_HTML = YES -HTML_OUTPUT = html -HTML_FILE_EXTENSION = .html -HTML_HEADER = -HTML_FOOTER = -HTML_STYLESHEET = -HTML_ALIGN_MEMBERS = YES -GENERATE_HTMLHELP = NO -GENERATE_DOCSET = NO -DOCSET_FEEDNAME = "Doxygen generated docs" -DOCSET_BUNDLE_ID = org.doxygen.Project -HTML_DYNAMIC_SECTIONS = NO -CHM_FILE = -HHC_LOCATION = -GENERATE_CHI = NO -BINARY_TOC = NO -TOC_EXPAND = NO -DISABLE_INDEX = NO -ENUM_VALUES_PER_LINE = 4 -GENERATE_TREEVIEW = NO -TREEVIEW_WIDTH = 250 -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- -GENERATE_LATEX = YES -LATEX_OUTPUT = latex -LATEX_CMD_NAME = latex -MAKEINDEX_CMD_NAME = makeindex -COMPACT_LATEX = YES # NO -PAPER_TYPE = a4wide -EXTRA_PACKAGES = -LATEX_HEADER = -PDF_HYPERLINKS = YES -USE_PDFLATEX = YES -LATEX_BATCHMODE = NO -LATEX_HIDE_INDICES = NO -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- -GENERATE_RTF = NO -RTF_OUTPUT = rtf -COMPACT_RTF = NO -RTF_HYPERLINKS = NO -RTF_STYLESHEET_FILE = -RTF_EXTENSIONS_FILE = -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- -GENERATE_MAN = NO -MAN_OUTPUT = man -MAN_EXTENSION = .3 -MAN_LINKS = NO -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- -GENERATE_XML = NO -XML_OUTPUT = xml -XML_SCHEMA = -XML_DTD = -XML_PROGRAMLISTING = YES -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- -GENERATE_AUTOGEN_DEF = NO -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- -GENERATE_PERLMOD = NO -PERLMOD_LATEX = NO -PERLMOD_PRETTY = YES -PERLMOD_MAKEVAR_PREFIX = -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = NO -EXPAND_ONLY_PREDEF = NO -SEARCH_INCLUDES = YES -INCLUDE_PATH = -INCLUDE_FILE_PATTERNS = -PREDEFINED = WIN32 NTLM USE_LZO ENABLE_FRAGMENT P2MP P2MP_SERVER USE_CRYPTO USE_SSL ENABLE_PLUGIN ENABLE_MANAGEMENT ENABLE_OCC HAVE_GETTIMEOFDAY -EXPAND_AS_DEFINED = -SKIP_FUNCTION_MACROS = YES -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- -TAGFILES = -GENERATE_TAGFILE = -ALLEXTERNALS = NO -EXTERNAL_GROUPS = YES -PERL_PATH = /usr/bin/perl -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- -CLASS_DIAGRAMS = NO -MSCGEN_PATH = -HIDE_UNDOC_RELATIONS = YES -HAVE_DOT = YES -CLASS_GRAPH = YES -COLLABORATION_GRAPH = YES -GROUP_GRAPHS = YES -UML_LOOK = NO -TEMPLATE_RELATIONS = NO -INCLUDE_GRAPH = YES -INCLUDED_BY_GRAPH = YES -CALL_GRAPH = NO # YES -CALLER_GRAPH = NO # YES -GRAPHICAL_HIERARCHY = YES -DIRECTORY_GRAPH = YES -DOT_IMAGE_FORMAT = png -DOT_PATH = "/usr/bin/dot" -DOTFILE_DIRS = -DOT_GRAPH_MAX_NODES = 50 -MAX_DOT_GRAPH_DEPTH = 1000 -DOT_TRANSPARENT = YES -DOT_MULTI_TARGETS = NO -GENERATE_LEGEND = YES -DOT_CLEANUP = YES -#--------------------------------------------------------------------------- -# Configuration::additions related to the search engine -#--------------------------------------------------------------------------- -SEARCHENGINE = NO diff --git a/app/openvpn/doc/management-notes.txt b/app/openvpn/doc/management-notes.txt deleted file mode 100644 index ef39b855..00000000 --- a/app/openvpn/doc/management-notes.txt +++ /dev/null @@ -1,1039 +0,0 @@ -OpenVPN Management Interface Notes ----------------------------------- - -The OpenVPN Management interface allows OpenVPN to -be administratively controlled from an external program via -a TCP or unix domain socket. - -The interface has been specifically designed for developers -who would like to programmatically or remotely control -an OpenVPN daemon, and can be used when OpenVPN is running -as a client or server. - -The management interface is implemented using a client/server TCP -connection or unix domain socket where OpenVPN will listen on a -provided IP address and port for incoming management client connections. - -The management protocol is currently cleartext without an explicit -security layer. For this reason, it is recommended that the -management interface either listen on a unix domain socket, -localhost (127.0.0.1), or on the local VPN address. It's possible -to remotely connect to the management interface over the VPN itself, -though some capabilities will be limited in this mode, such as the -ability to provide private key passwords. - -The management interface is enabled in the OpenVPN -configuration file using the following directive: - ---management - -See the man page for documentation on this and related -directives. - -Once OpenVPN has started with the management layer enabled, -you can telnet to the management port (make sure to use -a telnet client which understands "raw" mode). - -Once connected to the management port, you can use -the "help" command to list all commands. - -COMMAND -- bytecount --------------------- - -The bytecount command is used to request real-time notification -of OpenVPN bandwidth usage. - -Command syntax: - - bytecount n (where n > 0) -- set up automatic notification of - bandwidth usage once every n seconds - bytecount 0 -- turn off bytecount notifications - -If OpenVPN is running as a client, the bytecount notification -will look like this: - - >BYTECOUNT:{BYTES_IN},{BYTES_OUT} - -BYTES_IN is the number of bytes that have been received from -the server and BYTES_OUT is the number of bytes that have been -sent to the server. - -If OpenVPN is running as a server, the bytecount notification -will look like this: - - >BYTECOUNT_CLI:{CID},{BYTES_IN},{BYTES_OUT} - -CID is the Client ID, BYTES_IN is the number of bytes that have -been received from the client and BYTES_OUT is the number of -bytes that have been sent to the client. - -Note that when the bytecount command is used on the server, every -connected client will report its bandwidth numbers once every n -seconds. - -When the client disconnects, the final bandwidth numbers will be -placed in the 'bytes_received' and 'bytes_sent' environmental variables -as included in the >CLIENT:DISCONNECT notification. - -COMMAND -- echo ---------------- - -The echo capability is used to allow GUI-specific -parameters to be either embedded in the OpenVPN config file -or pushed to an OpenVPN client from a server. - -Command examples: - - echo on -- turn on real-time notification of echo messages - echo all -- print the current echo history list - echo off -- turn off real-time notification of echo messages - echo on all -- atomically enable real-time notification, - plus show any messages in history buffer - -For example, suppose you are developing a OpenVPN GUI and -you want to give the OpenVPN server the ability to ask -the GUI to forget any saved passwords. - -In the OpenVPN server config file, add: - - push "echo forget-passwords" - -When the OpenVPN client receives its pulled list of directives -from the server, the "echo forget-passwords" directive will -be in the list, and it will cause the management interface -to save the "forget-passwords" string in its list of echo -parameters. - -The management client can use "echo all" to output the full -list of echoed parameters, "echo on" to turn on real-time -notification of echoed parameters via the ">ECHO:" prefix, -or "echo off" to turn off real-time notification. - -When the GUI connects to the OpenVPN management socket, it -can issue an "echo all" command, which would produce output -like this: - - 1101519562,forget-passwords - END - -Essentially the echo command allowed us to pass parameters from -the OpenVPN server to the OpenVPN client, and then to the -management client (such as a GUI). The large integer is the -unix date/time when the echo parameter was received. - -If the management client had issued the command "echo on", -it would have enabled real-time notifications of echo -parameters. In this case, our "forget-passwords" message -would be output like this: - - >ECHO:1101519562,forget-passwords - -Like the log command, the echo command can atomically show -history while simultaneously activating real-time updates: - - echo on all - -The size of the echo buffer is currently hardcoded to 100 -messages. - -COMMAND -- exit, quit ---------------------- - -Close the managment session, and resume listening on the -management port for connections from other clients. Currently, -the OpenVPN daemon can at most support a single management client -any one time. - -COMMAND -- help ---------------- - -Print a summary of commands. - -COMMAND -- hold ---------------- - -The hold command can be used to manipulate the hold flag, -or release OpenVPN from a hold state. - -If the hold flag is set on initial startup or -restart, OpenVPN will hibernate prior to initializing -the tunnel until the management interface receives -a "hold release" command. - -The --management-hold directive of OpenVPN can be used -to start OpenVPN with the hold flag set. - -The hold flag setting is persistent and will not -be reset by restarts. - -OpenVPN will indicate that it is in a hold state by -sending a real-time notification to the management -client: - - >HOLD:Waiting for hold release - -Command examples: - - hold -- show current hold flag, 0=off, 1=on. - hold on -- turn on hold flag so that future restarts - will hold. - hold off -- turn off hold flag so that future restarts will - not hold. - hold release -- leave hold state and start OpenVPN, but - do not alter the current hold flag setting. - -COMMAND -- kill ---------------- - -In server mode, kill a particlar client instance. - -Command examples: - - kill Test-Client -- kill the client instance having a - common name of "Test-Client". - kill 1.2.3.4:4000 -- kill the client instance having a - source address and port of 1.2.3.4:4000 - -Use the "status" command to see which clients are connected. - -COMMAND -- log --------------- - -Show the OpenVPN log file. Only the most recent n lines -of the log file are cached by the management interface, where -n is controlled by the OpenVPN --management-log-cache directive. - -Command examples: - - log on -- Enable real-time output of log messages. - log all -- Show currently cached log file history. - log on all -- Atomically show all currently cached log file - history then enable real-time notification of - new log file messages. - log off -- Turn off real-time notification of log messages. - log 20 -- Show the most recent 20 lines of log file history. - -Real-time notification format: - -Real-time log messages begin with the ">LOG:" prefix followed -by the following comma-separated fields: - - (a) unix integer date/time, - (b) zero or more message flags in a single string: - I -- informational - F -- fatal error - N -- non-fatal error - W -- warning - D -- debug, and - (c) message text. - -COMMAND -- mute ---------------- - -Change the OpenVPN --mute parameter. The mute parameter is -used to silence repeating messages of the same message -category. - -Command examples: - - mute 40 -- change the mute parameter to 40 - mute -- show the current mute setting - -COMMAND -- net --------------- - -(Windows Only) Produce output equivalent to the OpenVPN ---show-net directive. The output includes OpenVPN's view -of the system network adapter list and routing table based -on information returned by the Windows IP helper API. - -COMMAND -- pid --------------- - -Shows the process ID of the current OpenVPN process. - -COMMAND -- password and username --------------------------------- - - The password command is used to pass passwords to OpenVPN. - - If OpenVPN is run with the --management-query-passwords - directive, it will query the management interface for RSA - private key passwords and the --auth-user-pass - username/password. - - When OpenVPN needs a password from the management interface, - it will produce a real-time ">PASSWORD:" message. - - Example 1: - - >PASSWORD:Need 'Private Key' password - - OpenVPN is indicating that it needs a password of type - "Private Key". - - The management client should respond to this query as follows: - - password "Private Key" foo - - Example 2: - - >PASSWORD:Need 'Auth' username/password - - OpenVPN needs a --auth-user-pass password. The management - client should respond: - - username "Auth" foo - password "Auth" bar - - The username/password itself can be in quotes, and special - characters such as double quote or backslash must be escaped, - for example, - - password "Private Key" "foo\"bar" - - The escaping rules are the same as for the config file. - See the "Command Parsing" section below for more info. - - The PASSWORD real-time message type can also be used to - indicate password or other types of authentication failure: - - Example 3: The private key password is incorrect and OpenVPN - is exiting: - - >PASSWORD:Verification Failed: 'Private Key' - - Example 4: The --auth-user-pass username/password failed, - and OpenVPN is exiting: - - >PASSWORD:Verification Failed: 'Auth' - - Example 5: The --auth-user-pass username/password failed, - and the server provided a custom client-reason-text string - using the client-deny server-side management interface command. - - >PASSWORD:Verification Failed: 'custom server-generated string' - -COMMAND -- forget-passwords ---------------------------- - -The forget-passwords command will cause the daemon to forget passwords -entered during the session. - -Command example: - - forget-passwords -- forget passwords entered so far. - -COMMAND -- signal ------------------ - -The signal command will send a signal to the OpenVPN daemon. -The signal can be one of SIGHUP, SIGTERM, SIGUSR1, or SIGUSR2. - -Command example: - - signal SIGUSR1 -- send a SIGUSR1 signal to daemon - -COMMAND -- state ----------------- - -Show the current OpenVPN state, show state history, or -enable real-time notification of state changes. - -These are the OpenVPN states: - -CONNECTING -- OpenVPN's initial state. -WAIT -- (Client only) Waiting for initial response - from server. -AUTH -- (Client only) Authenticating with server. -GET_CONFIG -- (Client only) Downloading configuration options - from server. -ASSIGN_IP -- Assigning IP address to virtual network - interface. -ADD_ROUTES -- Adding routes to system. -CONNECTED -- Initialization Sequence Completed. -RECONNECTING -- A restart has occurred. -EXITING -- A graceful exit is in progress. - -Command examples: - - state -- Print current OpenVPN state. - state on -- Enable real-time notification of state changes. - state off -- Disable real-time notification of state changes. - state all -- Print current state history. - state 3 -- Print the 3 most recent state transitions. - state on all -- Atomically show state history while at the - same time enable real-time state notification - of future state transitions. - -The output format consists of 4 comma-separated parameters: - (a) the integer unix date/time, - (b) the state name, - (c) optional descriptive string (used mostly on RECONNECTING - and EXITING to show the reason for the disconnect), - (d) optional TUN/TAP local IP address (shown for ASSIGN_IP - and CONNECTED), and - (e) optional address of remote server (OpenVPN 2.1 or higher). - -Real-time state notifications will have a ">STATE:" prefix -prepended to them. - -COMMAND -- status ------------------ - -Show current daemon status information, in the same format as -that produced by the OpenVPN --status directive. - -Command examples: - -status -- Show status information using the default status - format version. - -status 3 -- Show status information using the format of - --status-version 3. - -COMMAND -- username -------------------- - -See the "password" section above. - -COMMAND -- verb ---------------- - -Change the OpenVPN --verb parameter. The verb parameter -controls the output verbosity, and may range from 0 (no output) -to 15 (maximum output). See the OpenVPN man page for additional -info on verbosity levels. - -Command examples: - - verb 4 -- change the verb parameter to 4 - mute -- show the current verb setting - -COMMAND -- version ------------------- - -Show the current OpenVPN and Management Interface versions. - - -COMMAND -- auth-retry ---------------------- - -Set the --auth-retry setting to control how OpenVPN responds to -username/password authentication errors. See the manual page -for more info. - -Command examples: - - auth-retry interact -- Don't exit when bad username/passwords are entered. - Query for new input and retry. - -COMMAND -- needok (OpenVPN 2.1 or higher) ------------------------------------------- - -Confirm a ">NEED-OK" real-time notification, normally used by -OpenVPN to block while waiting for a specific user action. - -Example: - - OpenVPN needs the user to insert a cryptographic token, - so it sends a real-time notification: - - >NEED-OK:Need 'token-insertion-request' confirmation MSG:Please insert your cryptographic token - - The management client, if it is a GUI, can flash a dialog - box containing the text after the "MSG:" marker to the user. - When the user acknowledges the dialog box, - the management client can issue this command: - - needok token-insertion-request ok - or - needok token-insertion-request cancel - -COMMAND -- needstr (OpenVPN 2.1 or higher) -------------------------------------------- - -Confirm a ">NEED-STR" real-time notification, normally used by -OpenVPN to block while waiting for a specific user input. - -Example: - - OpenVPN needs the user to specify some input, so it sends a - real-time notification: - - >NEED-STR:Need 'name' input MSG:Please specify your name - - The management client, if it is a GUI, can flash a dialog - box containing the text after the "MSG:" marker to the user. - When the user acknowledges the dialog box, - the management client can issue this command: - - needstr name "John" - -COMMAND -- pkcs11-id-count (OpenVPN 2.1 or higher) ---------------------------------------------------- - -Retrieve available number of certificates. - -Example: - - pkcs11-id-count - >PKCS11ID-COUNT:5 - -COMMAND -- pkcs11-id-get (OpenVPN 2.1 or higher) -------------------------------------------------- - -Retrieve certificate by index, the ID string should be provided -as PKCS#11 identity, the blob is BASE64 encoded certificate. - -Example: - - pkcs11-id-get 1 - PKCS11ID-ENTRY:'1', ID:'<snip>', BLOB:'<snip>' - -COMMAND -- client-auth (OpenVPN 2.1 or higher) ------------------------------------------------ - -Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request and specify -"client-connect" configuration directives in a subsequent text block. - -The OpenVPN server should have been started with the ---management-client-auth directive so that it will ask the management -interface to approve client connections. - - - client-auth {CID} {KID} - line_1 - line_2 - ... - line_n - END - -CID,KID -- client ID and Key ID. See documentation for ">CLIENT:" -notification for more info. - -line_1 to line_n -- client-connect configuration text block, as would be -returned by a --client-connect script. The text block may be null, with -"END" immediately following the "client-auth" line (using a null text -block is equivalent to using the client-auth-nt command). - -A client-connect configuration text block contains OpenVPN directives -that will be applied to the client instance object representing a newly -connected client. - -COMMAND -- client-auth-nt (OpenVPN 2.1 or higher) --------------------------------------------------- - -Authorize a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request without specifying -client-connect configuration text. - -The OpenVPN server should have been started with the ---management-client-auth directive so that it will ask the management -interface to approve client connections. - - client-auth-nt {CID} {KID} - -CID,KID -- client ID and Key ID. See documentation for ">CLIENT:" -notification for more info. - -COMMAND -- client-deny (OpenVPN 2.1 or higher) ------------------------------------------------ - -Deny a ">CLIENT:CONNECT" or ">CLIENT:REAUTH" request. - - client-deny {CID} {KID} "reason-text" ["client-reason-text"] - -CID,KID -- client ID and Key ID. See documentation for ">CLIENT:" -notification for more info. - -reason-text: a human-readable message explaining why the authentication -request was denied. This message will be output to the OpenVPN log -file or syslog. - -client-reason-text: a message that will be sent to the client as -part of the AUTH_FAILED message. - -Note that client-deny denies a specific Key ID (pertaining to a -TLS renegotiation). A client-deny command issued in response to -an initial TLS key negotiation (notified by ">CLIENT:CONNECT") will -terminate the client session after returning "AUTH-FAILED" to the client. -On the other hand, a client-deny command issued in response to -a TLS renegotiation (">CLIENT:REAUTH") will invalidate the renegotiated -key, however the TLS session associated with the currently active -key will continue to live for up to --tran-window seconds before -expiration. - -To immediately kill a client session, use "client-kill". - -COMMAND -- client-kill (OpenVPN 2.1 or higher) ------------------------------------------------ - -Immediately kill a client instance by CID. - - client-kill {CID} - -CID -- client ID. See documentation for ">CLIENT:" notification for more -info. - -COMMAND -- client-pf (OpenVPN 2.1 or higher) ---------------------------------------------- - -Push a packet filter file to a specific client. - -The OpenVPN server should have been started with the ---management-client-pf directive so that it will require that -VPN tunnel packets sent or received by client instances must -conform to that client's packet filter configuration. - - client-pf {CID} - line_1 - line_2 - ... - line_n - END - -CID -- client ID. See documentation for ">CLIENT:" notification for -more info. - -line_1 to line_n -- the packet filter configuration file for this -client. - -Packet filter file grammar: - - [CLIENTS DROP|ACCEPT] - {+|-}common_name1 - {+|-}common_name2 - . . . - [SUBNETS DROP|ACCEPT] - {+|-}subnet1 - {+|-}subnet2 - . . . - [END] - - Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS | "unknown" - - CLIENTS refers to the set of clients (by their common-name) which - this instance is allowed ('+') to connect to, or is excluded ('-') - from connecting to. Note that in the case of client-to-client - connections, such communication must be allowed by the packet filter - configuration files of both clients AND the --client-to-client - directive must have been specified in the OpenVPN server config. - - SUBNETS refers to IP addresses or IP address subnets which this - client instance may connect to ('+') or is excluded ('-') from - connecting to, and applies to IPv4 and ARP packets. The special - "unknown" tag refers to packets of unknown type, i.e. a packet that - is not IPv4 or ARP. - - DROP or ACCEPT defines default policy when there is no explicit match - for a common-name or subnet. The [END] tag must exist. - - Notes: - - * The SUBNETS section currently only supports IPv4 addresses and - subnets. - - * A given client or subnet rule applies to both incoming and - outgoing packets. - - * The CLIENTS list is order-invariant. Because the list is stored - as a hash-table, the order of the list does not affect its function. - - * The SUBNETS table is scanned sequentially, and the first item to - match is chosen. Therefore the SUBNETS table is NOT order-invariant. - - * No client-to-client communication is allowed unless the - --client-to-client configuration directive is enabled AND - the CLIENTS list of BOTH clients allows the communication. - -Example packet filter spec, as transmitted to the management interface: - - client-pf 42 - [CLIENTS ACCEPT] - -accounting - -enigma - [SUBNETS DROP] - -10.46.79.9 - +10.0.0.0/8 - [END] - END - -The above example sets the packet filter policy for the client -identified by CID=42. This client may connect to all other clients -except those having a common name of "accounting" or "enigma". -The client may only interact with external IP addresses in the -10.0.0.0/8 subnet, however access to 10.46.79.9 is specifically -excluded. - -Another example packet filter spec, as transmitted to the -management interface: - - client-pf 99 - [CLIENTS DENY] - +public - [SUBNETS ACCEPT] - +10.10.0.1 - -10.0.0.0/8 - -unknown - [END] - END - -The above example sets the packet filter policy for the client -identified by CID=99. This client may not connect to any other -clients except those having a common name of "public". It may -interact with any external IP address except those in the -10.0.0.0/8 netblock. However interaction with one address in -the 10.0.0.0/8 netblock is allowed: 10.10.0.1. Also, the client -may not interact with external IP addresses using an "unknown" -protocol (i.e. one that is not IPv4 or ARP). - -COMMAND -- remote (OpenVPN AS 2.1.5/OpenVPN 2.3 or higher) --------------------------------------------- - -Provide remote host/port in response to a >REMOTE notification -(client only). Requires that the --management-query-remote -directive is used. - - remote ACTION [HOST PORT] - -The "remote" command should only be given in response to a >REMOTE -notification. For example, the following >REMOTE notification -indicates that the client config file would ordinarily connect -to vpn.example.com port 1194 (UDP): - - >REMOTE:vpn.example.com,1194,udp - -Now, suppose we want to override the host and port, connecting -instead to vpn.otherexample.com port 1234. After receiving -the above notification, use this command: - - remote MOD vpn.otherexample.com 1234 - -To accept the same host and port as the client would ordinarily -have connected to, use this command: - - remote ACCEPT - -To skip the current connection entry and advance to the next one, -use this command: - - remote SKIP - -COMMAND -- proxy (OpenVPN 2.3 or higher) --------------------------------------------- - -Provide proxy server host/port and flags in response to a >PROXY -notification (client only). Requires that the --management-query-proxy -directive is used. - - proxy TYPE HOST PORT ["nct"] - -The "proxy" command must only be given in response to a >PROXY -notification. Use the "nct" flag if you only want to allow -non-cleartext auth with the proxy server. The following >PROXY -notification indicates that the client config file would ordinarily -connect to the first --remote configured, vpn.example.com using TCP: - - >PROXY:1,TCP,vpn.example.com - -Now, suppose we want to connect to the remote host using the proxy server -proxy.intranet port 8080 with secure authentication only, if required. -After receiving the above notification, use this command: - - proxy HTTP proxy.intranet 8080 nct - -You can also use the SOCKS keyword to pass a SOCKS server address, like: - - proxy SOCKS fe00::1 1080 - -To accept connecting to the host and port directly, use this command: - - proxy NONE - -COMMAND -- rsa-sig (OpenVPN 2.3 or higher) ------------------------------------------- -Provides support for external storage of the private key. Requires the ---management-external-key option. This option can be used instead of "key" -in client mode, and allows the client to run without the need to load the -actual private key. When the SSL protocol needs to perform an RSA sign -operation, the data to be signed will be sent to the management interface -via a notification as follows: - ->RSA_SIGN:[BASE64_DATA] - -The management interface client should then sign BASE64_DATA -using the private key and return the SSL signature as follows: - -rsa-sig -[BASE64_SIG_LINE] -. -. -. -END - -Base64 encoded output of RSA_sign(NID_md5_sha1,... will provide a -correct signature. - -This capability is intended to allow the use of arbitrary cryptographic -service providers with OpenVPN via the management interface. - - -OUTPUT FORMAT -------------- - -(1) Command success/failure indicated by "SUCCESS: [text]" or - "ERROR: [text]". - -(2) For commands which print multiple lines of output, - the last line will be "END". - -(3) Real-time messages will be in the form ">[source]:[text]", - where source is "CLIENT", "ECHO", "FATAL", "HOLD", "INFO", "LOG", - "NEED-OK", "PASSWORD", or "STATE". - -REAL-TIME MESSAGE FORMAT ------------------------- - -The OpenVPN management interface produces two kinds of -output: (a) output from a command, or (b) asynchronous, -real-time output which can be generated at any time. - -Real-time messages start with a '>' character in the first -column and are immediately followed by a type keyword -indicating the type of real-time message. The following -types are currently defined: - -BYTECOUNT -- Real-time bandwidth usage notification, as enabled - by "bytecount" command when OpenVPN is running as - a client. - -BYTECOUNT_CLI -- Real-time bandwidth usage notification per-client, - as enabled by "bytecount" command when OpenVPN is - running as a server. - -CLIENT -- Notification of client connections and disconnections - on an OpenVPN server. Enabled when OpenVPN is started - with the --management-client-auth option. CLIENT - notifications may be multi-line. See "The CLIENT - notification" section below for detailed info. - -ECHO -- Echo messages as controlled by the "echo" command. - -FATAL -- A fatal error which is output to the log file just - prior to OpenVPN exiting. - -HOLD -- Used to indicate that OpenVPN is in a holding state - and will not start until it receives a - "hold release" command. - -INFO -- Informational messages such as the welcome message. - -LOG -- Log message output as controlled by the "log" command. - -NEED-OK -- OpenVPN needs the end user to do something, such as - insert a cryptographic token. The "needok" command can - be used to tell OpenVPN to continue. - -NEED-STR -- OpenVPN needs information from end, such as - a certificate to use. The "needstr" command can - be used to tell OpenVPN to continue. - -PASSWORD -- Used to tell the management client that OpenVPN - needs a password, also to indicate password - verification failure. - -STATE -- Shows the current OpenVPN state, as controlled - by the "state" command. - -The CLIENT notification ------------------------ - -The ">CLIENT:" notification is enabled by the --management-client-auth -OpenVPN configuration directive that gives the management interface client -the responsibility to authenticate OpenVPN clients after their client -certificate has been verified. CLIENT notifications may be multi-line, and -the sequentiality of a given CLIENT notification, its associated environmental -variables, and the terminating ">CLIENT:ENV,END" line are guaranteed to be -atomic. - -CLIENT notification types: - -(1) Notify new client connection ("CONNECT") or existing client TLS session - renegotiation ("REAUTH"). Information about the client is provided - by a list of environmental variables which are documented in the OpenVPN - man page. The environmental variables passed are equivalent to those - that would be passed to an --auth-user-pass-verify script. - - >CLIENT:CONNECT|REAUTH,{CID},{KID} - >CLIENT:ENV,name1=val1 - >CLIENT:ENV,name2=val2 - >CLIENT:ENV,... - >CLIENT:ENV,END - -(2) Notify successful client authentication and session initiation. - Called after CONNECT. - - >CLIENT:ESTABLISHED,{CID} - >CLIENT:ENV,name1=val1 - >CLIENT:ENV,name2=val2 - >CLIENT:ENV,... - >CLIENT:ENV,END - -(3) Notify existing client disconnection. The environmental variables passed - are equivalent to those that would be passed to a --client-disconnect - script. - - >CLIENT:DISCONNECT,{CID} - >CLIENT:ENV,name1=val1 - >CLIENT:ENV,name2=val2 - >CLIENT:ENV,... - >CLIENT:ENV,END - -(4) Notify that a particular virtual address or subnet - is now associated with a specific client. - - >CLIENT:ADDRESS,{CID},{ADDR},{PRI} - -Variables: - -CID -- Client ID, numerical ID for each connecting client, sequence = 0,1,2,... -KID -- Key ID, numerical ID for the key associated with a given client TLS session, - sequence = 0,1,2,... -PRI -- Primary (1) or Secondary (0) VPN address/subnet. All clients have at least - one primary IP address. Secondary address/subnets are associated with - client-specific "iroute" directives. -ADDR -- IPv4 address/subnet in the form 1.2.3.4 or 1.2.3.0/255.255.255.0 - -In the unlikely scenario of an extremely long-running OpenVPN server, -CID and KID should be assumed to recycle to 0 after (2^32)-1, however this -recycling behavior is guaranteed to be collision-free. - -Command Parsing ---------------- - -The management interface uses the same command line lexical analyzer -as is used by the OpenVPN config file parser. - -Whitespace is a parameter separator. - -Double quotation or single quotation characters ("", '') can be used -to enclose parameters containing whitespace. - -Backslash-based shell escaping is performed, using the following -mappings, when not in single quotations: - -\\ Maps to a single backslash character (\). -\" Pass a literal doublequote character ("), don't - interpret it as enclosing a parameter. -\[SPACE] Pass a literal space or tab character, don't - interpret it as a parameter delimiter. - -Challenge/Response Protocol ---------------------------- - -The OpenVPN Challenge/Response Protocol allows an OpenVPN server to -generate challenge questions that are shown to the user, and to see -the user's responses to those challenges. Based on the responses, the -server can allow or deny access. - -In this way, the OpenVPN Challenge/Response Protocol can be used -to implement multi-factor authentication. Two different -variations on the challenge/response protocol are supported: the -"Dynamic" and "Static" protocols. - -The basic idea of Challenge/Response is that the user must enter an -additional piece of information, in addition to the username and -password, to successfully authenticate. Normally, this information -is used to prove that the user posesses a certain key-like device -such as cryptographic token or a particular mobile phone. - -Dynamic protocol: - -The OpenVPN dynamic challenge/response protocol works by returning -a specially formatted error message after initial successful -authentication. This error message contains the challenge question, -and is formatted as such: - - CRV1:<flags>:<state_id>:<username_base64>:<challenge_text> - -flags: a series of optional, comma-separated flags: - E : echo the response when the user types it - R : a response is required - -state_id: an opaque string that should be returned to the server - along with the response. - -username_base64 : the username formatted as base64 - -challenge_text : the challenge text to be shown to the user - -Example challenge: - - CRV1:R,E:Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l:Y3Ix:Please enter token PIN - -After showing the challenge_text and getting a response from the user -(if R flag is specified), the client should submit the following -auth creds back to the OpenVPN server: - -Username: [username decoded from username_base64] -Password: CRV1::<state_id>::<response_text> - -Where state_id is taken from the challenge request and response_text -is what the user entered in response to the challenge_text. -If the R flag is not present, response_text may be the empty -string. - -Example response (suppose the user enters "8675309" for the token PIN): - - Username: cr1 ("Y3Ix" base64 decoded) - Password: CRV1::Om01u7Fh4LrGBS7uh0SWmzwabUiGiW6l::8675309 - -Static protocol: - -The static protocol differs from the dynamic protocol in that the -challenge question and response field is given to the user in the -initial username/password dialog, and the username, password, and -response are delivered back to the server in a single transaction. - -The "static-challenge" directive is used to give the challenge text -to OpenVPN and indicate whether or not the response should be echoed. - -When the "static-challenge" directive is used, the management -interface will respond as such when credentials are needed: - - >PASSWORD:Need 'Auth' username/password SC:<ECHO>,<TEXT> - - ECHO: "1" if response should be echoed, "0" to not echo - TEXT: challenge text that should be shown to the user to - facilitate their response - -For example: - - >PASSWORD:Need 'Auth' username/password SC:1,Please enter token PIN - -The above notification indicates that OpenVPN needs a --auth-user-pass -password plus a response to a static challenge ("Please enter token PIN"). -The "1" after the "SC:" indicates that the response should be echoed. - -The management interface client in this case should add the static -challenge text to the auth dialog followed by a field for the user to -enter a response. Then the client should pack the password and response -together into an encoded password: - - username "Auth" foo - password "Auth" "SCRV1:<BASE64_PASSWORD>:<BASE64_RESPONSE>" - -For example, if the user entered "bar" as the password and 8675309 -as the PIN, the following management interface commands should be -issued: - - username "Auth" foo - password "Auth" "SCRV1:Zm9v:ODY3NTMwOQ==" - -Client-side support for challenge/response protocol: - -Currently, the Access Server client and standalone OpenVPN -client support both static and dynamic challenge/response -protocols. However, any OpenVPN client UI that drives OpenVPN -via the management interface needs to add explicit support -for the challenge/response protocol. diff --git a/app/openvpn/doc/openvpn.8 b/app/openvpn/doc/openvpn.8 deleted file mode 100644 index d66bd665..00000000 --- a/app/openvpn/doc/openvpn.8 +++ /dev/null @@ -1,6438 +0,0 @@ -.\" OpenVPN -- An application to securely tunnel IP networks -.\" over a single TCP/UDP port, with support for SSL/TLS-based -.\" session authentication and key exchange, -.\" packet encryption, packet authentication, and -.\" packet compression. -.\" -.\" Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net> -.\" -.\" This program is free software; you can redistribute it and/or modify -.\" it under the terms of the GNU General Public License version 2 -.\" as published by the Free Software Foundation. -.\" -.\" This program is distributed in the hope that it will be useful, -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" along with this program (see the file COPYING included with this -.\" distribution); if not, write to the Free Software Foundation, Inc., -.\" 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -.\" -.\" Manual page for openvpn -.\ -.\" SH section heading -.\" SS subsection heading -.\" LP paragraph -.\" IP indented paragraph -.\" TP hanging label -.\ -.\" .nf -- no formatting -.\" .fi -- resume formatting -.\" .ft 3 -- boldface -.\" .ft -- normal face -.\" .in +|-{n} -- indent -.\" -.TH openvpn 8 "17 November 2008" -.\"********************************************************* -.SH NAME -openvpn \- secure IP tunnel daemon. -.\"********************************************************* -.SH SYNOPSIS -.ft 3 -openvpn [ options ... ] -.ft -.\"********************************************************* -.SH INTRODUCTION -.LP -OpenVPN is an open source VPN daemon by James Yonan. -Because OpenVPN tries to -be a universal VPN tool offering a great deal of flexibility, -there are a lot of options on this manual page. -If you're new to OpenVPN, you might want to skip ahead to the -examples section where you will see how to construct simple -VPNs on the command line without even needing a configuration file. - -Also note that there's more documentation and examples on -the OpenVPN web site: -.I http://openvpn.net/ - -And if you would like to see a shorter version of this manual, -see the openvpn usage message which can be obtained by -running -.B openvpn -without any parameters. -.\"********************************************************* -.SH DESCRIPTION -.LP -OpenVPN is a robust and highly flexible VPN daemon. -OpenVPN supports SSL/TLS security, ethernet bridging, -TCP or UDP tunnel transport through proxies or NAT, -support for dynamic IP addresses and DHCP, -scalability to hundreds or thousands of users, -and portability to most major OS platforms. - -OpenVPN is tightly bound to the OpenSSL library, and derives much -of its crypto capabilities from it. - -OpenVPN supports -conventional encryption -using a pre-shared secret key -.B (Static Key mode) -or -public key security -.B (SSL/TLS mode) -using client & server certificates. -OpenVPN also -supports non-encrypted TCP/UDP tunnels. - -OpenVPN is designed to work with the -.B TUN/TAP -virtual networking interface that exists on most platforms. - -Overall, OpenVPN aims to offer many of the key features of IPSec but -with a relatively lightweight footprint. -.\"********************************************************* -.SH OPTIONS -OpenVPN allows any option to be placed either on the command line -or in a configuration file. Though all command line options are preceded -by a double-leading-dash ("\-\-"), this prefix can be removed when -an option is placed in a configuration file. -.\"********************************************************* -.TP -.B \-\-help -Show options. -.\"********************************************************* -.TP -.B \-\-config file -Load additional config options from -.B file -where each line corresponds to one command line option, -but with the leading '\-\-' removed. - -If -.B \-\-config file -is the only option to the openvpn command, -the -.B \-\-config -can be removed, and the command can be given as -.B openvpn file - -Note that -configuration files can be nested to a reasonable depth. - -Double quotation or single quotation characters ("", '') -can be used to enclose single parameters containing whitespace, -and "#" or ";" characters in the first column -can be used to denote comments. - -Note that OpenVPN 2.0 and higher performs backslash-based shell -escaping for characters not in single quotations, -so the following mappings should be observed: - -.nf -.ft 3 -.in +4 -\\\\ Maps to a single backslash character (\\). -\\" Pass a literal doublequote character ("), don't - interpret it as enclosing a parameter. -\\[SPACE] Pass a literal space or tab character, don't - interpret it as a parameter delimiter. -.in -4 -.ft -.fi - -For example on Windows, use double backslashes to -represent pathnames: - -.nf -.ft 3 -.in +4 -secret "c:\\\\OpenVPN\\\\secret.key" -.in -4 -.ft -.fi - -For examples of configuration files, -see -.I http://openvpn.net/examples.html - -Here is an example configuration file: - -.nf -.ft 3 -.in +4 -# -# Sample OpenVPN configuration file for -# using a pre-shared static key. -# -# '#' or ';' may be used to delimit comments. - -# Use a dynamic tun device. -dev tun - -# Our remote peer -remote mypeer.mydomain - -# 10.1.0.1 is our local VPN endpoint -# 10.1.0.2 is our remote VPN endpoint -ifconfig 10.1.0.1 10.1.0.2 - -# Our pre-shared static key -secret static.key -.in -4 -.ft -.fi -.\"********************************************************* -.SS Tunnel Options: -.TP -.B \-\-mode m -Set OpenVPN major mode. By default, OpenVPN runs in -point-to-point mode ("p2p"). OpenVPN 2.0 introduces -a new mode ("server") which implements a multi-client -server capability. -.\"********************************************************* -.TP -.B \-\-local host -Local host name or IP address for bind. -If specified, OpenVPN will bind to this address only. -If unspecified, OpenVPN will bind to all interfaces. -.\"********************************************************* -.TP -.B \-\-remote host [port] [proto] -Remote host name or IP address. On the client, multiple -.B \-\-remote -options may be specified for redundancy, each referring -to a different OpenVPN server. Specifying multiple -.B \-\-remote -options for this purpose is a special case of the more -general connection-profile feature. See the -.B <connection> -documentation below. - -The OpenVPN client will try to connect to a server at -.B host:port -in the order specified by the list of -.B \-\-remote -options. - -.B proto -indicates the protocol to use when connecting with the -remote, and may be "tcp" or "udp". - -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> |