1 .\" OpenVPN -- An application to securely tunnel IP networks
2 .\" over a single TCP/UDP port, with support for SSL/TLS-based
3 .\" session authentication and key exchange,
4 .\" packet encryption, packet authentication, and
5 .\" packet compression.
7 .\" Copyright (C) 2002-2008 OpenVPN Technologies, Inc. <sales@openvpn.net>
9 .\" This program is free software; you can redistribute it and/or modify
10 .\" it under the terms of the GNU General Public License version 2
11 .\" as published by the Free Software Foundation.
13 .\" This program is distributed in the hope that it will be useful,
14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 .\" GNU General Public License for more details.
18 .\" You should have received a copy of the GNU General Public License
19 .\" along with this program (see the file COPYING included with this
20 .\" distribution); if not, write to the Free Software Foundation, Inc.,
21 .\" 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
23 .\" Manual page for openvpn
24 .\" SH section heading
25 .\" SS subsection heading
27 .\" IP indented paragraph
29 .TH openvpn 8 "3 August 2005"
30 .\"*********************************************************
32 openvpn \- secure IP tunnel daemon.
33 .\"*********************************************************
49 [\ \fB\-\-config\fR\ \fIfile\fR\ ]
58 [\ \fB\-\-genkey\fR\ ]
59 [\ \fB\-\-secret\fR\ \fIfile\fR\ ]
70 [\ \fB\-\-dev\fR\ \fItunX\ |\ tapX\fR\ ]
71 [\ \fB\-\-dev\-type\fR\ \fIdevice\-type\fR\ ]
72 [\ \fB\-\-dev\-node\fR\ \fInode\fR\ ]
73 [\ \fB\-\-lladdr\fR\ \fIaddress\fR\ ]
74 [\ \fB\-\-user\fR\ \fIuser\fR\ ]
75 [\ \fB\-\-group\fR\ \fIgroup\fR\ ]
84 [\ \fB\-\-test\-crypto\fR\ ]
85 [\ \fB\-\-secret\fR\ \fIfile\fR\ ]
86 [\ \fB\-\-auth\fR\ \fIalg\fR\ ]
87 [\ \fB\-\-cipher\fR\ \fIalg\fR\ ]
88 [\ \fB\-\-engine\fR\ ]
89 [\ \fB\-\-keysize\fR\ \fIn\fR\ ]
90 [\ \fB\-\-no\-replay\fR\ ]
91 [\ \fB\-\-no\-iv\fR\ ]
100 [\ \fB\-\-allow\-nonadmin\fR\ \fI[TAP\-adapter]\fR\ ]
101 [\ \fB\-\-allow\-pull\-fqdn\fR\ ]
102 [\ \fB\-\-askpass\fR\ \fI[file]\fR\ ]
103 [\ \fB\-\-auth\-nocache\fR\ ]
104 [\ \fB\-\-auth\-retry\fR\ \fItype\fR\ ]
105 [\ \fB\-\-auth\-user\-pass\-verify\fR\ \fIscript\fR\ ]
106 [\ \fB\-\-auth\-user\-pass\fR\ \fIup\fR\ ]
107 [\ \fB\-\-auth\fR\ \fIalg\fR\ ]
108 [\ \fB\-\-auto\-proxy\fR\ ]
109 [\ \fB\-\-bcast\-buffers\fR\ \fIn\fR\ ]
110 [\ \fB\-\-ca\fR\ \fIfile\fR\ ]
111 [\ \fB\-\-ccd\-exclusive\fR\ ]
112 [\ \fB\-\-cd\fR\ \fIdir\fR\ ]
113 [\ \fB\-\-cert\fR\ \fIfile\fR\ ]
114 [\ \fB\-\-chroot\fR\ \fIdir\fR\ ]
115 [\ \fB\-\-cipher\fR\ \fIalg\fR\ ]
116 [\ \fB\-\-client\-cert\-not\-required\fR\ ]
117 [\ \fB\-\-client\-config\-dir\fR\ \fIdir\fR\ ]
118 [\ \fB\-\-client\-connect\fR\ \fIscript\fR\ ]
119 [\ \fB\-\-client\-disconnect\fR\ ]
120 [\ \fB\-\-client\-to\-client\fR\ ]
121 [\ \fB\-\-client\fR\ ]
122 [\ \fB\-\-comp\-lzo\fR\ \fI[mode]\fR\ ]
123 [\ \fB\-\-comp\-noadapt\fR\ ]
124 [\ \fB\-\-config\fR\ \fIfile\fR\ ]
125 [\ \fB\-\-connect\-freq\fR\ \fIn\ sec\fR\ ]
126 [\ \fB\-\-connect\-retry\fR\ \fIn\fR\ ]
127 [\ \fB\-\-connect\-retry\-max\fR\ \fIn\fR\ ]
128 [\ \fB\-\-crl\-verify\fR\ \fIcrl\fR\ ]
129 [\ \fB\-\-cryptoapicert\fR\ \fIselect\-string\fR\ ]
130 [\ \fB\-\-daemon\fR\ \fI[progname]\fR\ ]
131 [\ \fB\-\-dev\-node\fR\ \fInode\fR\ ]
132 [\ \fB\-\-dev\-type\fR\ \fIdevice\-type\fR\ ]
133 [\ \fB\-\-dev\fR\ \fItunX\ |\ tapX\ |\ null\fR\ ]
134 [\ \fB\-\-dev\fR\ \fItunX\ |\ tapX\fR\ ]
135 [\ \fB\-\-dh\fR\ \fIfile\fR\ ]
136 [\ \fB\-\-dhcp\-option\fR\ \fItype\ [parm]\fR\ ]
137 [\ \fB\-\-dhcp\-release\fR\ ]
138 [\ \fB\-\-dhcp\-renew\fR\ ]
139 [\ \fB\-\-disable\-occ\fR\ ]
140 [\ \fB\-\-disable\fR\ ]
141 [\ \fB\-\-down\-pre\fR\ ]
142 [\ \fB\-\-down\fR\ \fIcmd\fR\ ]
143 [\ \fB\-\-duplicate\-cn\fR\ ]
144 [\ \fB\-\-echo\fR\ \fI[parms...]\fR\ ]
145 [\ \fB\-\-engine\fR\ \fI[engine\-name]\fR\ ]
146 [\ \fB\-\-explicit\-exit\-notify\fR\ \fI[n]\fR\ ]
147 [\ \fB\-\-fast\-io\fR\ ]
148 [\ \fB\-\-float\fR\ ]
149 [\ \fB\-\-fragment\fR\ \fImax\fR\ ]
150 [\ \fB\-\-genkey\fR\ ]
151 [\ \fB\-\-group\fR\ \fIgroup\fR\ ]
152 [\ \fB\-\-hand\-window\fR\ \fIn\fR\ ]
153 [\ \fB\-\-hash\-size\fR\ \fIr\ v\fR\ ]
155 [\ \fB\-\-http\-proxy\-option\fR\ \fItype\ [parm]\fR\ ]
156 [\ \fB\-\-http\-proxy\-retry\fR\ ]
157 [\ \fB\-\-http\-proxy\-timeout\fR\ \fIn\fR\ ]
158 [\ \fB\-\-http\-proxy\fR\ \fIserver\ port\ [authfile]\ [auth\-method]\fR\ ]
159 [\ \fB\-\-ifconfig\-noexec\fR\ ]
160 [\ \fB\-\-ifconfig\-nowarn\fR\ ]
161 [\ \fB\-\-ifconfig\-pool\-linear\fR\ ]
162 [\ \fB\-\-ifconfig\-pool\-persist\fR\ \fIfile\ [seconds]\fR\ ]
163 [\ \fB\-\-ifconfig\-pool\fR\ \fIstart\-IP\ end\-IP\ [netmask]\fR\ ]
164 [\ \fB\-\-ifconfig\-push\fR\ \fIlocal\ remote\-netmask\fR\ ]
165 [\ \fB\-\-ifconfig\fR\ \fIl\ rn\fR\ ]
166 [\ \fB\-\-inactive\fR\ \fIn\ [bytes]\fR\ ]
167 [\ \fB\-\-inetd\fR\ \fI[wait|nowait]\ [progname]\fR\ ]
168 [\ \fB\-\-ip\-win32\fR\ \fImethod\fR\ ]
169 [\ \fB\-\-ipchange\fR\ \fIcmd\fR\ ]
170 [\ \fB\-\-iproute\fR\ \fIcmd\fR\ ]
171 [\ \fB\-\-iroute\fR\ \fInetwork\ [netmask]\fR\ ]
172 [\ \fB\-\-keepalive\fR\ \fIn\ m\fR\ ]
173 [\ \fB\-\-key\-method\fR\ \fIm\fR\ ]
174 [\ \fB\-\-key\fR\ \fIfile\fR\ ]
175 [\ \fB\-\-keysize\fR\ \fIn\fR\ ]
176 [\ \fB\-\-learn\-address\fR\ \fIcmd\fR\ ]
177 [\ \fB\-\-link\-mtu\fR\ \fIn\fR\ ]
178 [\ \fB\-\-local\fR\ \fIhost\fR\ ]
179 [\ \fB\-\-log\-append\fR\ \fIfile\fR\ ]
180 [\ \fB\-\-log\fR\ \fIfile\fR\ ]
181 [\ \fB\-\-suppress-timestamps\fR\ ]
182 [\ \fB\-\-lport\fR\ \fIport\fR\ ]
183 [\ \fB\-\-management\-client\-auth\fR\ ]
184 [\ \fB\-\-management\-client\-group\fR\ \fIg\fR\ ]
185 [\ \fB\-\-management\-client\-pf\fR\ ]
186 [\ \fB\-\-management\-client\-user\fR\ \fIu\fR\ ]
187 [\ \fB\-\-management\-forget\-disconnect\fR\ ]
188 [\ \fB\-\-management\-hold\fR\ ]
189 [\ \fB\-\-management\-log\-cache\fR\ \fIn\fR\ ]
190 [\ \fB\-\-management\-signal\fR\ ]
191 [\ \fB\-\-management\-query\-passwords\fR\ ]
192 [\ \fB\-\-management\fR\ \fIIP\ port\ [pw\-file]\fR\ ]
193 [\ \fB\-\-max\-clients\fR\ \fIn\fR\ ]
194 [\ \fB\-\-max\-routes\-per\-client\fR\ \fIn\fR\ ]
195 [\ \fB\-\-mktun\fR\ ]
196 [\ \fB\-\-mlock\fR\ ]
197 [\ \fB\-\-mode\fR\ \fIm\fR\ ]
198 [\ \fB\-\-mssfix\fR\ \fImax\fR\ ]
199 [\ \fB\-\-mtu\-disc\fR\ \fItype\fR\ ]
200 [\ \fB\-\-mtu\-test\fR\ ]
201 [\ \fB\-\-mute\-replay\-warnings\fR\ ]
202 [\ \fB\-\-mute\fR\ \fIn\fR\ ]
203 [\ \fB\-\-nice\fR\ \fIn\fR\ ]
204 [\ \fB\-\-no\-iv\fR\ ]
205 [\ \fB\-\-no\-replay\fR\ ]
207 [\ \fB\-\-nobind\fR\ ]
208 [\ \fB\-\-ns\-cert\-type\fR\ \fIclient|server\fR\ ]
209 [\ \fB\-\-passtos\fR\ ]
210 [\ \fB\-\-pause\-exit\fR\ ]
211 [\ \fB\-\-persist\-key\fR\ ]
212 [\ \fB\-\-persist\-local\-ip\fR\ ]
213 [\ \fB\-\-persist\-remote\-ip\fR\ ]
214 [\ \fB\-\-persist\-tun\fR\ ]
215 [\ \fB\-\-ping\-exit\fR\ \fIn\fR\ ]
216 [\ \fB\-\-ping\-restart\fR\ \fIn\fR\ ]
217 [\ \fB\-\-ping\-timer\-rem\fR\ ]
218 [\ \fB\-\-ping\fR\ \fIn\fR\ ]
219 [\ \fB\-\-pkcs11\-cert\-private\fR\ \fI[0|1]...\fR\ ]
220 [\ \fB\-\-pkcs11\-id\fR\ \fIname\fR\ ]
221 [\ \fB\-\-pkcs11\-id\-management\fR\ ]
222 [\ \fB\-\-pkcs11\-pin\-cache\fR\ \fIseconds\fR\ ]
223 [\ \fB\-\-pkcs11\-private\-mode\fR\ \fImode...\fR\ ]
224 [\ \fB\-\-pkcs11\-protected\-authentication\fR\ \fI[0|1]...\fR\ ]
225 [\ \fB\-\-pkcs11\-providers\fR\ \fIprovider...\fR\ ]
226 [\ \fB\-\-pkcs12\fR\ \fIfile\fR\ ]
227 [\ \fB\-\-plugin\fR\ \fImodule\-pathname\ init\-string\fR\ ]
228 [\ \fB\-\-port\fR\ \fIport\fR\ ]
229 [\ \fB\-\-port\-share\fR\ \fIhost\ port\fR\ ]
230 [\ \fB\-\-proto\fR\ \fIp\fR\ ]
232 [\ \fB\-\-push\-reset\fR\ ]
233 [\ \fB\-\-push\fR\ \fI"option"\fR\ ]
234 [\ \fB\-\-rcvbuf\fR\ \fIsize\fR\ ]
235 [\ \fB\-\-redirect\-gateway\fR\ \fIflags...\fR\ ]
236 [\ \fB\-\-remap\-usr1\fR\ \fIsignal\fR\ ]
237 [\ \fB\-\-remote\-random\fR\ ]
238 [\ \fB\-\-remote\fR\ \fIhost\ [port]\fR\ ]
239 [\ \fB\-\-remote\-cert\-ku\ \fIv...\fR\ ]
240 [\ \fB\-\-remote\-cert\-eku\ \fIoid\fR\ ]
241 [\ \fB\-\-remote\-cert\-tls\ \fIt\fR\ ]
242 [\ \fB\-\-reneg\-bytes\fR\ \fIn\fR\ ]
243 [\ \fB\-\-reneg\-pkts\fR\ \fIn\fR\ ]
244 [\ \fB\-\-reneg\-sec\fR\ \fIn\fR\ ]
245 [\ \fB\-\-replay\-persist\fR\ \fIfile\fR\ ]
246 [\ \fB\-\-replay\-window\fR\ \fIn\ [t]\fR\ ]
247 [\ \fB\-\-resolv\-retry\fR\ \fIn\fR\ ]
248 [\ \fB\-\-rmtun\fR\ ]
249 [\ \fB\-\-route\-delay\fR\ \fI[n]\ [w]\fR\ ]
250 [\ \fB\-\-route\-gateway\fR\ \fIgw\fR\ ]
251 [\ \fB\-\-route\-method\fR\ \fIm\fR\ ]
252 [\ \fB\-\-route\-metric\fR\ \fIm\fR\ ]
253 [\ \fB\-\-route\-noexec\fR\ ]
254 [\ \fB\-\-route\-nopull\fR\ ]
255 [\ \fB\-\-route\-up\fR\ \fIcmd\fR\ ]
256 [\ \fB\-\-route\fR\ \fInetwork\ [netmask]\ [gateway]\ [metric]\fR\ ]
257 [\ \fB\-\-rport\fR\ \fIport\fR\ ]
258 [\ \fB\-\-script\-security\fR\ \fIlevel\fR\ ]
259 [\ \fB\-\-secret\fR\ \fIfile\ [direction]\fR\ ]
260 [\ \fB\-\-secret\fR\ \fIfile\fR\ ]
261 [\ \fB\-\-server\-bridge\fR\ \fIgateway\ netmask\ pool\-start\-IP\ pool\-end\-IP\fR\ ]
262 [\ \fB\-\-server\fR\ \fInetwork\ netmask\fR\ ]
263 [\ \fB\-\-service\fR\ \fIexit\-event\ [0|1]\fR\ ]
264 [\ \fB\-\-setenv\fR\ \fIname\ value\fR\ ]
265 [\ \fB\-\-setenv\-safe\fR\ \fIname\ value\fR\ ]
266 [\ \fB\-\-shaper\fR\ \fIn\fR\ ]
267 [\ \fB\-\-show\-adapters\fR\ ]
268 [\ \fB\-\-show\-ciphers\fR\ ]
269 [\ \fB\-\-show\-digests\fR\ ]
270 [\ \fB\-\-show\-engines\fR\ ]
271 [\ \fB\-\-show\-pkcs11\-ids\fR\ \fIprovider\ [cert_private]\fR\ ]
272 [\ \fB\-\-show\-net\-up\fR\ ]
273 [\ \fB\-\-show\-net\fR\ ]
274 [\ \fB\-\-show\-tls\fR\ ]
275 [\ \fB\-\-show\-valid\-subnets\fR\ ]
276 [\ \fB\-\-single\-session\fR\ ]
277 [\ \fB\-\-sndbuf\fR\ \fIsize\fR\ ]
278 [\ \fB\-\-socks\-proxy\-retry\fR\ ]
279 [\ \fB\-\-socks\-proxy\fR\ \fIserver\ [port]\fR\ ]
280 [\ \fB\-\-status\fR\ \fIfile\ [n]\fR\ ]
281 [\ \fB\-\-status\-version\fR\ \fIn\fR\ ]
282 [\ \fB\-\-syslog\fR\ \fI[progname]\fR\ ]
283 [\ \fB\-\-tap\-sleep\fR\ \fIn\fR\ ]
284 [\ \fB\-\-tcp\-queue\-limit\fR\ \fIn\fR\ ]
285 [\ \fB\-\-test\-crypto\fR\ ]
286 [\ \fB\-\-tls\-auth\fR\ \fIfile\ [direction]\fR\ ]
287 [\ \fB\-\-tls\-cipher\fR\ \fIl\fR\ ]
288 [\ \fB\-\-tls\-client\fR\ ]
289 [\ \fB\-\-tls\-exit\fR\ ]
290 [\ \fB\-\-tls\-remote\fR\ \fIx509name\fR\ ]
291 [\ \fB\-\-tls\-server\fR\ ]
292 [\ \fB\-\-tls\-timeout\fR\ \fIn\fR\ ]
293 [\ \fB\-\-tls\-verify\fR\ \fIcmd\fR\ ]
294 [\ \fB\-\-tmp\-dir\fR\ \fIdir\fR\ ]
295 [\ \fB\-\-topology\fR\ \fImode\fR\ ]
296 [\ \fB\-\-tran\-window\fR\ \fIn\fR\ ]
297 [\ \fB\-\-tun\-ipv6\fR\ ]
298 [\ \fB\-\-tun\-mtu\-extra\fR\ \fIn\fR\ ]
299 [\ \fB\-\-tun\-mtu\fR\ \fIn\fR\ ]
300 [\ \fB\-\-txqueuelen\fR\ \fIn\fR\ ]
301 [\ \fB\-\-up\-delay\fR\ ]
302 [\ \fB\-\-up\-restart\fR\ ]
303 [\ \fB\-\-up\fR\ \fIcmd\fR\ ]
304 [\ \fB\-\-user\fR\ \fIuser\fR\ ]
305 [\ \fB\-\-username\-as\-common\-name\fR\ ]
306 [\ \fB\-\-verb\fR\ \fIn\fR\ ]
307 [\ \fB\-\-win\-sys\fR\ \fIpath|'env'\fR\ ]
308 [\ \fB\-\-writepid\fR\ \fIfile\fR\ ]
312 .\"*********************************************************
315 OpenVPN is an open source VPN daemon by James Yonan.
316 Because OpenVPN tries to
317 be a universal VPN tool offering a great deal of flexibility,
318 there are a lot of options on this manual page.
319 If you're new to OpenVPN, you might want to skip ahead to the
320 examples section where you will see how to construct simple
321 VPNs on the command line without even needing a configuration file.
323 Also note that there's more documentation and examples on
324 the OpenVPN web site:
325 .I http://openvpn.net/
327 And if you would like to see a shorter version of this manual,
328 see the openvpn usage message which can be obtained by
331 without any parameters.
332 .\"*********************************************************
335 OpenVPN is a robust and highly flexible VPN daemon.
336 OpenVPN supports SSL/TLS security, ethernet bridging,
337 TCP or UDP tunnel transport through proxies or NAT,
338 support for dynamic IP addresses and DHCP,
339 scalability to hundreds or thousands of users,
340 and portability to most major OS platforms.
342 OpenVPN is tightly bound to the OpenSSL library, and derives much
343 of its crypto capabilities from it.
346 conventional encryption
347 using a pre-shared secret key
352 using client & server certificates.
354 supports non-encrypted TCP/UDP tunnels.
356 OpenVPN is designed to work with the
358 virtual networking interface that exists on most platforms.
360 Overall, OpenVPN aims to offer many of the key features of IPSec but
361 with a relatively lightweight footprint.
362 .\"*********************************************************
364 OpenVPN allows any option to be placed either on the command line
365 or in a configuration file. Though all command line options are preceded
366 by a double-leading-dash ("--"), this prefix can be removed when
367 an option is placed in a configuration file.
368 .\"*********************************************************
372 .\"*********************************************************
375 Load additional config options from
377 where each line corresponds to one command line option,
378 but with the leading '--' removed.
382 is the only option to the openvpn command,
385 can be removed, and the command can be given as
389 configuration files can be nested to a reasonable depth.
391 Double quotation or single quotation characters ("", '')
392 can be used to enclose single parameters containing whitespace,
393 and "#" or ";" characters in the first column
394 can be used to denote comments.
396 Note that OpenVPN 2.0 and higher performs backslash-based shell
397 escaping for characters not in single quotations,
398 so the following mappings should be observed:
404 \\\\ Maps to a single backslash character (\\).
405 \\" Pass a literal doublequote character ("), don't
406 interpret it as enclosing a parameter.
407 \\[SPACE] Pass a literal space or tab character, don't
408 interpret it as a parameter delimiter.
414 For example on Windows, use double backslashes to
421 secret "c:\\\\OpenVPN\\\\secret.key"
427 For examples of configuration files,
429 .I http://openvpn.net/examples.html
431 Here is an example configuration file:
437 # Sample OpenVPN configuration file for
438 # using a pre-shared static key.
440 # '#' or ';' may be used to delimit comments.
442 # Use a dynamic tun device.
446 remote mypeer.mydomain
448 # 10.1.0.1 is our local VPN endpoint
449 # 10.1.0.2 is our remote VPN endpoint
450 ifconfig 10.1.0.1 10.1.0.2
452 # Our pre-shared static key
458 .\"*********************************************************
462 Set OpenVPN major mode. By default, OpenVPN runs in
463 point-to-point mode ("p2p"). OpenVPN 2.0 introduces
464 a new mode ("server") which implements a multi-client
466 .\"*********************************************************
469 Local host name or IP address for bind.
470 If specified, OpenVPN will bind to this address only.
471 If unspecified, OpenVPN will bind to all interfaces.
472 .\"*********************************************************
474 .B --remote host [port] [proto]
475 Remote host name or IP address. On the client, multiple
477 options may be specified for redundancy, each referring
478 to a different OpenVPN server. Specifying multiple
480 options for this purpose is a special case of the more
481 general connection-profile feature. See the
485 The OpenVPN client will try to connect to a server at
487 in the order specified by the list of
492 indicates the protocol to use when connecting with the
493 remote, and may be "tcp" or "udp".
495 The client will move on to the next host in the list,
496 in the event of connection failure.
497 Note that at any given time, the OpenVPN client
498 will at most be connected to
501 Note that since UDP is connectionless, connection failure
508 Note the following corner case: If you use multiple
510 options, AND you are dropping root privileges on
515 AND the client is running a non-Windows OS, if the client needs
516 to switch to a different server, and that server pushes
517 back different TUN/TAP or route settings, the client may lack
518 the necessary privileges to close and reopen the TUN/TAP interface.
519 This could cause the client to exit with a fatal error.
523 is unspecified, OpenVPN will listen
524 for packets from any IP address, but will not act on those packets unless
525 they pass all authentication tests. This requirement for authentication
526 is binding on all potential peers, even those from known and supposedly
527 trusted IP addresses (it is very easy to forge a source IP address on
530 When used in TCP mode,
532 will act as a filter, rejecting connections from any host which does
538 is a DNS name which resolves to multiple IP addresses,
540 chosen, providing a sort of basic load-balancing and
542 .\"*********************************************************
545 Define a client connection
546 profile. Client connection profiles are groups of OpenVPN options that
547 describe how to connect to a given OpenVPN server. Client connection
548 profiles are specified within an OpenVPN configuration file, and
549 each profile is bracketed by
554 An OpenVPN client will try each connection profile sequentially
555 until it achieves a successful connection.
558 can be used to initially "scramble" the connection
561 Here is an example of connection profile usage:
571 remote 198.19.34.56 1194 udp
575 remote 198.19.34.56 443 tcp
579 remote 198.19.34.56 443 tcp
580 http-proxy 192.168.0.8 8080
585 remote 198.19.36.99 443 tcp
586 http-proxy 192.168.0.8 8080
600 First we try to connect to a server at 198.19.34.56:1194 using UDP.
601 If that fails, we then try to connect to 198.19.34.56:443 using TCP.
602 If that also fails, then try connecting through an HTTP proxy at
603 192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to
604 connect through the same proxy to a server at 198.19.36.99:443
607 The following OpenVPN options may be used inside of
614 .B connect-retry-max,
618 .B http-proxy-option,
620 .B http-proxy-timeout,
629 .B socks-proxy-retry.
631 A defaulting mechanism exists for specifying options to apply to
634 profiles. If any of the above options (with the exception of
636 ) appear outside of a
638 block, but in a configuration file which has one or more
640 blocks, the option setting will be used as a default for
642 blocks which follow it in the configuration file.
644 For example, suppose the
646 option were placed in the sample configuration file above, near
647 the top of the file, before the first
649 block. The effect would be as if
655 .\"*********************************************************
660 address/ports are specified, or if connection profiles are being
661 used, initially randomize the order of the list
662 as a kind of basic load-balancing measure.
663 .\"*********************************************************
668 for communicating with remote host.
676 The default protocol is
684 should be specified on both peers.
686 For TCP operation, one peer must use
687 .B --proto tcp-server
688 and the other must use
689 .B --proto tcp-client.
692 will wait indefinitely for an incoming connection. A peer
695 will attempt to connect, and if that fails, will sleep for 5
696 seconds (adjustable via the
698 option) and try again infinite or up to N retries (adjustable via the
699 .B --connect-retry-max
700 option). Both TCP client and server will simulate
701 a SIGUSR1 restart signal if either side resets the connection.
703 OpenVPN is designed to operate optimally over UDP, but TCP capability is provided
704 for situations where UDP cannot be used.
705 In comparison with UDP, TCP will usually be
706 somewhat less efficient and less robust when used over unreliable or congested
709 This article outlines some of problems with tunneling IP over TCP:
711 .I http://sites.inka.de/sites/bigred/devel/tcp-tcp.html
713 There are certain cases, however, where using TCP may be advantageous from
714 a security and robustness perspective, such as tunneling non-IP or
715 application-level UDP protocols, or tunneling protocols which don't
716 possess a built-in reliability layer.
717 .\"*********************************************************
721 .B --proto tcp-client,
725 number of seconds to wait
726 between connection retries (default=5).
727 .\"*********************************************************
729 .B --connect-retry-max n
731 .B --proto tcp-client,
735 number of retries of connection attempt (default=infinite).
736 .\"*********************************************************
739 Try to sense HTTP or SOCKS proxy settings automatically.
740 If no settings are present, a direct connection will be attempted.
741 If both HTTP and SOCKS settings are present, HTTP will be preferred.
742 If the HTTP proxy server requires a password, it will be queried from
743 stdin or the management interface. If the underlying OS doesn't support an API for
744 returning proxy settings, a direct connection will be attempted.
745 Currently, only Windows clients support this option via the
746 InternetQueryOption API.
747 This option exists in OpenVPN 2.1 or higher.
748 .\"*********************************************************
750 .B --http-proxy server port [authfile|'auto'] [auth-method]
751 Connect to remote host through an HTTP proxy at address
755 If HTTP Proxy-Authenticate is required,
757 is a file containing a username and password on 2 lines, or
758 "stdin" to prompt from console.
761 should be one of "none", "basic", or "ntlm".
765 flag causes OpenVPN to automatically determine the
767 and query stdin or the management interface for
768 username/password credentials, if required. This flag
769 exists on OpenVPN 2.1 or higher.
770 .\"*********************************************************
772 .B --http-proxy-retry
773 Retry indefinitely on HTTP proxy errors. If an HTTP proxy error
774 occurs, simulate a SIGUSR1 reset.
775 .\"*********************************************************
777 .B --http-proxy-timeout n
781 .\"*********************************************************
783 .B --http-proxy-option type [parm]
784 Set extended HTTP proxy options.
785 Repeat to set multiple options.
787 .B VERSION version --
788 Set HTTP version number to
792 .B AGENT user-agent --
793 Set HTTP "User-Agent" string to
795 .\"*********************************************************
797 .B --socks-proxy server [port]
798 Connect to remote host through a Socks5 proxy at address
803 .\"*********************************************************
805 .B --socks-proxy-retry
806 Retry indefinitely on Socks proxy errors. If a Socks proxy error
807 occurs, simulate a SIGUSR1 reset.
808 .\"*********************************************************
811 If hostname resolve fails for
815 seconds before failing.
819 to "infinite" to retry indefinitely.
822 .B --resolv-retry infinite
823 is enabled. You can disable by setting n=0.
824 .\"*********************************************************
827 Allow remote peer to change its IP address and/or port number, such as due to
828 DHCP (this is the default if
834 allows an OpenVPN session to initially connect to a peer
835 at a known address, however if packets arrive from a new
836 address and pass all authentication tests, the new address
837 will take control of the session. This is useful when
838 you are connecting to a peer which holds a dynamic address
839 such as a dial-in user or DHCP client.
843 tells OpenVPN to accept authenticated packets
844 from any address, not only the address which was specified in the
847 .\"*********************************************************
850 Execute shell command
852 when our remote ip-address is initially authenticated or
857 .B cmd ip_address port_number
867 See the "Environmental Variables" section below for
868 additional parameters passed as environmental variables.
872 can be a shell command with multiple arguments, in which
873 case all OpenVPN-generated arguments will be appended
876 to build a command line which will be passed to the script.
878 If you are running in a dynamic IP address environment where
879 the IP addresses of either peer could change without notice,
880 you can use this script, for example, to edit the
882 file with the current address of the peer. The script will
883 be run every time the remote peer changes its IP address.
887 IP address changes due to DHCP, we should configure
888 our IP address change script (see man page for
894 signal to OpenVPN. OpenVPN will then
895 reestablish a connection with its most recently authenticated
896 peer on its new IP address.
897 .\"*********************************************************
900 TCP/UDP port number for both local and remote. The current
901 default of 1194 represents the official IANA port number
902 assignment for OpenVPN and has been used since version 2.0-beta17.
903 Previous versions used port 5000 as the default.
904 .\"*********************************************************
907 TCP/UDP port number for bind.
908 .\"*********************************************************
911 TCP/UDP port number for remote.
912 .\"*********************************************************
915 Bind to local address and port. This is the default unless any of
916 .B --proto tcp-client
922 .\"*********************************************************
925 Do not bind to local address and port. The IP stack will allocate
926 a dynamic port for returning packets. Since the value of the dynamic port
927 could not be known in advance by a peer, this option is only suitable for
928 peers which will be initiating connections by using the
931 .\"*********************************************************
933 .B --dev tunX | tapX | null
934 TUN/TAP virtual network device (
936 can be omitted for a dynamic device.)
938 See examples section below
939 for an example on setting up a TUN device.
941 You must use either tun devices on both ends of the connection
942 or tap devices on both ends. You cannot mix them, as they
943 represent different underlying protocols.
946 devices encapsulate IPv4 or IPv6 while
948 devices encapsulate Ethernet 802.3.
949 .\"*********************************************************
951 .B --dev-type device-type
952 Which device type are we using?
958 Use this option only if the TUN/TAP device used with
964 .\"*********************************************************
967 Configure virtual addressing topology when running in
969 mode. This directive has no meaning in
971 mode, which always uses a
975 If you set this directive on the server, the
979 directives will automatically push your chosen topology setting to clients
980 as well. This directive can also be manually pushed to clients. Like the
982 directive, this directive must always be compatible between client and server.
988 Use a point-to-point topology, by allocating one /30 subnet per client.
989 This is designed to allow point-to-point semantics when some
990 or all of the connecting clients might be Windows systems. This is the
991 default on OpenVPN 2.0.
994 Use a point-to-point topology where the remote endpoint of the client's
995 tun interface always points to the local endpoint of the server's tun interface.
996 This mode allocates a single IP address per connecting client.
998 when none of the connecting clients are Windows systems. This mode
999 is functionally equivalent to the
1000 .B --ifconfig-pool-linear
1001 directive which is available in OpenVPN 2.0 and is now deprecated.
1004 Use a subnet rather than a point-to-point topology by
1005 configuring the tun interface with a local IP address and subnet mask,
1006 similar to the topology used in
1008 and ethernet bridging mode.
1009 This mode allocates a single IP address per connecting client and works on
1010 Windows as well. Only available when server and clients are OpenVPN 2.1 or
1011 higher, or OpenVPN 2.0.x which has been manually patched with the
1013 directive code. When used on Windows, requires version 8.2 or higher
1014 of the TAP-Win32 driver. When used on *nix, requires that the tun
1017 command which sets a subnet instead of a remote endpoint IP address.
1019 This option exists in OpenVPN 2.1 or higher.
1020 .\"*********************************************************
1023 Build a tun link capable of forwarding IPv6 traffic.
1024 Should be used in conjunction with
1028 A warning will be displayed
1029 if no specific IPv6 TUN support for your OS has been compiled into OpenVPN.
1030 .\"*********************************************************
1033 Explicitly set the device node rather than using
1034 /dev/net/tun, /dev/tun, /dev/tap, etc. If OpenVPN
1035 cannot figure out whether
1037 is a TUN or TAP device based on the name, you should
1043 On Windows systems, select the TAP-Win32 adapter which
1046 in the Network Connections Control Panel or the
1047 raw GUID of the adapter enclosed by braces.
1050 option under Windows can also be used
1051 to enumerate all available TAP-Win32
1052 adapters and will show both the network
1053 connections control panel name and the GUID for
1054 each TAP-Win32 adapter.
1057 Specify the link layer address, more commonly known as the MAC address.
1058 Only applied to TAP devices.
1059 .\"*********************************************************
1062 Set alternate command to execute instead of default iproute2 command.
1063 May be used in order to execute OpenVPN in unprivileged environment.
1064 .\"*********************************************************
1067 Set TUN/TAP adapter parameters.
1069 is the IP address of the local VPN endpoint.
1072 is the IP address of the remote VPN endpoint.
1075 is the subnet mask of the virtual ethernet segment
1076 which is being created or connected to.
1078 For TUN devices, which facilitate virtual
1079 point-to-point IP connections,
1082 is to use two private IP addresses
1083 which are not a member of any
1084 existing subnet which is in use.
1085 The IP addresses may be consecutive
1086 and should have their order reversed
1087 on the remote peer. After the VPN
1088 is established, by pinging
1090 you will be pinging across the VPN.
1092 For TAP devices, which provide
1093 the ability to create virtual
1096 is used to set an IP address and
1097 subnet mask just as a physical
1098 ethernet adapter would be
1099 similarly configured. If you are
1100 attempting to connect to a remote
1101 ethernet bridge, the IP address
1102 and subnet should be set to values
1103 which would be valid on the
1104 the bridged ethernet segment (note
1105 also that DHCP can be used for the
1108 This option, while primarily a proxy for the
1110 command, is designed to simplify TUN/TAP
1111 tunnel configuration by providing a
1112 standard interface to the different
1113 ifconfig implementations on different
1117 parameters which are IP addresses can
1118 also be specified as a DNS or /etc/hosts
1119 file resolvable name.
1123 should not be used if the TAP interface will be
1124 getting an IP address lease from a DHCP
1126 .\"*********************************************************
1128 .B --ifconfig-noexec
1129 Don't actually execute ifconfig/netsh commands, instead
1132 parameters to scripts using environmental variables.
1133 .\"*********************************************************
1135 .B --ifconfig-nowarn
1136 Don't output an options consistency check warning
1139 option on this side of the
1140 connection doesn't match the remote side. This is useful
1141 when you want to retain the overall benefits of the
1142 options consistency check (also see
1144 option) while only disabling the ifconfig component of
1148 if you have a configuration where the local host uses
1150 but the remote host does not, use
1151 .B --ifconfig-nowarn
1154 This option will also silence warnings about potential
1155 address conflicts which occasionally annoy more experienced
1156 users by triggering "false positive" warnings.
1157 .\"*********************************************************
1159 .B --route network/IP [netmask] [gateway] [metric]
1160 Add route to routing table after connection is established.
1161 Multiple routes can be specified. Routes will be
1162 automatically torn down in reverse order prior to
1163 TUN/TAP device close.
1165 This option is intended as
1166 a convenience proxy for the
1169 while at the same time providing portable semantics
1170 across OpenVPN's platform space.
1173 default -- 255.255.255.255
1176 default -- taken from
1178 or the second parameter to
1185 default -- taken from
1189 The default can be specified by leaving an option blank or setting
1197 also be specified as a DNS or /etc/hosts
1198 file resolvable name, or as one of three special keywords:
1201 -- The remote VPN endpoint address
1202 (derived either from
1204 or the second parameter to
1211 -- The pre-existing IP default gateway, read from the routing
1212 table (not supported on all OSes).
1217 address if OpenVPN is being run in client mode, and is undefined in server mode.
1218 .\"*********************************************************
1220 .B --route-gateway gw|'dhcp'
1221 Specify a default gateway
1228 is specified as the parameter,
1229 the gateway address will be extracted from a DHCP
1230 negotiation with the OpenVPN server-side LAN.
1231 .\"*********************************************************
1234 Specify a default metric
1238 .\"*********************************************************
1240 .B --route-delay [n] [w]
1243 seconds (default=0) after connection
1244 establishment, before adding routes. If
1246 is 0, routes will be added immediately upon connection
1249 is omitted, routes will be added immediately after TUN/TAP device
1252 script execution, before any
1256 privilege downgrade (or
1260 This option is designed to be useful in scenarios where DHCP is
1262 tap adapter addresses. The delay will give the DHCP handshake
1263 time to complete before routes are added.
1267 tries to be more intelligent by waiting
1269 seconds (w=30 by default)
1270 for the TAP-Win32 adapter to come up before adding routes.
1271 .\"*********************************************************
1274 Execute shell command
1276 after routes are added, subject to
1279 See the "Environmental Variables" section below for
1280 additional parameters passed as environmental variables.
1284 can be a shell command with multiple arguments.
1285 .\"*********************************************************
1288 Don't add or remove routes automatically. Instead pass routes to
1290 script using environmental variables.
1291 .\"*********************************************************
1298 accept options pushed by server EXCEPT for routes.
1300 When used on the client, this option effectively bars the
1301 server from adding routes to the client's routing table,
1302 however note that this option still allows the server
1303 to set the TCP/IP properties of the client's TUN/TAP interface.
1304 .\"*********************************************************
1306 .B --allow-pull-fqdn
1307 Allow client to pull DNS names from server (rather than being limited
1313 .\"*********************************************************
1315 .B --redirect-gateway flags...
1316 (Experimental) Automatically execute routing commands to cause all outgoing IP traffic
1317 to be redirected over the VPN.
1319 This option performs three steps:
1322 Create a static route for the
1324 address which forwards to the pre-existing default gateway.
1325 This is done so that
1327 will not create a routing loop.
1330 Delete the default gateway route.
1333 Set the new default gateway to be the VPN endpoint address (derived either from
1335 or the second parameter to
1341 When the tunnel is torn down, all of the above steps are reversed so
1342 that the original default route is restored.
1349 flag if both OpenVPN servers are directly connected via a common subnet,
1350 such as with wireless. The
1352 flag will cause step
1354 above to be omitted.
1357 Use this flag to override
1358 the default gateway by using 0.0.0.0/1 and 128.0.0.0/1
1359 rather than 0.0.0.0/0. This has the benefit of overriding
1360 but not wiping out the original default gateway.
1363 Add a direct route to the DHCP server (if it is non-local) which
1365 (Available on Windows clients, may not be available
1366 on non-Windows clients).
1369 Add a direct route to the DNS server(s) (if they are non-local) which
1371 (Available on Windows clients, may not be available
1372 on non-Windows clients).
1374 Using the def1 flag is highly recommended.
1375 .\"*********************************************************
1378 Sets an upper bound on the size of UDP packets which are sent
1379 between OpenVPN peers. It's best not to set this parameter unless
1380 you know what you're doing.
1381 .\"*********************************************************
1384 Take the TUN device MTU to be
1386 and derive the link MTU
1387 from it (default=1500). In most cases, you will probably want to
1388 leave this parameter set to its default value.
1390 The MTU (Maximum Transmission Units) is
1391 the maximum datagram size in bytes that can be sent unfragmented
1392 over a particular network path. OpenVPN requires that packets
1393 on the control or data channels be sent unfragmented.
1395 MTU problems often manifest themselves as connections which
1396 hang during periods of active usage.
1398 It's best to use the
1402 options to deal with MTU sizing issues.
1403 .\"*********************************************************
1405 .B --tun-mtu-extra n
1406 Assume that the TUN/TAP device might return as many as
1410 size on read. This parameter defaults to 0, which is sufficient for
1411 most TUN devices. TAP devices may introduce additional overhead in excess
1412 of the MTU size, and a setting of 32 is the default when TAP devices are used.
1413 This parameter only controls internal OpenVPN buffer sizing,
1414 so there is no transmission overhead associated with using a larger value.
1415 .\"*********************************************************
1418 Should we do Path MTU discovery on TCP/UDP channel? Only supported on OSes such
1419 as Linux that supports the necessary system call to set.
1422 -- Never send DF (Don't Fragment) frames
1425 -- Use per-route hints
1428 -- Always DF (Don't Fragment)
1430 .\"*********************************************************
1433 To empirically measure MTU on connection startup,
1436 option to your configuration.
1437 OpenVPN will send ping packets of various sizes
1438 to the remote peer and measure the largest packets
1439 which were successfully received. The
1441 process normally takes about 3 minutes to complete.
1442 .\"*********************************************************
1445 Enable internal datagram fragmentation so
1446 that no UDP datagrams are sent which
1453 parameter is interpreted in the same way as the
1455 parameter, i.e. the UDP packet size after encapsulation
1456 overhead has been added in, but not including
1457 the UDP header itself.
1461 option only makes sense when you are using the UDP protocol (
1466 adds 4 bytes of overhead per datagram.
1470 option below for an important related option to
1473 It should also be noted that this option is not meant to replace
1474 UDP fragmentation at the IP stack level. It is only meant as a
1475 last resort when path MTU discovery is broken. Using this option
1476 is less efficient than fixing path MTU discovery for your IP link and
1477 using native IP fragmentation instead.
1479 Having said that, there are circumstances where using OpenVPN's
1480 internal fragmentation capability may be your only option, such
1481 as tunneling a UDP multicast stream which requires fragmentation.
1482 .\"*********************************************************
1485 Announce to TCP sessions running over the tunnel that they should limit
1486 their send packet sizes such that after OpenVPN has encapsulated them,
1487 the resulting UDP packet size that OpenVPN sends to its peer will not
1494 parameter is interpreted in the same way as the
1496 parameter, i.e. the UDP packet size after encapsulation
1497 overhead has been added in, but not including
1498 the UDP header itself.
1502 option only makes sense when you are using the UDP protocol
1503 for OpenVPN peer-to-peer communication, i.e.
1509 can be ideally used together, where
1511 will try to keep TCP from needing
1512 packet fragmentation in the first place,
1513 and if big packets come through anyhow
1514 (from protocols other than TCP),
1516 will internally fragment them.
1522 are designed to work around cases where Path MTU discovery
1523 is broken on the network path between OpenVPN peers.
1525 The usual symptom of such a breakdown is an OpenVPN
1526 connection which successfully starts, but then stalls
1527 during active usage.
1535 will take its default
1541 Therefore, one could lower the maximum UDP packet size
1542 to 1300 (a good first try for solving MTU-related
1543 connection problems) with the following options:
1545 .B --tun-mtu 1500 --fragment 1300 --mssfix
1546 .\"*********************************************************
1549 Set the TCP/UDP socket send buffer size.
1550 Currently defaults to 65536 bytes.
1551 .\"*********************************************************
1554 Set the TCP/UDP socket receive buffer size.
1555 Currently defaults to 65536 bytes.
1556 .\"*********************************************************
1558 .B --socket-flags flags...
1559 Apply the given flags to the OpenVPN transport socket.
1566 socket flag is useful in TCP mode, and causes the kernel
1567 to send tunnel packets immediately over the TCP connection without
1568 trying to group several smaller packets into a larger packet.
1569 This can result in a considerably improvement in latency.
1571 This option is pushable from server to client, and should be used
1572 on both client and server for maximum effect.
1573 .\"*********************************************************
1576 (Linux only) Set the TX queue length on the TUN/TAP interface.
1577 Currently defaults to 100.
1578 .\"*********************************************************
1581 Limit bandwidth of outgoing tunnel data to
1583 bytes per second on the TCP/UDP port.
1584 If you want to limit the bandwidth
1585 in both directions, use this option on both peers.
1587 OpenVPN uses the following algorithm to implement
1588 traffic shaping: Given a shaper rate of
1590 bytes per second, after a datagram write of
1592 bytes is queued on the TCP/UDP port, wait a minimum of
1594 seconds before queuing the next write.
1596 It should be noted that OpenVPN supports multiple
1597 tunnels between the same two peers, allowing you
1598 to construct full-speed and reduced bandwidth tunnels
1600 routing low-priority data such as off-site backups
1601 over the reduced bandwidth tunnel, and other data
1602 over the full-speed tunnel.
1604 Also note that for low bandwidth tunnels
1605 (under 1000 bytes per second), you should probably
1606 use lower MTU values as well (see above), otherwise
1607 the packet latency will grow so large as to trigger
1608 timeouts in the TLS layer and TCP connections running
1613 to be between 100 bytes/sec and 100 Mbytes/sec.
1614 .\"*********************************************************
1616 .B --inactive n [bytes]
1617 Causes OpenVPN to exit after
1619 seconds of inactivity on the TUN/TAP device. The time length
1620 of inactivity is measured since the last incoming tunnel packet.
1624 parameter is included,
1625 exit after n seconds of activity on tun/tap device
1626 produces a combined in/out byte count that is less than
1628 .\"*********************************************************
1631 Ping remote over the TCP/UDP control channel
1632 if no packets have been sent for at least
1636 on both peers to cause ping packets to be sent in both directions since
1637 OpenVPN ping packets are not echoed like IP ping packets).
1638 When used in one of OpenVPN's secure modes (where
1639 .B --secret, --tls-server,
1642 is specified), the ping packet
1643 will be cryptographically secure.
1645 This option has two intended uses:
1648 with stateful firewalls. The periodic ping will ensure that
1649 a stateful firewall rule which allows OpenVPN UDP packets to
1650 pass will not time out.
1652 (2) To provide a basis for the remote to test the existence
1653 of its peer using the
1656 .\"*********************************************************
1659 Causes OpenVPN to exit after
1661 seconds pass without reception of a ping
1662 or other packet from remote.
1663 This option can be combined with
1664 .B --inactive, --ping,
1667 to create a two-tiered inactivity disconnect.
1671 .B openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60
1673 when used on both peers will cause OpenVPN to exit within 60
1674 seconds if its peer disconnects, but will exit after one
1675 hour if no actual tunnel data is exchanged.
1676 .\"*********************************************************
1685 seconds pass without reception of a ping
1686 or other packet from remote.
1688 This option is useful in cases
1689 where the remote peer has a dynamic IP address and
1690 a low-TTL DNS name is used to track the IP address using
1692 .I http://dyndns.org/
1693 + a dynamic DNS client such
1697 If the peer cannot be reached, a restart will be triggered, causing
1698 the hostname used with
1700 to be re-resolved (if
1705 .B --ping-restart, --inactive,
1706 or any other type of internally generated signal will always be
1708 individual client instance objects, never to whole server itself.
1709 Note also in server mode that any internally generated signal
1710 which would normally cause a restart, will cause the deletion
1711 of the client instance object instead.
1715 parameter is set to 120 seconds by default. This default will
1716 hold until the client pulls a replacement value from the server, based on
1719 setting in the server configuration.
1720 To disable the 120 second default, set
1724 See the signals section below for more information
1728 Note that the behavior of
1730 can be modified by the
1731 .B --persist-tun, --persist-key, --persist-local-ip,
1733 .B --persist-remote-ip
1740 are mutually exclusive and cannot be used together.
1741 .\"*********************************************************
1744 A helper directive designed to simplify the expression of
1748 in server mode configurations.
1751 .B --keepalive 10 60
1762 push "ping-restart 60"
1770 .\"*********************************************************
1777 timer only if we have a remote address. Use this option if you are
1778 starting the daemon in listen mode (i.e. without an explicit
1780 peer), and you don't want to start clocking timeouts until a remote
1782 .\"*********************************************************
1785 Don't close and reopen TUN/TAP device or run up/down scripts
1793 is a restart signal similar to
1795 but which offers finer-grained control over
1797 .\"*********************************************************
1800 Don't re-read key files across
1805 This option can be combined with
1807 to allow restarts triggered by the
1810 Normally if you drop root privileges in OpenVPN,
1811 the daemon cannot be restarted since it will now be unable to re-read protected
1814 This option solves the problem by persisting keys across
1816 resets, so they don't need to be re-read.
1817 .\"*********************************************************
1819 .B --persist-local-ip
1820 Preserve initially resolved local IP address and port number
1826 .\"*********************************************************
1828 .B --persist-remote-ip
1829 Preserve most recently authenticated remote IP address and port number
1835 .\"*********************************************************
1838 Disable paging by calling the POSIX mlockall function.
1839 Requires that OpenVPN be initially run as root (though
1840 OpenVPN can subsequently downgrade its UID using the
1844 Using this option ensures that key material and tunnel
1845 data are never written to disk due to virtual
1846 memory paging operations which occur under most
1847 modern operating systems. It ensures that even if an
1848 attacker was able to crack the box running OpenVPN, he
1849 would not be able to scan the system swap file to
1850 recover previously used
1851 ephemeral keys, which are used for a period of time
1854 options (see below), then are discarded.
1859 is that it will reduce the amount of physical
1860 memory available to other applications.
1861 .\"*********************************************************
1864 Shell command to run after successful TUN/TAP device open
1867 UID change). The up script is useful for specifying route
1868 commands which route IP traffic destined for
1869 private subnets which exist at the other
1870 end of the VPN connection into the tunnel.
1876 .B cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [ init | restart ]
1882 .B cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [ init | restart ]
1884 See the "Environmental Variables" section below for
1885 additional parameters passed as environmental variables.
1889 can be a shell command with multiple arguments, in which
1890 case all OpenVPN-generated arguments will be appended
1893 to build a command line which will be passed to the shell.
1897 will run a script to add routes to the tunnel.
1899 Normally the up script is called after the TUN/TAP device is opened.
1900 In this context, the last command line parameter passed to the script
1905 option is also used, the up script will be called for restarts as
1906 well. A restart is considered to be a partial reinitialization
1907 of OpenVPN where the TUN/TAP instance is preserved (the
1909 option will enable such preservation). A restart
1910 can be generated by a SIGUSR1 signal, a
1912 timeout, or a connection reset when the TCP protocol is enabled
1915 option. If a restart occurs, and
1917 has been specified, the up script will be called with
1919 as the last parameter.
1921 The following standalone example shows how the
1923 script can be called in both an initialization and restart context.
1924 (NOTE: for security reasons, don't run the following example unless UDP port
1925 9999 is blocked by your firewall. Also, the example will run indefinitely,
1926 so you should abort with control-c).
1928 .B openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 --up 'echo up' --down 'echo down' --persist-tun --up-restart
1930 Note that OpenVPN also provides the
1932 option to automatically ifconfig the TUN device,
1933 eliminating the need to define an
1935 script, unless you also want to configure routes
1942 is also specified, OpenVPN will pass the ifconfig local
1943 and remote endpoints on the command line to the
1945 script so that they can be used to configure routes such as:
1947 .B route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
1948 .\"*********************************************************
1951 Delay TUN/TAP open and possible
1954 until after TCP/UDP connection establishment with peer.
1958 mode, this option normally requires the use of
1960 to allow connection initiation to be sensed in the absence
1961 of tunnel data, since UDP is a "connectionless" protocol.
1963 On Windows, this option will delay the TAP-Win32 media state
1964 transitioning to "connected" until connection establishment,
1965 i.e. the receipt of the first authenticated packet from the peer.
1966 .\"*********************************************************
1969 Shell command to run after TUN/TAP device close
1974 ). Called with the same parameters and environmental
1979 Note that if you reduce privileges by using
1985 script will also run at reduced privilege.
1986 .\"*********************************************************
1991 cmd/script before, rather than after, TUN/TAP close.
1992 .\"*********************************************************
1999 scripts to be called for restarts as well as initial program start.
2000 This option is described more fully above in the
2002 option documentation.
2003 .\"*********************************************************
2005 .B --setenv name value
2006 Set a custom environmental variable
2009 .\"*********************************************************
2011 .B --setenv-safe name value
2012 Set a custom environmental variable
2013 .B OPENVPN_name=value
2016 This directive is designed to be pushed by the server to clients,
2017 and the prepending of "OPENVPN_" to the environmental variable
2018 is a safety precaution to prevent a LD_PRELOAD style attack
2019 from a malicious or compromised server.
2020 .\"*********************************************************
2022 .B --script-security level
2023 This directive offers policy-level control over OpenVPN's usage of external programs
2024 and scripts. Lower values are more restrictive, higher values are more permissive. Settings for
2028 Strictly no calling of external programs.
2031 (Default) Only call built-in executables such as ifconfig, ip, route, or netsh.
2034 Allow calling of built-in executables and user-defined scripts.
2037 Allow passwords to be passed to scripts via environmental variables (potentially unsafe).
2038 .\"*********************************************************
2041 Don't output a warning message if option inconsistencies are detected between
2042 peers. An example of an option inconsistency would be where one peer uses
2044 while the other peer uses
2047 Use of this option is discouraged, but is provided as
2048 a temporary fix in situations where a recent version of OpenVPN must
2049 connect to an old version.
2050 .\"*********************************************************
2053 Change the user ID of the OpenVPN process to
2055 after initialization, dropping privileges in the process.
2056 This option is useful to protect the system
2057 in the event that some hostile party was able to gain control of
2058 an OpenVPN session. Though OpenVPN's security features make
2059 this unlikely, it is provided as a second line of defense.
2065 or somebody similarly unprivileged, the hostile party would be
2066 limited in what damage they could cause. Of course once
2067 you take away privileges, you cannot return them
2068 to an OpenVPN session. This means, for example, that if
2069 you want to reset an OpenVPN daemon with a
2072 (for example in response
2073 to a DHCP reset), you should make use of one or more of the
2075 options to ensure that OpenVPN doesn't need to execute any privileged
2076 operations in order to restart (such as re-reading key files
2080 .\"*********************************************************
2086 this option changes the group ID of the OpenVPN process to
2088 after initialization.
2089 .\"*********************************************************
2094 prior to reading any files such as
2095 configuration files, key files, scripts, etc.
2097 should be an absolute path, with a leading "/",
2098 and without any references
2099 to the current directory such as "." or "..".
2101 This option is useful when you are running
2104 mode, and you want to consolidate all of
2105 your OpenVPN control files in one location.
2106 .\"*********************************************************
2111 after initialization.
2113 essentially redefines
2116 level directory tree (/). OpenVPN will therefore
2117 be unable to access any files outside this tree.
2118 This can be desirable from a security standpoint.
2120 Since the chroot operation is delayed until after
2121 initialization, most OpenVPN options that reference
2122 files will operate in a pre-chroot context.
2126 parameter can point to an empty directory, however
2127 complications can result when scripts or restarts
2128 are executed after the chroot operation.
2129 .\"*********************************************************
2131 .B --daemon [progname]
2132 Become a daemon after all initialization functions are completed.
2133 This option will cause all message and error output to
2134 be sent to the syslog file (such as /var/log/messages),
2135 except for the output of shell scripts and
2137 which will go to /dev/null unless otherwise redirected.
2138 The syslog redirection occurs immediately at the point
2141 is parsed on the command line even though
2142 the daemonization point occurs later. If one of the
2144 options is present, it will supercede syslog
2149 parameter will cause OpenVPN to report its program name
2150 to the system logger as
2152 This can be useful in linking OpenVPN messages
2153 in the syslog file with specific tunnels.
2156 defaults to "openvpn".
2158 When OpenVPN is run with the
2160 option, it will try to delay daemonization until the majority of initialization
2161 functions which are capable of generating fatal errors are complete. This means
2162 that initialization scripts can test the return status of the
2163 openvpn command for a fairly reliable indication of whether the command
2164 has correctly initialized and entered the packet forwarding event loop.
2166 In OpenVPN, the vast majority of errors which occur after initialization are non-fatal.
2167 .\"*********************************************************
2169 .B --syslog [progname]
2170 Direct log output to system logger, but do not become a daemon.
2173 directive above for description of
2176 .\"*********************************************************
2179 Set the TOS field of the tunnel packet to what the payload's TOS is.
2180 .\"*********************************************************
2182 .B --inetd [wait|nowait] [progname]
2183 Use this option when OpenVPN is being run from the inetd or
2189 option must match what is specified in the inetd/xinetd
2192 mode can only be used with
2193 .B --proto tcp-server.
2198 mode can be used to instantiate the OpenVPN daemon as a classic TCP server,
2199 where client connection requests are serviced on a single
2200 port number. For additional information on this kind of configuration,
2201 see the OpenVPN FAQ:
2202 .I http://openvpn.net/faq.html#oneport
2204 This option precludes the use of
2205 .B --daemon, --local,
2208 Note that this option causes message and error output to be handled in the same
2211 option. The optional
2213 parameter is also handled exactly as in
2218 mode, each OpenVPN tunnel requires a separate TCP/UDP port and
2219 a separate inetd or xinetd entry. See the OpenVPN 1.x HOWTO for an example
2220 on using OpenVPN with xinetd:
2221 .I http://openvpn.net/1xhowto.html
2222 .\"*********************************************************
2225 Output logging messages to
2227 including output to stdout/stderr which
2228 is generated by called scripts.
2231 already exists it will be truncated.
2232 This option takes effect
2233 immediately when it is parsed in the command line
2234 and will supercede syslog output if
2239 This option is persistent over the entire course of
2240 an OpenVPN instantiation and will not be reset by SIGHUP,
2244 Note that on Windows, when OpenVPN is started as a service,
2245 logging occurs by default without the need to specify
2247 .\"*********************************************************
2249 .B --log-append file
2250 Append logging messages to
2254 does not exist, it will be created.
2255 This option behaves exactly like
2257 except that it appends to rather
2258 than truncating the log file.
2259 .\"*********************************************************
2261 .B --suppress-timestamps
2262 Avoid writing timestamps to log messages, even when they
2263 otherwise would be prepended. In particular, this applies to
2264 log messages sent to stdout.
2265 .\"*********************************************************
2268 Write OpenVPN's main process ID to
2270 .\"*********************************************************
2273 Change process priority after initialization
2276 greater than 0 is lower priority,
2278 less than zero is higher priority).
2279 .\"*********************************************************
2282 .\"Change priority of background TLS work thread. The TLS thread
2283 .\"feature is enabled when OpenVPN is built
2284 .\"with pthread support, and you are running OpenVPN
2285 .\"in TLS mode (i.e. with
2291 .\"Using a TLS thread offloads the CPU-intensive process of SSL/TLS-based
2292 .\"key exchange to a background thread so that it does not become
2293 .\"a latency bottleneck in the tunnel packet forwarding process.
2297 .\"is interpreted exactly as with the
2299 .\"option above, but in relation to the work thread rather
2300 .\"than the main thread.
2301 .\"*********************************************************
2304 (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding
2305 a call to poll/epoll/select prior to the write operation. The purpose
2306 of such a call would normally be to block until the device
2307 or socket is ready to accept the write. Such blocking is unnecessary
2308 on some platforms which don't support write blocking on UDP sockets
2309 or TUN/TAP devices. In such cases, one can optimize the event loop
2310 by avoiding the poll/epoll/select call, improving CPU efficiency
2313 This option can only be used on non-Windows systems, when
2315 is specified, and when
2318 .\"*********************************************************
2320 .B --echo [parms...]
2325 Designed to be used to send messages to a controlling application
2326 which is receiving the OpenVPN log output.
2327 .\"*********************************************************
2329 .B --remap-usr1 signal
2330 Control whether internally or externally
2331 generated SIGUSR1 signals are remapped to
2332 SIGHUP (restart without persisting state) or
2336 can be set to "SIGHUP" or "SIGTERM". By default, no remapping
2338 .\"*********************************************************
2341 Set output verbosity to
2343 (default=1). Each level shows all info from the previous levels.
2344 Level 3 is recommended if you want a good summary
2345 of what's happening without being swamped by output.
2348 No output except fatal errors.
2358 characters to the console for each packet read and write, uppercase is
2359 used for TCP/UDP packets and lowercase is used for TUN/TAP packets.
2362 Debug info range (see errlevel.h for additional
2363 information on debug levels).
2364 .\"*********************************************************
2366 .B --status file [n]
2367 Write operational status to
2373 Status can also be written to the syslog by sending a
2376 .\"*********************************************************
2378 .B --status-version [n]
2379 Choose the status file format version number. Currently
2381 can be 1 or 2 and defaults to 1.
2382 .\"*********************************************************
2387 consecutive messages in the same category. This is useful to
2388 limit repetitive logging of similar message types.
2389 .\"*********************************************************
2391 .B --comp-lzo [mode]
2392 Use fast LZO compression -- may add up to 1 byte per
2393 packet for incompressible data.
2395 may be "yes", "no", or "adaptive" (default).
2397 In a server mode setup, it is possible to selectively turn
2398 compression on or off for individual clients.
2400 First, make sure the client-side config file enables selective
2401 compression by having at least one
2405 This will turn off compression by default,
2406 but allow a future directive push from the server to
2407 dynamically change the
2408 on/off/adaptive setting.
2411 .B --client-config-dir
2412 file, specify the compression setting for the client,
2426 The first line sets the
2428 setting for the server
2429 side of the link, the second sets the client side.
2430 .\"*********************************************************
2433 When used in conjunction with
2435 this option will disable OpenVPN's adaptive compression algorithm.
2436 Normally, adaptive compression is enabled with
2439 Adaptive compression tries to optimize the case where you have
2440 compression enabled, but you are sending predominantly uncompressible
2441 (or pre-compressed) packets over the tunnel, such as an FTP or rsync transfer
2442 of a large, compressed file. With adaptive compression,
2443 OpenVPN will periodically sample the compression process to measure its
2444 efficiency. If the data being sent over the tunnel is already compressed,
2445 the compression efficiency will be very low, triggering openvpn to disable
2446 compression for a period of time until the next re-sample test.
2447 .\"*********************************************************
2449 .B --management IP port [pw-file]
2450 Enable a TCP server on
2452 to handle daemon management functions.
2455 is a password file (password on first line)
2456 or "stdin" to prompt from standard input. The password
2457 provided will set the password which TCP clients will need
2458 to provide in order to access management functions.
2460 The management interface can also listen on a unix domain socket,
2461 for those platforms that support it. To use a unix domain socket, specify
2462 the unix socket pathname in place of
2466 to 'unix'. While the default behavior is to create a unix domain socket
2467 that may be connected to by any process, the
2468 .B --management-client-user
2470 .B --management-client-group
2471 directives can be used to restrict access.
2473 The management interface provides a special mode where the TCP
2474 management link can operate over the tunnel itself. To enable this mode,
2477 = "tunnel". Tunnel mode will cause the management interface
2478 to listen for a TCP connection on the local VPN address of the
2481 While the management port is designed for programmatic control
2482 of OpenVPN by other applications, it is possible to telnet
2483 to the port, using a telnet client in "raw" mode. Once connected,
2484 type "help" for a list of commands.
2486 For detailed documentation on the management interface, see
2487 the management-notes.txt file in the
2490 the OpenVPN source distribution.
2492 It is strongly recommended that
2495 (localhost) to restrict accessibility of the management
2496 server to local clients.
2497 .\"*********************************************************
2499 .B --management-query-passwords
2500 Query management channel for private key password and
2502 username/password. Only query the management channel
2503 for inputs which ordinarily would have been queried from the
2505 .\"*********************************************************
2507 .B --management-forget-disconnect
2508 Make OpenVPN forget passwords when management session
2511 This directive does not affect the
2513 username/password. It is always cached.
2514 .\"*********************************************************
2516 .B --management-hold
2517 Start OpenVPN in a hibernating state, until a client
2518 of the management interface explicitly starts it
2522 .\"*********************************************************
2524 .B --management-signal
2525 Send SIGUSR1 signal to OpenVPN if management session disconnects.
2526 This is useful when you wish to disconnect an OpenVPN session on
2528 .\"*********************************************************
2530 .B --management-log-cache n
2531 Cache the most recent
2533 lines of log file history for usage
2534 by the management channel.
2535 .\"*********************************************************
2537 .B --management-client-auth
2538 Gives management interface client the responsibility
2539 to authenticate clients after their client certificate
2540 has been verified. See management-notes.txt in OpenVPN
2541 distribution for detailed notes.
2542 .\"*********************************************************
2544 .B --management-client-pf
2545 Management interface clients must specify a packet
2546 filter file for each connecting client. See management-notes.txt
2547 in OpenVPN distribution for detailed notes.
2548 .\"*********************************************************
2550 .B --management-client-user u
2551 When the management interface is listening on a unix domain socket,
2552 only allow connections from user
2554 .\"*********************************************************
2556 .B --management-client-group g
2557 When the management interface is listening on a unix domain socket,
2558 only allow connections from group
2560 .\"*********************************************************
2562 .B --plugin module-pathname [init-string]
2563 Load plug-in module from the file
2568 to the module initialization function. Multiple
2569 plugin modules may be loaded into one OpenVPN
2572 For more information and examples on how to build OpenVPN
2573 plug-in modules, see the README file in the
2575 folder of the OpenVPN source distribution.
2577 If you are using an RPM install of OpenVPN, see
2578 /usr/share/openvpn/plugin. The documentation is
2581 and the actual plugin modules are in
2584 Multiple plugin modules can be cascaded, and modules can be
2585 used in tandem with scripts. The modules will be called by
2586 OpenVPN in the order that they are declared in the config
2587 file. If both a plugin and script are configured for the same
2588 callback, the script will be called last. If the
2589 return code of the module/script controls an authentication
2590 function (such as tls-verify, auth-user-pass-verify, or
2591 client-connect), then
2592 every module and script must return success (0) in order for
2593 the connection to be authenticated.
2594 .\"*********************************************************
2596 Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode
2597 is supported, and can be enabled with the
2599 option. In server mode, OpenVPN will listen on a single
2600 port for incoming client connections. All client
2601 connections will be routed through a single tun or tap
2602 interface. This mode is designed for scalability and should
2603 be able to support hundreds or even thousands of clients
2604 on sufficiently fast hardware. SSL/TLS authentication must
2605 be used in this mode.
2606 .\"*********************************************************
2608 .B --server network netmask
2609 A helper directive designed to simplify the configuration
2610 of OpenVPN's server mode. This directive will set up an
2611 OpenVPN server which will allocate addresses to clients
2612 out of the given network/netmask. The server itself
2613 will take the ".1" address of the given network
2614 for use as the server-side endpoint of the local
2618 .B --server 10.8.0.0 255.255.255.0
2627 push "topology [topology]"
2629 if dev tun AND (topology == net30 OR topology == p2p):
2630 ifconfig 10.8.0.1 10.8.0.2
2631 ifconfig-pool 10.8.0.4 10.8.0.251
2632 route 10.8.0.0 255.255.255.0
2633 if client-to-client:
2634 push "route 10.8.0.0 255.255.255.0"
2635 else if topology == net30:
2636 push "route 10.8.0.1"
2638 if dev tap OR (dev tun AND topology == subnet):
2639 ifconfig 10.8.0.1 255.255.255.0
2640 ifconfig-pool 10.8.0.2 10.8.0.254 255.255.255.0
2641 push "route-gateway 10.8.0.1"
2649 if you are ethernet bridging. Use
2652 .\"*********************************************************
2654 .B --server-bridge [ gateway netmask pool-start-IP pool-end-IP ]
2656 A helper directive similar to
2658 which is designed to simplify the configuration
2659 of OpenVPN's server mode in ethernet bridging configurations.
2663 is used without any parameters, it will enable a DHCP-proxy
2664 mode, where connecting OpenVPN clients will receive an IP
2665 address for their TAP adapter from the DHCP server running
2666 on the OpenVPN server-side LAN.
2667 Note that only clients that support
2668 the binding of a DHCP client with the TAP adapter (such as
2669 Windows) can support this mode.
2671 To configure ethernet bridging, you
2672 must first use your OS's bridging capability
2673 to bridge the TAP interface with the ethernet
2674 NIC interface. For example, on Linux this is done
2677 tool, and with Windows XP it is done in the Network
2678 Connections Panel by selecting the ethernet and
2679 TAP adapters and right-clicking on "Bridge Connections".
2681 Next you you must manually set the
2682 IP/netmask on the bridge interface. The
2688 can be set to either the IP/netmask of the
2689 bridge interface, or the IP/netmask of the
2690 default gateway/router on the bridged
2693 Finally, set aside a IP range in the bridged
2699 for OpenVPN to allocate to connecting
2703 .B server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 10.8.0.254
2713 ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0
2714 push "route-gateway 10.8.0.4"
2722 (without parameters) expands as follows:
2731 push "route-gateway dhcp"
2736 .\"*********************************************************
2739 Push a config file option back to the client for remote
2740 execution. Note that
2743 must be enclosed in double quotes (""). The client must specify
2745 in its config file. The set of options which can be
2746 pushed is limited by both feasibility and security.
2747 Some options such as those which would execute scripts
2748 are banned, since they would effectively allow a compromised
2749 server to execute arbitrary code on the client.
2750 Other options such as TLS or MTU parameters
2751 cannot be pushed because the client needs to know
2752 them before the connection to the server can be initiated.
2754 This is a partial list of options which can currently be pushed:
2755 .B --route, --route-gateway, --route-delay, --redirect-gateway,
2756 .B --ip-win32, --dhcp-option,
2757 .B --inactive, --ping, --ping-exit, --ping-restart,
2759 .B --persist-key, --persist-tun, --echo,
2762 .B --sndbuf, --rcvbuf
2763 .\"*********************************************************
2766 Don't inherit the global push list for a specific client instance.
2767 Specify this option in a client-specific context such
2769 .B --client-config-dir
2770 configuration file. This option will ignore
2772 options at the global config file level.
2773 .\"*********************************************************
2776 Disable a particular client (based on the common name)
2777 from connecting. Don't use this option to disable a client
2778 due to key or password compromise. Use a CRL (certificate
2779 revocation list) instead (see the
2783 This option must be associated with a specific client instance,
2784 which means that it must be specified either in a client
2785 instance config file using
2786 .B --client-config-dir
2787 or dynamically generated using a
2790 .\"*********************************************************
2792 .B --ifconfig-pool start-IP end-IP [netmask]
2793 Set aside a pool of subnets to be
2794 dynamically allocated to connecting clients, similar
2795 to a DHCP server. For tun-style
2796 tunnels, each client will be given a /30 subnet (for
2797 interoperability with Windows clients). For tap-style
2798 tunnels, individual addresses will be allocated, and the
2801 parameter will also be pushed to clients.
2803 .\"*********************************************************
2805 .B --ifconfig-pool-persist file [seconds]
2806 Persist/unpersist ifconfig-pool
2811 intervals (default=600), as well as on program startup and
2814 The goal of this option is to provide a long-term association
2815 between clients (denoted by their common name) and the virtual
2816 IP address assigned to them from the ifconfig-pool.
2817 Maintaining a long-term
2818 association is good for clients because it allows them
2819 to effectively use the
2824 is a comma-delimited ASCII file, formatted as
2825 <Common-Name>,<IP-address>.
2831 will be treated as read-only. This is useful if
2832 you would like to treat
2834 as a configuration file.
2836 Note that the entries in this file are treated by OpenVPN as
2837 suggestions only, based on past associations between
2838 a common name and IP address. They do not guarantee that the given common
2839 name will always receive the given IP address. If you want guaranteed
2842 .\"*********************************************************
2844 .B --ifconfig-pool-linear
2848 allocate individual TUN interface addresses for
2849 clients rather than /30 subnets. NOTE: This option
2850 is incompatible with Windows clients.
2852 This option is deprecated, and should be replaced with
2854 which is functionally equivalent.
2855 .\"*********************************************************
2857 .B --ifconfig-push local remote-netmask
2858 Push virtual IP endpoints for client tunnel,
2859 overriding the --ifconfig-pool dynamic allocation.
2865 are set according to the
2867 directive which you want to execute on the client machine to
2868 configure the remote end of the tunnel. Note that the parameters
2872 are from the perspective of the client, not the server. They may be
2873 DNS names rather than IP addresses, in which case they will be resolved
2874 on the server at the time of client connection.
2876 This option must be associated with a specific client instance,
2877 which means that it must be specified either in a client
2878 instance config file using
2879 .B --client-config-dir
2880 or dynamically generated using a
2884 Remember also to include a
2886 directive in the main OpenVPN config file which encloses
2888 so that the kernel will know to route it
2889 to the server's TUN/TAP interface.
2891 OpenVPN's internal client IP address selection algorithm works as
2896 .B --client-connect script
2897 generated file for static IP (first choice).
2901 .B --client-config-dir
2902 file for static IP (next choice).
2907 allocation for dynamic IP (last choice).
2909 .\"*********************************************************
2911 .B --iroute network [netmask]
2912 Generate an internal route to a specific
2915 parameter, if omitted, defaults to 255.255.255.255.
2917 This directive can be used to route a fixed subnet from
2918 the server to a particular client, regardless
2919 of where the client is connecting from. Remember
2920 that you must also add the route to the system
2921 routing table as well (such as by using the
2923 directive). The reason why two routes are needed
2926 directive routes the packet from the kernel
2927 to OpenVPN. Once in OpenVPN, the
2929 directive routes to the specific client.
2931 This option must be specified either in a client
2932 instance config file using
2933 .B --client-config-dir
2934 or dynamically generated using a
2940 directive also has an important interaction with
2944 essentially defines a subnet which is owned by a
2945 particular client (we will call this client A).
2946 If you would like other clients to be able to reach A's
2951 .B --client-to-client
2952 to effect this. In order for all clients to see
2953 A's subnet, OpenVPN must push this route to all clients
2954 EXCEPT for A, since the subnet is already owned by A.
2955 OpenVPN accomplishes this by not
2956 not pushing a route to a client
2957 if it matches one of the client's iroutes.
2958 .\"*********************************************************
2960 .B --client-to-client
2961 Because the OpenVPN server mode handles multiple clients
2962 through a single tun or tap interface, it is effectively
2964 .B --client-to-client
2965 flag tells OpenVPN to internally route client-to-client
2966 traffic rather than pushing all client-originating traffic
2967 to the TUN/TAP interface.
2969 When this option is used, each client will "see" the other
2970 clients which are currently connected. Otherwise, each
2971 client will only see the server. Don't use this option
2972 if you want to firewall tunnel traffic using
2973 custom, per-client rules.
2974 .\"*********************************************************
2977 Allow multiple clients with the same common name to concurrently connect.
2978 In the absence of this option, OpenVPN will disconnect a client instance
2979 upon connection of a new client having the same common name.
2980 .\"*********************************************************
2982 .B --client-connect script
2985 on client connection. The script is passed the common name
2986 and IP address of the just-authenticated client
2987 as environmental variables (see environmental variable section
2988 below). The script is also passed
2989 the pathname of a not-yet-created temporary file as $1
2990 (i.e. the first command line argument), to be used by the script
2991 to pass dynamically generated config file directives back to OpenVPN.
2993 If the script wants to generate a dynamic config file
2994 to be applied on the server when the client connects,
2995 it should write it to the file named by $1.
2998 .B --client-config-dir
2999 option below for options which
3000 can be legally used in a dynamically generated config file.
3002 Note that the return value of
3006 returns a non-zero error status, it will cause the client
3008 .\"*********************************************************
3010 .B --client-disconnect
3013 but called on client instance shutdown. Will not be called
3016 script and plugins (if defined)
3017 were previously called on this instance with
3018 successful (0) status returns.
3020 The exception to this rule is if the
3021 .B --client-disconnect
3022 script or plugins are cascaded, and at least one client-connect
3023 function succeeded, then ALL of the client-disconnect functions for
3024 scripts and plugins will be called on client instance object deletion,
3025 even in cases where some of the related client-connect functions returned
3028 .\"*********************************************************
3030 .B --client-config-dir dir
3033 for custom client config files. After
3034 a connecting client has been authenticated, OpenVPN will
3035 look in this directory for a file having the same name
3036 as the client's X509 common name. If a matching file
3037 exists, it will be opened and parsed for client-specific
3038 configuration options. If no matching file is found, OpenVPN
3039 will instead try to open and parse a default file called
3040 "DEFAULT", which may be provided but is not required.
3042 This file can specify a fixed IP address for a given
3045 as well as fixed subnets owned by the client using
3048 One of the useful properties of this option is that it
3049 allows client configuration files to be conveniently
3050 created, edited, or removed while the server is live,
3051 without needing to restart the server.
3054 options are legal in a client-specific context:
3055 .B --push, --push-reset, --iroute, --ifconfig-push,
3058 .\"*********************************************************
3062 condition of authentication, that a connecting client has a
3063 .B --client-config-dir
3065 .\"*********************************************************
3070 for temporary files. This directory will be used by
3072 scripts to dynamically generate client-specific
3073 configuration files.
3074 .\"*********************************************************
3077 Set the size of the real address hash table to
3079 and the virtual address table to
3081 By default, both tables are sized at 256 buckets.
3082 .\"*********************************************************
3084 .B --bcast-buffers n
3087 buffers for broadcast datagrams (default=256).
3088 .\"*********************************************************
3090 .B --tcp-queue-limit n
3091 Maximum number of output packets queued before TCP (default=64).
3093 When OpenVPN is tunneling data from a TUN/TAP device to a
3094 remote client over a TCP connection, it is possible that the TUN/TAP device
3095 might produce data at a faster rate than the TCP connection
3096 can support. When the number of output packets queued before sending to
3097 the TCP socket reaches this limit for a given client connection,
3098 OpenVPN will start to drop outgoing packets directed
3100 .\"*********************************************************
3103 Limit server to a maximum of
3106 .\"*********************************************************
3108 .B --max-routes-per-client n
3111 internal routes per client (default=256).
3113 help contain DoS attacks where an authenticated client floods the
3114 server with packets appearing to come from many unique MAC addresses,
3115 forcing the server to deplete
3116 virtual memory as its internal routing table expands.
3117 This directive can be used in a
3118 .B --client-config-dir
3119 file or auto-generated by a
3121 script to override the global value for a particular client.
3124 directive affects OpenVPN's internal routing table, not the
3125 kernel routing table.
3126 .\"*********************************************************
3128 .B --connect-freq n sec
3133 seconds from clients. This is designed to contain DoS attacks which flood
3134 the server with connection requests using certificates which
3135 will ultimately fail to authenticate.
3137 This is an imperfect solution however, because in a real
3138 DoS scenario, legitimate connections might also be refused.
3140 For the best protection against DoS attacks in server mode,
3145 .\"*********************************************************
3147 .B --learn-address cmd
3148 Run script or shell command
3150 to validate client virtual addresses or routes.
3153 will be executed with 3 parameters:
3156 "add", "update", or "delete" based on whether or not
3157 the address is being added to, modified, or deleted from
3158 OpenVPN's internal routing table.
3161 The address being learned or unlearned. This can be
3162 an IPv4 address such as "198.162.10.14", an IPv4 subnet
3163 such as "198.162.10.0/24", or an ethernet MAC address (when
3165 is being used) such as "00:FF:01:02:03:04".
3167 .B [3] common name --
3168 The common name on the certificate associated with the
3169 client linked to this address. Only present for "add"
3170 or "update" operations, not "delete".
3172 On "add" or "update" methods, if the script returns
3173 a failure code (non-zero), OpenVPN will reject the address
3174 and will not modify its internal routing table.
3178 script will use the information provided above to set
3179 appropriate firewall entries on the VPN TUN/TAP interface.
3180 Since OpenVPN provides the association between virtual IP
3181 or MAC address and the client's authenticated common name,
3182 it allows a user-defined script to configure firewall access
3183 policies with regard to the client's high-level common name,
3184 rather than the low level client virtual addresses.
3185 .\"*********************************************************
3187 .B --auth-user-pass-verify script method
3188 Require the client to provide a username/password (possibly
3189 in addition to a client certificate) for authentication.
3191 OpenVPN will execute
3193 as a shell command to validate the username/password
3194 provided by the client.
3198 is set to "via-env", OpenVPN will call
3200 with the environmental variables
3204 set to the username/password strings provided by the client.
3205 Be aware that this method is insecure on some platforms which
3206 make the environment of a process publicly visible to other
3207 unprivileged processes.
3211 is set to "via-file", OpenVPN will write the username and
3212 password to the first two lines of a temporary file. The filename
3213 will be passed as an argument to
3215 and the file will be automatically deleted by OpenVPN after
3216 the script returns. The location of the temporary file is
3219 option, and will default to the current directory if unspecified.
3220 For security, consider setting
3222 to a volatile storage medium such as
3224 (if available) to prevent the username/password file from touching the hard drive.
3226 The script should examine the username
3228 returning a success exit code (0) if the
3229 client's authentication request is to be accepted, or a failure
3230 code (1) to reject the client.
3232 This directive is designed to enable a plugin-style interface
3233 for extending OpenVPN's authentication capabilities.
3235 To protect against a client passing a maliciously formed
3236 username or password string, the username string must
3237 consist only of these characters: alphanumeric, underbar
3238 ('_'), dash ('-'), dot ('.'), or at ('@'). The password
3239 string can consist of any printable characters except for
3240 CR or LF. Any illegal characters in either the username
3241 or password string will be converted to underbar ('_').
3243 Care must be taken by any user-defined scripts to avoid
3244 creating a security vulnerability in the way that these
3245 strings are handled. Never use these strings in such a way
3246 that they might be escaped or evaluated by a shell interpreter.
3248 For a sample script that performs PAM authentication, see
3249 .B sample-scripts/auth-pam.pl
3250 in the OpenVPN source distribution.
3251 .\"*********************************************************
3253 .B --client-cert-not-required
3254 Don't require client certificate, client will authenticate
3255 using username/password only. Be aware that using this directive
3256 is less secure than requiring certificates from all clients.
3258 If you use this directive, the
3259 entire responsibility of authentication will rest on your
3260 .B --auth-user-pass-verify
3261 script, so keep in mind that bugs in your script
3262 could potentially compromise the security of your VPN.
3264 If you don't use this directive, but you also specify an
3265 .B --auth-user-pass-verify
3266 script, then OpenVPN will perform double authentication. The
3267 client certificate verification AND the
3268 .B --auth-user-pass-verify
3269 script will need to succeed in order for a client to be
3270 authenticated and accepted onto the VPN.
3271 .\"*********************************************************
3273 .B --username-as-common-name
3275 .B --auth-user-pass-verify
3277 the authenticated username as the common name,
3278 rather than the common name from the client cert.
3279 .\"*********************************************************
3281 .B --port-share host port
3282 When run in TCP server mode, share the OpenVPN port with
3283 another application, such as an HTTPS server. If OpenVPN
3284 senses a connection to its port which is using a non-OpenVPN
3285 protocol, it will proxy the connection to the server at
3287 Currently only designed to work with HTTP/HTTPS,
3288 though it would be theoretically possible to extend to
3289 other protocols such as ssh.
3291 Not implemented on Windows.
3292 .\"*********************************************************
3294 Use client mode when connecting to an OpenVPN server
3296 .B --server, --server-bridge,
3299 in it's configuration.
3300 .\"*********************************************************
3303 A helper directive designed to simplify the configuration
3304 of OpenVPN's client mode. This directive is equivalent to:
3316 .\"*********************************************************
3319 This option must be used on a client which is connecting
3320 to a multi-client server. It indicates to OpenVPN that it
3321 should accept options pushed by the server, provided they
3322 are part of the legal set of pushable options (note that the
3324 option is implied by
3330 allows the server to push routes to the client, so you should
3335 in situations where you don't trust the server to have control
3336 over the client's routing table.
3337 .\"*********************************************************
3339 .B --auth-user-pass [up]
3340 Authenticate with server using username/password.
3342 is a file containing username/password on 2 lines (Note: OpenVPN
3343 will only read passwords from a file if it has been built
3344 with the --enable-password-save configure option, or on Windows
3345 by defining ENABLE_PASSWORD_SAVE in config-win32.h).
3349 is omitted, username/password will be prompted from the
3352 The server configuration must specify an
3353 .B --auth-user-pass-verify
3354 script to verify the username/password provided by
3356 .\"*********************************************************
3358 .B --auth-retry type
3359 Controls how OpenVPN responds to username/password verification
3360 errors such as the client-side response to an AUTH_FAILED message from the server
3361 or verification failure of the private key password.
3363 Normally used to prevent auth errors from being fatal
3364 on the client side, and to permit username/password requeries in case
3367 An AUTH_FAILED message is generated by the server if the client
3370 authentication, or if the server-side
3372 script returns an error status when the client
3379 Client will exit with a fatal error (this is the default).
3382 Client will retry the connection without requerying for an
3384 username/password. Use this option for unattended clients.
3387 Client will requery for an
3389 username/password and/or private key password before attempting a reconnection.
3391 Note that while this option cannot be pushed, it can be controlled
3392 from the management interface.
3393 .\"*********************************************************
3395 .B --explicit-exit-notify [n]
3396 In UDP client mode or point-to-point mode, send server/peer an exit notification
3397 if tunnel is restarted or OpenVPN process is exited. In client mode, on
3399 option will tell the server to immediately close its client instance object
3400 rather than waiting for a timeout. The
3402 parameter (default=1) controls the maximum number of retries that the client
3403 will attempt to resend the exit notification message.
3404 .\"*********************************************************
3405 .SS Data Channel Encryption Options:
3406 These options are meaningful for both Static & TLS-negotiated key modes
3407 (must be compatible between peers).
3408 .\"*********************************************************
3410 .B --secret file [direction]
3411 Enable Static Key encryption mode (non-TLS).
3412 Use pre-shared secret
3414 which was generated with
3419 parameter enables the use of 4 distinct keys
3420 (HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that
3421 each data flow direction has a different set of HMAC and cipher keys.
3422 This has a number of desirable security properties including
3423 eliminating certain kinds of DoS and message replay attacks.
3427 parameter is omitted, 2 keys are used bidirectionally, one for HMAC
3428 and the other for encryption/decryption.
3432 parameter should always be complementary on either side of the connection,
3433 i.e. one side should use "0" and the other should use "1", or both sides
3434 should omit it altogether.
3438 parameter requires that
3440 contains a 2048 bit key. While pre-1.5 versions of OpenVPN
3441 generate 1024 bit key files, any version of OpenVPN which
3444 parameter, will also support 2048 bit key file generation
3449 Static key encryption mode has certain advantages,
3450 the primary being ease of configuration.
3452 There are no certificates
3453 or certificate authorities or complicated negotiation handshakes and protocols.
3454 The only requirement is that you have a pre-existing secure channel with
3457 ) to initially copy the key. This requirement, along with the
3458 fact that your key never changes unless you manually generate a new one,
3459 makes it somewhat less secure than TLS mode (see below). If an attacker
3460 manages to steal your key, everything that was ever encrypted with
3461 it is compromised. Contrast that to the perfect forward secrecy features of
3462 TLS mode (using Diffie Hellman key exchange), where even if an attacker
3463 was able to steal your private key, he would gain no information to help
3464 him decrypt past sessions.
3466 Another advantageous aspect of Static Key encryption mode is that
3467 it is a handshake-free protocol
3468 without any distinguishing signature or feature
3469 (such as a header or protocol handshake sequence)
3470 that would mark the ciphertext packets as being
3471 generated by OpenVPN. Anyone eavesdropping on the wire
3473 but random-looking data.
3474 .\"*********************************************************
3477 Authenticate packets with HMAC using message
3483 HMAC is a commonly used message authentication algorithm (MAC) that uses
3484 a data string, a secure hash algorithm, and a key, to produce
3485 a digital signature.
3487 OpenVPN's usage of HMAC is to first encrypt a packet, then HMAC the resulting ciphertext.
3489 In static-key encryption mode, the HMAC key
3490 is included in the key file generated by
3492 In TLS mode, the HMAC key is dynamically generated and shared
3493 between peers via the TLS control channel. If OpenVPN receives a packet with
3494 a bad HMAC it will drop the packet.
3495 HMAC usually adds 16 or 20 bytes per packet.
3498 to disable authentication.
3500 For more information on HMAC see
3501 .I http://www.cs.ucsd.edu/users/mihir/papers/hmac.html
3502 .\"*********************************************************
3505 Encrypt packets with cipher algorithm
3509 an abbreviation for Blowfish in Cipher Block Chaining mode.
3510 Blowfish has the advantages of being fast, very secure, and allowing key sizes
3511 of up to 448 bits. Blowfish is designed to be used in situations where
3512 keys are changed infrequently.
3514 For more information on blowfish, see
3515 .I http://www.counterpane.com/blowfish.html
3517 To see other ciphers that are available with
3522 OpenVPN supports the CBC, CFB, and OFB cipher modes.
3526 to disable encryption.
3527 .\"*********************************************************
3530 Size of cipher key in bits (optional).
3531 If unspecified, defaults to cipher-specific default. The
3533 option (see below) shows all available OpenSSL ciphers,
3534 their default key sizes, and whether the key size can
3535 be changed. Use care in changing a cipher's default
3536 key size. Many ciphers have not been extensively
3537 cryptanalyzed with non-standard key lengths, and a
3538 larger key may offer no real guarantee of greater
3539 security, or may even reduce security.
3540 .\"*********************************************************
3542 .B --engine [engine-name]
3543 Enable OpenSSL hardware-based crypto engine functionality.
3548 use a specific crypto engine. Use the
3550 standalone option to list the crypto engines which are
3551 supported by OpenSSL.
3552 .\"*********************************************************
3555 Disable OpenVPN's protection against replay attacks.
3556 Don't use this option unless you are prepared to make
3557 a tradeoff of greater efficiency in exchange for less
3560 OpenVPN provides datagram replay protection by default.
3562 Replay protection is accomplished
3563 by tagging each outgoing datagram with an identifier
3564 that is guaranteed to be unique for the key being used.
3565 The peer that receives the datagram will check for
3566 the uniqueness of the identifier. If the identifier
3567 was already received in a previous datagram, OpenVPN
3568 will drop the packet. Replay protection is important
3569 to defeat attacks such as a SYN flood attack, where
3570 the attacker listens in the wire, intercepts a TCP
3571 SYN packet (identifying it by the context in which
3572 it occurs in relation to other packets), then floods
3573 the receiving peer with copies of this packet.
3575 OpenVPN's replay protection is implemented in slightly
3576 different ways, depending on the key management mode
3580 or when using an CFB or OFB mode cipher, OpenVPN uses a
3581 64 bit unique identifier that combines a time stamp with
3582 an incrementing sequence number.
3584 When using TLS mode for key exchange and a CBC cipher
3585 mode, OpenVPN uses only a 32 bit sequence number without
3586 a time stamp, since OpenVPN can guarantee the uniqueness
3587 of this value for each key. As in IPSec, if the sequence number is
3588 close to wrapping back to zero, OpenVPN will trigger
3591 To check for replays, OpenVPN uses
3596 .\"*********************************************************
3598 .B --replay-window n [t]
3599 Use a replay protection sliding-window of size
3601 and a time window of
3607 is 64 (the IPSec default) and
3611 This option is only relevant in UDP mode, i.e.
3616 option is specified.
3618 When OpenVPN tunnels IP packets over UDP, there is the possibility that
3619 packets might be dropped or delivered out of order. Because OpenVPN, like IPSec,
3620 is emulating the physical network layer,
3621 it will accept an out-of-order packet sequence, and
3622 will deliver such packets in the same order they were received to
3623 the TCP/IP protocol stack, provided they satisfy several constraints.
3626 The packet cannot be a replay (unless
3628 is specified, which disables replay protection altogether).
3631 If a packet arrives out of order, it will only be accepted if the difference
3632 between its sequence number and the highest sequence number received
3637 If a packet arrives out of order, it will only be accepted if it arrives no later
3640 seconds after any packet containing a higher sequence number.
3642 If you are using a network link with a large pipeline (meaning that
3643 the product of bandwidth and latency is high), you may want to use
3646 Satellite links in particular often require this.
3648 If you run OpenVPN at
3650 you will see the message "Replay-window backtrack occurred [x]"
3651 every time the maximum sequence number backtrack seen thus far
3652 increases. This can be used to calibrate
3655 There is some controversy on the appropriate method of handling packet
3656 reordering at the security layer.
3658 Namely, to what extent should the
3659 security layer protect the encapsulated protocol from attacks which masquerade
3660 as the kinds of normal packet loss and reordering that occur over IP networks?
3662 The IPSec and OpenVPN approach is to allow packet reordering within a certain
3663 fixed sequence number window.
3665 OpenVPN adds to the IPSec model by limiting the window size in time as well as
3668 OpenVPN also adds TCP transport as an option (not offered by IPSec) in which
3669 case OpenVPN can adopt a very strict attitude towards message deletion and
3670 reordering: Don't allow it. Since TCP guarantees reliability, any packet
3671 loss or reordering event can be assumed to be an attack.
3673 In this sense, it could be argued that TCP tunnel transport is preferred when
3674 tunneling non-IP or UDP application protocols which might be vulnerable to a
3675 message deletion or reordering attack which falls within the normal
3676 operational parameters of IP networks.
3678 So I would make the statement that one should never tunnel a non-IP protocol
3679 or UDP application protocol over UDP, if the protocol might be vulnerable to a
3680 message deletion or reordering attack that falls within the normal operating
3681 parameters of what is to be expected from the physical IP layer. The problem
3682 is easily fixed by simply using TCP as the VPN transport layer.
3683 .\"*********************************************************
3685 .B --mute-replay-warnings
3686 Silence the output of replay warnings, which are a common
3687 false alarm on WiFi networks. This option preserves
3688 the security of the replay protection code without
3689 the verbosity associated with warnings about duplicate
3691 .\"*********************************************************
3693 .B --replay-persist file
3694 Persist replay-protection state across sessions using
3696 to save and reload the state.
3698 This option will strengthen protection against replay attacks,
3699 especially when you are using OpenVPN in a dynamic context (such
3702 when OpenVPN sessions are frequently started and stopped.
3704 This option will keep a disk copy of the current replay protection
3705 state (i.e. the most recent packet timestamp and sequence number
3706 received from the remote peer), so that if an OpenVPN session
3707 is stopped and restarted, it will reject any replays of packets
3708 which were already received by the prior session.
3710 This option only makes sense when replay protection is enabled
3711 (the default) and you are using either
3713 (shared-secret key mode) or TLS mode with
3715 .\"*********************************************************
3718 Disable OpenVPN's use of IV (cipher initialization vector).
3719 Don't use this option unless you are prepared to make
3720 a tradeoff of greater efficiency in exchange for less
3723 OpenVPN uses an IV by default, and requires it for CFB and
3724 OFB cipher modes (which are totally insecure without it).
3725 Using an IV is important for security when multiple
3726 messages are being encrypted/decrypted with the same key.
3728 IV is implemented differently depending on the cipher mode used.
3730 In CBC mode, OpenVPN uses a pseudo-random IV for each packet.
3732 In CFB/OFB mode, OpenVPN uses a unique sequence number and time stamp
3733 as the IV. In fact, in CFB/OFB mode, OpenVPN uses a datagram
3734 space-saving optimization that uses the unique identifier for
3735 datagram replay protection as the IV.
3736 .\"*********************************************************
3739 Do a self-test of OpenVPN's crypto options by encrypting and
3740 decrypting test packets using the data channel encryption options
3741 specified above. This option does not require a peer to function,
3742 and therefore can be specified without
3747 The typical usage of
3749 would be something like this:
3751 .B openvpn --test-crypto --secret key
3755 .B openvpn --test-crypto --secret key --verb 9
3757 This option is very useful to test OpenVPN after it has been ported to
3758 a new platform, or to isolate problems in the compiler, OpenSSL
3759 crypto library, or OpenVPN's crypto code. Since it is a self-test mode,
3760 problems with encryption and authentication can be debugged independently
3761 of network and tunnel issues.
3762 .\"*********************************************************
3763 .SS TLS Mode Options:
3764 TLS mode is the most powerful crypto mode of OpenVPN in both security and flexibility.
3765 TLS mode works by establishing control and
3766 data channels which are multiplexed over a single TCP/UDP port. OpenVPN initiates
3767 a TLS session over the control channel and uses it to exchange cipher
3768 and HMAC keys to protect the data channel. TLS mode uses a robust reliability
3769 layer over the UDP connection for all control channel communication, while
3770 the data channel, over which encrypted tunnel data passes, is forwarded without
3771 any mediation. The result is the best of both worlds: a fast data channel
3772 that forwards over UDP with only the overhead of encrypt,
3773 decrypt, and HMAC functions,
3774 and a control channel that provides all of the security features of TLS,
3775 including certificate-based authentication and Diffie Hellman forward secrecy.
3777 To use TLS mode, each peer that runs OpenVPN should have its own local
3778 certificate/key pair (
3782 ), signed by the root certificate which is specified
3786 When two OpenVPN peers connect, each presents its local certificate to the
3787 other. Each peer will then check that its partner peer presented a
3788 certificate which was signed by the master root certificate as specified in
3791 If that check on both peers succeeds, then the TLS negotiation
3792 will succeed, both OpenVPN
3793 peers will exchange temporary session keys, and the tunnel will begin
3796 The OpenVPN distribution contains a set of scripts for
3797 managing RSA certificates & keys,
3802 The easy-rsa package is also rendered in web form here:
3803 .I http://openvpn.net/easyrsa.html
3804 .\"*********************************************************
3807 Enable TLS and assume server role during TLS handshake. Note that
3808 OpenVPN is designed as a peer-to-peer application. The designation
3809 of client or server is only for the purpose of negotiating the TLS
3811 .\"*********************************************************
3814 Enable TLS and assume client role during TLS handshake.
3815 .\"*********************************************************
3818 Certificate authority (CA) file in .pem format, also referred to as the
3820 certificate. This file can have multiple
3821 certificates in .pem format, concatenated together. You can construct your own
3822 certificate authority certificate and private key by using a command such as:
3824 .B openssl req -nodes -new -x509 -keyout ca.key -out ca.crt
3826 Then edit your openssl.cnf file and edit the
3828 variable to point to your new root certificate
3831 For testing purposes only, the OpenVPN distribution includes a sample
3832 CA certificate (ca.crt).
3833 Of course you should never use
3834 the test certificates and test keys distributed with OpenVPN in a
3835 production environment, since by virtue of the fact that
3836 they are distributed with OpenVPN, they are totally insecure.
3837 .\"*********************************************************
3840 File containing Diffie Hellman parameters
3841 in .pem format (required for
3845 .B openssl dhparam -out dh1024.pem 1024
3847 to generate your own, or use the existing dh1024.pem file
3848 included with the OpenVPN distribution. Diffie Hellman parameters
3849 may be considered public.
3850 .\"*********************************************************
3853 Local peer's signed certificate in .pem format -- must be signed
3854 by a certificate authority whose certificate is in
3856 Each peer in an OpenVPN link running in TLS mode should have its own
3857 certificate and private key file. In addition, each certificate should
3858 have been signed by the key of a certificate
3859 authority whose public key resides in the
3861 certificate authority file.
3862 You can easily make your own certificate authority (see above) or pay money
3863 to use a commercial service such as thawte.com (in which case you will be
3864 helping to finance the world's second space tourist :).
3865 To generate a certificate,
3866 you can use a command such as:
3868 .B openssl req -nodes -new -keyout mycert.key -out mycert.csr
3870 If your certificate authority private key lives on another machine, copy
3871 the certificate signing request (mycert.csr) to this other machine (this can
3872 be done over an insecure channel such as email). Now sign the certificate
3873 with a command such as:
3875 .B openssl ca -out mycert.crt -in mycert.csr
3877 Now copy the certificate (mycert.crt)
3878 back to the peer which initially generated the .csr file (this
3879 can be over a public medium).
3882 command reads the location of the certificate authority key from its
3883 configuration file such as
3884 .B /usr/share/ssl/openssl.cnf
3886 that for certificate authority functions, you must set up the files
3894 .\"*********************************************************
3897 Local peer's private key in .pem format. Use the private key which was generated
3898 when you built your peer's certificate (see
3901 .\"*********************************************************
3904 Specify a PKCS #12 file containing local private key,
3905 local certificate, and root CA certificate.
3906 This option can be used instead of
3910 .\"*********************************************************
3912 .B --pkcs11-cert-private [0|1]...
3913 Set if access to certificate object should be performed after login.
3914 Every provider has its own setting.
3915 .\"*********************************************************
3918 Specify the serialized certificate id to be used. The id can be gotten
3920 .B --show-pkcs11-ids
3922 .\"*********************************************************
3924 .B --pkcs11-id-management
3925 Acquire PKCS#11 id from management interface. In this case a NEED-STR 'pkcs11-id-request'
3926 real-time message will be triggered, application may use pkcs11-id-count command to
3927 retrieve available number of certificates, and pkcs11-id-get command to retrieve certificate
3928 id and certificate body.
3929 .\"*********************************************************
3931 .B --pkcs11-pin-cache seconds
3932 Specify how many seconds the PIN can be cached, the default is until the token is removed.
3933 .\"*********************************************************
3935 .B --pkcs11-protected-authentication [0|1]...
3936 Use PKCS#11 protected authentication path, useful for biometric and external
3938 Every provider has its own setting.
3939 .\"*********************************************************
3941 .B --pkcs11-providers provider...
3942 Specify a RSA Security Inc. PKCS #11 Cryptographic Token Interface (Cryptoki) providers
3944 This option can be used instead of
3948 .\"*********************************************************
3950 .B --pkcs11-private-mode mode...
3951 Specify which method to use in order to perform private key operations.
3952 A different mode can be specified for each provider.
3953 Mode is encoded as hex number, and can be a mask one of the following:
3956 (default) -- Try to determind automatically.
3962 -- Use sign recover.
3970 .\"*********************************************************
3972 .B --cryptoapicert select-string
3973 Load the certificate and private key from the
3974 Windows Certificate System Store (Windows Only).
3976 Use this option instead of
3982 it possible to use any smart card, supported by Windows, but also any
3983 kind of certificate, residing in the Cert Store, where you have access to
3984 the private key. This option has been tested with a couple of different
3985 smart cards (GemSAFE, Cryptoflex, and Swedish Post Office eID) on the
3986 client side, and also an imported PKCS12 software certificate on the
3989 To select a certificate, based on a substring search in the
3990 certificate's subject:
3993 "SUBJ:Peter Runestig"
3995 To select a certificate, based on certificate's thumbprint:
3998 "THUMB:f6 49 24 41 01 b4 ..."
4000 The thumbprint hex string can easily be copy-and-pasted from the Windows
4001 Certificate Store GUI.
4003 .\"*********************************************************
4006 Use data channel key negotiation method
4008 The key method must match on both sides of the connection.
4010 After OpenVPN negotiates a TLS session, a new set of keys
4011 for protecting the tunnel data channel is generated and
4012 exchanged over the TLS session.
4014 In method 1 (the default for OpenVPN 1.x), both sides generate
4015 random encrypt and HMAC-send keys which are forwarded to
4016 the other host over the TLS channel.
4018 In method 2, (the default for OpenVPN 2.0)
4019 the client generates a random key. Both client
4020 and server also generate some random seed material. All key source
4021 material is exchanged over the TLS channel. The actual
4022 keys are generated using the TLS PRF function, taking source
4023 entropy from both client and server. Method 2 is designed to
4024 closely parallel the key generation process used by TLS 1.0.
4026 Note that in TLS mode, two separate levels
4029 (1) The TLS connection is initially negotiated, with both sides
4030 of the connection producing certificates and verifying the certificate
4031 (or other authentication info provided) of
4034 parameter has no effect on this process.
4036 (2) After the TLS connection is established, the tunnel session keys are
4037 separately negotiated over the existing secure TLS channel. Here,
4039 determines the derivation of the tunnel session keys.
4040 .\"*********************************************************
4045 of allowable TLS ciphers delimited by a colon (":").
4046 If you require a high level of security,
4047 you may want to set this parameter manually, to prevent a
4048 version rollback attack where a man-in-the-middle attacker tries
4049 to force two peers to negotiate to the lowest level
4050 of security they both support.
4053 to see a list of supported TLS ciphers.
4054 .\"*********************************************************
4057 Packet retransmit timeout on TLS control channel
4058 if no acknowledgment from remote within
4060 seconds (default=2). When OpenVPN sends a control
4061 packet to its peer, it will expect to receive an
4062 acknowledgement within
4064 seconds or it will retransmit the packet, subject
4065 to a TCP-like exponential backoff algorithm. This parameter
4066 only applies to control channel packets. Data channel
4067 packets (which carry encrypted tunnel data) are never
4068 acknowledged, sequenced, or retransmitted by OpenVPN because
4069 the higher level network protocols running on top of the tunnel
4070 such as TCP expect this role to be left to them.
4071 .\"*********************************************************
4074 Renegotiate data channel key after
4076 bytes sent or received (disabled by default).
4077 OpenVPN allows the lifetime of a key
4078 to be expressed as a number of bytes encrypted/decrypted, a number of packets, or
4079 a number of seconds. A key renegotiation will be forced
4080 if any of these three criteria are met by either peer.
4081 .\"*********************************************************
4084 Renegotiate data channel key after
4086 packets sent and received (disabled by default).
4087 .\"*********************************************************
4090 Renegotiate data channel key after
4092 seconds (default=3600).
4094 When using dual-factor authentication, note that this default value may
4095 cause the end user to be challenged to reauthorize once per hour.
4097 Also, keep in mind that this option can be used on both the client and server,
4098 and whichever uses the lower value will be the one to trigger the renegotiation.
4099 A common mistake is to set
4101 to a higher value on either the client or server, while the other side of the connection
4102 is still using the default value of 3600 seconds, meaning that the renegotiation will
4103 still occur once per 3600 seconds. The solution is to increase --reneg-sec on both the
4104 client and server, or set it to 0 on one side of the connection (to disable), and to
4105 your chosen value on the other side.
4106 .\"*********************************************************
4109 Handshake Window -- the TLS-based key exchange must finalize within
4112 of handshake initiation by any peer (default = 60 seconds).
4113 If the handshake fails
4114 we will attempt to reset our connection with our peer and try again.
4115 Even in the event of handshake failure we will still use
4116 our expiring key for up to
4118 seconds to maintain continuity of transmission of tunnel
4120 .\"*********************************************************
4123 Transition window -- our old key can live this many seconds
4124 after a new a key renegotiation begins (default = 3600 seconds).
4125 This feature allows for a graceful transition from old to new
4126 key, and removes the key renegotiation sequence from the critical
4127 path of tunnel data forwarding.
4128 .\"*********************************************************
4131 After initially connecting to a remote peer, disallow any new connections.
4133 option means that a remote peer cannot connect, disconnect, and then
4136 If the daemon is reset by a signal or
4138 it will allow one new connection.
4145 to create a single dynamic session that will exit when finished.
4146 .\"*********************************************************
4149 Exit on TLS negotiation failure.
4150 .\"*********************************************************
4152 .B --tls-auth file [direction]
4153 Add an additional layer of HMAC authentication on top of the TLS
4154 control channel to protect against DoS attacks.
4158 enables a kind of "HMAC firewall" on OpenVPN's TCP/UDP port,
4159 where TLS control channel packets
4160 bearing an incorrect HMAC signature can be dropped immediately without
4164 (required) is a key file which can be in one of two formats:
4167 An OpenVPN static key file generated by
4174 A freeform passphrase file. In this case the HMAC key will
4175 be derived by taking a secure hash of this file, similar to
4182 OpenVPN will first try format (1), and if the file fails to parse as
4183 a static key file, format (2) will be used.
4187 option for more information on the optional
4192 is recommended when you are running OpenVPN in a mode where
4193 it is listening for packets from any IP address, such as when
4195 is not specified, or
4201 this feature is as follows. TLS requires a multi-packet exchange
4202 before it is able to authenticate a peer. During this time
4203 before authentication, OpenVPN is allocating resources (memory
4204 and CPU) to this potential peer. The potential peer is also
4205 exposing many parts of OpenVPN and the OpenSSL library to the packets
4206 it is sending. Most successful network attacks today seek
4207 to either exploit bugs in programs (such as buffer overflow attacks) or
4208 force a program to consume so many resources that it becomes unusable.
4209 Of course the first line of defense is always to produce clean,
4210 well-audited code. OpenVPN has been written with buffer overflow
4211 attack prevention as a top priority.
4212 But as history has shown, many of the most widely used
4213 network applications have, from time to time,
4214 fallen to buffer overflow attacks.
4216 So as a second line of defense, OpenVPN offers
4217 this special layer of authentication on top of the TLS control channel so that
4218 every packet on the control channel is authenticated by an
4219 HMAC signature and a unique ID for replay protection.
4220 This signature will also help protect against DoS (Denial of Service) attacks.
4221 An important rule of thumb in reducing vulnerability to DoS attacks is to
4222 minimize the amount of resources a potential, but as yet unauthenticated,
4223 client is able to consume.
4226 does this by signing every TLS control channel packet with an HMAC signature,
4227 including packets which are sent before the TLS level has had a chance
4228 to authenticate the peer.
4229 The result is that packets without
4230 the correct signature can be dropped immediately upon reception,
4231 before they have a chance to consume additional system resources
4232 such as by initiating a TLS handshake.
4234 can be strengthened by adding the
4236 option which will keep OpenVPN's replay protection state
4237 in a file so that it is not lost across restarts.
4239 It should be emphasized that this feature is optional and that the
4240 passphrase/key file used with
4242 gives a peer nothing more than the power to initiate a TLS
4243 handshake. It is not used to encrypt or authenticate any tunnel data.
4244 .\"*********************************************************
4247 Get certificate password from console or
4249 before we daemonize.
4252 security conscious, it is possible to protect your private key with
4253 a password. Of course this means that every time the OpenVPN
4254 daemon is started you must be there to type the password. The
4256 option allows you to start OpenVPN from the command line. It will
4257 query you for a password before it daemonizes. To protect a private
4258 key with a password you should omit the
4260 option when you use the
4262 command line tool to manage certificates and private keys.
4266 is specified, read the password from the first line of
4268 Keep in mind that storing your password in a file
4269 to a certain extent invalidates the extra security provided by
4270 using an encrypted key (Note: OpenVPN
4271 will only read passwords from a file if it has been built
4272 with the --enable-password-save configure option, or on Windows
4273 by defining ENABLE_PASSWORD_SAVE in config-win32.h).
4274 .\"*********************************************************
4281 username/passwords in virtual memory.
4283 If specified, this directive will cause OpenVPN to immediately
4284 forget username/password inputs after they are used. As a result,
4285 when OpenVPN needs a username/password, it will prompt for input
4286 from stdin, which may be multiple times during the duration of an
4289 This directive does not affect the
4291 username/password. It is always cached.
4292 .\"*********************************************************
4295 Execute shell command
4297 to verify the X509 name of a
4298 pending TLS connection that has otherwise passed all other
4299 tests of certification (except for revocation via
4301 directive; the revocation test occurs after the
4306 should return 0 to allow the TLS handshake to proceed, or 1 to fail.
4310 .B cmd certificate_depth X509_NAME_oneline
4312 This feature is useful if the peer you want to trust has a certificate
4313 which was signed by a certificate authority who also signed many
4314 other certificates, where you don't necessarily want to trust all of them,
4315 but rather be selective about which
4316 peer certificate you will accept. This feature allows you to write a script
4317 which will test the X509 name on a certificate and decide whether or
4318 not it should be accepted. For a simple perl script which will test
4319 the common name field on the certificate, see the file
4321 in the OpenVPN distribution.
4323 See the "Environmental Variables" section below for
4324 additional parameters passed as environmental variables.
4328 can be a shell command with multiple arguments, in which
4329 case all OpenVPN-generated arguments will be appended
4332 to build a command line which will be passed to the script.
4333 .\"*********************************************************
4335 .B --tls-remote name
4336 Accept connections only from a host with X509 name
4337 or common name equal to
4339 The remote host must also pass all other tests
4342 Name can also be a common name prefix, for example if you
4343 want a client to only accept connections to "Server-1",
4344 "Server-2", etc., you can simply use
4345 .B --tls-remote Server
4347 Using a common name prefix is a useful alternative to managing
4348 a CRL (Certificate Revocation List) on the client, since it allows the client
4349 to refuse all certificates except for those associated
4350 with designated servers.
4353 is a useful replacement for the
4355 option to verify the remote host, because
4360 .\"*********************************************************
4362 .B --ns-cert-type client|server
4363 Require that peer certificate was signed with an explicit
4365 designation of "client" or "server".
4367 This is a useful security option for clients, to ensure that
4368 the host they connect with is a designated server.
4370 See the easy-rsa/build-key-server script for an example
4371 of how to generate a certificate with the
4373 field set to "server".
4375 If the server certificate's nsCertType field is set
4376 to "server", then the clients can verify this with
4377 .B --ns-cert-type server.
4379 This is an important security precaution to protect against
4380 a man-in-the-middle attack where an authorized client
4381 attempts to connect to another client by impersonating the server.
4382 The attack is easily prevented by having clients verify
4383 the server certificate using any one of
4384 .B --ns-cert-type, --tls-remote,
4387 .\"*********************************************************
4389 .B --remote-cert-ku v...
4390 Require that peer certificate was signed with an explicit
4393 This is a useful security option for clients, to ensure that
4394 the host they connect to is a designated server.
4396 The key usage should be encoded in hex, more than one key
4397 usage can be specified.
4398 .\"*********************************************************
4400 .B --remote-cert-eku oid
4401 Require that peer certificate was signed with an explicit
4402 .B extended key usage.
4404 This is a useful security option for clients, to ensure that
4405 the host they connect to is a designated server.
4407 The extended key usage should be encoded in oid notation, or
4408 OpenSSL symbolic representation.
4409 .\"*********************************************************
4411 .B --remote-cert-tls client|server
4412 Require that peer certificate was signed with an explicit
4415 .B extended key usage
4416 based on RFC3280 TLS rules.
4418 This is a useful security option for clients, to ensure that
4419 the host they connect to is a designated server.
4422 .B --remote-cert-tls client
4423 option is equivalent to
4425 --remote-cert-ku 80 08 88 --remote-cert-eku "TLS Web Client Authentication"
4427 The key usage is digitalSignature and/or keyAgreement.
4430 .B --remote-cert-tls server
4431 option is equivalent to
4433 --remote-cert-ku a0 88 --remote-cert-eku "TLS Web Server Authentication"
4435 The key usage is digitalSignature and ( keyEncipherment or keyAgreement ).
4437 This is an important security precaution to protect against
4438 a man-in-the-middle attack where an authorized client
4439 attempts to connect to another client by impersonating the server.
4440 The attack is easily prevented by having clients verify
4441 the server certificate using any one of
4442 .B --remote-cert-tls, --tls-remote,
4445 .\"*********************************************************
4448 Check peer certificate against the file
4452 A CRL (certificate revocation list) is used when a particular key is
4453 compromised but when the overall PKI is still intact.
4455 Suppose you had a PKI consisting of a CA, root certificate, and a number of
4456 client certificates. Suppose a laptop computer containing a client key and
4457 certificate was stolen. By adding the stolen certificate to the CRL file,
4458 you could reject any connection which attempts to use it, while preserving the
4459 overall integrity of the PKI.
4461 The only time when it would be necessary to rebuild the entire PKI from scratch would be
4462 if the root certificate key itself was compromised.
4463 .\"*********************************************************
4464 .SS SSL Library information:
4465 .\"*********************************************************
4469 Show all cipher algorithms to use with the
4472 .\"*********************************************************
4476 Show all message digest algorithms to use with the
4479 .\"*********************************************************
4483 Show all TLS ciphers (TLS used only as a control channel). The TLS
4484 ciphers will be sorted from highest preference (most secure) to
4486 .\"*********************************************************
4490 Show currently available hardware-based crypto acceleration
4491 engines supported by the OpenSSL library.
4492 .\"*********************************************************
4493 .SS Generate a random key:
4494 Used only for non-TLS static key encryption mode.
4495 .\"*********************************************************
4499 Generate a random key to be used as a shared secret,
4502 option. This file must be shared with the
4503 peer over a pre-existing secure channel such as
4506 .\"*********************************************************
4511 .\"*********************************************************
4512 .SS TUN/TAP persistent tunnel config mode:
4513 Available with linux 2.4.7+. These options comprise a standalone mode
4514 of OpenVPN which can be used to create and delete persistent tunnels.
4515 .\"*********************************************************
4519 Create a persistent tunnel on platforms which support them such
4520 as Linux. Normally TUN/TAP tunnels exist only for
4521 the period of time that an application has them open. This option
4522 takes advantage of the TUN/TAP driver's ability to build persistent
4523 tunnels that live through multiple instantiations of OpenVPN and die
4524 only when they are deleted or the machine is rebooted.
4526 One of the advantages of persistent tunnels is that they eliminate the
4531 scripts to run the appropriate
4535 commands. These commands can be placed in the the same shell script
4536 which starts or terminates an OpenVPN session.
4538 Another advantage is that open connections through the TUN/TAP-based tunnel
4539 will not be reset if the OpenVPN peer restarts. This can be useful to
4540 provide uninterrupted connectivity through the tunnel in the event of a DHCP
4541 reset of the peer's public IP address (see the
4545 One disadvantage of persistent tunnels is that it is harder to automatically
4546 configure their MTU value (see
4552 On some platforms such as Windows, TAP-Win32 tunnels are persistent by
4554 .\"*********************************************************
4558 Remove a persistent tunnel.
4559 .\"*********************************************************
4561 .B --dev tunX | tapX
4563 .\"*********************************************************
4566 Optional user to be owner of this tunnel.
4567 .\"*********************************************************
4570 Optional group to be owner of this tunnel.
4571 .\"*********************************************************
4572 .SS Windows-Specific Options:
4573 .\"*********************************************************
4575 .B --win-sys path|'env'
4576 Set the Windows system directory pathname to use when looking for system
4581 By default, if this directive is
4582 not specified, the pathname will be set to "C:\\WINDOWS"
4586 indicates that the pathname should be read from the
4588 environmental variable.
4589 .\"*********************************************************
4591 .B --ip-win32 method
4594 on Windows, set the TAP-Win32 adapter
4595 IP address and netmask using
4597 Don't use this option unless you are also using
4601 Don't set the IP address or netmask automatically.
4602 Instead output a message
4603 to the console telling the user to configure the
4604 adapter manually and indicating the IP/netmask which
4605 OpenVPN expects the adapter to be set to.
4607 .B dynamic [offset] [lease-time] --
4608 Automatically set the IP address and netmask by replying to
4609 DHCP query messages generated by the kernel. This mode is
4610 probably the "cleanest" solution
4611 for setting the TCP/IP properties since it uses the well-known
4612 DHCP protocol. There are, however, two prerequisites for using
4613 this mode: (1) The TCP/IP properties for the TAP-Win32
4614 adapter must be set to "Obtain an IP address automatically," and
4615 (2) OpenVPN needs to claim an IP address in the subnet for use
4616 as the virtual DHCP server address. By default in
4619 take the normally unused first address in the subnet. For example,
4620 if your subnet is 192.168.4.0 netmask 255.255.255.0, then
4621 OpenVPN will take the IP address 192.168.4.0 to use as the
4622 virtual DHCP server address. In
4624 mode, OpenVPN will cause the DHCP server to masquerade as if it were
4625 coming from the remote endpoint. The optional offset parameter is
4626 an integer which is > -256 and < 256 and which defaults to 0.
4627 If offset is positive, the DHCP server will masquerade as the IP
4628 address at network address + offset.
4629 If offset is negative, the DHCP server will masquerade as the IP
4630 address at broadcast address + offset. The Windows
4632 command can be used to show what Windows thinks the DHCP server
4633 address is. OpenVPN will "claim" this address, so make sure to
4634 use a free address. Having said that, different OpenVPN instantiations,
4635 including different ends of the same connection, can share the same
4636 virtual DHCP server address. The
4638 parameter controls the lease time of the DHCP assignment given to
4639 the TAP-Win32 adapter, and is denoted in seconds.
4640 Normally a very long lease time is preferred
4641 because it prevents routes involving the TAP-Win32 adapter from
4642 being lost when the system goes to sleep. The default
4643 lease time is one year.
4646 Automatically set the IP address and netmask using
4647 the Windows command-line "netsh"
4648 command. This method appears to work correctly on
4649 Windows XP but not Windows 2000.
4652 Automatically set the IP address and netmask using the
4653 Windows IP Helper API. This approach
4654 does not have ideal semantics, though testing has indicated
4655 that it works okay in practice. If you use this option,
4656 it is best to leave the TCP/IP properties for the TAP-Win32
4657 adapter in their default state, i.e. "Obtain an IP address
4663 method initially and fail over to
4665 if the DHCP negotiation with the TAP-Win32 adapter does
4666 not succeed in 20 seconds. Such failures have been known
4667 to occur when certain third-party firewall packages installed
4668 on the client machine block the DHCP negotiation used by
4669 the TAP-Win32 adapter.
4672 failover occurs, the TAP-Win32 adapter
4673 TCP/IP properties will be reset from DHCP to static, and this
4674 will cause future OpenVPN startups using the
4678 immediately, rather than trying
4680 first. To "unstick" the
4684 run OpenVPN at least once using the
4686 mode to restore the TAP-Win32 adapter TCP/IP properties
4687 to a DHCP configuration.
4688 .\"*********************************************************
4693 to use for adding routes on Windows?
4696 (default) -- Try IP helper API first. If that fails, fall
4697 back to the route.exe shell command.
4700 -- Use IP helper API.
4703 -- Call the route.exe shell command.
4704 .\"*********************************************************
4706 .B --dhcp-option type [parm]
4707 Set extended TAP-Win32 TCP/IP properties, must
4709 .B --ip-win32 dynamic
4711 .B --ip-win32 adaptive.
4712 This option can be used to set additional TCP/IP properties
4713 on the TAP-Win32 adapter, and is particularly useful for
4714 configuring an OpenVPN client to access a Samba server
4718 Set Connection-specific DNS Suffix.
4721 Set primary domain name server address. Repeat
4722 this option to set secondary DNS server addresses.
4725 Set primary WINS server address (NetBIOS over TCP/IP Name Server).
4726 Repeat this option to set secondary WINS server addresses.
4729 Set primary NBDD server address (NetBIOS over TCP/IP Datagram Distribution Server)
4731 to set secondary NBDD server addresses.
4734 Set primary NTP server address (Network Time Protocol).
4736 to set secondary NTP server addresses.
4739 Set NetBIOS over TCP/IP Node type. Possible options:
4741 = b-node (broadcasts),
4743 = p-node (point-to-point
4744 name queries to a WINS server),
4747 then query name server), and
4749 = h-node (query name server, then broadcast).
4752 Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID provides an extended
4753 naming service for the NetBIOS over TCP/IP (Known as NBT) module. The
4754 primary purpose of a NetBIOS scope ID is to isolate NetBIOS traffic on
4755 a single network to only those nodes with the same NetBIOS scope ID.
4756 The NetBIOS scope ID is a character string that is appended to the NetBIOS
4757 name. The NetBIOS scope ID on two hosts must match, or the two hosts
4758 will not be able to communicate. The NetBIOS Scope ID also allows
4759 computers to use the same computer name, as they have different
4760 scope IDs. The Scope ID becomes a part of the NetBIOS name, making the name unique.
4761 (This description of NetBIOS scopes courtesy of NeonSurge@abyss.com)
4764 Disable Netbios-over-TCP/IP.
4770 to a non-windows client, the option will be saved in the client's
4771 environment before the up script is called, under
4772 the name "foreign_option_{n}".
4773 .\"*********************************************************
4776 Cause OpenVPN to sleep for
4778 seconds immediately after the TAP-Win32 adapter state
4779 is set to "connected".
4781 This option is intended to be used to troubleshoot problems
4786 options, and is used to give
4787 the TAP-Win32 adapter time to come up before
4788 Windows IP Helper API operations are applied to it.
4789 .\"*********************************************************
4792 Output OpenVPN's view of the system routing table and network
4793 adapter list to the syslog or log file after the TUN/TAP adapter
4794 has been brought up and any routes have been added.
4795 .\"*********************************************************
4798 Ask Windows to renew the TAP adapter lease on startup.
4799 This option is normally unnecessary, as Windows automatically
4800 triggers a DHCP renegotiation on the TAP adapter when it
4801 comes up, however if you set the TAP-Win32 adapter
4802 Media Status property to "Always Connected", you may need this
4804 .\"*********************************************************
4807 Ask Windows to release the TAP adapter lease on shutdown.
4808 This option has the same caveats as
4811 .\"*********************************************************
4814 Put up a "press any key to continue" message on the console prior
4815 to OpenVPN program exit. This option is automatically used by the
4816 Windows explorer when OpenVPN is run on a configuration
4817 file using the right-click explorer menu.
4818 .\"*********************************************************
4820 .B --service exit-event [0|1]
4821 Should be used when OpenVPN is being automatically executed by another
4823 a context that no interaction with the user via display or keyboard
4824 is possible. In general, end-users should never need to explicitly
4825 use this option, as it is automatically added by the OpenVPN service wrapper
4826 when a given OpenVPN configuration is being run as a service.
4829 is the name of a Windows global event object, and OpenVPN will continuously
4830 monitor the state of this event object and exit when it becomes signaled.
4832 The second parameter indicates the initial state of
4834 and normally defaults to 0.
4836 Multiple OpenVPN processes can be simultaneously executed with the same
4838 parameter. In any case, the controlling process can signal
4840 causing all such OpenVPN processes to exit.
4842 When executing an OpenVPN process using the
4844 directive, OpenVPN will probably not have a console
4845 window to output status/error
4846 messages, therefore it is useful to use
4850 to write these messages to a file.
4851 .\"*********************************************************
4855 Show available TAP-Win32 adapters which can be selected using the
4857 option. On non-Windows systems, the
4859 command provides similar functionality.
4860 .\"*********************************************************
4862 .B --allow-nonadmin [TAP-adapter]
4866 to allow access from non-administrative accounts. If
4868 is omitted, all TAP adapters on the system will be configured to allow
4870 The non-admin access setting will only persist for the length of time that
4871 the TAP-Win32 device object and driver remain loaded, and will need
4872 to be re-enabled after a reboot, or if the driver is unloaded
4874 This directive can only be used by an administrator.
4875 .\"*********************************************************
4877 .B --show-valid-subnets
4879 Show valid subnets for
4881 emulation. Since the TAP-Win32 driver
4882 exports an ethernet interface to Windows, and since TUN devices are
4883 point-to-point in nature, it is necessary for the TAP-Win32 driver
4884 to impose certain constraints on TUN endpoint address selection.
4886 Namely, the point-to-point endpoints used in TUN device emulation
4887 must be the middle two addresses of a /30 subnet (netmask 255.255.255.252).
4888 .\"*********************************************************
4892 Show OpenVPN's view of the system routing table and network
4894 .\"*********************************************************
4895 .SS PKCS#11 Standalone Options:
4896 .\"*********************************************************
4898 .B --show-pkcs11-ids provider [cert_private]
4900 Show PKCS#11 token object list. Specify cert_private as 1
4901 if certificates are stored as private objects.
4904 option can be used BEFORE this option to produce debugging information.
4905 .\"*********************************************************
4906 .SH SCRIPTING AND ENVIRONMENTAL VARIABLES
4907 OpenVPN exports a series
4908 of environmental variables for use by user-defined scripts.
4909 .\"*********************************************************
4910 .SS Script Order of Execution
4911 .\"*********************************************************
4914 Executed after TCP/UDP socket bind and TUN/TAP open.
4915 .\"*********************************************************
4918 Executed when we have a still untrusted remote peer.
4919 .\"*********************************************************
4922 Executed after connection authentication, or remote IP address change.
4923 .\"*********************************************************
4928 mode immediately after client authentication.
4929 .\"*********************************************************
4932 Executed after connection authentication, either
4933 immediately after, or some number of seconds after
4937 .\"*********************************************************
4939 .B --client-disconnect
4942 mode on client instance shutdown.
4943 .\"*********************************************************
4946 Executed after TCP/UDP and TUN/TAP close.
4947 .\"*********************************************************
4952 mode whenever an IPv4 address/route or MAC address is added to OpenVPN's
4953 internal routing table.
4954 .\"*********************************************************
4956 .B --auth-user-pass-verify
4959 mode on new client connections, when the client is
4961 .\"*********************************************************
4962 .SS String Types and Remapping
4963 In certain cases, OpenVPN will perform remapping of characters
4964 in strings. Essentially, any characters outside the set of
4965 permitted characters for each string type will be converted
4969 Why is string remapping necessary?
4972 It's an important security feature to prevent the malicious coding of
4973 strings from untrusted sources to be passed as parameters to scripts,
4974 saved in the environment, used as a common name, translated to a filename,
4977 Here is a brief rundown of OpenVPN's current string types and the
4978 permitted character class for each string:
4981 Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), at
4982 ('@'), colon (':'), slash ('/'), and equal ('='). Alphanumeric is defined
4983 as a character which will cause the C library isalnum() function to return
4987 Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), and at
4990 .B --auth-user-pass username:
4991 Same as Common Name, with one exception: starting with OpenVPN 2.0.1,
4992 the username is passed to the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin in its raw form,
4993 without string remapping.
4995 .B --auth-user-pass password:
4996 Any "printable" character except CR or LF.
4997 Printable is defined to be a character which will cause the C library
4998 isprint() function to return true.
5000 .B --client-config-dir filename as derived from common name or username:
5001 Alphanumeric, underbar ('_'), dash ('-'), and dot ('.') except for "." or
5002 ".." as standalone strings. As of 2.0.1-rc6, the at ('@') character has
5003 been added as well for compatibility with the common name character class.
5005 .B Environmental variable names:
5006 Alphanumeric or underbar ('_').
5008 .B Environmental variable values:
5009 Any printable character.
5011 For all cases, characters in a string which are not members of the legal
5012 character class for that string type will be remapped to underbar ('_').
5013 .\"*********************************************************
5014 .SS Environmental Variables
5015 Once set, a variable is persisted
5016 indefinitely until it is reset by a new value or a restart,
5018 As of OpenVPN 2.0-beta12, in server mode, environmental
5019 variables set by OpenVPN
5020 are scoped according to the client objects
5022 associated with, so there should not be any issues with
5023 scripts having access to stale, previously set variables
5024 which refer to different client instances.
5025 .\"*********************************************************
5028 Total number of bytes received from client during VPN session.
5029 Set prior to execution of the
5030 .B --client-disconnect
5032 .\"*********************************************************
5035 Total number of bytes sent to client during VPN session.
5036 Set prior to execution of the
5037 .B --client-disconnect
5039 .\"*********************************************************
5042 The X509 common name of an authenticated client.
5043 Set prior to execution of
5044 .B --client-connect, --client-disconnect,
5046 .B --auth-user-pass-verify
5048 .\"*********************************************************
5054 Set on program initiation and reset on SIGHUP.
5055 .\"*********************************************************
5060 directive is specified, or "0" otherwise.
5061 Set on program initiation and reset on SIGHUP.
5062 .\"*********************************************************
5064 .B daemon_log_redirect
5069 directives are specified, or "0" otherwise.
5070 Set on program initiation and reset on SIGHUP.
5071 .\"*********************************************************
5074 The actual name of the TUN/TAP device, including
5075 a unit number if it exists.
5081 .\"*********************************************************
5083 .B foreign_option_{n}
5084 An option pushed via
5086 to a client which does not natively support it,
5089 on a non-Windows system, will be recorded to this
5090 environmental variable sequence prior to
5093 .\"*********************************************************
5095 .B ifconfig_broadcast
5096 The broadcast address for the virtual
5097 ethernet segment which is derived from the
5102 Set prior to OpenVPN calling the
5106 (windows version of ifconfig) commands which
5107 normally occurs prior to
5110 .\"*********************************************************
5113 The local VPN endpoint IP address specified in the
5115 option (first parameter).
5116 Set prior to OpenVPN calling the
5120 (windows version of ifconfig) commands which
5121 normally occurs prior to
5124 .\"*********************************************************
5127 The remote VPN endpoint IP address specified in the
5129 option (second parameter) when
5132 Set prior to OpenVPN calling the
5136 (windows version of ifconfig) commands which
5137 normally occurs prior to
5140 .\"*********************************************************
5143 The subnet mask of the virtual ethernet segment
5144 that is specified as the second parameter to
5149 Set prior to OpenVPN calling the
5153 (windows version of ifconfig) commands which
5154 normally occurs prior to
5157 .\"*********************************************************
5159 .B ifconfig_pool_local_ip
5161 virtual IP address for the TUN/TAP tunnel taken from an
5163 directive if specified, or otherwise from
5164 the ifconfig pool (controlled by the
5166 config file directive).
5170 This option is set on the server prior to execution
5174 .B --client-disconnect
5176 .\"*********************************************************
5178 .B ifconfig_pool_netmask
5180 virtual IP netmask for the TUN/TAP tunnel taken from an
5182 directive if specified, or otherwise from
5183 the ifconfig pool (controlled by the
5185 config file directive).
5189 This option is set on the server prior to execution
5193 .B --client-disconnect
5195 .\"*********************************************************
5197 .B ifconfig_pool_remote_ip
5199 virtual IP address for the TUN/TAP tunnel taken from an
5201 directive if specified, or otherwise from
5202 the ifconfig pool (controlled by the
5204 config file directive).
5205 This option is set on the server prior to execution
5209 .B --client-disconnect
5211 .\"*********************************************************
5214 The maximum packet size (not including the IP header)
5215 of tunnel data in UDP tunnel transport mode.
5221 .\"*********************************************************
5227 Set on program initiation and reset on SIGHUP.
5228 .\"*********************************************************
5231 The local port number, specified by
5235 Set on program initiation and reset on SIGHUP.
5236 .\"*********************************************************
5239 The password provided by a connecting client.
5241 .B --auth-user-pass-verify
5242 script execution only when the
5244 modifier is specified, and deleted from the environment
5245 after the script returns.
5246 .\"*********************************************************
5252 Set on program initiation and reset on SIGHUP.
5253 .\"*********************************************************
5259 Set on program initiation and reset on SIGHUP.
5260 .\"*********************************************************
5263 The remote port number, specified by
5267 Set on program initiation and reset on SIGHUP.
5268 .\"*********************************************************
5270 .B route_net_gateway
5271 The pre-existing default IP gateway in the system routing
5276 .\"*********************************************************
5278 .B route_vpn_gateway
5279 The default gateway used by
5281 options, as specified in either the
5283 option or the second parameter to
5291 .\"*********************************************************
5294 A set of variables which define each route to be added, and
5300 will be one of "network", "netmask", "gateway", or "metric".
5303 is the OpenVPN route number, starting from 1.
5305 If the network or gateway are resolvable DNS names,
5306 their IP address translations will be recorded rather
5307 than their names as denoted on the command line
5308 or configuration file.
5309 .\"*********************************************************
5312 Set to "init" or "restart" prior to up/down script execution.
5313 For more information, see
5316 .\"*********************************************************
5320 .B up, down, ipchange, route-up, tls-verify, auth-user-pass-verify,
5321 .B client-connect, client-disconnect,
5324 Set prior to execution of any script.
5325 .\"*********************************************************
5328 The reason for exit or restart. Can be one of
5329 .B sigusr1, sighup, sigterm, sigint, inactive
5342 (triggered on TCP connection reset),
5346 (unknown signal). This variable is set just prior to down script execution.
5347 .\"*********************************************************
5350 Client connection timestamp, formatted as a human-readable
5352 Set prior to execution of the
5355 .\"*********************************************************
5358 The duration (in seconds) of the client session which is now
5360 Set prior to execution of the
5361 .B --client-disconnect
5363 .\"*********************************************************
5366 Client connection timestamp, formatted as a unix integer
5368 Set prior to execution of the
5371 .\"*********************************************************
5374 A series of certificate fields from the remote peer,
5377 is the verification level. Only set for TLS connections. Set prior
5381 .\"*********************************************************
5384 The serial number of the certificate from the remote peer,
5387 is the verification level. Only set for TLS connections. Set prior
5391 .\"*********************************************************
5394 The MTU of the TUN/TAP device.
5400 .\"*********************************************************
5403 Actual IP address of connecting client or peer which has been authenticated.
5404 Set prior to execution of
5405 .B --ipchange, --client-connect,
5407 .B --client-disconnect
5409 .\"*********************************************************
5412 Actual port number of connecting client or peer which has been authenticated.
5413 Set prior to execution of
5414 .B --ipchange, --client-connect,
5416 .B --client-disconnect
5418 .\"*********************************************************
5421 Actual IP address of connecting client or peer which has not been authenticated
5422 yet. Sometimes used to
5424 the connecting host in a
5426 script to ensure it is firewalled properly.
5427 Set prior to execution of
5430 .B --auth-user-pass-verify
5432 .\"*********************************************************
5435 Actual port number of connecting client or peer which has not been authenticated
5437 Set prior to execution of
5440 .B --auth-user-pass-verify
5442 .\"*********************************************************
5445 The username provided by a connecting client.
5447 .B --auth-user-pass-verify
5448 script execution only when the
5450 modifier is specified.
5451 .\"*********************************************************
5455 Cause OpenVPN to close all TUN/TAP and
5456 network connections,
5457 restart, re-read the configuration file (if any),
5458 and reopen TUN/TAP and network connections.
5459 .\"*********************************************************
5464 except don't re-read configuration file, and possibly don't close and reopen TUN/TAP
5465 device, re-read key files, preserve local IP address/port, or preserve most recently authenticated
5466 remote IP address/port based on
5467 .B --persist-tun, --persist-key, --persist-local-ip,
5469 .B --persist-remote-ip
5470 options respectively (see above).
5472 This signal may also be internally generated by a timeout condition, governed
5477 This signal, when combined with
5478 .B --persist-remote-ip,
5480 sent when the underlying parameters of the host's network interface change
5481 such as when the host is a DHCP client and is assigned a new IP address.
5484 above for more information.
5485 .\"*********************************************************
5488 Causes OpenVPN to display its current statistics (to the syslog
5491 is used, or stdout otherwise).
5492 .\"*********************************************************
5495 Causes OpenVPN to exit gracefully.
5496 .\"*********************************************************
5497 .SH TUN/TAP DRIVER SETUP
5498 If you are running Linux 2.4.7 or higher, you probably have the TUN/TAP driver
5499 already installed. If so, there are still a few things you need to do:
5502 .B mknod /dev/net/tun c 10 200
5507 If you have Linux 2.2 or earlier, you should obtain version 1.1 of the
5509 .I http://vtun.sourceforge.net/tun/
5510 and follow the installation instructions.
5511 .\"*********************************************************
5513 Prior to running these examples, you should have OpenVPN installed on two
5514 machines with network connectivity between them. If you have not
5515 yet installed OpenVPN, consult the INSTALL file included in the OpenVPN
5517 .\"*********************************************************
5519 If you are using Linux 2.4 or higher,
5520 make the tun device node and load the tun module:
5522 .B mknod /dev/net/tun c 10 200
5527 If you installed from RPM, the
5529 step may be omitted, because the RPM install does that for you.
5531 If you have Linux 2.2, you should obtain version 1.1 of the
5533 .I http://vtun.sourceforge.net/tun/
5534 and follow the installation instructions.
5536 For other platforms, consult the INSTALL file at
5537 .I http://openvpn.net/install.html
5538 for more information.
5539 .\"*********************************************************
5541 If firewalls exist between
5542 the two machines, they should be set to forward UDP port 1194
5543 in both directions. If you do not have control over the firewalls
5544 between the two machines, you may still be able to use OpenVPN by adding
5548 commands used below in the examples (this will cause each peer to send out
5549 a UDP ping to its remote peer once every 15 seconds which will cause many
5550 stateful firewalls to forward packets in both directions
5551 without an explicit firewall rule).
5553 If you are using a Linux iptables-based firewall, you may need to enter
5554 the following command to allow incoming packets on the TUN device:
5556 .B iptables -A INPUT -i tun+ -j ACCEPT
5558 See the firewalls section below for more information on configuring firewalls
5559 for use with OpenVPN.
5560 .\"*********************************************************
5561 .SS VPN Address Setup:
5563 of our example, our two machines will be called
5567 If you are constructing a VPN over the internet, then replace
5571 with the internet hostname or IP address that each machine will use
5572 to contact the other over the internet.
5574 Now we will choose the tunnel endpoints. Tunnel endpoints are
5575 private IP addresses that only have meaning in the context of
5576 the VPN. Each machine will use the tunnel endpoint of the other
5577 machine to access it over the VPN. In our example,
5578 the tunnel endpoint for may.kg
5579 will be 10.4.0.1 and for june.kg, 10.4.0.2.
5581 Once the VPN is established, you have essentially
5582 created a secure alternate path between the two hosts
5583 which is addressed by using the tunnel endpoints. You can
5584 control which network
5585 traffic passes between the hosts
5586 (a) over the VPN or (b) independently of the VPN, by choosing whether to use
5587 (a) the VPN endpoint address or (b) the public internet address,
5588 to access the remote host. For example if you are on may.kg and you wish to connect to june.kg
5591 without using the VPN (since
5593 has its own built-in security) you would use the command
5595 However in the same scenario, you could also use the command
5597 to create a telnet session with june.kg over the VPN, that would
5598 use the VPN to secure the session rather than
5601 You can use any address you wish for the
5603 but make sure that they are private addresses
5604 (such as those that begin with 10 or 192.168) and that they are
5605 not part of any existing subnet on the networks of
5606 either peer, unless you are bridging. If you use an address that is part of
5607 your local subnet for either of the tunnel endpoints,
5608 you will get a weird feedback loop.
5609 .\"*********************************************************
5610 .SS Example 1: A simple tunnel without security
5614 .B openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 --verb 9
5618 .B openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 --verb 9
5620 Now verify the tunnel is working by pinging across the tunnel.
5632 option will produce verbose output, similar to the
5636 option to have OpenVPN run quietly.
5637 .\"*********************************************************
5638 .SS Example 2: A tunnel with static-key security (i.e. using a pre-shared secret)
5639 First build a static key on may.
5641 .B openvpn --genkey --secret key
5643 This command will build a random key file called
5648 to june over a secure medium such as by
5655 .B openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 --verb 5 --secret key
5659 .B openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 --verb 5 --secret key
5661 Now verify the tunnel is working by pinging across the tunnel.
5670 .\"*********************************************************
5671 .SS Example 3: A tunnel with full TLS-based security
5672 For this test, we will designate
5674 as the TLS client and
5677 .I Note that client or server designation only has meaning for the TLS subsystem. It has no bearing on OpenVPN's peer-to-peer, UDP-based communication model.
5679 First, build a separate certificate/key pair
5680 for both may and june (see above where
5682 is discussed for more info). Then construct
5683 Diffie Hellman parameters (see above where
5685 is discussed for more info). You can also use the
5686 included test files client.crt, client.key,
5687 server.crt, server.key and ca.crt.
5688 The .crt files are certificates/public-keys, the .key
5689 files are private keys, and ca.crt is a certification
5690 authority who has signed both
5691 client.crt and server.crt. For Diffie Hellman
5692 parameters you can use the included file dh1024.pem.
5693 .I Note that all client, server, and certificate authority certificates and keys included in the OpenVPN distribution are totally insecure and should be used for testing only.
5697 .B openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 --tls-client --ca ca.crt --cert client.crt --key client.key --reneg-sec 60 --verb 5
5701 .B openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 --tls-server --dh dh1024.pem --ca ca.crt --cert server.crt --key server.key --reneg-sec 60 --verb 5
5703 Now verify the tunnel is working by pinging across the tunnel.
5715 option we used above. That tells OpenVPN to renegotiate
5716 the data channel keys every minute.
5719 above, you will see status information on each new key negotiation.
5721 For production operations, a key renegotiation interval of 60 seconds
5722 is probably too frequent. Omit the
5724 option to use OpenVPN's default key renegotiation interval of one hour.
5725 .\"*********************************************************
5727 Assuming you can ping across the tunnel,
5728 the next step is to route a real subnet over
5729 the secure tunnel. Suppose that may and june have two network
5730 interfaces each, one connected
5731 to the internet, and the other to a private
5732 network. Our goal is to securely connect
5733 both private networks. We will assume that may's private subnet
5734 is 10.0.0.0/24 and june's is 10.0.1.0/24.
5736 First, ensure that IP forwarding is enabled on both peers.
5737 On Linux, enable routing:
5739 .B echo 1 > /proc/sys/net/ipv4/ip_forward
5741 and enable TUN packet forwarding through the firewall:
5743 .B iptables -A FORWARD -i tun+ -j ACCEPT
5747 .B route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
5751 .B route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
5753 Now any machine on the 10.0.0.0/24 subnet can
5754 access any machine on the 10.0.1.0/24 subnet
5755 over the secure tunnel (or vice versa).
5757 In a production environment, you could put the route command(s)
5758 in a shell script and execute with the
5761 .\"*********************************************************
5763 OpenVPN's usage of a single UDP port makes it fairly firewall-friendly.
5764 You should add an entry to your firewall rules to allow incoming OpenVPN
5765 packets. On Linux 2.4+:
5767 .B iptables -A INPUT -p udp -s 1.2.3.4 --dport 1194 -j ACCEPT
5769 This will allow incoming packets on UDP port 1194 (OpenVPN's default UDP port)
5770 from an OpenVPN peer at 1.2.3.4.
5772 If you are using HMAC-based packet authentication (the default in any of
5773 OpenVPN's secure modes), having the firewall filter on source
5774 address can be considered optional, since HMAC packet authentication
5775 is a much more secure method of verifying the authenticity of
5776 a packet source. In that case:
5778 .B iptables -A INPUT -p udp --dport 1194 -j ACCEPT
5780 would be adequate and would not render the host inflexible with
5781 respect to its peer having a dynamic IP address.
5783 OpenVPN also works well on stateful firewalls. In some cases, you may
5784 not need to add any static rules to the firewall list if you are
5785 using a stateful firewall that knows how to track UDP connections.
5788 OpenVPN will be guaranteed
5789 to send a packet to its peer at least once every
5793 is less than the stateful firewall connection timeout, you can
5794 maintain an OpenVPN connection indefinitely without explicit
5797 You should also add firewall rules to allow incoming IP traffic on
5798 TUN or TAP devices such as:
5800 .B iptables -A INPUT -i tun+ -j ACCEPT
5802 to allow input packets from tun devices,
5804 .B iptables -A FORWARD -i tun+ -j ACCEPT
5806 to allow input packets from tun devices to be forwarded to
5807 other hosts on the local network,
5809 .B iptables -A INPUT -i tap+ -j ACCEPT
5811 to allow input packets from tap devices, and
5813 .B iptables -A FORWARD -i tap+ -j ACCEPT
5815 to allow input packets from tap devices to be forwarded to
5816 other hosts on the local network.
5818 These rules are secure if you use packet authentication,
5819 since no incoming packets will arrive on a TUN or TAP
5821 unless they first pass an HMAC authentication test.
5822 .\"*********************************************************
5824 .I http://openvpn.net/faq.html
5825 .\"*********************************************************
5827 For a more comprehensive guide to setting up OpenVPN
5828 in a production setting, see the OpenVPN HOWTO at
5829 .I http://openvpn.net/howto.html
5830 .\"*********************************************************
5832 For a description of OpenVPN's underlying protocol,
5834 .I http://openvpn.net/security.html
5835 .\"*********************************************************
5837 OpenVPN's web site is at
5838 .I http://openvpn.net/
5840 Go here to download the latest version of OpenVPN, subscribe
5841 to the mailing lists, read the mailing list
5842 archives, or browse the CVS repository.
5843 .\"*********************************************************
5845 Report all bugs to the OpenVPN users list <openvpn-users@lists.sourceforge.net>.
5846 To subscribe to the list or see the archives, go to
5847 .I http://openvpn.net/mail.html
5848 .\"*********************************************************
5856 .\"*********************************************************
5859 This product includes software developed by the
5861 .I http://www.openssl.org/
5864 For more information on the TLS protocol, see
5865 .I http://www.ietf.org/rfc/rfc2246.txt
5867 For more information on the LZO real-time compression library see
5868 .I http://www.oberhumer.com/opensource/lzo/
5869 .\"*********************************************************
5871 Copyright (C) 2002-2008 OpenVPN Technologies, Inc. This program is free software;
5872 you can redistribute it and/or modify
5873 it under the terms of the GNU General Public License version 2
5874 as published by the Free Software Foundation.
5875 .\"*********************************************************
5877 James Yonan <jim@yonan.net>