Skip to content
GitLab
Hide whitespace changes
Inline Side-by-side
doc/doxygen/doc_mainpage.h 0 → 100644
View file @ e1e1377b
/*
* 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-2021 Fox Crypto B.V. <openvpn@foxcrypto.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; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
/**
* @file
* Main page documentation file.
*/
/**
* @mainpage OpenVPN source code documentation
*
* This documentation describes the internal structure of OpenVPN. It was
* automatically generated from specially formatted comment blocks in
* OpenVPN's source code using Doxygen. (See
* http://www.stack.nl/~dimitri/doxygen/ for more information on Doxygen)
*
* The \ref mainpage_modules "Modules section" below gives an introduction
* into the high-level module concepts used throughout this documentation.
* The \ref mainpage_relatedpages "Related Pages section" below describes
* various special subjects related to OpenVPN's implementation which are
* discussed in the related pages section.
*
* @section mainpage_modules Modules
*
* For the purpose of describing the internal structure of OpenVPN, this
* documentation and the underlying source code has been broken up into a
* number of conceptually well-defined parts, known as modules. Each
* module plays a specific role within the OpenVPN process, and in most
* cases each module has a clear interfacing strategy for interacting with
* other modules.
*
* The following modules have been defined:
* - Driver module:
* - The \link eventloop Main Event Loop\endlink: this module drives the
* event handling of OpenVPN. It implements various types of
* select-loop which wait until an event happens, and then delegate
* the handling of that event to the appropriate module.
* - Network interface modules:
* - The \link external_multiplexer External Multiplexer\endlink: this
* module sends and receives packets to and from remote OpenVPN peers
* over the external network interface. It also takes care of
* demultiplexing received packets to their appropriate VPN tunnel and
* splitting control channel and data channel packets.
* - The \link internal_multiplexer Internal Multiplexer\endlink: this
* module sends and receives packets to and from locally reachable
* posts over the virtual tun/tap network interface. It also takes
* care of determining through which VPN tunnel a received packet must
* be sent to reach its destination.
* - Control channel modules:
* - The \link reliable Reliability Layer\endlink: this module offers a
* %reliable and sequential transport layer for control channel
* messages.
* - The \link control_tls Control Channel TLS module\endlink: this
* module offers a secure encapsulation of control channel messages
* using the TLS protocol.
* - The \link control_processor Control Channel Processor\endlink: his
* module manages the setup, maintenance, and shut down of VPN
* tunnels.
* - Data channel modules:
* - The \link data_control Data Channel Control module\endlink: this
* module controls the processing of data channel packets and,
* depending on the settings of the packet's VPN tunnel, passes the
* packet to the three modules below for handling.
* - The \link data_crypto Data Channel Crypto module\endlink: this
* module performs security operations on data channel packets.
* - The \link fragmentation Data Channel Fragmentation module\endlink:
* this module offers fragmentation of data channel packets larger
* than the VPN tunnel's MTU.
* - The \link compression Data Channel Compression module\endlink: this
* module offers compression of data channel packets.
*
* @subsection mainpage_modules_example Example event: receiving a packet
*
* OpenVPN handles many types of events during operation. These include
* external events, such as network traffic being received, and internal
* events, such as a %key session timing out causing renegotiation. An
* example event, receiving a packet over the network, is described here
* together with which modules play what roles:
* -# The \link eventloop Main Event Loop\endlink detects that a packet
* can be read from the external or the virtual tun/tap network
* interface.
* -# The \link eventloop Main Event Loop\endlink calls the \link
* external_multiplexer External Multiplexer\endlink or \link
* internal_multiplexer Internal Multiplexer\endlink to read and
* process the packet.
* -# The multiplexer module determines the type of packet and its
* destination, and passes the packet on to the appropriate handling
* module:
* - A control channel packet received by the \link
* external_multiplexer External Multiplexer\endlink is passed on
* through the \link reliable Reliability Layer\endlink and the \link
* control_tls Control Channel TLS module\endlink to the \link
* control_processor Control Channel Processor\endlink.
* - A data channel packet received by either multiplexer module is
* passed on to the \link data_control Data Channel Control
* module\endlink.
* -# The packet is processed by the appropriate control channel or data
* channel modules.
* -# If, after processing the packet, a resulting packet is generated
* that needs to be sent to a local or remote destination, it is given
* to the \link external_multiplexer External Multiplexer\endlink or
* \link internal_multiplexer Internal Multiplexer\endlink for sending.
* -# If a packet is waiting to be sent by either multiplexer module and
* the \link eventloop Main Event Loop\endlink detects that data can be
* written to the associated network interface, it calls the
* multiplexer module to send the packet.
*
* @section mainpage_relatedpages Related pages
*
* This documentation includes a number of descriptions of various aspects
* of OpenVPN and its implementation. These are not directly related to
* one module, function, or data structure, and are therefore listed
* separately under "Related Pages".
*
* @subsection mainpage_relatedpages_key_generation Data channel key generation
*
* The @ref key_generation "Data channel key generation" related page
* describes how, during VPN tunnel setup and renegotiation, OpenVPN peers
* generate and exchange the %key material required for the symmetric
* encryption/decryption and HMAC signing/verifying security operations
* performed on data channel packets.
*
* @subsection mainpage_relatedpages_tunnel_state VPN tunnel state
*
* The @ref tunnel_state "Structure of VPN tunnel state storage" related
* page describes how an OpenVPN process manages the state information
* associated with its active VPN tunnels.
*
* @subsection mainpage_relatedpages_network_protocol Network protocol
*
* The @ref network_protocol "Network protocol" related page describes the
* format and content of VPN tunnel packets exchanged between OpenVPN
* peers.
*
* @subsection mainpage_relatedpages_memory_management Memory management
*
* The @ref memory_management "Memory management strategies" related page
* gives a brief introduction into OpenVPN's memory %buffer library and
* garbage collection facilities.
*/
doc/doxygen/doc_memory_management.h 0 → 100644
View file @ e1e1377b
/*
* 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-2021 Fox Crypto B.V. <openvpn@foxcrypto.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; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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.
*/
doc/doxygen/doc_protocol_overview.h 0 → 100644
View file @ e1e1377b
/*
* 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-2021 Fox Crypto B.V. <openvpn@foxcrypto.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; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
/**
* @file Network protocol overview documentation file.
*/
/**
* @page network_protocol OpenVPN's network protocol
*
* Description of packet structure in OpenVPN's network protocol.
*
* This document describes the structure of packets exchanged between
* OpenVPN peers. It is based on the protocol description in the \c ssl.h
* file.
*
* @section network_protocol_external Outer structure of packets exchanged between OpenVPN peers
*
* VPN tunnel packets are transported between OpenVPN peers using the UDP
* or TCP protocols. Their structure is described below.
*
* @subsection network_protocol_external_structure External packet structure
*
* - packet length (16 bits, unsigned) [TCP-mode only]: always sent as
* plain text. Since TCP is a stream protocol, this packet length
* defines the packetization of the stream.
* - packet opcode and key_id (8 bits) [TLS-mode only]:
* - package message type (high 5 bits)
* - key_id (low 3 bits): the key_id refers to an already negotiated
* TLS session. OpenVPN seamlessly renegotiates the TLS session by
* using a new key_id for the new session. Overlap (controlled by
* user definable parameters) between old and new TLS sessions is
* allowed, providing a seamless transition during tunnel operation.
* - payload (n bytes)
*
* @subsection network_protocol_external_types Message types
*
* The type of a VPN tunnel packet is indicated by its opcode. The
* following describes the various opcodes available.
*
* - Control channel messages:
* - \ref P_CONTROL_HARD_RESET_CLIENT_V1 -- %Key method 1, initial %key
* from client, forget previous state.
* - \ref P_CONTROL_HARD_RESET_SERVER_V1 -- %Key method 1, initial %key
* from server, forget previous state.
* - \ref P_CONTROL_HARD_RESET_CLIENT_V2 -- %Key method 2, initial %key
* from client, forget previous state.
* - \ref P_CONTROL_HARD_RESET_SERVER_V2 -- %Key method 2, initial %key
* from server, forget previous state.
* - \ref P_CONTROL_SOFT_RESET_V1 -- New %key, with a graceful
* transition from old to new %key in the sense that a transition
* window exists where both the old or new key_id can be used.
* - \ref P_CONTROL_V1 -- Control channel packet (usually TLS
* ciphertext).
* - \ref P_ACK_V1 -- Acknowledgement for control channel packets
* received.
* - Data channel messages:
* - \ref P_DATA_V1 -- Data channel packet containing data channel
* ciphertext.
* - \ref P_DATA_V2 -- Data channel packet containing peer-id and data
* channel ciphertext.
*
* @subsection network_protocol_external_key_id Session IDs and Key IDs
*
* OpenVPN uses two different forms of packet identifiers:
* - The first form is 64 bits and is used for all control channel
* messages. This form is referred to as a \c session_id.
* - Data channel messages on the other hand use a shortened form of 3
* bits for efficiency reasons since the vast majority of OpenVPN
* packets in an active tunnel will be data channel messages. This
* form is referred to as a \c key_id.
*
* The control and data channels use independent packet-id sequences,
* because the data channel is an unreliable channel while the control
* channel is a %reliable channel. Each use their own independent HMAC
* keys.
*
* @subsection network_protocol_external_reliable Control channel reliability layer
*
* Control channel messages (\c P_CONTROL_* and \c P_ACK_* message types)
* are TLS ciphertext packets which have been encapsulated inside of a
* reliability layer. The reliability layer is implemented as a
* straightforward acknowledge and retransmit model.
*
* Acknowledgments of received messages can be encoded in either the
* dedicated \c P_ACK_* record or they can be prepended to a \c
* P_CONTROL_* message.
*
* See the \link reliable Reliability Layer\endlink module for a detailed
* description.
*
* @section network_protocol_control Structure of control channel messages
*
* @subsection network_protocol_control_ciphertext Structure of ciphertext control channel messages
*
* Control channel packets in ciphertext form consist of the following
* parts:
*
* - local \c session_id (random 64 bit value to identify TLS session).
* (the tls-server side uses a HMAC of the client to create a pseudo
* random number for a SYN Cookie like approach)
* - 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
*
* Once the TLS session has been initialized and authenticated, the TLS
* channel is used to exchange random %key material for bidirectional
* cipher and HMAC keys which will be used to secure data channel packets.
* OpenVPN currently implements two %key methods. %Key method 1 directly
* derives keys using random bits obtained from the \c rand_bytes() function.
* %Key method 2 mixes random %key material from both sides of the connection
* using the TLS PRF mixing function. %Key method 2 is the preferred method and
* is the default for OpenVPN 2.0+.
*
* The @ref key_generation "Data channel key generation" related page
* describes the %key methods in more detail.
*
* @subsection network_protocol_control_plaintext Structure of plaintext control channel messages
*
* - %Key method 1 (support removed in OpenVPN 2.5):
* - Cipher %key length in bytes (1 byte).
* - Cipher %key (n bytes).
* - HMAC %key length in bytes (1 byte).
* - HMAC %key (n bytes).
* - %Options string (n bytes, null terminated, client/server %options
* string should match).
* - %Key method 2:
* - Literal 0 (4 bytes).
* - %Key method (1 byte).
* - \c key_source structure (\c key_source.pre_master only defined
* for client -> server).
* - %Options string length, including null (2 bytes).
* - %Options string (n bytes, null terminated, client/server %options
* string must match).
* - [The username/password data below is optional, record can end at
* this point.]
* - Username string length, including null (2 bytes).
* - Username string (n bytes, null terminated).
* - Password string length, including null (2 bytes).
* - Password string (n bytes, null terminated).
*
* @section network_protocol_data Structure of data channel messages
*
* The P_DATA_* payload represents encapsulated tunnel packets which tend to be
* either IP packets or Ethernet frames. This is essentially the "payload" of
* the VPN. Data channel packets consist of a data channel header, and a
* payload. There are two possible formats:
*
* @par P_DATA_V1
* P_DATA_V1 packets have a 1-byte header, carrying the \ref P_DATA_V1 \c opcode
* and \c key_id, followed by the payload:\n
* <tt> [ 5-bit opcode | 3-bit key_id ] [ payload ] </tt>
*
* @par P_DATA_V2
* P_DATA_V2 packets have the same 1-byte opcode/key_id, but carrying the \ref
* P_DATA_V2 opcode, followed by a 3-byte peer-id, which uniquely identifies
* the peer:\n
* <tt> [ 5-bit opcode | 3-bit key_id ] [ 24-bit peer-id ] [ payload ] </tt>
*
* See @ref data_crypto for details on the data channel payload format.
*
*/
doc/doxygen/doc_reliable.h 0 → 100644
View file @ e1e1377b
/*
* 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-2021 Fox Crypto B.V. <openvpn@foxcrypto.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; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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.
*/
doc/doxygen/doc_tunnel_state.h 0 → 100644
View file @ e1e1377b
/*
* 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-2021 Fox Crypto B.V. <openvpn@foxcrypto.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; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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() 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.
*/
doc/doxygen/openvpn.doxyfile.in 0 → 100644
View file @ e1e1377b
# Doxyfile 1.5.5
#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = "OpenVPN"
PROJECT_NUMBER =
OUTPUT_DIRECTORY = "@abs_top_builddir@/doc/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 = "@abs_top_srcdir@"
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 = "@abs_top_srcdir@"
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 ENABLE_CRYPTO_OPENSSL ENABLE_PLUGIN ENABLE_MANAGEMENT ENABLE_OCC HAVE_GETTIMEOFDAY
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES
#---------------------------------------------------------------------------
# Configuration::additions related to external references
#---------------------------------------------------------------------------
TAGFILES =
GENERATE_TAGFILE =
ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
PERL_PATH = /usr/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
CLASS_DIAGRAMS = NO
MSCGEN_PATH =
HIDE_UNDOC_RELATIONS = YES
HAVE_DOT = YES
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
GROUP_GRAPHS = YES
UML_LOOK = NO
TEMPLATE_RELATIONS = NO
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = NO # YES
CALLER_GRAPH = NO # YES
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES
DOT_IMAGE_FORMAT = png
DOT_PATH = "/usr/bin/dot"
DOTFILE_DIRS =
DOT_GRAPH_MAX_NODES = 50
MAX_DOT_GRAPH_DEPTH = 1000
DOT_TRANSPARENT = YES
DOT_MULTI_TARGETS = NO
GENERATE_LEGEND = YES
DOT_CLEANUP = YES
#---------------------------------------------------------------------------
# Configuration::additions related to the search engine
#---------------------------------------------------------------------------
SEARCHENGINE = NO
doc/gui-notes.txt 0 → 100644
View file @ e1e1377b
Management Interface "echo" protocol
================================================================================
THIS IS A PRELIMINARY VERSION OF THIS DOCUMENT. ALL INFORMATION IN IT
IS SUBJECT TO CHANGE.
================================================================================
CONTENTS
THE OPENVPN --ECHO OPTION
ENVIRONMENT COMMAND
MESSSAGE COMMANDS
PASSWORD COMMANDS
QUOTING
COMMMAND DETAILS
=========================
THE OPENVPN --ECHO OPTION
=========================
The OpenVPN --echo option causes commands to be sent out through the
management interface, typically to a Graphic User Interface (GUI) such
as "OpenVPN for Android", "Tunnelblick" (for macOS), or "Windows
OpenVPN GUI". It can be included in a configuration file or on a
command line, or can be pushed from the server.
This document describes the commands that can be sent and how they are
interpreted by various GUIs.
* OpenVPN does not process the commands in an --echo option; it only
sends them out through the management interface.
* "echo" commands are processed by the GUI if, as, when, and in the
order they are received. If no GUI is present the processing of
commands may be delayed, the commands may never be processed, or only
some commands may be processed. (That can happen if OpenVPN discards
commands because its buffer for the commands fills up.)
* There is no mechanism for the GUI to acknowledge the receipt,
success, or failure of a command.
* "echo" commands are stored by OpenVPN (within limits, see the next
point) and sent only when the GUI requests them through the management
interface. "echo" commands in the configuration file or the command
line are typically requested and processed at the start of a
connection attempt. "echo" commands that are pushed by the server are
also typically asked for at the start of a connection attempt but can
be sent at any time. They are processed in the middle of a connection
attempt or after a connection is established, as the "push" options
are received by the client from the server.
* OpenVPN's storage for echo commands is limited in size, so a large
number of commands or commands with long messages may require that
some commands be removed from the storage. If that happens, some of
the commands may not be sent through the management interface when a
GUI does connect to it or asks for the "echo" commands.
* On SIGUSR1 and SIGHUP connection restarts, "echo" commands that
were sent through the management interface and have been saved by
OpenVPN are sent again and will be re-processed by the GUI. (The
message commands include a mechanism for muting (skipping) duplicate
messages, see MESSAGE COMMANDS, below.)
* OpenVPN limits the number of separate arguments in each line of a
configuration file. Arguments may be quoted to work around this
limitation, see QUOTING, below.
* OpenVPN limits the size of each "echo" command sent over the
management interface to 255 bytes, including overhead characters. To
allow messages of arbitrary length, several message commands can be
concatenated together before being displayed to the user, see MESSAGE
COMMANDS, below.
* There no indication to the GUI of the source of the command
(configuration file, command line option, or pushed from a server). It
might be possible for the GUI to deduce that a command was pushed from
a server because of timing or other management interface interactions.
===================
ENVIRONMENT COMMAND
===================
Typically, a GUI allows users to specify shell commands (typically
scripts) to run at certain points in the connection/disconnection
process, in addition to those provided by OpenVPN options such as
"--up" and "--down".
The "setenv" command can be used to set environment variables that are
available to the scripts run by the GUI. Each "setenv" command
specifies a value for one environment variable that is available to
the scripts that the GUI runs.
This is similar to Openvpn's "--setenv" option, which specifies an
additional environment variable that is included in the environment
variables that are available to the scripts that OpenVPN runs.
=================
MESSSAGE COMMANDS
=================
Four commands can be used to display a message to the user from the
OpenVPN configuration or server:
msg
msg-n
msg-window
msg-notify
"msg" and "msg-n" commands are concatenated to construct a message.
When a "msg-window"or "msg-notify" command is received the message is
displayed to the user.
Identical messages (same title, text, and destination) received during
one connection may be ignored or muted. Some GUIs may only show the
first message for a connection, or the first message shown in a window
and the first message shown as a notification.
=================
PASSWORD COMMANDS
=================
Three commands can be used to control the GUI's storage of usernames,
passwords, and private keys:
disable-save-passwords
forget-passwords
save-passwords
=======
QUOTING
=======
* In a configuration file, the rest of the line is parsed into
separate arguments and then 'echo' and the arguments are passed, each
separated by a single space, through the management interface. For
example:
echo argument1 argument2
echo " argument1 argument2"
will be sent through the management interface as
>ECHO:timestamp,argument1 argument2
>ECHO:timestamp, argument1 argument2
* In a command line option, the single argument following "--echo" is
parsed similarly, so
--echo argument1 argument2
--echo " argument1 argument2"
will be sent through the management interface as
>ECHO:timestamp,argument1 argument2
>ECHO:timestamp, argument1 argument2
* In a "push" option in a server configuration file, the single
option following "push" is parsed similarly, so
push "echo argument1 argument2 argument3 argument4"
push "echo ' argument1 argument2 argument3 argument4'"
will be sent through the management interface as
>ECHO:timestamp,argument1 argument2 argument3 argument4
>ECHO:timestamp, argument1 argument2 argument3 argument4
================
COMMMAND DETAILS
================
COMMAND -- disable-save-passwords
---------------------------------
Syntax: disable-save-passwords
The GUI is instructed to not allow the user to save passwords or
private keys for the configuration. The user is still allowed to save
usernames. Any passwords or private keys that have been saved will be
forgotten.
This command will be effective at startup only if present in the
configuration file or as a command line option. If pushed from the
server, saving passwords will be disabled in password prompts only
after the initial prompt has been shown to the user.
Android: ??????
Tunnelblick: Planned. This command will disable saving of
passwords or private keys and forget any saved usernames, passwords,
or private keys regardless of the normal (non-forced) global or
per-configuration settings. A computer administrator can "force" this
setting, overriding this command.
Windows OpenVPN GUI: Planned. This command will disable saving of
passwords or private keys and forget any saved usernames, passwords,
or private keys regardless of any global settings.
COMMAND -- forget-passwords
---------------------------
Syntax: forget-passwords
The GUI is instructed to forget any usernames, passwords, and private
keys it has saved for the configuration. Useful when pushed from the
server so that it is processed after authentication.
Android: ??????
Tunnelblick: Planned.
Windows OpenVPN GUI: supported since release 2.4.1 (GUI version 11.5.0)
COMMAND -- msg
--------------
Syntax: msg text
The text is appended to any previous text from "msg" or "msg-n"
commands, and a newline is appended after that.
A trailing newline will be removed from the completed message before
it is displayed to the user.
The text may include any UTF-8 character except a comma (","), CR
(0x0D), LF (0x0A), or NUL (0x00).
The text may not contain percent ("%") except in "percent encoding"
sequences. To display a percent sign, use %25.
The text may not contain commas (",") because of constraints imposed
by OpenVPN. Commas should be encoded using "percent encoding" (URL
encoding): a '%' character followed by two hexadecimal digits, the
high- and then low-nibble of the ASCII code for the character to be
shown. Examples: a comma is encoded as %2C or %2c; a percent sign is
encoded as %25.
Text containing comment characters # and ; must be enclosed in quotes to
survive after option parsing by openvpn.
The insertion of line endings (CR, LF) in the text is discouraged
because it is OS dependent. Instead, use the "msg" command, which
appends a line ending appropriate for the OS on which the GUI is
running.
Android: Planned.
Tunnelblick: Planned.
Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
(GUI version v11.22.0)
COMMAND -- msg-n
----------------
Syntax: msg-n text
The text is appended to any previous text from "msg"" or "msg-n""
commands. (Like "msg" except that no newline is appended.)
See "COMMAND -- msg" for details about "text".
Android: Planned.
Tunnelblick: Planned.
Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
(GUI version v11.22.0)
COMMAND -- msg-notify
---------------------
Syntax: msg-notify title
The text from previous "msg" and/or "msg-n" commands is displayed to
the user as a notification with title "title" and the previous text is
forgotten.
Android: Planned.
Tunnelblick: Planned.
Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
(GUI version v11.22.0)
Note: The max length that will correctly display as a notification
message is OS dependent.
COMMAND -- msg-window title
---------------------------
Syntax: msg-window title
The text from previous "msg" and/or "msg-n" commands is displayed to
the user in a non-modal popup window with title "title" and the
previous text is forgotten. How the title is displayed exactly is left
to the implementation. Could be set as the window title or as a
differently formatted text as the heading of the message, for example.
Android: Planned.
Tunnelblick: Planned.
Windows OpenVPN GUI: supported since release v2.4.11 / v2.5.1
(GUI version v11.22.0)
COMMAND -- save-passwords
-------------------------
Syntax: save-passwords
The GUI is instructed to allow the user to save usernames, passwords
and private keys for the configuration.
This command will be effective at startup only if present in the
configuration file or as a command line option. If pushed from the
server, saving passwords will be allowed in password prompts only
after the initial prompt has been shown to the user.
This command typically has the effect of presenting the password
dialogs to the user with a "save password" checkbox checked. The user
may still uncheck it during the dialog.
Android: ??????
Tunnelblick: Planned. Tunnelblick ignores this command. Usernames,
passwords, and private keys may be saved by default, and this command
will not override the separate Tunnelblick global or per-configuration
settings used to disable saving them.
Windows OpenVPN GUI: Supported since release 2.4.1 (GUI version 11.5.0)
COMMAND -- setenv
-----------------
Syntax: setenv name value
Sets an environment variable that will be available to the scripts run
by the GUI.
This will set environment variable "OPENVPN_name" to value "value" for
the scripts run by the GUI. "name" is changed to "OPENVPN_name" to
prevent overwriting sensitive variables such as PATH. Variables are
set in the order received, with later values replacing earlier ones
for the same "name".
Names may include only alphanumeric characters and underscores. A
"setenv" command with an invalid name will be ignored.
Android: ??????
Tunnelblick: Planned.
Windows OpenVPN GUI: supported since release v2.4.7 (GUI version v11.12.0)
The variables set by "setenv" are merged with those for the process
environment. In case of duplicate names the one in the setenv list is
chosen.
doc/keying-material-exporter.txt 0 → 100644
View file @ e1e1377b
OpenVPN Daniel Kubec <niel@rtfm.cz>
RFC-5705 February 2015
Added support for TLS Keying Material Exporters
Keying Material Exporter [RFC-5705] allow additional keying material to be
derived from existing TLS channel. This exported keying material can then be
used for a variety of purposes. TLS allows client and server to establish
keying material for use in the upper layers between the TLS end-points and
channel bindings is straightforward and well-defined mechanism how to
authenticate other layers.
OpenVPN Configuration
--keying-material-exporter label len
Export Keying Material [RFC-5705] of len bytes (min. 16 bytes) using label in
environment (exported_keying_material) for use by plugins in
OPENVPN_PLUGIN_TLS_FINAL callback.
Note that exporter labels have the potential to collide with existing PRF
labels. In order to prevent this, labels MUST begin with "EXPORTER".
(This option requires OpenSSL 1.0.1 or newer.)
Use Cases:
Secure bindings of AAA information to application layer
OpenVPN Client <------> OpenVPN Server
[KeyAgreement] [KeyAgreement]
[TLSExportedKeyingMaterial] [TLSExportedKeyingMaterial]
[AAASessionKey] [AAASessionKey]
Client <------> Server
[Authenticated layer on top of (D)TLS]
TLS side channel authentication and straightforward bindings of AAA information
to application layer using well-defined mechanism.
OpenVPN Client <------> OpenVPN Server
[KeyAgreement] [KeyAgreement]
[TLSExportedKeyingMaterial] [TLSExportedKeyingMaterial]
[DerivedAAABindingKey] [DerivedAAABindingKey]
[AuthenticateBindingKeys]
Client -------> Server
[Confidential channel]
TLS Message flow for a full handshake
ClientHello -------->
ServerHello
Certificate*
ServerKeyExchange*
CertificateRequest*
<-------- ServerHelloDone
Certificate*
ClientKeyExchange
CertificateVerify*
[ChangeCipherSpec]
Finished -------->
[ChangeCipherSpec]
<-------- Finished
GenerateTLSBindingKey GenerateTLSBindingKey
Application Data <-------> Application Data
Terminology
AAA Authentication, Authorization, and Accounting:
functions that are generally required to control
access to a service and support auditing.
Secure channel a packet, datagram, octet stream connection, or
sequence of connections between two end-points that
affords cryptographic integrity and confidentiality
to data exchanged over it.
Channel binding the process of establishing that no man-in-the-middle
exists between two end-points that have been
authenticated using secure channel.
TLS Binding Key Exported Keying Material [RFC5705]
If no context is provided, it then computes:
PRF(SecurityParameters.master_secret, label,
SecurityParameters.client_random +
SecurityParameters.server_random
)[length]
If context is provided, it computes:
PRF(SecurityParameters.master_secret, label,
SecurityParameters.client_random +
SecurityParameters.server_random +
context_value_length + context_value
)[length]
AAA Binding Key TLS side channel authentication based on secure
channel bindings requires one more key derivation.
SHA1(TLSExportedKeyingMaterial + ServerPublicKey)
Reference
[OPENAAA] "TLS side channel authentication and straightforward
bindings of AAA information to application
layer using well-defined mechanism."
Daniel Kubec <niel@rtfm.cz> March 2013
https://github.com/n13l/openaaa
[RFC5705] "Keying Material Exporters for TLS"
E. Rescorla, RFC 5705 March 2010
http://tools.ietf.org/html/rfc5705
[RFC5929] "Channel Bindings for TLS"
J. Altman, N. Williams, L. Zhu, RFC 5929, July 2010
http://tools.ietf.org/html/rfc5929
[RFC4680] "TLS Handshake Message for Supplemental Data"
S. Santesson, RFC 4680, September 2006
http://tools.ietf.org/html/rfc4680
[RFC5878] "TLS Authorization Extension"
M. Brown, R. Housley, RFC 5878, May 2010
http://tools.ietf.org/html/rfc5878
[RFC5746] "TLS Renegotiation Indication Extension"
E. Rescorla, M. Raym, S. Dispensa, N. Oskov
RFC 5746, February 2010
http://tools.ietf.org/html/rfc5746
doc/man-sections/advanced-options.rst 0 → 100644
View file @ e1e1377b
Standalone Debug Options
------------------------
--show-gateway args
(Standalone) Show current IPv4 and IPv6 default gateway and interface
towards the gateway (if the protocol in question is enabled).
Valid syntax:
::
--show-gateway
--show-gateway IPv6-target
For IPv6 this queries the route towards ::/128, or the specified IPv6
target address if passed as argument.
For IPv4 on Linux, Windows, MacOS and BSD it looks for a 0.0.0.0/0 route.
If there are more specific routes, the result will not always be matching
the route of the IPv4 packets to the VPN gateway.
Advanced Expert Options
-----------------------
These are options only required when special tweaking is needed, often
used when debugging or testing out special usage scenarios.
--hash-size args
Set the size of the real address hash table to ``r`` and the virtual
address table to ``v``.
Valid syntax:
::
hash-size r v
By default, both tables are sized at 256 buckets.
--bcast-buffers n
Allocate ``n`` buffers for broadcast datagrams (default :code:`256`).
--persist-local-ip
Preserve initially resolved local IP address and port number across
``SIGUSR1`` or ``--ping-restart`` restarts.
--persist-remote-ip
Preserve most recently authenticated remote IP address and port number
across :code:`SIGUSR1` or ``--ping-restart`` restarts.
--rcvbuf size
Set the TCP/UDP socket receive buffer size. Defaults to operating system
default.
--shaper n
Limit bandwidth of outgoing tunnel data to ``n`` bytes per second on the
TCP/UDP port. Note that this will only work if mode is set to
:code:`p2p`. If you want to limit the bandwidth in both directions, use
this option on both peers.
OpenVPN uses the following algorithm to implement traffic shaping: Given
a shaper rate of ``n`` bytes per second, after a datagram write of ``b``
bytes is queued on the TCP/UDP port, wait a minimum of ``(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 ``n`` to be between 100 bytes/sec and 100 Mbytes/sec.
--sndbuf size
Set the TCP/UDP socket send buffer size. Defaults to operating system
default.
--tcp-queue-limit n
Maximum number of output packets queued before TCP (default :code:`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.
--txqueuelen n
*(Linux only)* Set the TX queue length on the TUN/TAP interface.
Currently defaults to operating system default.
--disable-dco
Disables the opportunistic use of data channel offloading if available.
Without this option, OpenVPN will opportunistically use DCO mode if
the config options and the running kernel supports using DCO.
Data channel offload currently requires data-ciphers to only contain
AEAD ciphers (AES-GCM and Chacha20-Poly1305) and Linux with the
ovpn-dco module.
Note that some options have no effect or cannot be used when DCO mode
is enabled.
On platforms that do not support DCO ``disable-dco`` has no effect.
doc/man-sections/cipher-negotiation.rst 0 → 100644
View file @ e1e1377b
Data channel cipher negotiation
===============================
OpenVPN 2.4 and higher have the capability to negotiate the data cipher that
is used to encrypt data packets. This section describes the mechanism in more detail and the
different backwards compatibility mechanism with older server and clients.
OpenVPN 2.5 and later behaviour
--------------------------------
When both client and server are at least running OpenVPN 2.5, that the order of
the ciphers of the server's ``--data-ciphers`` is used to pick the the data cipher.
That means that the first cipher in that list that is also in the client's
``--data-ciphers`` list is chosen. If no common cipher is found the client is rejected
with a AUTH_FAILED message (as seen in client log):
AUTH: Received control message: AUTH_FAILED,Data channel cipher negotiation failed (no shared cipher)
OpenVPN 2.5 and later will only allow the ciphers specified in ``--data-ciphers``.
If ``--data-ciphers`` is not set the default is :code:`AES-256-GCM:AES-128-GCM`.
In 2.6 and later the default is changed to
:code:`AES-256-GCM:AES-128-GCM:CHACHA20-POLY1305` when Chacha20-Poly1305 is available.
For backwards compatibility OpenVPN 2.6 and later with ``--compat-mode 2.4.x``
(or lower) and OpenVPN 2.5 will automatically add a cipher specified using the
``--cipher`` option to this list.
OpenVPN 2.4 clients
-------------------
The negotiation support in OpenVPN 2.4 was the first iteration of the implementation
and still had some quirks. Its main goal was "upgrade to AES-256-GCM when possible".
An OpenVPN 2.4 client that is built against a crypto library that supports AES in GCM
mode and does not have ``--ncp-disable`` will always announce support for
`AES-256-GCM` and `AES-128-GCM` to a server by sending :code:`IV_NCP=2`.
This only causes a problem if ``--ncp-ciphers`` option has been changed from the
default of :code:`AES-256-GCM:AES-128-GCM` to a value that does not include
these two ciphers. When a OpenVPN servers try to use `AES-256-GCM` or
`AES-128-GCM` the connection will then fail. It is therefore recommended to
always have the `AES-256-GCM` and `AES-128-GCM` ciphers to the ``--ncp-ciphers``
options to avoid this behaviour.
OpenVPN 3 clients
-----------------
Clients based on the OpenVPN 3.x library (https://github.com/openvpn/openvpn3/)
do not have a configurable ``--ncp-ciphers`` or ``--data-ciphers`` option. Instead
these clients will announce support for all their supported AEAD ciphers
(`AES-256-GCM`, `AES-128-GCM` and in newer versions also `Chacha20-Poly1305`).
To support OpenVPN 3.x based clients at least one of these ciphers needs to be
included in the server's ``--data-ciphers`` option.
OpenVPN 2.3 and older clients (and clients with ``--ncp-disable``)
------------------------------------------------------------------
When a client without cipher negotiation support connects to a server the
cipher specified with the ``--cipher`` option in the client configuration
must be included in the ``--data-ciphers`` option of the server to allow
the client to connect. Otherwise the client will be sent the ``AUTH_FAILED``
message that indicates no shared cipher.
If the client is 2.3 or older and has been configured with the
``--enable-small`` :code:`./configure` argument, using
``data-ciphers-fallback cipher`` in the server config file with the explicit
cipher used by the client is necessary.
OpenVPN 2.4 server
------------------
When a client indicates support for `AES-128-GCM` and `AES-256-GCM`
(with ``IV_NCP=2``) an OpenVPN 2.4 server will send the first
cipher of the ``--ncp-ciphers`` to the OpenVPN client regardless of what
the cipher is. To emulate the behaviour of an OpenVPN 2.4 client as close
as possible and have compatibility to a setup that depends on this quirk,
adding `AES-128-GCM` and `AES-256-GCM` to the client's ``--data-ciphers``
option is required. OpenVPN 2.5+ will only announce the ``IV_NCP=2`` flag if
those ciphers are present.
OpenVPN 2.3 and older servers (and servers with ``--ncp-disable``)
------------------------------------------------------------------
The cipher used by the server must be included in ``--data-ciphers`` to
allow the client connecting to a server without cipher negotiation
support.
(For compatibility OpenVPN 2.5 will also accept the cipher set with
``--cipher``)
If the server is 2.3 or older and has been configured with the
``--enable-small`` :code:`./configure` argument, adding
``data-ciphers-fallback cipher`` to the client config with the explicit
cipher used by the server is necessary.
Blowfish in CBC mode (BF-CBC) deprecation
------------------------------------------
The ``--cipher`` option defaulted to ``BF-CBC`` in OpenVPN 2.4 and older
version. The default was never changed to ensure backwards compatibility.
In OpenVPN 2.5 this behaviour has now been changed so that if the ``--cipher``
is not explicitly set it does not allow the weak ``BF-CBC`` cipher any more
and needs to explicitly added as ``--cipher BFC-CBC`` or added to
``--data-ciphers``.
We strongly recommend to switching away from BF-CBC to a
more secure cipher as soon as possible instead.
doc/man-sections/client-options.rst 0 → 100644
View file @ e1e1377b
Client Options
--------------
The client options are used when connecting to an OpenVPN server configured
to use ``--server``, ``--server-bridge``, or ``--mode server`` in its
configuration.
--allow-pull-fqdn
Allow client to pull DNS names from server (rather than being limited to
IP address) for ``--ifconfig``, ``--route``, and ``--route-gateway``.
--allow-recursive-routing
When this option is set, OpenVPN will not drop incoming tun packets with
same destination as host.
--auth-token token
This is not an option to be used directly in any configuration files,
but rather push this option from a ``--client-connect`` script or a
``--plugin`` which hooks into the :code:`OPENVPN_PLUGIN_CLIENT_CONNECT`
or :code:`OPENVPN_PLUGIN_CLIENT_CONNECT_V2` calls. This option provides a
possibility to replace the clients password with an authentication token
during the lifetime of the OpenVPN client.
Whenever the connection is renegotiated and the
``--auth-user-pass-verify`` script or ``--plugin`` making use of the
:code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` hook is triggered, it will
pass over this token as the password instead of the password the user
provided. The authentication token can only be reset by a full reconnect
where the server can push new options to the client. The password the
user entered is never preserved once an authentication token has been
set. If the OpenVPN server side rejects the authentication token then
the client will receive an :code:`AUTH_FAILED` and disconnect.
The purpose of this is to enable two factor authentication methods, such
as HOTP or TOTP, to be used without needing to retrieve a new OTP code
each time the connection is renegotiated. Another use case is to cache
authentication data on the client without needing to have the users
password cached in memory during the life time of the session.
To make use of this feature, the ``--client-connect`` script or
``--plugin`` needs to put
::
push "auth-token UNIQUE_TOKEN_VALUE"
into the file/buffer for dynamic configuration data. This will then make
the OpenVPN server to push this value to the client, which replaces the
local password with the ``UNIQUE_TOKEN_VALUE``.
Newer clients (2.4.7+) will fall back to the original password method
after a failed auth. Older clients will keep using the token value and
react according to ``--auth-retry``
--auth-token-user base64username
Companion option to ``--auth-token``. This options allows to override
the username used by the client when reauthenticating with the ``auth-token``.
It also allows to use ``--auth-token`` in setups that normally do not use
username and password.
The username has to be base64 encoded.
--auth-user-pass
Authenticate with server using username/password.
Valid syntaxes:
::
auth-user-pass
auth-user-pass up
If ``up`` is present, it must be a file containing username/password on 2
lines. If the password line is missing, OpenVPN will prompt for one.
If ``up`` is omitted, username/password will be prompted from the
console.
The server configuration must specify an ``--auth-user-pass-verify``
script to verify the username/password provided by the client.
--auth-retry type
Controls how OpenVPN responds to username/password verification errors
such as the client-side response to an :code:`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 :code:`AUTH_FAILED` message is generated by the server if the client
fails ``--auth-user-pass`` authentication, or if the server-side
``--client-connect`` script returns an error status when the client
tries to connect.
``type`` can be one of:
:code:`none`
Client will exit with a fatal error (this is the default).
:code:`nointeract`
Client will retry the connection without requerying
for an ``--auth-user-pass`` username/password. Use this option for
unattended clients.
:code:`interact`
Client will requery for an ``--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.
--client
A helper directive designed to simplify the configuration of OpenVPN's
client mode. This directive is equivalent to:
::
pull
tls-client
--client-nat args
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.
Examples:
::
client-nat snat 192.168.0.0/255.255.0.0
client-nat dnat 10.64.0.0/255.255.0.0
``network/netmask`` (for example :code:`192.168.0.0/255.255.0.0`) defines
the local view of a resource from the client perspective, while
``alias/netmask`` (for example :code:`10.64.0.0/255.255.0.0`) defines the
remote view from the server perspective.
Use :code:`snat` (source NAT) for resources owned by the client and
:code:`dnat` (destination NAT) for remote resources.
Set ``--verb 6`` for debugging info showing the transformation of
src/dest addresses in packets.
--connect-retry n
Wait ``n`` seconds between connection attempts (default :code:`5`).
Repeated reconnection attempts are slowed down after 5 retries per
remote by doubling the wait time after each unsuccessful attempt. An
optional argument ``max`` specifies the maximum value of wait time in
seconds at which it gets capped (default :code:`300`).
--connect-retry-max n
``n`` specifies the number of times each ``--remote`` or
``<connection>`` entry is tried. Specifying ``n`` as :code:`1` would try
each entry exactly once. A successful connection resets the counter.
(default *unlimited*).
--connect-timeout n
See ``--server-poll-timeout``.
--dns args
Client DNS configuration to be used with the connection.
Valid syntaxes:
::
dns search-domains domain [domain ...]
dns server n address addr[:port] [addr[:port]]
dns server n resolve-domains|exclude-domains domain [domain ...]
dns server n dnssec yes|optional|no
dns server n transport DoH|DoT|plain
dns server n sni server-name
The ``--dns search-domains`` directive takes one or more domain names
to be added as DNS domain suffixes. If it is repeated multiple times within
a configuration the domains are appended, thus e.g. domain names pushed by
a server will amend locally defined ones.
The ``--dns server`` directive is used to configure DNS server ``n``.
The server id ``n`` must be a value between -128 and 127. For pushed
DNS server options it must be between 0 and 127. The server id is used
to group options and also for ordering the list of configured DNS servers;
lower numbers come first. DNS servers being pushed to a client replace
already configured DNS servers with the same server id.
The ``address`` option configures the IPv4 and / or IPv6 address of
the DNS server. Optionally a port can be appended after a colon. IPv6
addresses need to be enclosed in brackets if a port is appended.
The ``resolve-domains`` and ``exclude-domains`` options take one or
more DNS domains which are explicitly resolved or explicitly not resolved
by a server. Only one of the options can be configured for a server.
``resolve-domains`` is used to define a split-dns setup, where only
given domains are resolved by a server. ``exclude-domains`` is used to
define domains which will never be resolved by a server (e.g. domains
which can only be resolved locally). Systems which do not support fine
grained DNS domain configuration, will ignore these settings.
The ``dnssec`` option is used to configure validation of DNSSEC records.
While the exact semantics may differ for resolvers on different systems,
``yes`` likely makes validation mandatory, ``no`` disables it, and ``optional``
uses it opportunistically.
The ``transport`` option enables DNS-over-HTTPS (``DoH``) or DNS-over-TLS (``DoT``)
for a DNS server. The ``sni`` option can be used with them to specify the
``server-name`` for TLS server name indication.
Each server has to have at least one address configured for a configuration
to be valid. All the other options can be omitted.
Note that not all options may be supported on all platforms. As soon support
for different systems is implemented, information will be added here how
unsupported options are treated.
The ``--dns`` option will eventually obsolete the ``--dhcp-option`` directive.
Until then it will replace configuration at the places ``--dhcp-option`` puts it,
so that ``--dns`` overrides ``--dhcp-option``. Thus, ``--dns`` can be used today
to migrate from ``--dhcp-option``.
--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 **n** parameter (default :code:`1` if not present) controls the
maximum number of attempts that the client will try to resend the exit
notification message.
In UDP server mode, send :code:`RESTART` control channel command to
connected clients. The ``n`` parameter (default :code:`1` if not present)
controls client behavior. With ``n`` = :code:`1` client will attempt to
reconnect to the same server, with ``n`` = :code:`2` client will advance
to the next server.
OpenVPN will not send any exit notifications unless this option is
enabled.
--inactive args
Causes OpenVPN to exit after ``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.
Valid syntaxes:
::
inactive n
inactive n bytes
If the optional ``bytes`` parameter is included, exit if less than
``bytes`` of combined in/out traffic are produced on the tun/tap device
in ``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.
--proto-force p
When iterating through connection profiles, only consider profiles using
protocol ``p`` (:code:`tcp` \| :code:`udp`).
Note that this specifically only filters by the transport layer
protocol, i.e. UDP or TCP. This does not affect whether IPv4 or
IPv6 is used as IP protocol.
For implementation reasons the option accepts the :code:`4` and :code:`6`
suffixes when specifying the protocol
(i.e. :code:`udp4` / :code:`udp6` / :code:`tcp4` / :code:`tcp6`).
However, these behave the same as without the suffix and should be avoided
to prevent confusion.
--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 ``--pull`` option is implied by
``--client`` ).
In particular, ``--pull`` allows the server to push routes to the
client, so you should not use ``--pull`` or ``--client`` in situations
where you don't trust the server to have control over the client's
routing table.
--pull-filter args
Filter options on the client pushed by the server to the client.
Valid syntaxes:
::
pull-filter accept text
pull-filter ignore text
pull-filter reject text
Filter options received from the server if the option starts with
:code:`text`. The action flag :code:`accept` allows the option,
:code:`ignore` removes it and :code:`reject` flags an error and triggers
a :code:`SIGUSR1` restart. The filters may be specified multiple times,
and each filter is applied in the order it is specified. The filtering of
each option stops as soon as a match is found. Unmatched options are accepted
by default.
Prefix comparison is used to match :code:`text` against the received option so
that
::
pull-filter ignore "route"
would remove all pushed options starting with ``route`` which would
include, for example, ``route-gateway``. Enclose *text* in quotes to
embed spaces.
::
pull-filter accept "route 192.168.1."
pull-filter ignore "route "
would remove all routes that do not start with ``192.168.1``.
*Note* that :code:`reject` may result in a repeated cycle of failure and
reconnect, unless multiple remotes are specified and connection to the
next remote succeeds. To silently ignore an option pushed by the server,
use :code:`ignore`.
--push-peer-info
Push additional information about the client to server. The following
data is always pushed to the server:
:code:`IV_VER=<version>`
The client OpenVPN version
:code:`IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]`
The client OS platform
:code:`IV_LZO_STUB=1`
If client was built with LZO stub capability
:code:`IV_LZ4=1`
If the client supports LZ4 compressions.
:code:`IV_PROTO`
Details about protocol extensions that the peer supports. The
variable is a bitfield and the bits are defined as follows
(starting a bit 0 for the first (unused) bit:
- bit 1: The peer supports peer-id floating mechanism
- bit 2: The client expects a push-reply and the server may
send this reply without waiting for a push-request first.
- bit 3: The client is capable of doing key derivation using
RFC5705 key material exporter.
- bit 4: The client is capable of accepting additional arguments
to the `AUTH_PENDING` message.
:code:`IV_NCP=2`
Negotiable ciphers, client supports ``--cipher`` pushed by
the server, a value of 2 or greater indicates client supports
*AES-GCM-128* and *AES-GCM-256*.
:code:`IV_CIPHERS=<ncp-ciphers>`
The client announces the list of supported ciphers configured with the
``--data-ciphers`` option to the server.
:code:`IV_GUI_VER=<gui_id> <version>`
The UI version of a UI if one is running, for example
:code:`de.blinkt.openvpn 0.5.47` for the Android app.
:code:`IV_SSO=[crtext,][openurl,][proxy_url]`
Additional authentication methods supported by the client.
This may be set by the client UI/GUI using ``--setenv``
When ``--push-peer-info`` is enabled the additional information consists
of the following data:
:code:`IV_HWADDR=<string>`
This is intended to be a unique and persistent ID of the client.
The string value can be any readable ASCII string up to 64 bytes.
OpenVPN 2.x and some other implementations use the MAC address of
the client's interface used to reach the default gateway. If this
string is generated by the client, it should be consistent and
preserved across independent session and preferably
re-installations and upgrades.
:code:`IV_SSL=<version string>`
The ssl version used by the client, e.g.
:code:`OpenSSL 1.0.2f 28 Jan 2016`.
:code:`IV_PLAT_VER=x.y`
The version of the operating system, e.g. 6.1 for Windows 7.
:code:`UV_<name>=<value>`
Client environment variables whose names start with
:code:`UV_`
--remote args
Remote host name or IP address, port and protocol.
Valid syntaxes:
::
remote host
remote host port
remote host port proto
The ``port`` and ``proto`` arguments are optional. The OpenVPN client
will try to connect to a server at ``host:port``. The ``proto`` argument
indicates the protocol to use when connecting with the remote, and may be
:code:`tcp` or :code:`udp`. To enforce IPv4 or IPv6 connections add a
:code:`4` or :code:`6` suffix; like :code:`udp4` / :code:`udp6`
/ :code:`tcp4` / :code:`tcp6`.
On the client, multiple ``--remote`` options may be specified for
redundancy, each referring to a different OpenVPN server, in the order
specified by the list of ``--remote`` options. Specifying multiple
``--remote`` options for this purpose is a special case of the more
general connection-profile feature. See the ``<connection>``
documentation below.
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.
Examples:
::
remote server1.example.net
remote server1.example.net 1194
remote server2.example.net 1194 tcp
*Note:*
Since UDP is connectionless, connection failure is defined by
the ``--ping`` and ``--ping-restart`` options.
Also, if you use multiple ``--remote`` options, AND you are dropping
root privileges on the client with ``--user`` and/or ``--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 ``--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, ``--remote`` will act as a filter, rejecting
connections from any host which does not match ``host``.
If ``host`` is a DNS name which resolves to multiple IP addresses,
OpenVPN will try them in the order that the system getaddrinfo()
presents them, so priorization and DNS randomization is done by the
system library. Unless an IP version is forced by the protocol
specification (4/6 suffix), OpenVPN will try both IPv4 and IPv6
addresses, in the order getaddrinfo() returns them.
--remote-random
When multiple ``--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.
--remote-random-hostname
Prepend a random string (6 bytes, 12 hex characters) to hostname to
prevent DNS caching. For example, "foo.bar.gov" would be modified to
"<random-chars>.foo.bar.gov".
--resolv-retry n
If hostname resolve fails for ``--remote``, retry resolve for ``n``
seconds before failing.
Set ``n`` to :code:`infinite` to retry indefinitely.
By default, ``--resolv-retry infinite`` is enabled. You can disable by
setting n=0.
--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 ``--ping-restart``, it will allow
one new connection.
``--single-session`` can be used with ``--ping-exit`` or ``--inactive``
to create a single dynamic session that will exit when finished.
--server-poll-timeout n
When connecting to a remote server do not wait for more than ``n``
seconds for a response before trying the next server. The default value
is :code:`120`. This timeout includes proxy and TCP connect timeouts.
--static-challenge args
Enable static challenge/response protocol
Valid syntax:
::
static-challenge text echo
The ``text`` challenge text is presented to the user which describes what
information is requested. The ``echo`` flag indicates if the user's
input should be echoed on the screen. Valid ``echo`` values are
:code:`0` or :code:`1`.
See management-notes.txt in the OpenVPN distribution for a description of
the OpenVPN challenge/response protocol.
.. include:: proxy-options.rst
doc/man-sections/connection-profiles.rst 0 → 100644
View file @ e1e1377b
CONNECTION PROFILES
===================
Client configuration files may contain multiple remote servers which
it will attempt to connect against. But there are some configuration
options which are related to specific ``--remote`` options. For these
use cases, connection profiles are the solution.
By enacpulating the ``--remote`` option and related options within
``<connection>`` and ``</connection>``, these options are handled as a
group.
An OpenVPN client will try each connection profile sequentially until it
achieves a successful connection.
``--remote-random`` can be used to initially "scramble" the connection
list.
Here is an example of connection profile usage:
::
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
</connection>
<connection>
remote 198.19.36.99 443 tcp
http-proxy 192.168.0.8 8080
</connection>
persist-key
persist-tun
pkcs12 client.p12
remote-cert-tls server
verb 3
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 ``<connection>``
block:
``bind``, ``connect-retry``, ``connect-retry-max``, ``connect-timeout``,
``explicit-exit-notify``, ``float``, ``fragment``, ``http-proxy``,
``http-proxy-option``, ``key-direction``, ``link-mtu``, ``local``,
``lport``, ``mssfix``, ``mtu-disc``, ``nobind``, ``port``, ``proto``,
``remote``, ``rport``, ``socks-proxy``, ``tls-auth``, ``tls-crypt``,
``tun-mtu and``, ``tun-mtu-extra``.
A defaulting mechanism exists for specifying options to apply to all
``<connection>`` profiles. If any of the above options (with the
exception of ``remote`` ) appear outside of a ``<connection>`` block,
but in a configuration file which has one or more ``<connection>``
blocks, the option setting will be used as a default for
``<connection>`` blocks which follow it in the configuration file.
For example, suppose the ``nobind`` option were placed in the sample
configuration file above, near the top of the file, before the first
``<connection>`` block. The effect would be as if ``nobind`` were
declared in all ``<connection>`` blocks below it.
doc/man-sections/encryption-options.rst 0 → 100644
View file @ e1e1377b
Encryption Options
==================
SSL Library information
-----------------------
--show-ciphers
(Standalone) Show all cipher algorithms to use with the ``--cipher``
option.
--show-digests
(Standalone) Show all message digest algorithms to use with the
``--auth`` option.
--show-tls
(Standalone) Show all TLS ciphers supported by the crypto library.
OpenVPN uses TLS to secure the control channel, over which the keys that
are used to protect the actual VPN traffic are exchanged. The TLS
ciphers will be sorted from highest preference (most secure) to lowest.
Be aware that whether a cipher suite in this list can actually work
depends on the specific setup of both peers (e.g. both peers must
support the cipher, and an ECDSA cipher suite will not work if you are
using an RSA certificate, etc.).
--show-engines
(Standalone) Show currently available hardware-based crypto acceleration
engines supported by the OpenSSL library.
--show-groups
(Standalone) Show all available elliptic curves/groups to use with the
``--ecdh-curve`` and ``tls-groups`` options.
Generating key material
-----------------------
--genkey args
(Standalone) Generate a key to be used of the type keytype. if keyfile
is left out or empty the key will be output on stdout. See the following
sections for the different keytypes.
Valid syntax:
::
--genkey keytype keyfile
Valid keytype arguments are:
:code:`secret` Standard OpenVPN shared secret keys
:code:`tls-crypt` Alias for :code:`secret`
:code:`tls-auth` Alias for :code:`secret`
:code:`auth-token` Key used for ``--auth-gen-token-key``
:code:`tls-crypt-v2-server` TLS Crypt v2 server key
:code:`tls-crypt-v2-client` TLS Crypt v2 client key
Examples:
::
$ openvpn --genkey secret shared.key
$ openvpn --genkey tls-crypt shared.key
$ openvpn --genkey tls-auth shared.key
$ openvpn --genkey tls-crypt-v2-server v2crypt-server.key
$ openvpn --tls-crypt-v2 v2crypt-server.key --genkey tls-crypt-v2-client v2crypt-client-1.key
* Generating *Shared Secret Keys*
Generate a shared secret, for use with the ``--secret``, ``--tls-auth``
or ``--tls-crypt`` options.
Syntax:
::
$ openvpn --genkey secret|tls-crypt|tls-auth keyfile
The key is saved in ``keyfile``. All three variants (``--secret``,
``tls-crypt`` and ``tls-auth``) generate the same type of key. The
aliases are added for convenience.
If using this for ``--secret``, this file must be shared with the peer
over a pre-existing secure channel such as ``scp``\(1).
* Generating *TLS Crypt v2 Server key*
Generate a ``--tls-crypt-v2`` key to be used by an OpenVPN server.
The key is stored in ``keyfile``.
Syntax:
::
--genkey tls-crypt-v2-server keyfile
* Generating *TLS Crypt v2 Client key*
Generate a --tls-crypt-v2 key to be used by OpenVPN clients. The
key is stored in ``keyfile``.
Syntax
::
--genkey tls-crypt-v2-client keyfile [metadata]
If supplied, include the supplied ``metadata`` in the wrapped client
key. This metadata must be supplied in base64-encoded form. The
metadata must be at most 735 bytes long (980 bytes in base64).
If no metadata is supplied, OpenVPN will use a 64-bit unix timestamp
representing the current time in UTC, encoded in network order, as
metadata for the generated key.
A tls-crypt-v2 client key is wrapped using a server key. To generate a
client key, the user must therefore supply the server key using the
``--tls-crypt-v2`` option.
Servers can use ``--tls-crypt-v2-verify`` to specify a metadata
verification command.
* Generate *Authentication Token key*
Generate a new secret that can be used with **--auth-gen-token-secret**
Syntax:
::
--genkey auth-token [keyfile]
*Note:*
This file should be kept secret to the server as anyone that has
access to this file will be able to generate auth tokens that the
OpenVPN server will accept as valid.
.. include:: renegotiation.rst
.. include:: tls-options.rst
.. include:: pkcs11-options.rst
doc/man-sections/example-fingerprint.rst 0 → 100644
View file @ e1e1377b
Small OpenVPN setup with peer-fingerprint
=========================================
This section consists of instructions how to build a small OpenVPN setup with the
:code:`peer-fingerprint` option. This has the advantage of being easy to setup
and should be suitable for most small lab and home setups without the need for a PKI.
For bigger scale setup setting up a PKI (e.g. via easy-rsa) is still recommended.
Both server and client configuration can be further modified to customise the
setup.
Server setup
------------
1. Install openvpn
Compile from source-code (see `INSTALL` file) or install via a distribution (apt/yum/ports)
or via installer (Windows).
2. Generate a self-signed certificate for the server:
::
openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -keyout server.key -out server.crt -nodes -sha256 -days 3650 -subj '/CN=server'
3. Generate SHA256 fingerprint of the server certificate
Use the OpenSSL command line utility to view the fingerprint of just
created certificate:
::
openssl x509 -fingerprint -sha256 -in server.crt -noout
This output something similar to:
::
SHA256 Fingerprint=00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff
3. Write a server configuration (`server.conf`):
::
# The server certificate we created in step 1
cert server.crt
key server.key
dh none
dev tun
# Listen on IPv6+IPv4 simultaneously
proto udp6
# The ip address the server will distribute
server 10.8.0.0 255.255.255.0
server-ipv6 fd00:6f76:706e::/64
# A tun-mtu of 1400 avoids problems of too big packets after VPN encapsulation
tun-mtu 1400
# The fingerprints of your clients. After adding/removing one here restart the
# server
<peer-fingerprint>
</peer-fingerprint>
# Notify clients when you restart the server to reconnect quickly
explicit-exit-notify 1
# Ping every 60s, restart if no data received for 5 minutes
keepalive 60 300
4. Add at least one client as described in the client section.
5. Start the server.
- On systemd based distributions move `server.crt`, `server.key` and
`server.conf` to :code:`/etc/openvpn/server` and start it via systemctl
::
sudo mv server.conf server.key server.crt /etc/openvpn/server
sudo systemctl start openvpn-server@server
Adding a client
---------------
1. Install OpenVPN
2. Generate a self-signed certificate for the client. In this example the client
name is alice. Each client should have a unique name. Replace alice with a
different name for each client.
::
openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -nodes -sha256 -days 3650 -subj '/CN=alice'
This generate a certificate and a key for the client. The output of the command will look
something like this:
::
-----BEGIN PRIVATE KEY-----
[base64 content]
-----END PRIVATE KEY-----
-----
-----BEGIN CERTIFICATE-----
[base 64 content]
-----END CERTIFICATE-----
3. Create a new client configuration file. In this example we will name the file
`alice.ovpn`:
::
# The name of your server to connect to
remote yourserver.example.net
client
# use a random source port instead the fixed 1194
nobind
# Uncomment the following line if you want to route
# all traffic via the VPN
# redirect-gateway def1 ipv6
# To set a DNS server
# dhcp-option DNS 192.168.234.1
<key>
-----BEGIN PRIVATE KEY-----
[Insert here the key created in step 2]
-----END PRIVATE KEY-----
</key>
<cert>
-----BEGIN CERTIFICATE-----
[Insert here the certificate created in step 2]
-----END CERTIFICATE-----
</cert>
# This is the fingerprint of the server that we trust. We generated this fingerprint
# in step 2 of the server setup
peer-fingerprint 00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff
# The tun-mtu of the client should match the server MTU
tun-mtu 1400
dev tun
4. Generate the fingerprint of the client certificate. For that we will
let OpenSSL read the client configuration file as the x509 command will
ignore anything that is not between the begin and end markers of the certificate:
::
openssl x509 -fingerprint -sha256 -noout -in alice.ovpn
This will again output something like
::
SHA256 Fingerprint=ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00
5. Edit the `server.conf` configuration file and add this new client
fingerprint as additional line between :code:`<peer-fingerprint>`
and :code:`</peer-fingerprint>`
After adding *two* clients the part of configuration would look like this:
::
<peer-fingerprint>
ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00
99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:88:77:66:55:44:33
</peer-fingperint>
6. (optional) if the client is an older client that does not support the
:code:`peer-fingerprint` (e.g. OpenVPN 2.5 and older, OpenVPN Connect 3.3
and older), the client config `alice.ovpn` can be modified to still work with
these clients.
Remove the line starting with :code:`peer-fingerprint`. Then
add a new :code:`<ca>` section at the end of the configuration file
with the contents of the :code:`server.crt` created in step 2 of the
server setup. The end of `alice.ovpn` file should like:
::
[...] # Beginning of the file skipped
</cert>
# The tun-mtu of the client should match the server MTU
tun-mtu 1400
dev tun
<ca>
[contents of the server.crt]
</ca>
Note that we put the :code:`<ca>` section after the :code:`<cert>` section
to make the fingerprint generation from step 4 still work since it will
only use the first certificate it finds.
7. Import the file into the OpenVPN client or just use the
:code:`openvpn alice.ovpn` to start the VPN.
doc/man-sections/examples.rst 0 → 100644
View file @ e1e1377b
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.
Firewall Setup:
---------------
If firewalls exist between the two machines, they should be set to
forward the port OpenVPN is configured to use, in both directions.
The default for OpenVPN is 1194/udp. If you do not have control
over the firewalls between the two machines, you may still be able to
use OpenVPN by adding ``--ping 15`` to each of the ``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).
Please see your operating system guides for how to configure the firewall
on your systems.
VPN Address Setup:
------------------
For purposes of our example, our two machines will be called
``bob.example.com`` and ``alice.example.com``. If you are constructing a
VPN over the internet, then replace ``bob.example.com`` and
``alice.example.com`` 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 bob.example.com will be
10.4.0.1 and for alice.example.com, 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
bob.example.com and you wish to connect to ``alice.example.com`` via
``ssh`` without using the VPN (since **ssh** has its own built-in security)
you would use the command ``ssh alice.example.com``. However in the same
scenario, you could also use the command ``telnet 10.4.0.2`` to create a
telnet session with alice.example.com over the VPN, that would use the
VPN to secure the session rather than ``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.
Example 1: A simple tunnel without security (not recommended)
-------------------------------------------------------------
On bob:
::
openvpn --remote alice.example.com --dev tun1 \
--ifconfig 10.4.0.1 10.4.0.2 --verb 9
On alice:
::
openvpn --remote bob.example.com --dev tun1 \
--ifconfig 10.4.0.2 10.4.0.1 --verb 9
Now verify the tunnel is working by pinging across the tunnel.
On bob:
::
ping 10.4.0.2
On alice:
::
ping 10.4.0.1
The ``--verb 9`` option will produce verbose output, similar to the
``tcpdump``\(8) program. Omit the ``--verb 9`` option to have OpenVPN run
quietly.
Example 2: A tunnel with self-signed certificates and fingerprint
-----------------------------------------------------------------
First build a self-signed certificate on bob and display its fingerprint.
::
openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -keyout bob.pem -out bob.pem -nodes -sha256 -days 3650 -subj '/CN=bob'
openssl x509 -noout -sha256 -fingerprint -in bob.pem
and the same on alice:
::
openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -keyout alice.pem -out alice.pem -nodes -sha256 -days 3650 -subj '/CN=alice'
openssl x509 -noout -sha256 -fingerprint -in alice.pem
These commands will build a text file called ``bob.pem`` or ``alice.pem`` (in ascii format)
that contain both self-signed certificate and key and show the fingerprint of the certificates.
Transfer the fingerprints over a secure medium such as by using
the ``scp``\(1) or ``ssh``\(1) program.
On bob:
::
openvpn --ifconfig 10.4.0.1 10.4.0.2 --tls-server --dev tun --dh none \
--cert bob.pem --key bob.pem --cipher AES-256-GCM \
--peer-fingerprint "$fingerprint_of_alices_cert"
On alice:
::
openvpn --remote bob.example.com --tls-client --dev tun1 \
--ifconfig 10.4.0.2 10.4.0.1 --cipher AES-256-GCM \
--cert alice.pem --key alice.pem
--peer-fingerprint "$fingerprint_of_bobs_cert"
Now verify the tunnel is working by pinging across the tunnel.
On bob:
::
ping 10.4.0.2
On alice:
::
ping 10.4.0.1
Note: This example use a elliptic curve (`secp384`), which allows
``--dh`` to be set to ``none``.
Example 3: A tunnel with full PKI and TLS-based security
--------------------------------------------------------
For this test, we will designate ``bob`` as the TLS client and ``alice``
as the TLS server.
*Note:*
The 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 bob and alice (see
above where ``--cert`` is discussed for more info). Then construct
Diffie Hellman parameters (see above where ``--dh`` is discussed for
more info). You can also use the included test files :code:`client.crt`,
:code:`client.key`, :code:`server.crt`, :code:`server.key` and
:code:`ca.crt`. The ``.crt`` files are certificates/public-keys, the
``.key`` files are private keys, and :code:`ca.crt` is a certification
authority who has signed both :code:`client.crt` and :code:`server.crt`.
For Diffie Hellman parameters you can use the included file
:code:`dh2048.pem`.
*WARNING:*
All client, server, and certificate authority certificates
and keys included in the OpenVPN distribution are totally
insecure and should be used for testing only.
On bob:
::
openvpn --remote alice.example.com --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
On alice:
::
openvpn --remote bob.example.com --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
Now verify the tunnel is working by pinging across the tunnel.
On bob:
::
ping 10.4.0.2
On alice:
::
ping 10.4.0.1
Notice the ``--reneg-sec 60`` option we used above. That tells OpenVPN
to renegotiate the data channel keys every minute. Since we used
``--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 ``--reneg-sec 60`` option to use
OpenVPN's default key renegotiation interval of one hour.
Routing:
--------
Assuming you can ping across the tunnel, the next step is to route a
real subnet over the secure tunnel. Suppose that bob and alice 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 bob's private subnet is *10.0.0.0/24* and
alice's is *10.0.1.0/24*.
First, ensure that IP forwarding is enabled on both peers. On Linux,
enable routing:
::
echo 1 > /proc/sys/net/ipv4/ip_forward
This setting is not persistent. Please see your operating systems
documentation how to properly configure IP forwarding, which is also
persistent through system boots.
If your system is configured with a firewall. Please see your operating
systems guide on how to configure the firewall. You typically want to
allow traffic coming from and going to the tun/tap adapter OpenVPN is
configured to use.
On bob:
::
route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
On alice:
::
route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
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 ``--up`` option.
doc/man-sections/generic-options.rst 0 → 100644
View file @ e1e1377b
Generic Options
---------------
This section covers generic options which are accessible regardless of
which mode OpenVPN is configured as.
--help
Show options.
--auth-nocache
Don't cache ``--askpass`` or ``--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.
When using ``--auth-nocache`` in combination with a user/password file
and ``--chroot`` or ``--daemon``, make sure to use an absolute path.
This directive does not affect the ``--http-proxy`` username/password.
It is always cached.
--cd dir
Change directory to ``dir`` prior to reading any files such as
configuration files, key files, scripts, etc. ``dir`` should be an
absolute path, with a leading "/", and without any references to the
current directory such as :code:`.` or :code:`..`.
This option is useful when you are running OpenVPN in ``--daemon`` mode,
and you want to consolidate all of your OpenVPN control files in one
location.
--chroot dir
Chroot to ``dir`` after initialization. ``--chroot`` essentially
redefines ``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 ``dir`` parameter can point to an empty directory,
however complications can result when scripts or restarts are executed
after the chroot operation.
Note: The SSL library will probably need /dev/urandom to be available
inside the chroot directory ``dir``. This is because SSL libraries
occasionally need to collect fresh randomness. Newer linux kernels and some
BSDs implement a getrandom() or getentropy() syscall that removes the
need for /dev/urandom to be available.
--compat-mode version
This option provides a way to alter the default of OpenVPN to be more
compatible with the version ``version`` specified. All of the changes
this option does can also be achieved using individual configuration
options.
Note: Using this option reverts defaults to no longer recommended
values and should be avoided if possible.
The following table details what defaults are changed depending on the
version specified.
- 2.5.x or lower: ``--allow-compression asym`` is automatically added
to the configuration if no other compression options are present.
- 2.4.x or lower: The cipher in ``--cipher`` is appended to
``--data-ciphers``
- 2.3.x or lower: ``--data-cipher-fallback`` is automatically added with
the same cipher as ``--cipher``
- 2.3.6 or lower: ``--tls-version-min 1.0`` is added to the configuration
when ``--tls-version-min`` is not explicitly set.
--config file
Load additional config options from ``file`` where each line corresponds
to one command line option, but with the leading :code:`--` removed.
If ``--config file`` is the only option to the openvpn command, the
``--config`` can be removed, and the command can be given as ``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:
::
\\ 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.
For example on Windows, use double backslashes to represent pathnames:
::
secret "c:\\OpenVPN\\secret.key"
For examples of configuration files, see
https://openvpn.net/community-resources/how-to/
Here is an example configuration file:
::
#
# 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
--daemon progname
Become a daemon after all initialization functions are completed.
Valid syntaxes::
daemon
daemon progname
This option will cause all message and error output to be sent to the syslog
file (such as :code:`/var/log/messages`), except for the output of
scripts and ifconfig commands, which will go to :code:`/dev/null` unless
otherwise redirected. The syslog redirection occurs immediately at the
point that ``--daemon`` is parsed on the command line even though the
daemonization point occurs later. If one of the ``--log`` options is
present, it will supersede syslog redirection.
The optional ``progname`` parameter will cause OpenVPN to report its
program name to the system logger as ``progname``. This can be useful in
linking OpenVPN messages in the syslog file with specific tunnels. When
unspecified, ``progname`` defaults to :code:`openvpn`.
When OpenVPN is run with the ``--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.
Note: as soon as OpenVPN has daemonized, it can not ask for usernames,
passwords, or key pass phrases anymore. This has certain consequences,
namely that using a password-protected private key will fail unless the
``--askpass`` option is used to tell OpenVPN to ask for the pass phrase
(this requirement is new in v2.3.7, and is a consequence of calling
daemon() before initializing the crypto layer).
Further, using ``--daemon`` together with ``--auth-user-pass`` (entered
on console) and ``--auth-nocache`` will fail as soon as key
renegotiation (and reauthentication) occurs.
--disable-occ
Disable "options consistency check" (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 ``--dev tun`` while the other peer uses ``--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.
--engine engine-name
Enable OpenSSL hardware-based crypto engine functionality.
Valid syntaxes::
engine
engine engine-name
If ``engine-name`` is specified, use a specific crypto engine. Use the
``--show-engines`` standalone option to list the crypto engines which
are supported by OpenSSL.
--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 ``--proto
udp`` is specified, and when ``--shaper`` is *NOT* specified.
--group group
Similar to the ``--user`` option, this option changes the group ID of
the OpenVPN process to ``group`` after initialization.
--ignore-unknown-option args
Valid syntax:
::
ignore-unknown-options opt1 opt2 opt3 ... optN
When one of options ``opt1 ... optN`` is encountered in the configuration
file the configuration file parsing does not fail if this OpenVPN version
does not support the option. Multiple ``--ignore-unknown-option`` options
can be given to support a larger number of options to ignore.
This option should be used with caution, as there are good security
reasons for having OpenVPN fail if it detects problems in a config file.
Having said that, there are valid reasons for wanting new software
features to gracefully degrade when encountered by older software
versions.
``--ignore-unknown-option`` is available since OpenVPN 2.3.3.
--iproute cmd
Set alternate command to execute instead of default ``iproute2`` command.
May be used in order to execute OpenVPN in unprivileged environment.
--keying-material-exporter args
Save Exported Keying Material [RFC5705] of ``len`` bytes (must be between 16
and 4095 bytes) using ``label`` in environment
(:code:`exported_keying_material`) for use by plugins in
:code:`OPENVPN_PLUGIN_TLS_FINAL` callback.
Valid syntax:
::
keying-material-exporter label len
Note that exporter ``labels`` have the potential to collide with existing
PRF labels. In order to prevent this, labels *MUST* begin with
:code:`EXPORTER`.
--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 ``--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 ``--reneg`` options (see
below), then are discarded.
The downside of using ``--mlock`` is that it will reduce the amount of
physical memory available to other applications.
The limit on how much memory can be locked and how that limit
is enforced are OS-dependent. On Linux the default limit that an
unprivileged process may lock (RLIMIT_MEMLOCK) is low, and if
privileges are dropped later, future memory allocations will very
likely fail. The limit can be increased using ulimit or systemd
directives depending on how OpenVPN is started.
If the platform has the getrlimit(2) system call, OpenVPN will check
for the amount of mlock-able memory before calling mlockall(2), and
tries to increase the limit to 100 MB if less than this is configured.
100 Mb is somewhat arbitrary - it is enough for a moderately-sized
OpenVPN deployment, but the memory usage might go beyond that if the
number of concurrent clients is high.
--nice n
Change process priority after initialization (``n`` greater than 0 is
lower priority, ``n`` less than zero is higher priority).
--persist-key
Don't re-read key files across :code:`SIGUSR1` or ``--ping-restart``.
This option can be combined with ``--user nobody`` to allow restarts
triggered by the :code:`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 :code:`SIGUSR1`
resets, so they don't need to be re-read.
--providers providers
Load the list of (OpenSSL) providers. This is mainly useful for using an
external provider for key management like tpm2-openssl or to load the
legacy provider with
::
--providers legacy default
Behaviour of changing this option between :code:`SIGHUP` might not be well behaving.
If you need to change/add/remove this option, fully restart OpenVPN.
--remap-usr1 signal
Control whether internally or externally generated :code:`SIGUSR1` signals
are remapped to :code:`SIGHUP` (restart without persisting state) or
:code:`SIGTERM` (exit).
``signal`` can be set to :code:`SIGHUP` or :code:`SIGTERM`. By default,
no remapping occurs.
--script-security level
This directive offers policy-level control over OpenVPN's usage of
external programs and scripts. Lower ``level`` values are more
restrictive, higher values are more permissive. Settings for ``level``:
:code:`0`
Strictly no calling of external programs.
:code:`1`
(Default) Only call built-in executables such as ifconfig,
ip, route, or netsh.
:code:`2`
Allow calling of built-in executables and user-defined
scripts.
:code:`3`
Allow passwords to be passed to scripts via environmental
variables (potentially unsafe).
OpenVPN releases before v2.3 also supported a ``method`` flag which
indicated how OpenVPN should call external commands and scripts. This
could be either :code:`execve` or :code:`system`. As of OpenVPN 2.3, this
flag is no longer accepted. In most \*nix environments the execve()
approach has been used without any issues.
Some directives such as ``--up`` allow options to be passed to the
external script. In these cases make sure the script name does not
contain any spaces or the configuration parser will choke because it
can't determine where the script name ends and script options start.
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 ``system`` flag to run these scripts. As of OpenVPN
2.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:
::
--up 'C:\\Windows\\System32\\wscript.exe C:\\Program\ Files\\OpenVPN\\config\\my-up-script.vbs'
Please note the single quote marks and the escaping of the backslashes
(\\) and the space character.
The reason the support for the :code:`system` flag was removed is due to
the security implications with shell expansions when executing scripts
via the :code:`system()` call.
--setcon context
Apply SELinux ``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 ``--user`` and
``--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 ``--persist-key`` and ``--persist-tun`` options.
--status args
Write operational status to ``file`` every ``n`` seconds. ``n`` defaults
to :code:`60` if not specified.
Valid syntaxes:
::
status file
status file n
Status can also be written to the syslog by sending a :code:`SIGUSR2`
signal.
With multi-client capability enabled on a server, the status file
includes a list of clients and a routing table. The output format can be
controlled by the ``--status-version`` option in that case.
For clients or instances running in point-to-point mode, it will contain
the traffic statistics.
--status-version n
Set the status file format version number to ``n``.
This only affects the status file on servers with multi-client
capability enabled. Valid status version values:
:code:`1`
Traditional format (default). The client list contains the
following fields comma-separated: Common Name, Real Address, Bytes
Received, Bytes Sent, Connected Since.
:code:`2`
A more reliable format for external processing. Compared to
version :code:`1`, the client list contains some additional fields:
Virtual Address, Virtual IPv6 Address, Username, Client ID, Peer ID,
Data Channel Cipher. Future versions may extend the number of fields.
:code:`3`
Identical to :code:`2`, but fields are tab-separated.
--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 ``--dev`` or ``--remote``.
The typical usage of ``--test-crypto`` would be something like this:
::
openvpn --test-crypto --secret key
or
::
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.
--tmp-dir dir
Specify a directory ``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:
* ``--client-connect`` scripts and :code:`OPENVPN_PLUGIN_CLIENT_CONNECT`
plug-in hook to dynamically generate client-specific configuration
:code:`client_connect_config_file` and return success/failure via
:code:`client_connect_deferred_file` when using deferred client connect
method
* :code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` plug-in hooks returns
success/failure via :code:`auth_control_file` when using deferred auth
method and pending authentification via :code:`pending_auth_file`.
--use-prediction-resistance
Enable prediction resistance on mbed TLS'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.
--user user
Change the user ID of the OpenVPN process to ``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 ``user`` to :code:`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 :code:`SIGUSR1` signal (for example in response to
a DHCP reset), you should make use of one or more of the ``--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
``ifconfig`` on the TUN device).
--writepid file
Write OpenVPN's main process ID to ``file``.
doc/man-sections/inline-files.rst 0 → 100644
View file @ e1e1377b
INLINE FILE SUPPORT
===================
OpenVPN allows including files in the main configuration for the ``--ca``,
``--cert``, ``--dh``, ``--extra-certs``, ``--key``, ``--pkcs12``,
``--secret``, ``--crl-verify``, ``--http-proxy-user-pass``, ``--tls-auth``,
``--auth-gen-token-secret``, ``--peer-fingerprint``, ``--tls-crypt``,
``--tls-crypt-v2`` and ``--verify-hash`` options.
Each inline file started by the line ``<option>`` and ended by the line
``</option>``
Here is an example of an inline file usage
::
<cert>
-----BEGIN CERTIFICATE-----
[...]
-----END CERTIFICATE-----
</cert>
When using the inline file feature with ``--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 :code:`openssl base64 -in input.p12`
doc/man-sections/link-options.rst 0 → 100644
View file @ e1e1377b
Link Options
------------
This link options section covers options related to the connection between
the local and the remote host.
--bind keywords
Bind to local address and port. This is the default unless any of
``--proto tcp-client`` , ``--http-proxy`` or ``--socks-proxy`` are used.
If the optional :code:`ipv6only` keyword is present OpenVPN will bind only
to IPv6 (as opposed to IPv6 and IPv4) when a IPv6 socket is opened.
--float
Allow remote peer to change its IP address and/or port number, such as
due to DHCP (this is the default if ``--remote`` is not used).
``--float`` when specified with ``--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, ``--float`` tells OpenVPN to accept authenticated packets
from any address, not only the address which was specified in the
``--remote`` option.
--fragment args
Valid syntax:
::
fragment max
fragment max mtu
Enable internal datagram fragmentation so that no UDP datagrams are sent
which are larger than ``max`` bytes.
If the :code:`mtu` parameter is present the ``max`` parameter is
interpreted to include IP and UDP encapsulation overhead. The
:code:`mtu` parameter is introduced in OpenVPN version 2.6.0.
If the :code:`mtu` parameter is absent, the ``max`` parameter is
interpreted in the same way as the ``--link-mtu`` parameter, i.e.
the UDP packet size after encapsulation overhead has been added in,
but not including the UDP header itself.
The ``--fragment`` option only makes sense when you are using the UDP
protocol (``--proto udp``).
``--fragment`` adds 4 bytes of overhead per datagram.
See the ``--mssfix`` option below for an important related option to
``--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.
--keepalive args
A helper directive designed to simplify the expression of ``--ping`` and
``--ping-restart``.
Valid syntax:
::
keepalive interval timeout
Send ping once every ``interval`` seconds, restart if ping is not received
for ``timeout`` seconds.
This option can be used on both client and server side, but it is enough
to add this on the server side as it will push appropriate ``--ping``
and ``--ping-restart`` options to the client. If used on both server and
client, the values pushed from server will override the client local
values.
The ``timeout`` argument will be twice as long on the server side. This
ensures that a timeout is detected on client side before the server side
drops the connection.
For example, ``--keepalive 10 60`` expands as follows:
::
if mode server:
ping 10 # Argument: interval
ping-restart 120 # Argument: timeout*2
push "ping 10" # Argument: interval
push "ping-restart 60" # Argument: timeout
else
ping 10 # Argument: interval
ping-restart 60 # Argument: timeout
--link-mtu n
**DEPRECATED** 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.*
Due to variable header size of IP header (20 bytes for IPv4 and 40 bytes
for IPv6) and dynamically negotiated data channel cipher, this option
is not reliable. It is recommended to set tun-mtu with enough headroom
instead.
--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.
--lport port
Set local TCP/UDP port number or name. Cannot be used together with
``--nobind`` option.
--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.
--mode m
Set OpenVPN major mode. By default, OpenVPN runs in point-to-point mode
(:code:`p2p`). OpenVPN 2.0 introduces a new mode (:code:`server`) which
implements a multi-client server capability.
--mssfix args
Valid syntax:
::
mssfix max [mtu]
mssfix max [fixed]
mssfix
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 ``max`` bytes. The default value is :code:`1492 mtu`. Use :code:`0`
as max to disable mssfix.
If the :code:`mtu` parameter is specified the ``max`` value is interpreted
as the resulting packet size of VPN packets including the IP and UDP header.
Support for the :code:`mtu` parameter was added with OpenVPN version 2.6.0.
If the :code:`mtu` parameter is not specified, the ``max`` parameter
is interpreted in the same way as the ``--link-mtu`` parameter, i.e.
the UDP packet size after encapsulation overhead has been added in, but
not including the UDP header itself. Resulting packet would be at most 28
bytes larger for IPv4 and 48 bytes for IPv6 (20/40 bytes for IP header and
8 bytes for UDP header). Default value of 1450 allows OpenVPN packets to be
transmitted over IPv4 on a link with MTU 1478 or higher without IP level
fragmentation (and 1498 for IPv6).
If the :code:`fixed` parameter is specified, OpenVPN will make no attempt
to calculate the VPN encapsulation overhead but instead will set the MSS to
limit the size of the payload IP packets to the specified number. IPv4 packets
will have the MSS value lowered to mssfix - 40 and IPv6 packets to mssfix - 60.
if ``--mssfix`` is specified is specified without any parameter it
inherits the parameters of ``--fragment`` if specified or uses the
default for ``--mssfix`` otherwise.
The ``--mssfix`` option only makes sense when you are using the UDP
protocol for OpenVPN peer-to-peer communication, i.e. ``--proto udp``.
``--mssfix`` and ``--fragment`` can be ideally used together, where
``--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), ``--fragment`` will internally fragment them.
Both ``--fragment`` and ``--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 ``--fragment`` and ``--mssfix`` are used together, ``--mssfix`` will
take its default ``max`` parameter from the ``--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:
::
--tun-mtu 1500 --fragment 1300 --mssfix
--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.
Valid types:
:code:`no` Never send DF (Don't Fragment) frames
:code:`maybe` Use per-route hints
:code:`yes` Always DF (Don't Fragment)
--mtu-test
To empirically measure MTU on connection startup, add the ``--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 ``--mtu-test`` process normally takes about 3
minutes to complete.
--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 ``--remote``
option.
--passtos
Set the TOS field of the tunnel packet to what the payload's TOS is.
--ping n
Ping remote over the TCP/UDP control channel if no packets have been
sent for at least ``n`` seconds (specify ``--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 ``--secret``, ``--tls-server`` or
``--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 ``--ping-exit`` option.
When using OpenVPN in server mode see also ``--keepalive``.
--ping-exit n
Causes OpenVPN to exit after ``n`` seconds pass without reception of a
ping or other packet from remote. This option can be combined with
``--inactive``, ``--ping`` and ``--ping-exit`` to create a two-tiered
inactivity disconnect.
For example,
::
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.
--ping-restart n
Similar to ``--ping-exit``, but trigger a :code:`SIGUSR1` restart after
``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 https://www.nsupdate.info/ + a dynamic DNS client such as
``ddclient``.
If the peer cannot be reached, a restart will be triggered, causing the
hostname used with ``--remote`` to be re-resolved (if ``--resolv-retry``
is also specified).
In server mode, ``--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 ``--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 ``--keepalive`` setting in the
server configuration. To disable the 120 second default, set
``--ping-restart 0`` on the client.
See the signals section below for more information on :code:`SIGUSR1`.
Note that the behavior of ``SIGUSR1`` can be modified by the
``--persist-tun``, ``--persist-key``, ``--persist-local-ip`` and
``--persist-remote-ip`` options.
Also note that ``--ping-exit`` and ``--ping-restart`` are mutually
exclusive and cannot be used together.
--ping-timer-rem
Run the ``--ping-exit`` / ``--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 ``--remote`` peer), and you don't want to
start clocking timeouts until a remote peer connects.
--proto p
Use protocol ``p`` for communicating with remote host. ``p`` can be
:code:`udp`, :code:`tcp-client`, or :code:`tcp-server`. You can also
limit OpenVPN to use only IPv4 or only IPv6 by specifying ``p`` as
:code:`udp4`, :code:`tcp4-client`, :code:`tcp4-server` or :code:`udp6`,
:code:`tcp6-client`, :code:`tcp6-server`, respectively.
The default protocol is :code:`udp` when ``--proto`` is not specified.
For UDP operation, ``--proto udp`` should be specified on both peers.
For TCP operation, one peer must use ``--proto tcp-server`` and the
other must use ``--proto tcp-client``. A peer started with
:code:`tcp-server` will wait indefinitely for an incoming connection. A peer
started with :code:`tcp-client` will attempt to connect, and if that fails,
will sleep for 5 seconds (adjustable via the ``--connect-retry`` option)
and try again infinite or up to N retries (adjustable via the
``--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:
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.
--port port
TCP/UDP port number or port name for both local and remote (sets both
``--lport`` and ``--rport`` options to given port). 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.
--rport port
Set TCP/UDP port number or name used by the ``--remote`` option. The
port can also be set directly using the ``--remote`` option.
--replay-window args
Modify the replay protection sliding-window size and time window.
Valid syntaxes::
replay-window n
replay-window n t
Use a replay protection sliding-window of size ``n`` and a time window
of ``t`` seconds.
By default ``n`` is :code:`64` (the IPSec default) and ``t`` is
:code:`15` seconds.
This option is only relevant in UDP mode, i.e. when either ``--proto
udp`` is specified, or no ``--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.
(a) The packet cannot be a replay (unless ``--no-replay`` is
specified, which disables replay protection altogether).
(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 ``n``.
(c) If a packet arrives out of order, it will only be accepted if it
arrives no later than ``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 ``n``. Satellite links in particular often require this.
If you run OpenVPN at ``--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
``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.
--replay-persist file
Persist replay-protection state across sessions using ``file`` to save
and reload the state.
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 ``--secret`` (shared-secret key mode)
or TLS mode with ``--tls-auth``.
--socket-flags flags
Apply the given flags to the OpenVPN transport socket. Currently, only
:code:`TCP_NODELAY` is supported.
The :code:`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.
--tcp-nodelay
This macro sets the :code:`TCP_NODELAY` socket flag on the server as well
as pushes it to connecting clients. The :code:`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, :code:`TCP_NODELAY` is generally a good
latency optimization.
The macro expands as follows:
::
if mode server:
socket-flags TCP_NODELAY
push "socket-flags TCP_NODELAY"
doc/man-sections/log-options.rst 0 → 100644
View file @ e1e1377b
Log options
-----------
--echo parms
Echo ``parms`` to log output.
Designed to be used to send messages to a controlling application which
is receiving the OpenVPN log output.
--errors-to-stderr
Output errors to stderr instead of stdout unless log output is
redirected by one of the ``--log`` options.
--log file
Output logging messages to ``file``, including output to stdout/stderr
which is generated by called scripts. If ``file`` already exists it will
be truncated. This option takes effect immediately when it is parsed in
the command line and will supersede syslog output if ``--daemon``
is also specified. This option is persistent over the entire
course of an OpenVPN instantiation and will not be reset by
:code:`SIGHUP`, :code:`SIGUSR1`, or ``--ping-restart``.
Note that on Windows, when OpenVPN is started as a service, logging
occurs by default without the need to specify this option.
--log-append file
Append logging messages to ``file``. If ``file`` does not exist, it will
be created. This option behaves exactly like ``--log`` except that it
appends to rather than truncating the log file.
--machine-readable-output
Always write timestamps and message flags to log messages, even when
they otherwise would not be prefixed. In particular, this applies to log
messages sent to stdout.
--mute n
Log at most ``n`` consecutive messages in the same category. This is
useful to limit repetitive logging of similar message types.
--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.
--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.
--syslog progname
Direct log output to system logger, but do not become a daemon. See
``--daemon`` directive above for description of ``progname`` parameter.
--verb n
Set output verbosity to ``n`` (default :code:`1`). Each level shows all
info from the previous levels. Level :code:`3` is recommended if you want
a good summary of what's happening without being swamped by output.
:code:`0`
No output except fatal errors.
:code:`1` to :code:`4`
Normal usage range.
:code:`5`
Outputs :code:`R` and :code:`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.
:code:`6` to :code:`11`
Debug info range (see :code:`errlevel.h` in the source code for
additional information on debug levels).
doc/man-sections/management-options.rst 0 → 100644
View file @ e1e1377b
Management Interface Options
----------------------------
OpenVPN provides a feature rich socket based management interface for both
server and client mode operations.
--management args
Enable a management server on a ``socket-name`` Unix socket on those
platforms supporting it, or on a designated TCP port.
Valid syntaxes:
::
management socket-name unix #
management socket-name unix pw-file # (recommended)
management IP port # (INSECURE)
management IP port pw-file #
``pw-file``, if specified, is a password file where the password must
be on first line. Instead of a filename it can use the keyword stdin
which will prompt the user for a password to use when OpenVPN is
starting.
For unix sockets, the default behaviour is to create a unix domain
socket that may be connected to by any process. Use the
``--management-client-user`` and ``--management-client-group``
directives 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 IP to ``tunnel``. Tunnel mode will cause the management interface to
listen for a TCP connection on the local VPN address of the TUN/TAP
interface.
***BEWARE*** of enabling the management interface over TCP. In these cases
you should *ALWAYS* make use of ``pw-file`` to password protect the
management interface. Any user who can connect to this TCP ``IP:port``
will be able to manage and control (and interfere with) the OpenVPN
process. It is also strongly recommended to set IP to 127.0.0.1
(localhost) to restrict accessibility of the management server to local
clients.
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 :code:`help`
for a list of commands.
For detailed documentation on the management interface, see the
*management-notes.txt* file in the management folder of the OpenVPN
source distribution.
--management-client
Management interface will connect as a TCP/unix domain client to
``IP:port`` specified by ``--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.
--management-client-auth
Gives management interface client the responsibility to authenticate
clients after their client certificate has been verified. See
:code:`management-notes.txt` in OpenVPN distribution for detailed notes.
--management-client-group g
When the management interface is listening on a unix domain socket, only
allow connections from group ``g``.
--management-client-user u
When the management interface is listening on a unix domain socket, only
allow connections from user ``u``.
--management-external-cert certificate-hint
Allows usage for external certificate instead of ``--cert`` option
(client-only). ``certificate-hint`` is an arbitrary string which is
passed to a management interface client as an argument of
*NEED-CERTIFICATE* notification. Requires ``--management-external-key``.
--management-external-key args
Allows usage for external private key file instead of ``--key`` option
(client-only).
Valid syntaxes:
::
management-external-key
management-external-key nopadding
management-external-key pkcs1
management-external-key pss
or any combination like:
::
management-external-key nopadding pkcs1
management-external-key pkcs1 pss
The optional parameters :code:`nopadding` :code:`pkcs1` and :code:`pss` signal
support for different padding algorithms. See
:code:`doc/mangement-notes.txt` for a complete description of this
feature.
--management-forget-disconnect
Make OpenVPN forget passwords when management session disconnects.
This directive does not affect the ``--http-proxy`` username/password.
It is always cached.
--management-hold
Start OpenVPN in a hibernating state, until a client of the management
interface explicitly starts it with the :code:`hold release` command.
--management-log-cache n
Cache the most recent ``n`` lines of log file history for usage by the
management channel.
--management-query-passwords
Query management channel for private key password and
``--auth-user-pass`` username/password. Only query the management
channel for inputs which ordinarily would have been queried from the
console.
--management-query-proxy
Query management channel for proxy server information for a specific
``--remote`` (client-only).
--management-query-remote
Allow management interface to override ``--remote`` directives
(client-only).
--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 :code:`SIGTERM`.
--management-up-down
Report tunnel up/down events to management interface.