1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
/*
* OpenVPN -- An application to securely tunnel IP networks
* over a single TCP/UDP port, with support for SSL/TLS-based
* session authentication and key exchange,
* packet encryption, packet authentication, and
* packet compression.
*
* Copyright (C) 2010 Fox Crypto B.V. <openvpn@fox-it.com>
*
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2
* as published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program (see the file COPYING included with this
* distribution); if not, write to the Free Software Foundation, Inc.,
* 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
/**
* @file
* VPN tunnel state documentation file.
*/
/**
* @page tunnel_state Structure of the VPN tunnel state storage
*
* This section describes how OpenVPN stores its VPN tunnel state during
* operation.
*
* OpenVPN uses several data structures as storage containers for state
* information of active VPN tunnels. These are described in this
* section, together with a little bit of history to help understand the
* origin of the current architecture.
*
* Whether an OpenVPN process is running in client-mode or server-mode
* determines whether it can support only one or multiple simultaneously
* active VPN tunnels. This consequently also determines how the
* associated state information is wrapped up internally. This section
* gives an overview of the differences.
*
* @section tunnel_state_history Historic developments
*
* In the old v1.x series, an OpenVPN process managed only one single VPN
* tunnel. This allowed the VPN tunnel state to be stored together with
* process-global information in one single \c context structure.
*
* This changed, however, in the v2.x series, as new OpenVPN versions
* running in server-mode can support multiple simultaneously active VPN
* tunnels. This necessitated a redesign of the VPN tunnel state
* container structures, and modification of the \link
* external_multiplexer External Multiplexer\endlink and \link
* internal_multiplexer Internal Multiplexer\endlink systems. The
* majority of these changes are only relevant for OpenVPN processes
* running in server-mode, and the client-mode structure has remained very
* similar to the v1.x single-tunnel form.
*
* @section tunnel_state_client Client-mode state
*
* An OpenVPN process running in client-mode can manage at most one single
* VPN tunnel at any one time. The state information for a client's VPN
* tunnel is stored in a \c context structure.
*
* The \c context structure is created in the \c main() function. That is
* also where process-wide initialization takes place, such as parsing
* command line %options and reading configuration files. The \c context
* is then passed to \c tunnel_point_to_point() which drives OpenVPN's
* main event processing loop. These functions are both part of the \link
* eventloop Main Event Loop\endlink module.
*
* @subsection tunnel_state_client_init Initialization and cleanup
*
* Because there is only one \c context structure present, it can be
* initialized and cleaned up from the client's main event processing
* function. Before the \c tunnel_point_to_point() function enters its
* event loop, it calls \c init_instance_handle_signals() which calls \c
* init_instance() to initialize the single \c context structure. After
* the event loop stops, it calls \c close_instance() to clean up the \c
* context.
*
* @subsection tunnel_state_client_event Event processing
*
* When the main event processing loop activates the external or internal
* multiplexer to handle a network event, it is not necessary to determine
* which VPN tunnel the event is associated with, because there is only
* one VPN tunnel active.
*
* @section tunnel_state_server Server-mode state
*
* An OpenVPN process running in server-mode can manage multiple
* simultaneously active VPN tunnels. For every VPN tunnel active, in
* other words for every OpenVPN client which is connected to a server,
* the OpenVPN server has one \c context structure in which it stores that
* particular VPN tunnel's state information.
*
* @subsection tunnel_state_server_multi Multi_context and multi_instance structures
*
* To support multiple \c context structures, each is wrapped in a \c
* multi_instance structure, and all the \c multi_instance structures are
* registered in one single \c multi_context structure. The \link
* external_multiplexer External Multiplexer\endlink and \link
* internal_multiplexer Internal Multiplexer\endlink then use the \c
* multi_context to retrieve the correct \c multi_instance and \c context
* associated with a given network address.
*
* @subsection tunnel_state_server_init Startup and initialization
*
* An OpenVPN process running in server-mode starts in the same \c main()
* function as it would in client-mode. The same process-wide
* initialization is performed, and the resulting state and configuration
* is stored in a \c context structure. The server-mode and client-mode
* processes diverge when the \c main() function calls one of \c
* tunnel_point_to_point() or \c tunnel_server().
*
* In server-mode, \c main() calls the \c tunnel_server() function, which
* transfers control to \c tunnel_server_udp_single_threaded() or \c
* tunnel_server_tcp() depending on the external transport protocol.
*
* These functions receive the \c context created in \c main(). This
* object has a special status in server-mode, as it does not represent an
* active VPN tunnel, but does contain process-wide configuration
* parameters. In the source code, it is often stored in "top" variables.
* To distinguish this object from other instances of the same type, its
* \c context.mode value is set to \c CM_TOP. Other \c context objects,
* which do represent active VPN tunnels, have a \c context.mode set to \c
* CM_CHILD_UDP or \c CM_CHILD_TCP, depending on the external transport
* protocol.
*
* Both \c tunnel_server_udp_single_threaded() and \c tunnel_server_tcp()
* perform similar initialization. In either case, a \c multi_context
* structure is created, and it is initialized according to the
* configuration stored in the top \c context by the \c multi_init() and
* \c multi_top_init() functions.
*
* @subsection tunnel_state_server_tunnels Creating and destroying VPN tunnels
*
* When an OpenVPN client makes a new connection to a server, the server
* creates a new \c context and \c multi_instance. The latter is
* registered in the \c multi_context, which makes it possible for the
* external and internal multiplexers to retrieve the correct \c
* multi_instance and \c context when a network event occurs.
*
* @subsection tunnel_state_server_cleanup Final cleanup
*
* After the main event loop exits, both \c
* tunnel_server_udp_single_threaded() and \c tunnel_server_tcp() perform
* similar cleanup. They call \c multi_uninit() followed by \c
* multi_top_free() to clean up the \c multi_context structure.
*/
|
