~ubuntu-branches/ubuntu/saucy/openvpn/saucy-proposed
» Revision
53
: .pc/manpage_fixes.patch/openvpn.8
« back to all changes in this revision
Viewing changes to .pc/manpage_fixes.patch/openvpn.8
- browse files at revision 53
- compare with another revision
- download diff
- download tarball
- view history from revision 53
- Committer: Package Import Robot
- Author(s): Stéphane Graber
- Date: 2013-05-24 17:42:45 UTC
- mfrom: (1.1.19) (10.2.22 sid)
- Revision ID: package-import@ubuntu.com-20130524174245-g9y6wlforycufqy5
Tags: 2.3.1-2ubuntu1
* Merge from Debian unstable. Remaining changes:
- debian/openvpn.init.d:
+ Do not use start-stop-daemon and </dev/null to avoid blocking boot.
+ Show per-VPN result messages.
+ Add "--script-security 2" by default for backwards compatabliity.
- debian/openvpn.init.d:
+ Do not use start-stop-daemon and </dev/null to avoid blocking boot.
+ Show per-VPN result messages.
+ Add "--script-security 2" by default for backwards compatabliity.
- files added:
- .gitattributes
- .pc/accommodate_typo.patch/src
- .pc/accommodate_typo.patch/src/openvpn
- .pc/auth-pam_libpam_so_filename.patch/src
- .pc/auth-pam_libpam_so_filename.patch/src/plugins
- .pc/auth-pam_libpam_so_filename.patch/src/plugins/auth-pam
- .pc/close_socket_before_scripts.patch/src
- .pc/close_socket_before_scripts.patch/src/openvpn
- .pc/debian_nogroup_for_sample_files.patch/sample
- .pc/debian_nogroup_for_sample_files.patch/sample/sample-config-files
- .pc/kfreebsd_support.patch/src
- .pc/kfreebsd_support.patch/src/openvpn
- .pc/manpage_fixes.patch/doc
- .pc/openvpn-pkcs11warn.patch/src
- .pc/openvpn-pkcs11warn.patch/src/openvpn
- .pc/route_default_nil.patch/doc
- build
- build/msvc
- build/msvc/msvc-generate
- distro
- distro/rpm
- doc
- include
- m4
- sample
- sample/sample-config-files
- sample/sample-keys
- sample/sample-plugins
- sample/sample-plugins/defer
- sample/sample-plugins/log
- sample/sample-plugins/simple
- sample/sample-scripts
- sample/sample-windows
- src
- src/compat
- src/openvpn
- src/openvpnserv
- src/plugins
- src/plugins/auth-pam
- src/plugins/down-root
- tests
- files removed:
- .pc/accommodate_typo.patch/occ.c
- .pc/auth-pam_libpam_so_filename.patch/plugin
- .pc/auth-pam_libpam_so_filename.patch/plugin/auth-pam
- .pc/debian_nogroup_for_sample_files.patch/sample-config-files
- .pc/ipv6-payload.patch
- .pc/jjo-ipv6-support.patch
- .pc/use-dpkg-buildflags.patch
- .pc/use-dpkg-buildflags.patch/plugin
- .pc/use-dpkg-buildflags.patch/plugin/auth-pam
- .pc/use-dpkg-buildflags.patch/plugin/down-root
- easy-rsa
- easy-rsa/1.0
- easy-rsa/2.0
- easy-rsa/2.0/tmp
- easy-rsa/Windows
- images
- install-win32
- install-win32/openssl
- management
- plugin
- plugin/auth-pam
- plugin/defer
- plugin/down-root
- plugin/examples
- sample-config-files
- sample-keys
- sample-scripts
- service-win32
- suse
- tap-win32
- tap-win32/i386
- win
- files modified:
- .pc/applied-patches
added
removed
.pc/manpage_fixes.patch/openvpn.8
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.
6
.\"
7
.\" Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net>
8
.\"
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.
12
.\"
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.
17
.\"
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
22
.\"
23
.\" Manual page for openvpn
24
.\
25
.\" SH section heading
26
.\" SS subsection heading
27
.\" LP paragraph
28
.\" IP indented paragraph
29
.\" TP hanging label
30
.\
31
.\" .nf -- no formatting
32
.\" .fi -- resume formatting
33
.\" .ft 3 -- boldface
34
.\" .ft -- normal face
35
.\" .in +|-{n} -- indent
36
.\"
37
.TH openvpn 8 "17 November 2008"
38
.\"*********************************************************
39
.SH NAME
40
openvpn \- secure IP tunnel daemon.
41
.\"*********************************************************
42
.SH SYNOPSIS
43
.ft 3
44
openvpn [ options ... ]
45
.ft
46
.\"*********************************************************
47
.SH INTRODUCTION
48
.LP
49
OpenVPN is an open source VPN daemon by James Yonan.
50
Because OpenVPN tries to
51
be a universal VPN tool offering a great deal of flexibility,
52
there are a lot of options on this manual page.
53
If you're new to OpenVPN, you might want to skip ahead to the
54
examples section where you will see how to construct simple
55
VPNs on the command line without even needing a configuration file.
56
57
Also note that there's more documentation and examples on
58
the OpenVPN web site:
59
.I http://openvpn.net/
60
61
And if you would like to see a shorter version of this manual,
62
see the openvpn usage message which can be obtained by
63
running
64
.B openvpn
65
without any parameters.
66
.\"*********************************************************
67
.SH DESCRIPTION
68
.LP
69
OpenVPN is a robust and highly flexible VPN daemon.
70
OpenVPN supports SSL/TLS security, ethernet bridging,
71
TCP or UDP tunnel transport through proxies or NAT,
72
support for dynamic IP addresses and DHCP,
73
scalability to hundreds or thousands of users,
74
and portability to most major OS platforms.
75
76
OpenVPN is tightly bound to the OpenSSL library, and derives much
77
of its crypto capabilities from it.
78
79
OpenVPN supports
80
conventional encryption
81
using a pre-shared secret key
82
.B (Static Key mode)
83
or
84
public key security
85
.B (SSL/TLS mode)
86
using client & server certificates.
87
OpenVPN also
88
supports non-encrypted TCP/UDP tunnels.
89
90
OpenVPN is designed to work with the
91
.B TUN/TAP
92
virtual networking interface that exists on most platforms.
93
94
Overall, OpenVPN aims to offer many of the key features of IPSec but
95
with a relatively lightweight footprint.
96
.\"*********************************************************
97
.SH OPTIONS
98
OpenVPN allows any option to be placed either on the command line
99
or in a configuration file. Though all command line options are preceded
100
by a double-leading-dash ("\-\-"), this prefix can be removed when
101
an option is placed in a configuration file.
102
.\"*********************************************************
103
.TP
104
.B \-\-help
105
Show options.
106
.\"*********************************************************
107
.TP
108
.B \-\-config file
109
Load additional config options from
110
.B file
111
where each line corresponds to one command line option,
112
but with the leading '\-\-' removed.
113
114
If
115
.B \-\-config file
116
is the only option to the openvpn command,
117
the
118
.B \-\-config
119
can be removed, and the command can be given as
120
.B openvpn file
121
122
Note that
123
configuration files can be nested to a reasonable depth.
124
125
Double quotation or single quotation characters ("", '')
126
can be used to enclose single parameters containing whitespace,
127
and "#" or ";" characters in the first column
128
can be used to denote comments.
129
130
Note that OpenVPN 2.0 and higher performs backslash-based shell
131
escaping for characters not in single quotations,
132
so the following mappings should be observed:
133
134
.nf
135
.ft 3
136
.in +4
137
\\\\ Maps to a single backslash character (\\).
138
\\" Pass a literal doublequote character ("), don't
139
interpret it as enclosing a parameter.
140
\\[SPACE] Pass a literal space or tab character, don't
141
interpret it as a parameter delimiter.
142
.in -4
143
.ft
144
.fi
145
146
For example on Windows, use double backslashes to
147
represent pathnames:
148
149
.nf
150
.ft 3
151
.in +4
152
secret "c:\\\\OpenVPN\\\\secret.key"
153
.in -4
154
.ft
155
.fi
156
157
For examples of configuration files,
158
see
159
.I http://openvpn.net/examples.html
160
161
Here is an example configuration file:
162
163
.nf
164
.ft 3
165
.in +4
166
#
167
# Sample OpenVPN configuration file for
168
# using a pre-shared static key.
169
#
170
# '#' or ';' may be used to delimit comments.
171
172
# Use a dynamic tun device.
173
dev tun
174
175
# Our remote peer
176
remote mypeer.mydomain
177
178
# 10.1.0.1 is our local VPN endpoint
179
# 10.1.0.2 is our remote VPN endpoint
180
ifconfig 10.1.0.1 10.1.0.2
181
182
# Our pre-shared static key
183
secret static.key
184
.in -4
185
.ft
186
.fi
187
.\"*********************************************************
188
.SS Tunnel Options:
189
.TP
190
.B \-\-mode m
191
Set OpenVPN major mode. By default, OpenVPN runs in
192
point-to-point mode ("p2p"). OpenVPN 2.0 introduces
193
a new mode ("server") which implements a multi-client
194
server capability.
195
.\"*********************************************************
196
.TP
197
.B \-\-local host
198
Local host name or IP address for bind.
199
If specified, OpenVPN will bind to this address only.
200
If unspecified, OpenVPN will bind to all interfaces.
201
.\"*********************************************************
202
.TP
203
.B \-\-remote host [port] [proto]
204
Remote host name or IP address. On the client, multiple
205
.B \-\-remote
206
options may be specified for redundancy, each referring
207
to a different OpenVPN server. Specifying multiple
208
.B \-\-remote
209
options for this purpose is a special case of the more
210
general connection-profile feature. See the
211
.B <connection>
212
documentation below.
213
214
The OpenVPN client will try to connect to a server at
215
.B host:port
216
in the order specified by the list of
217
.B \-\-remote
218
options.
219
220
.B proto
221
indicates the protocol to use when connecting with the
222
remote, and may be "tcp" or "udp".
223
224
The client will move on to the next host in the list,
225
in the event of connection failure.
226
Note that at any given time, the OpenVPN client
227
will at most be connected to
228
one server.
229
230
Note that since UDP is connectionless, connection failure
231
is defined by the
232
.B \-\-ping
233
and
234
.B \-\-ping-restart
235
options.
236
237
Note the following corner case: If you use multiple
238
.B \-\-remote
239
options, AND you are dropping root privileges on
240
the client with
241
.B \-\-user
242
and/or
243
.B \-\-group,
244
AND the client is running a non-Windows OS, if the client needs
245
to switch to a different server, and that server pushes
246
back different TUN/TAP or route settings, the client may lack
247
the necessary privileges to close and reopen the TUN/TAP interface.
248
This could cause the client to exit with a fatal error.
249
250
If
251
.B \-\-remote
252
is unspecified, OpenVPN will listen
253
for packets from any IP address, but will not act on those packets unless
254
they pass all authentication tests. This requirement for authentication
255
is binding on all potential peers, even those from known and supposedly
256
trusted IP addresses (it is very easy to forge a source IP address on
257
a UDP packet).
258
259
When used in TCP mode,
260
.B \-\-remote
261
will act as a filter, rejecting connections from any host which does
262
not match
263
.B host.
264
265
If
266
.B host
267
is a DNS name which resolves to multiple IP addresses,
268
one will be randomly
269
chosen, providing a sort of basic load-balancing and
270
failover capability.
271
.\"*********************************************************
272
.TP
273
.B \-\-remote-random-hostname
274
Add a random string (6 characters) to first DNS label of hostname to prevent
275
DNS caching. For example, "foo.bar.gov" would be modified to
276
"<random-chars>.foo.bar.gov".
277
.\"*********************************************************
278
.TP
279
.B <connection>
280
Define a client connection
281
profile. Client connection profiles are groups of OpenVPN options that
282
describe how to connect to a given OpenVPN server. Client connection
283
profiles are specified within an OpenVPN configuration file, and
284
each profile is bracketed by
285
.B <connection>
286
and
287
.B </connection>.
288
289
An OpenVPN client will try each connection profile sequentially
290
until it achieves a successful connection.
291
292
.B \-\-remote-random
293
can be used to initially "scramble" the connection
294
list.
295
296
Here is an example of connection profile usage:
297
298
.nf
299
.ft 3
300
.in +4
301
client
302
dev tun
303
304
<connection>
305
remote 198.19.34.56 1194 udp
306
</connection>
307
308
<connection>
309
remote 198.19.34.56 443 tcp
310
</connection>
311
312
<connection>
313
remote 198.19.34.56 443 tcp
314
http-proxy 192.168.0.8 8080
315
http-proxy-retry
316
</connection>
317
318
<connection>
319
remote 198.19.36.99 443 tcp
320
http-proxy 192.168.0.8 8080
321
http-proxy-retry
322
</connection>
323
324
persist-key
325
persist-tun
326
pkcs12 client.p12
327
ns-cert-type server
328
verb 3
329
.in -4
330
.ft
331
.fi
332
333
First we try to connect to a server at 198.19.34.56:1194 using UDP.
334
If that fails, we then try to connect to 198.19.34.56:443 using TCP.
335
If that also fails, then try connecting through an HTTP proxy at
336
192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to
337
connect through the same proxy to a server at 198.19.36.99:443
338
using TCP.
339
340
The following OpenVPN options may be used inside of
341
a
342
.B <connection>
343
block:
344
345
.B bind,
346
.B connect-retry,
347
.B connect-retry-max,
348
.B connect-timeout,
349
.B float,
350
.B http-proxy,
351
.B http-proxy-option,
352
.B http-proxy-retry,
353
.B http-proxy-timeout,
354
.B local,
355
.B lport,
356
.B nobind,
357
.B port,
358
.B proto,
359
.B remote,
360
.B rport,
361
.B socks-proxy, and
362
.B socks-proxy-retry.
363
364
A defaulting mechanism exists for specifying options to apply to
365
all
366
.B <connection>
367
profiles. If any of the above options (with the exception of
368
.B remote
369
) appear outside of a
370
.B <connection>
371
block, but in a configuration file which has one or more
372
.B <connection>
373
blocks, the option setting will be used as a default for
374
.B <connection>
375
blocks which follow it in the configuration file.
376
377
For example, suppose the
378
.B nobind
379
option were placed in the sample configuration file above, near
380
the top of the file, before the first
381
.B <connection>
382
block. The effect would be as if
383
.B nobind
384
were declared in all
385
.B <connection>
386
blocks below it.
387
.\"*********************************************************
388
.TP
389
.B \-\-proto-force p
390
When iterating through connection profiles,
391
only consider profiles using protocol
392
.B p
393
('tcp'|'udp').
394
.\"*********************************************************
395
.TP
396
.B \-\-remote-random
397
When multiple
398
.B \-\-remote
399
address/ports are specified, or if connection profiles are being
400
used, initially randomize the order of the list
401
as a kind of basic load-balancing measure.
402
.\"*********************************************************
403
.TP
404
.B \-\-proto p
405
Use protocol
406
.B p
407
for communicating with remote host.
408
.B p
409
can be
410
.B udp,
411
.B tcp-client,
412
or
413
.B tcp-server.
414
415
The default protocol is
416
.B udp
417
when
418
.B \-\-proto
419
is not specified.
420
421
For UDP operation,
422
.B \-\-proto udp
423
should be specified on both peers.
424
425
For TCP operation, one peer must use
426
.B \-\-proto tcp-server
427
and the other must use
428
.B \-\-proto tcp-client.
429
A peer started with
430
.B tcp-server
431
will wait indefinitely for an incoming connection. A peer
432
started with
433
.B tcp-client
434
will attempt to connect, and if that fails, will sleep for 5
435
seconds (adjustable via the
436
.B \-\-connect-retry
437
option) and try again infinite or up to N retries (adjustable via the
438
.B \-\-connect-retry-max
439
option). Both TCP client and server will simulate
440
a SIGUSR1 restart signal if either side resets the connection.
441
442
OpenVPN is designed to operate optimally over UDP, but TCP capability is provided
443
for situations where UDP cannot be used.
444
In comparison with UDP, TCP will usually be
445
somewhat less efficient and less robust when used over unreliable or congested
446
networks.
447
448
This article outlines some of problems with tunneling IP over TCP:
449
450
.I http://sites.inka.de/sites/bigred/devel/tcp-tcp.html
451
452
There are certain cases, however, where using TCP may be advantageous from
453
a security and robustness perspective, such as tunneling non-IP or
454
application-level UDP protocols, or tunneling protocols which don't
455
possess a built-in reliability layer.
456
.\"*********************************************************
457
.TP
458
.B \-\-connect-retry n
459
For
460
.B \-\-proto tcp-client,
461
take
462
.B n
463
as the
464
number of seconds to wait
465
between connection retries (default=5).
466
.\"*********************************************************
467
.TP
468
.B \-\-connect-timeout n
469
For
470
.B \-\-proto tcp-client,
471
set connection timeout to
472
.B n
473
seconds (default=10).
474
.\"*********************************************************
475
.TP
476
.B \-\-connect-retry-max n
477
For
478
.B \-\-proto tcp-client,
479
take
480
.B n
481
as the
482
number of retries of connection attempt (default=infinite).
483
.\"*********************************************************
484
.TP
485
.B \-\-auto-proxy
486
Try to sense HTTP or SOCKS proxy settings automatically.
487
If no settings are present, a direct connection will be attempted.
488
If both HTTP and SOCKS settings are present, HTTP will be preferred.
489
If the HTTP proxy server requires a password, it will be queried from
490
stdin or the management interface. If the underlying OS doesn't support an API for
491
returning proxy settings, a direct connection will be attempted.
492
Currently, only Windows clients support this option via the
493
InternetQueryOption API.
494
This option exists in OpenVPN 2.1 or higher.
495
.\"*********************************************************
496
.TP
497
.B \-\-show-proxy-settings
498
Show sensed HTTP or SOCKS proxy settings. Currently, only Windows clients
499
support this option.
500
.\"*********************************************************
501
.TP
502
.B \-\-http-proxy server port [authfile|'auto'|'auto-nct'] [auth-method]
503
Connect to remote host through an HTTP proxy at address
504
.B server
505
and port
506
.B port.
507
If HTTP Proxy-Authenticate is required,
508
.B authfile
509
is a file containing a username and password on 2 lines, or
510
"stdin" to prompt from console.
511
512
.B auth-method
513
should be one of "none", "basic", or "ntlm".
514
515
HTTP Digest authentication is supported as well, but only via
516
the
517
.B auto
518
or
519
.B auto-nct
520
flags (below).
521
522
The
523
.B auto
524
flag causes OpenVPN to automatically determine the
525
.B auth-method
526
and query stdin or the management interface for
527
username/password credentials, if required. This flag
528
exists on OpenVPN 2.1 or higher.
529
530
The
531
.B auto-nct
532
flag (no clear-text auth) instructs OpenVPN to automatically
533
determine the authentication method, but to reject weak
534
authentication protocols such as HTTP Basic Authentication.
535
.\"*********************************************************
536
.TP
537
.B \-\-http-proxy-retry
538
Retry indefinitely on HTTP proxy errors. If an HTTP proxy error
539
occurs, simulate a SIGUSR1 reset.
540
.\"*********************************************************
541
.TP
542
.B \-\-http-proxy-timeout n
543
Set proxy timeout to
544
.B n
545
seconds, default=5.
546
.\"*********************************************************
547
.TP
548
.B \-\-http-proxy-option type [parm]
549
Set extended HTTP proxy options.
550
Repeat to set multiple options.
551
552
.B VERSION version \-\-
553
Set HTTP version number to
554
.B version
555
(default=1.0).
556
557
.B AGENT user-agent \-\-
558
Set HTTP "User-Agent" string to
559
.B user-agent.
560
.\"*********************************************************
561
.TP
562
.B \-\-socks-proxy server [port]
563
Connect to remote host through a Socks5 proxy at address
564
.B server
565
and port
566
.B port
567
(default=1080).
568
.\"*********************************************************
569
.TP
570
.B \-\-socks-proxy-retry
571
Retry indefinitely on Socks proxy errors. If a Socks proxy error
572
occurs, simulate a SIGUSR1 reset.
573
.\"*********************************************************
574
.TP
575
.B \-\-resolv-retry n
576
If hostname resolve fails for
577
.B \-\-remote,
578
retry resolve for
579
.B n
580
seconds before failing.
581
582
Set
583
.B n
584
to "infinite" to retry indefinitely.
585
586
By default,
587
.B \-\-resolv-retry infinite
588
is enabled. You can disable by setting n=0.
589
.\"*********************************************************
590
.TP
591
.B \-\-float
592
Allow remote peer to change its IP address and/or port number, such as due to
593
DHCP (this is the default if
594
.B \-\-remote
595
is not used).
596
.B \-\-float
597
when specified with
598
.B \-\-remote
599
allows an OpenVPN session to initially connect to a peer
600
at a known address, however if packets arrive from a new
601
address and pass all authentication tests, the new address
602
will take control of the session. This is useful when
603
you are connecting to a peer which holds a dynamic address
604
such as a dial-in user or DHCP client.
605
606
Essentially,
607
.B \-\-float
608
tells OpenVPN to accept authenticated packets
609
from any address, not only the address which was specified in the
610
.B \-\-remote
611
option.
612
.\"*********************************************************
613
.TP
614
.B \-\-ipchange cmd
615
Execute shell command
616
.B cmd
617
when our remote ip-address is initially authenticated or
618
changes.
619
620
Execute as:
621
622
.B cmd ip_address port_number
623
624
Don't use
625
.B \-\-ipchange
626
in
627
.B \-\-mode server
628
mode. Use a
629
.B \-\-client-connect
630
script instead.
631
632
See the "Environmental Variables" section below for
633
additional parameters passed as environmental variables.
634
635
Note that
636
.B cmd
637
can be a shell command with multiple arguments, in which
638
case all OpenVPN-generated arguments will be appended
639
to
640
.B cmd
641
to build a command line which will be passed to the script.
642
643
If you are running in a dynamic IP address environment where
644
the IP addresses of either peer could change without notice,
645
you can use this script, for example, to edit the
646
.I /etc/hosts
647
file with the current address of the peer. The script will
648
be run every time the remote peer changes its IP address.
649
650
Similarly if
651
.I our
652
IP address changes due to DHCP, we should configure
653
our IP address change script (see man page for
654
.BR dhcpcd (8)
655
) to deliver a
656
.B SIGHUP
657
or
658
.B SIGUSR1
659
signal to OpenVPN. OpenVPN will then
660
reestablish a connection with its most recently authenticated
661
peer on its new IP address.
662
.\"*********************************************************
663
.TP
664
.B \-\-port port
665
TCP/UDP port number for both local and remote. The current
666
default of 1194 represents the official IANA port number
667
assignment for OpenVPN and has been used since version 2.0-beta17.
668
Previous versions used port 5000 as the default.
669
.\"*********************************************************
670
.TP
671
.B \-\-lport port
672
TCP/UDP port number for bind.
673
.\"*********************************************************
674
.TP
675
.B \-\-rport port
676
TCP/UDP port number for remote.
677
.\"*********************************************************
678
.TP
679
.B \-\-bind
680
Bind to local address and port. This is the default unless any of
681
.B \-\-proto tcp-client
682
,
683
.B \-\-http-proxy
684
or
685
.B \-\-socks-proxy
686
are used.
687
.\"*********************************************************
688
.TP
689
.B \-\-nobind
690
Do not bind to local address and port. The IP stack will allocate
691
a dynamic port for returning packets. Since the value of the dynamic port
692
could not be known in advance by a peer, this option is only suitable for
693
peers which will be initiating connections by using the
694
.B \-\-remote
695
option.
696
.\"*********************************************************
697
.TP
698
.B \-\-dev tunX | tapX | null
699
TUN/TAP virtual network device (
700
.B X
701
can be omitted for a dynamic device.)
702
703
See examples section below
704
for an example on setting up a TUN device.
705
706
You must use either tun devices on both ends of the connection
707
or tap devices on both ends. You cannot mix them, as they
708
represent different underlying network layers.
709
710
.B tun
711
devices encapsulate IPv4 or IPv6 (OSI Layer 3) while
712
.B tap
713
devices encapsulate Ethernet 802.3 (OSI Layer 2).
714
.\"*********************************************************
715
.TP
716
.B \-\-dev-type device-type
717
Which device type are we using?
718
.B device-type
719
should be
720
.B tun
721
(OSI Layer 3)
722
or
723
.B tap
724
(OSI Layer 2).
725
Use this option only if the TUN/TAP device used with
726
.B \-\-dev
727
does not begin with
728
.B tun
729
or
730
.B tap.
731
.\"*********************************************************
732
.TP
733
.B \-\-topology mode
734
Configure virtual addressing topology when running in
735
.B \-\-dev tun
736
mode. This directive has no meaning in
737
.B \-\-dev tap
738
mode, which always uses a
739
.B subnet
740
topology.
741
742
If you set this directive on the server, the
743
.B \-\-server
744
and
745
.B \-\-server-bridge
746
directives will automatically push your chosen topology setting to clients
747
as well. This directive can also be manually pushed to clients. Like the
748
.B \-\-dev
749
directive, this directive must always be compatible between client and server.
750
751
.B mode
752
can be one of:
753
754
.B net30 \-\-
755
Use a point-to-point topology, by allocating one /30 subnet per client.
756
This is designed to allow point-to-point semantics when some
757
or all of the connecting clients might be Windows systems. This is the
758
default on OpenVPN 2.0.
759
760
.B p2p \-\-
761
Use a point-to-point topology where the remote endpoint of the client's
762
tun interface always points to the local endpoint of the server's tun interface.
763
This mode allocates a single IP address per connecting client.
764
Only use
765
when none of the connecting clients are Windows systems. This mode
766
is functionally equivalent to the
767
.B \-\-ifconfig-pool-linear
768
directive which is available in OpenVPN 2.0 and is now deprecated.
769
770
.B subnet \-\-
771
Use a subnet rather than a point-to-point topology by
772
configuring the tun interface with a local IP address and subnet mask,
773
similar to the topology used in
774
.B \-\-dev tap
775
and ethernet bridging mode.
776
This mode allocates a single IP address per connecting client and works on
777
Windows as well. Only available when server and clients are OpenVPN 2.1 or
778
higher, or OpenVPN 2.0.x which has been manually patched with the
779
.B \-\-topology
780
directive code. When used on Windows, requires version 8.2 or higher
781
of the TAP-Win32 driver. When used on *nix, requires that the tun
782
driver supports an
783
.BR ifconfig (8)
784
command which sets a subnet instead of a remote endpoint IP address.
785
786
This option exists in OpenVPN 2.1 or higher.
787
.\"*********************************************************
788
.TP
789
.B \-\-tun-ipv6
790
Build a tun link capable of forwarding IPv6 traffic.
791
Should be used in conjunction with
792
.B \-\-dev tun
793
or
794
.B \-\-dev tunX.
795
A warning will be displayed
796
if no specific IPv6 TUN support for your OS has been compiled into OpenVPN.
797
798
See below for further IPv6-related configuration options.
799
.\"*********************************************************
800
.TP
801
.B \-\-dev-node node
802
Explicitly set the device node rather than using
803
/dev/net/tun, /dev/tun, /dev/tap, etc. If OpenVPN
804
cannot figure out whether
805
.B node
806
is a TUN or TAP device based on the name, you should
807
also specify
808
.B \-\-dev-type tun
809
or
810
.B \-\-dev-type tap.
811
812
On Windows systems, select the TAP-Win32 adapter which
813
is named
814
.B node
815
in the Network Connections Control Panel or the
816
raw GUID of the adapter enclosed by braces.
817
The
818
.B \-\-show-adapters
819
option under Windows can also be used
820
to enumerate all available TAP-Win32
821
adapters and will show both the network
822
connections control panel name and the GUID for
823
each TAP-Win32 adapter.
824
.TP
825
.B \-\-lladdr address
826
Specify the link layer address, more commonly known as the MAC address.
827
Only applied to TAP devices.
828
.\"*********************************************************
829
.TP
830
.B \-\-iproute cmd
831
Set alternate command to execute instead of default iproute2 command.
832
May be used in order to execute OpenVPN in unprivileged environment.
833
.\"*********************************************************
834
.TP
835
.B \-\-ifconfig l rn
836
Set TUN/TAP adapter parameters.
837
.B l
838
is the IP address of the local VPN endpoint.
839
For TUN devices,
840
.B rn
841
is the IP address of the remote VPN endpoint.
842
For TAP devices,
843
.B rn
844
is the subnet mask of the virtual ethernet segment
845
which is being created or connected to.
846
847
For TUN devices, which facilitate virtual
848
point-to-point IP connections,
849
the proper usage of
850
.B \-\-ifconfig
851
is to use two private IP addresses
852
which are not a member of any
853
existing subnet which is in use.
854
The IP addresses may be consecutive
855
and should have their order reversed
856
on the remote peer. After the VPN
857
is established, by pinging
858
.B rn,
859
you will be pinging across the VPN.
860
861
For TAP devices, which provide
862
the ability to create virtual
863
ethernet segments,
864
.B \-\-ifconfig
865
is used to set an IP address and
866
subnet mask just as a physical
867
ethernet adapter would be
868
similarly configured. If you are
869
attempting to connect to a remote
870
ethernet bridge, the IP address
871
and subnet should be set to values
872
which would be valid on the
873
the bridged ethernet segment (note
874
also that DHCP can be used for the
875
same purpose).
876
877
This option, while primarily a proxy for the
878
.BR ifconfig (8)
879
command, is designed to simplify TUN/TAP
880
tunnel configuration by providing a
881
standard interface to the different
882
ifconfig implementations on different
883
platforms.
884
885
.B \-\-ifconfig
886
parameters which are IP addresses can
887
also be specified as a DNS or /etc/hosts
888
file resolvable name.
889
890
For TAP devices,
891
.B \-\-ifconfig
892
should not be used if the TAP interface will be
893
getting an IP address lease from a DHCP
894
server.
895
.\"*********************************************************
896
.TP
897
.B \-\-ifconfig-noexec
898
Don't actually execute ifconfig/netsh commands, instead
899
pass
900
.B \-\-ifconfig
901
parameters to scripts using environmental variables.
902
.\"*********************************************************
903
.TP
904
.B \-\-ifconfig-nowarn
905
Don't output an options consistency check warning
906
if the
907
.B \-\-ifconfig
908
option on this side of the
909
connection doesn't match the remote side. This is useful
910
when you want to retain the overall benefits of the
911
options consistency check (also see
912
.B \-\-disable-occ
913
option) while only disabling the ifconfig component of
914
the check.
915
916
For example,
917
if you have a configuration where the local host uses
918
.B \-\-ifconfig
919
but the remote host does not, use
920
.B \-\-ifconfig-nowarn
921
on the local host.
922
923
This option will also silence warnings about potential
924
address conflicts which occasionally annoy more experienced
925
users by triggering "false positive" warnings.
926
.\"*********************************************************
927
.TP
928
.B \-\-route network/IP [netmask] [gateway] [metric]
929
Add route to routing table after connection is established.
930
Multiple routes can be specified. Routes will be
931
automatically torn down in reverse order prior to
932
TUN/TAP device close.
933
934
This option is intended as
935
a convenience proxy for the
936
.BR route (8)
937
shell command,
938
while at the same time providing portable semantics
939
across OpenVPN's platform space.
940
941
.B netmask
942
default \-\- 255.255.255.255
943
944
.B gateway
945
default \-\- taken from
946
.B \-\-route-gateway
947
or the second parameter to
948
.B \-\-ifconfig
949
when
950
.B \-\-dev tun
951
is specified.
952
953
.B metric
954
default \-\- taken from
955
.B \-\-route-metric
956
otherwise 0.
957
958
The default can be specified by leaving an option blank or setting
959
it to "nil".
960
961
The
962
.B network
963
and
964
.B gateway
965
parameters can
966
also be specified as a DNS or /etc/hosts
967
file resolvable name, or as one of three special keywords:
968
969
.B vpn_gateway
970
\-\- The remote VPN endpoint address
971
(derived either from
972
.B \-\-route-gateway
973
or the second parameter to
974
.B \-\-ifconfig
975
when
976
.B \-\-dev tun
977
is specified).
978
979
.B net_gateway
980
\-\- The pre-existing IP default gateway, read from the routing
981
table (not supported on all OSes).
982
983
.B remote_host
984
\-\- The
985
.B \-\-remote
986
address if OpenVPN is being run in client mode, and is undefined in server mode.
987
.\"*********************************************************
988
.TP
989
.B \-\-max-routes n
990
Allow a maximum number of n
991
.B \-\-route
992
options to be specified, either in the local configuration file,
993
or pulled from an OpenVPN server. By default, n=100.
994
.\"*********************************************************
995
.TP
996
.B \-\-route-gateway gw|'dhcp'
997
Specify a default gateway
998
.B gw
999
for use with
1000
.B \-\-route.
1001
1002
If
1003
.B dhcp
1004
is specified as the parameter,
1005
the gateway address will be extracted from a DHCP
1006
negotiation with the OpenVPN server-side LAN.
1007
.\"*********************************************************
1008
.TP
1009
.B \-\-route-metric m
1010
Specify a default metric
1011
.B m
1012
for use with
1013
.B \-\-route.
1014
.\"*********************************************************
1015
.TP
1016
.B \-\-route-delay [n] [w]
1017
Delay
1018
.B n
1019
seconds (default=0) after connection
1020
establishment, before adding routes. If
1021
.B n
1022
is 0, routes will be added immediately upon connection
1023
establishment. If
1024
.B \-\-route-delay
1025
is omitted, routes will be added immediately after TUN/TAP device
1026
open and
1027
.B \-\-up
1028
script execution, before any
1029
.B \-\-user
1030
or
1031
.B \-\-group
1032
privilege downgrade (or
1033
.B \-\-chroot
1034
execution.)
1035
1036
This option is designed to be useful in scenarios where DHCP is
1037
used to set
1038
tap adapter addresses. The delay will give the DHCP handshake
1039
time to complete before routes are added.
1040
1041
On Windows,
1042
.B \-\-route-delay
1043
tries to be more intelligent by waiting
1044
.B w
1045
seconds (w=30 by default)
1046
for the TAP-Win32 adapter to come up before adding routes.
1047
.\"*********************************************************
1048
.TP
1049
.B \-\-route-up cmd
1050
Execute shell command
1051
.B cmd
1052
after routes are added, subject to
1053
.B \-\-route-delay.
1054
1055
See the "Environmental Variables" section below for
1056
additional parameters passed as environmental variables.
1057
1058
Note that
1059
.B cmd
1060
can be a shell command with multiple arguments.
1061
.\"*********************************************************
1062
.TP
1063
.B \-\-route-noexec
1064
Don't add or remove routes automatically. Instead pass routes to
1065
.B \-\-route-up
1066
script using environmental variables.
1067
.\"*********************************************************
1068
.TP
1069
.B \-\-route-nopull
1070
When used with
1071
.B \-\-client
1072
or
1073
.B \-\-pull,
1074
accept options pushed by server EXCEPT for routes.
1075
1076
When used on the client, this option effectively bars the
1077
server from adding routes to the client's routing table,
1078
however note that this option still allows the server
1079
to set the TCP/IP properties of the client's TUN/TAP interface.
1080
.\"*********************************************************
1081
.TP
1082
.B \-\-allow-pull-fqdn
1083
Allow client to pull DNS names from server (rather than being limited
1084
to IP address) for
1085
.B \-\-ifconfig,
1086
.B \-\-route,
1087
and
1088
.B \-\-route-gateway.
1089
.\"*********************************************************
1090
.TP
1091
.B \-\-redirect-gateway flags...
1092
(Experimental) Automatically execute routing commands to cause all outgoing IP traffic
1093
to be redirected over the VPN.
1094
1095
This option performs three steps:
1096
1097
.B (1)
1098
Create a static route for the
1099
.B \-\-remote
1100
address which forwards to the pre-existing default gateway.
1101
This is done so that
1102
.B (3)
1103
will not create a routing loop.
1104
1105
.B (2)
1106
Delete the default gateway route.
1107
1108
.B (3)
1109
Set the new default gateway to be the VPN endpoint address (derived either from
1110
.B \-\-route-gateway
1111
or the second parameter to
1112
.B \-\-ifconfig
1113
when
1114
.B \-\-dev tun
1115
is specified).
1116
1117
When the tunnel is torn down, all of the above steps are reversed so
1118
that the original default route is restored.
1119
1120
Option flags:
1121
1122
.B local \-\-
1123
Add the
1124
.B local
1125
flag if both OpenVPN servers are directly connected via a common subnet,
1126
such as with wireless. The
1127
.B local
1128
flag will cause step
1129
.B 1
1130
above to be omitted.
1131
1132
.B def1 \-\-
1133
Use this flag to override
1134
the default gateway by using 0.0.0.0/1 and 128.0.0.0/1
1135
rather than 0.0.0.0/0. This has the benefit of overriding
1136
but not wiping out the original default gateway.
1137
1138
.B bypass-dhcp \-\-
1139
Add a direct route to the DHCP server (if it is non-local) which
1140
bypasses the tunnel
1141
(Available on Windows clients, may not be available
1142
on non-Windows clients).
1143
1144
.B bypass-dns \-\-
1145
Add a direct route to the DNS server(s) (if they are non-local) which
1146
bypasses the tunnel
1147
(Available on Windows clients, may not be available
1148
on non-Windows clients).
1149
1150
Using the def1 flag is highly recommended.
1151
.\"*********************************************************
1152
.TP
1153
.B \-\-redirect-private [flags]
1154
Like \-\-redirect-gateway, but omit actually changing the default
1155
gateway. Useful when pushing private subnets.
1156
.\"*********************************************************
1157
.TP
1158
.B \-\-link-mtu n
1159
Sets an upper bound on the size of UDP packets which are sent
1160
between OpenVPN peers. It's best not to set this parameter unless
1161
you know what you're doing.
1162
.\"*********************************************************
1163
.TP
1164
.B \-\-tun-mtu n
1165
Take the TUN device MTU to be
1166
.B n
1167
and derive the link MTU
1168
from it (default=1500). In most cases, you will probably want to
1169
leave this parameter set to its default value.
1170
1171
The MTU (Maximum Transmission Units) is
1172
the maximum datagram size in bytes that can be sent unfragmented
1173
over a particular network path. OpenVPN requires that packets
1174
on the control or data channels be sent unfragmented.
1175
1176
MTU problems often manifest themselves as connections which
1177
hang during periods of active usage.
1178
1179
It's best to use the
1180
.B \-\-fragment
1181
and/or
1182
.B \-\-mssfix
1183
options to deal with MTU sizing issues.
1184
.\"*********************************************************
1185
.TP
1186
.B \-\-tun-mtu-extra n
1187
Assume that the TUN/TAP device might return as many as
1188
.B n
1189
bytes more than the
1190
.B \-\-tun-mtu
1191
size on read. This parameter defaults to 0, which is sufficient for
1192
most TUN devices. TAP devices may introduce additional overhead in excess
1193
of the MTU size, and a setting of 32 is the default when TAP devices are used.
1194
This parameter only controls internal OpenVPN buffer sizing,
1195
so there is no transmission overhead associated with using a larger value.
1196
.\"*********************************************************
1197
.TP
1198
.B \-\-mtu-disc type
1199
Should we do Path MTU discovery on TCP/UDP channel? Only supported on OSes such
1200
as Linux that supports the necessary system call to set.
1201
1202
.B 'no'
1203
\-\- Never send DF (Don't Fragment) frames
1204
.br
1205
.B 'maybe'
1206
\-\- Use per-route hints
1207
.br
1208
.B 'yes'
1209
\-\- Always DF (Don't Fragment)
1210
.br
1211
.\"*********************************************************
1212
.TP
1213
.B \-\-mtu-test
1214
To empirically measure MTU on connection startup,
1215
add the
1216
.B \-\-mtu-test
1217
option to your configuration.
1218
OpenVPN will send ping packets of various sizes
1219
to the remote peer and measure the largest packets
1220
which were successfully received. The
1221
.B \-\-mtu-test
1222
process normally takes about 3 minutes to complete.
1223
.\"*********************************************************
1224
.TP
1225
.B \-\-fragment max
1226
Enable internal datagram fragmentation so
1227
that no UDP datagrams are sent which
1228
are larger than
1229
.B max
1230
bytes.
1231
1232
The
1233
.B max
1234
parameter is interpreted in the same way as the
1235
.B \-\-link-mtu
1236
parameter, i.e. the UDP packet size after encapsulation
1237
overhead has been added in, but not including
1238
the UDP header itself.
1239
1240
The
1241
.B \-\-fragment
1242
option only makes sense when you are using the UDP protocol (
1243
.B \-\-proto udp
1244
).
1245
1246
.B \-\-fragment
1247
adds 4 bytes of overhead per datagram.
1248
1249
See the
1250
.B \-\-mssfix
1251
option below for an important related option to
1252
.B \-\-fragment.
1253
1254
It should also be noted that this option is not meant to replace
1255
UDP fragmentation at the IP stack level. It is only meant as a
1256
last resort when path MTU discovery is broken. Using this option
1257
is less efficient than fixing path MTU discovery for your IP link and
1258
using native IP fragmentation instead.
1259
1260
Having said that, there are circumstances where using OpenVPN's
1261
internal fragmentation capability may be your only option, such
1262
as tunneling a UDP multicast stream which requires fragmentation.
1263
.\"*********************************************************
1264
.TP
1265
.B \-\-mssfix max
1266
Announce to TCP sessions running over the tunnel that they should limit
1267
their send packet sizes such that after OpenVPN has encapsulated them,
1268
the resulting UDP packet size that OpenVPN sends to its peer will not
1269
exceed
1270
.B max
1271
bytes. The default value is
1272
.B 1450.
1273
1274
The
1275
.B max
1276
parameter is interpreted in the same way as the
1277
.B \-\-link-mtu
1278
parameter, i.e. the UDP packet size after encapsulation
1279
overhead has been added in, but not including
1280
the UDP header itself.
1281
1282
The
1283
.B \-\-mssfix
1284
option only makes sense when you are using the UDP protocol
1285
for OpenVPN peer-to-peer communication, i.e.
1286
.B \-\-proto udp.
1287
1288
.B \-\-mssfix
1289
and
1290
.B \-\-fragment
1291
can be ideally used together, where
1292
.B \-\-mssfix
1293
will try to keep TCP from needing
1294
packet fragmentation in the first place,
1295
and if big packets come through anyhow
1296
(from protocols other than TCP),
1297
.B \-\-fragment
1298
will internally fragment them.
1299
1300
Both
1301
.B \-\-fragment
1302
and
1303
.B \-\-mssfix
1304
are designed to work around cases where Path MTU discovery
1305
is broken on the network path between OpenVPN peers.
1306
1307
The usual symptom of such a breakdown is an OpenVPN
1308
connection which successfully starts, but then stalls
1309
during active usage.
1310
1311
If
1312
.B \-\-fragment
1313
and
1314
.B \-\-mssfix
1315
are used together,
1316
.B \-\-mssfix
1317
will take its default
1318
.B max
1319
parameter from the
1320
.B \-\-fragment max
1321
option.
1322
1323
Therefore, one could lower the maximum UDP packet size
1324
to 1300 (a good first try for solving MTU-related
1325
connection problems) with the following options:
1326
1327
.B \-\-tun-mtu 1500 \-\-fragment 1300 \-\-mssfix
1328
.\"*********************************************************
1329
.TP
1330
.B \-\-sndbuf size
1331
Set the TCP/UDP socket send buffer size.
1332
Currently defaults to 65536 bytes.
1333
.\"*********************************************************
1334
.TP
1335
.B \-\-rcvbuf size
1336
Set the TCP/UDP socket receive buffer size.
1337
Currently defaults to 65536 bytes.
1338
.\"*********************************************************
1339
.TP
1340
.B \-\-socket-flags flags...
1341
Apply the given flags to the OpenVPN transport socket.
1342
Currently, only
1343
.B TCP_NODELAY
1344
is supported.
1345
1346
The
1347
.B TCP_NODELAY
1348
socket flag is useful in TCP mode, and causes the kernel
1349
to send tunnel packets immediately over the TCP connection without
1350
trying to group several smaller packets into a larger packet.
1351
This can result in a considerably improvement in latency.
1352
1353
This option is pushable from server to client, and should be used
1354
on both client and server for maximum effect.
1355
.\"*********************************************************
1356
.TP
1357
.B \-\-txqueuelen n
1358
(Linux only) Set the TX queue length on the TUN/TAP interface.
1359
Currently defaults to 100.
1360
.\"*********************************************************
1361
.TP
1362
.B \-\-shaper n
1363
Limit bandwidth of outgoing tunnel data to
1364
.B n
1365
bytes per second on the TCP/UDP port.
1366
If you want to limit the bandwidth
1367
in both directions, use this option on both peers.
1368
1369
OpenVPN uses the following algorithm to implement
1370
traffic shaping: Given a shaper rate of
1371
.I n
1372
bytes per second, after a datagram write of
1373
.I b
1374
bytes is queued on the TCP/UDP port, wait a minimum of
1375
.I (b / n)
1376
seconds before queuing the next write.
1377
1378
It should be noted that OpenVPN supports multiple
1379
tunnels between the same two peers, allowing you
1380
to construct full-speed and reduced bandwidth tunnels
1381
at the same time,
1382
routing low-priority data such as off-site backups
1383
over the reduced bandwidth tunnel, and other data
1384
over the full-speed tunnel.
1385
1386
Also note that for low bandwidth tunnels
1387
(under 1000 bytes per second), you should probably
1388
use lower MTU values as well (see above), otherwise
1389
the packet latency will grow so large as to trigger
1390
timeouts in the TLS layer and TCP connections running
1391
over the tunnel.
1392
1393
OpenVPN allows
1394
.B n
1395
to be between 100 bytes/sec and 100 Mbytes/sec.
1396
.\"*********************************************************
1397
.TP
1398
.B \-\-inactive n [bytes]
1399
Causes OpenVPN to exit after
1400
.B n
1401
seconds of inactivity on the TUN/TAP device. The time length of
1402
inactivity is measured since the last incoming or outgoing tunnel
1403
packet. The default value is 0 seconds, which disables this feature.
1404
1405
If the optional
1406
.B bytes
1407
parameter is included,
1408
exit if less than
1409
.B bytes
1410
of combined in/out traffic are produced on the tun/tap device
1411
in
1412
.B n
1413
seconds.
1414
1415
In any case, OpenVPN's internal ping packets (which are just
1416
keepalives) and TLS control packets are not considered
1417
"activity", nor are they counted as traffic, as they are used
1418
internally by OpenVPN and are not an indication of actual user
1419
activity.
1420
.\"*********************************************************
1421
.TP
1422
.B \-\-ping n
1423
Ping remote over the TCP/UDP control channel
1424
if no packets have been sent for at least
1425
.B n
1426
seconds (specify
1427
.B \-\-ping
1428
on both peers to cause ping packets to be sent in both directions since
1429
OpenVPN ping packets are not echoed like IP ping packets).
1430
When used in one of OpenVPN's secure modes (where
1431
.B \-\-secret, \-\-tls-server,
1432
or
1433
.B \-\-tls-client
1434
is specified), the ping packet
1435
will be cryptographically secure.
1436
1437
This option has two intended uses:
1438
1439
(1) Compatibility
1440
with stateful firewalls. The periodic ping will ensure that
1441
a stateful firewall rule which allows OpenVPN UDP packets to
1442
pass will not time out.
1443
1444
(2) To provide a basis for the remote to test the existence
1445
of its peer using the
1446
.B \-\-ping-exit
1447
option.
1448
.\"*********************************************************
1449
.TP
1450
.B \-\-ping-exit n
1451
Causes OpenVPN to exit after
1452
.B n
1453
seconds pass without reception of a ping
1454
or other packet from remote.
1455
This option can be combined with
1456
.B \-\-inactive, \-\-ping,
1457
and
1458
.B \-\-ping-exit
1459
to create a two-tiered inactivity disconnect.
1460
1461
For example,
1462
1463
.B openvpn [options...] \-\-inactive 3600 \-\-ping 10 \-\-ping-exit 60
1464
1465
when used on both peers will cause OpenVPN to exit within 60
1466
seconds if its peer disconnects, but will exit after one
1467
hour if no actual tunnel data is exchanged.
1468
.\"*********************************************************
1469
.TP
1470
.B \-\-ping-restart n
1471
Similar to
1472
.B \-\-ping-exit,
1473
but trigger a
1474
.B SIGUSR1
1475
restart after
1476
.B n
1477
seconds pass without reception of a ping
1478
or other packet from remote.
1479
1480
This option is useful in cases
1481
where the remote peer has a dynamic IP address and
1482
a low-TTL DNS name is used to track the IP address using
1483
a service such as
1484
.I http://dyndns.org/
1485
+ a dynamic DNS client such
1486
as
1487
.B ddclient.
1488
1489
If the peer cannot be reached, a restart will be triggered, causing
1490
the hostname used with
1491
.B \-\-remote
1492
to be re-resolved (if
1493
.B \-\-resolv-retry
1494
is also specified).
1495
1496
In server mode,
1497
.B \-\-ping-restart, \-\-inactive,
1498
or any other type of internally generated signal will always be
1499
applied to
1500
individual client instance objects, never to whole server itself.
1501
Note also in server mode that any internally generated signal
1502
which would normally cause a restart, will cause the deletion
1503
of the client instance object instead.
1504
1505
In client mode, the
1506
.B \-\-ping-restart
1507
parameter is set to 120 seconds by default. This default will
1508
hold until the client pulls a replacement value from the server, based on
1509
the
1510
.B \-\-keepalive
1511
setting in the server configuration.
1512
To disable the 120 second default, set
1513
.B \-\-ping-restart 0
1514
on the client.
1515
1516
See the signals section below for more information
1517
on
1518
.B SIGUSR1.
1519
1520
Note that the behavior of
1521
.B SIGUSR1
1522
can be modified by the
1523
.B \-\-persist-tun, \-\-persist-key, \-\-persist-local-ip,
1524
and
1525
.B \-\-persist-remote-ip
1526
options.
1527
1528
Also note that
1529
.B \-\-ping-exit
1530
and
1531
.B \-\-ping-restart
1532
are mutually exclusive and cannot be used together.
1533
.\"*********************************************************
1534
.TP
1535
.B \-\-keepalive n m
1536
A helper directive designed to simplify the expression of
1537
.B \-\-ping
1538
and
1539
.B \-\-ping-restart
1540
in server mode configurations.
1541
1542
For example,
1543
.B \-\-keepalive 10 60
1544
expands as follows:
1545
1546
.nf
1547
.ft 3
1548
.in +4
1549
if mode server:
1550
ping 10
1551
ping-restart 120
1552
push "ping 10"
1553
push "ping-restart 60"
1554
else
1555
ping 10
1556
ping-restart 60
1557
.in -4
1558
.ft
1559
.fi
1560
.\"*********************************************************
1561
.TP
1562
.B \-\-ping-timer-rem
1563
Run the
1564
.B \-\-ping-exit
1565
/
1566
.B \-\-ping-restart
1567
timer only if we have a remote address. Use this option if you are
1568
starting the daemon in listen mode (i.e. without an explicit
1569
.B \-\-remote
1570
peer), and you don't want to start clocking timeouts until a remote
1571
peer connects.
1572
.\"*********************************************************
1573
.TP
1574
.B \-\-persist-tun
1575
Don't close and reopen TUN/TAP device or run up/down scripts
1576
across
1577
.B SIGUSR1
1578
or
1579
.B \-\-ping-restart
1580
restarts.
1581
1582
.B SIGUSR1
1583
is a restart signal similar to
1584
.B SIGHUP,
1585
but which offers finer-grained control over
1586
reset options.
1587
.\"*********************************************************
1588
.TP
1589
.B \-\-persist-key
1590
Don't re-read key files across
1591
.B SIGUSR1
1592
or
1593
.B \-\-ping-restart.
1594
1595
This option can be combined with
1596
.B \-\-user nobody
1597
to allow restarts triggered by the
1598
.B SIGUSR1
1599
signal.
1600
Normally if you drop root privileges in OpenVPN,
1601
the daemon cannot be restarted since it will now be unable to re-read protected
1602
key files.
1603
1604
This option solves the problem by persisting keys across
1605
.B SIGUSR1
1606
resets, so they don't need to be re-read.
1607
.\"*********************************************************
1608
.TP
1609
.B \-\-persist-local-ip
1610
Preserve initially resolved local IP address and port number
1611
across
1612
.B SIGUSR1
1613
or
1614
.B \-\-ping-restart
1615
restarts.
1616
.\"*********************************************************
1617
.TP
1618
.B \-\-persist-remote-ip
1619
Preserve most recently authenticated remote IP address and port number
1620
across
1621
.B SIGUSR1
1622
or
1623
.B \-\-ping-restart
1624
restarts.
1625
.\"*********************************************************
1626
.TP
1627
.B \-\-mlock
1628
Disable paging by calling the POSIX mlockall function.
1629
Requires that OpenVPN be initially run as root (though
1630
OpenVPN can subsequently downgrade its UID using the
1631
.B \-\-user
1632
option).
1633
1634
Using this option ensures that key material and tunnel
1635
data are never written to disk due to virtual
1636
memory paging operations which occur under most
1637
modern operating systems. It ensures that even if an
1638
attacker was able to crack the box running OpenVPN, he
1639
would not be able to scan the system swap file to
1640
recover previously used
1641
ephemeral keys, which are used for a period of time
1642
governed by the
1643
.B \-\-reneg
1644
options (see below), then are discarded.
1645
1646
The downside
1647
of using
1648
.B \-\-mlock
1649
is that it will reduce the amount of physical
1650
memory available to other applications.
1651
.\"*********************************************************
1652
.TP
1653
.B \-\-up cmd
1654
Shell command to run after successful TUN/TAP device open
1655
(pre
1656
.B \-\-user
1657
UID change). The up script is useful for specifying route
1658
commands which route IP traffic destined for
1659
private subnets which exist at the other
1660
end of the VPN connection into the tunnel.
1661
1662
For
1663
.B \-\-dev tun
1664
execute as:
1665
1666
.B cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [ init | restart ]
1667
1668
For
1669
.B \-\-dev tap
1670
execute as:
1671
1672
.B cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [ init | restart ]
1673
1674
See the "Environmental Variables" section below for
1675
additional parameters passed as environmental variables.
1676
1677
Note that
1678
.B cmd
1679
can be a shell command with multiple arguments, in which
1680
case all OpenVPN-generated arguments will be appended
1681
to
1682
.B cmd
1683
to build a command line which will be passed to the shell.
1684
1685
Typically,
1686
.B cmd
1687
will run a script to add routes to the tunnel.
1688
1689
Normally the up script is called after the TUN/TAP device is opened.
1690
In this context, the last command line parameter passed to the script
1691
will be
1692
.I init.
1693
If the
1694
.B \-\-up-restart
1695
option is also used, the up script will be called for restarts as
1696
well. A restart is considered to be a partial reinitialization
1697
of OpenVPN where the TUN/TAP instance is preserved (the
1698
.B \-\-persist-tun
1699
option will enable such preservation). A restart
1700
can be generated by a SIGUSR1 signal, a
1701
.B \-\-ping-restart
1702
timeout, or a connection reset when the TCP protocol is enabled
1703
with the
1704
.B \-\-proto
1705
option. If a restart occurs, and
1706
.B \-\-up-restart
1707
has been specified, the up script will be called with
1708
.I restart
1709
as the last parameter.
1710
1711
The following standalone example shows how the
1712
.B \-\-up
1713
script can be called in both an initialization and restart context.
1714
(NOTE: for security reasons, don't run the following example unless UDP port
1715
9999 is blocked by your firewall. Also, the example will run indefinitely,
1716
so you should abort with control-c).
1717
1718
.B openvpn \-\-dev tun \-\-port 9999 \-\-verb 4 \-\-ping-restart 10 \-\-up 'echo up' \-\-down 'echo down' \-\-persist-tun \-\-up-restart
1719
1720
Note that OpenVPN also provides the
1721
.B \-\-ifconfig
1722
option to automatically ifconfig the TUN device,
1723
eliminating the need to define an
1724
.B \-\-up
1725
script, unless you also want to configure routes
1726
in the
1727
.B \-\-up
1728
script.
1729
1730
If
1731
.B \-\-ifconfig
1732
is also specified, OpenVPN will pass the ifconfig local
1733
and remote endpoints on the command line to the
1734
.B \-\-up
1735
script so that they can be used to configure routes such as:
1736
1737
.B route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
1738
.\"*********************************************************
1739
.TP
1740
.B \-\-up-delay
1741
Delay TUN/TAP open and possible
1742
.B \-\-up
1743
script execution
1744
until after TCP/UDP connection establishment with peer.
1745
1746
In
1747
.B \-\-proto udp
1748
mode, this option normally requires the use of
1749
.B \-\-ping
1750
to allow connection initiation to be sensed in the absence
1751
of tunnel data, since UDP is a "connectionless" protocol.
1752
1753
On Windows, this option will delay the TAP-Win32 media state
1754
transitioning to "connected" until connection establishment,
1755
i.e. the receipt of the first authenticated packet from the peer.
1756
.\"*********************************************************
1757
.TP
1758
.B \-\-down cmd
1759
Shell command to run after TUN/TAP device close
1760
(post
1761
.B \-\-user
1762
UID change and/or
1763
.B \-\-chroot
1764
). Called with the same parameters and environmental
1765
variables as the
1766
.B \-\-up
1767
option above.
1768
1769
Note that if you reduce privileges by using
1770
.B \-\-user
1771
and/or
1772
.B \-\-group,
1773
your
1774
.B \-\-down
1775
script will also run at reduced privilege.
1776
.\"*********************************************************
1777
.TP
1778
.B \-\-down-pre
1779
Call
1780
.B \-\-down
1781
cmd/script before, rather than after, TUN/TAP close.
1782
.\"*********************************************************
1783
.TP
1784
.B \-\-up-restart
1785
Enable the
1786
.B \-\-up
1787
and
1788
.B \-\-down
1789
scripts to be called for restarts as well as initial program start.
1790
This option is described more fully above in the
1791
.B \-\-up
1792
option documentation.
1793
.\"*********************************************************
1794
.TP
1795
.B \-\-setenv name value
1796
Set a custom environmental variable
1797
.B name=value
1798
to pass to script.
1799
.\"*********************************************************
1800
.TP
1801
.B \-\-setenv FORWARD_COMPATIBLE 1
1802
Relax config file syntax checking so that unknown directives
1803
will trigger a warning but not a fatal error,
1804
on the assumption that a given unknown directive might be valid
1805
in future OpenVPN versions.
1806
1807
This option should be used with caution, as there are good security
1808
reasons for having OpenVPN fail if it detects problems in a
1809
config file. Having said that, there are valid reasons for wanting
1810
new software features to gracefully degrade when encountered by
1811
older software versions.
1812
.\"*********************************************************
1813
.TP
1814
.B \-\-setenv-safe name value
1815
Set a custom environmental variable
1816
.B OPENVPN_name=value
1817
to pass to script.
1818
1819
This directive is designed to be pushed by the server to clients,
1820
and the prepending of "OPENVPN_" to the environmental variable
1821
is a safety precaution to prevent a LD_PRELOAD style attack
1822
from a malicious or compromised server.
1823
.\"*********************************************************
1824
.TP
1825
.B \-\-script-security level [method]
1826
This directive offers policy-level control over OpenVPN's usage of external programs
1827
and scripts. Lower
1828
.B level
1829
values are more restrictive, higher values are more permissive. Settings for
1830
.B level:
1831
1832
.B 0 \-\-
1833
Strictly no calling of external programs.
1834
.br
1835
.B 1 \-\-
1836
(Default) Only call built-in executables such as ifconfig, ip, route, or netsh.
1837
.br
1838
.B 2 \-\-
1839
Allow calling of built-in executables and user-defined scripts.
1840
.br
1841
.B 3 \-\-
1842
Allow passwords to be passed to scripts via environmental variables (potentially unsafe).
1843
1844
The
1845
.B method
1846
parameter indicates how OpenVPN should call external commands and scripts.
1847
Settings for
1848
.B method:
1849
1850
.B execve \-\-
1851
(default) Use execve() function on Unix family OSes and CreateProcess() on Windows.
1852
.br
1853
.B system \-\-
1854
Use system() function (deprecated and less safe since the external program command
1855
line is subject to shell expansion).
1856
1857
The
1858
.B \-\-script-security
1859
option was introduced in OpenVPN 2.1_rc9. For configuration file compatibility
1860
with previous OpenVPN versions, use:
1861
.B \-\-script-security 3 system
1862
.\"*********************************************************
1863
.TP
1864
.B \-\-disable-occ
1865
Don't output a warning message if option inconsistencies are detected between
1866
peers. An example of an option inconsistency would be where one peer uses
1867
.B \-\-dev tun
1868
while the other peer uses
1869
.B \-\-dev tap.
1870
1871
Use of this option is discouraged, but is provided as
1872
a temporary fix in situations where a recent version of OpenVPN must
1873
connect to an old version.
1874
.\"*********************************************************
1875
.TP
1876
.B \-\-user user
1877
Change the user ID of the OpenVPN process to
1878
.B user
1879
after initialization, dropping privileges in the process.
1880
This option is useful to protect the system
1881
in the event that some hostile party was able to gain control of
1882
an OpenVPN session. Though OpenVPN's security features make
1883
this unlikely, it is provided as a second line of defense.
1884
1885
By setting
1886
.B user
1887
to
1888
.I nobody
1889
or somebody similarly unprivileged, the hostile party would be
1890
limited in what damage they could cause. Of course once
1891
you take away privileges, you cannot return them
1892
to an OpenVPN session. This means, for example, that if
1893
you want to reset an OpenVPN daemon with a
1894
.B SIGUSR1
1895
signal
1896
(for example in response
1897
to a DHCP reset), you should make use of one or more of the
1898
.B \-\-persist
1899
options to ensure that OpenVPN doesn't need to execute any privileged
1900
operations in order to restart (such as re-reading key files
1901
or running
1902
.BR ifconfig
1903
on the TUN device).
1904
.\"*********************************************************
1905
.TP
1906
.B \-\-group group
1907
Similar to the
1908
.B \-\-user
1909
option,
1910
this option changes the group ID of the OpenVPN process to
1911
.B group
1912
after initialization.
1913
.\"*********************************************************
1914
.TP
1915
.B \-\-cd dir
1916
Change directory to
1917
.B dir
1918
prior to reading any files such as
1919
configuration files, key files, scripts, etc.
1920
.B dir
1921
should be an absolute path, with a leading "/",
1922
and without any references
1923
to the current directory such as "." or "..".
1924
1925
This option is useful when you are running
1926
OpenVPN in
1927
.B \-\-daemon
1928
mode, and you want to consolidate all of
1929
your OpenVPN control files in one location.
1930
.\"*********************************************************
1931
.TP
1932
.B \-\-chroot dir
1933
Chroot to
1934
.B dir
1935
after initialization.
1936
.B \-\-chroot
1937
essentially redefines
1938
.B dir
1939
as being the top
1940
level directory tree (/). OpenVPN will therefore
1941
be unable to access any files outside this tree.
1942
This can be desirable from a security standpoint.
1943
1944
Since the chroot operation is delayed until after
1945
initialization, most OpenVPN options that reference
1946
files will operate in a pre-chroot context.
1947
1948
In many cases, the
1949
.B dir
1950
parameter can point to an empty directory, however
1951
complications can result when scripts or restarts
1952
are executed after the chroot operation.
1953
.\"*********************************************************
1954
.TP
1955
.B \-\-setcon context
1956
Apply SELinux
1957
.B context
1958
after initialization. This
1959
essentially provides the ability to restrict OpenVPN's
1960
rights to only network I/O operations, thanks to
1961
SELinux. This goes further than
1962
.B \-\-user
1963
and
1964
.B \-\-chroot
1965
in that those two, while being great security features,
1966
unfortunately do not protect against privilege escalation
1967
by exploitation of a vulnerable system call. You can of
1968
course combine all three, but please note that since
1969
setcon requires access to /proc you will have to provide
1970
it inside the chroot directory (e.g. with mount \-\-bind).
1971
1972
Since the setcon operation is delayed until after
1973
initialization, OpenVPN can be restricted to just
1974
network-related system calls, whereas by applying the
1975
context before startup (such as the OpenVPN one provided
1976
in the SELinux Reference Policies) you will have to
1977
allow many things required only during initialization.
1978
1979
Like with chroot, complications can result when scripts
1980
or restarts are executed after the setcon operation,
1981
which is why you should really consider using the
1982
.B \-\-persist-key
1983
and
1984
.B \-\-persist-tun
1985
options.
1986
.\"*********************************************************
1987
.TP
1988
.B \-\-daemon [progname]
1989
Become a daemon after all initialization functions are completed.
1990
This option will cause all message and error output to
1991
be sent to the syslog file (such as /var/log/messages),
1992
except for the output of shell scripts and
1993
ifconfig commands,
1994
which will go to /dev/null unless otherwise redirected.
1995
The syslog redirection occurs immediately at the point
1996
that
1997
.B \-\-daemon
1998
is parsed on the command line even though
1999
the daemonization point occurs later. If one of the
2000
.B \-\-log
2001
options is present, it will supercede syslog
2002
redirection.
2003
2004
The optional
2005
.B progname
2006
parameter will cause OpenVPN to report its program name
2007
to the system logger as
2008
.B progname.
2009
This can be useful in linking OpenVPN messages
2010
in the syslog file with specific tunnels.
2011
When unspecified,
2012
.B progname
2013
defaults to "openvpn".
2014
2015
When OpenVPN is run with the
2016
.B \-\-daemon
2017
option, it will try to delay daemonization until the majority of initialization
2018
functions which are capable of generating fatal errors are complete. This means
2019
that initialization scripts can test the return status of the
2020
openvpn command for a fairly reliable indication of whether the command
2021
has correctly initialized and entered the packet forwarding event loop.
2022
2023
In OpenVPN, the vast majority of errors which occur after initialization are non-fatal.
2024
.\"*********************************************************
2025
.TP
2026
.B \-\-syslog [progname]
2027
Direct log output to system logger, but do not become a daemon.
2028
See
2029
.B \-\-daemon
2030
directive above for description of
2031
.B progname
2032
parameter.
2033
.\"*********************************************************
2034
.TP
2035
.B \-\-passtos
2036
Set the TOS field of the tunnel packet to what the payload's TOS is.
2037
.\"*********************************************************
2038
.TP
2039
.B \-\-inetd [wait|nowait] [progname]
2040
Use this option when OpenVPN is being run from the inetd or
2041
.BR xinetd(8)
2042
server.
2043
2044
The
2045
.B wait/nowait
2046
option must match what is specified in the inetd/xinetd
2047
config file. The
2048
.B nowait
2049
mode can only be used with
2050
.B \-\-proto tcp-server.
2051
The default is
2052
.B wait.
2053
The
2054
.B nowait
2055
mode can be used to instantiate the OpenVPN daemon as a classic TCP server,
2056
where client connection requests are serviced on a single
2057
port number. For additional information on this kind of configuration,
2058
see the OpenVPN FAQ:
2059
.I http://openvpn.net/faq.html#oneport
2060
2061
This option precludes the use of
2062
.B \-\-daemon, \-\-local,
2063
or
2064
.B \-\-remote.
2065
Note that this option causes message and error output to be handled in the same
2066
way as the
2067
.B \-\-daemon
2068
option. The optional
2069
.B progname
2070
parameter is also handled exactly as in
2071
.B \-\-daemon.
2072
2073
Also note that in
2074
.B wait
2075
mode, each OpenVPN tunnel requires a separate TCP/UDP port and
2076
a separate inetd or xinetd entry. See the OpenVPN 1.x HOWTO for an example
2077
on using OpenVPN with xinetd:
2078
.I http://openvpn.net/1xhowto.html
2079
.\"*********************************************************
2080
.TP
2081
.B \-\-log file
2082
Output logging messages to
2083
.B file,
2084
including output to stdout/stderr which
2085
is generated by called scripts.
2086
If
2087
.B file
2088
already exists it will be truncated.
2089
This option takes effect
2090
immediately when it is parsed in the command line
2091
and will supercede syslog output if
2092
.B \-\-daemon
2093
or
2094
.B \-\-inetd
2095
is also specified.
2096
This option is persistent over the entire course of
2097
an OpenVPN instantiation and will not be reset by SIGHUP,
2098
SIGUSR1, or
2099
.B \-\-ping-restart.
2100
2101
Note that on Windows, when OpenVPN is started as a service,
2102
logging occurs by default without the need to specify
2103
this option.
2104
.\"*********************************************************
2105
.TP
2106
.B \-\-log-append file
2107
Append logging messages to
2108
.B file.
2109
If
2110
.B file
2111
does not exist, it will be created.
2112
This option behaves exactly like
2113
.B \-\-log
2114
except that it appends to rather
2115
than truncating the log file.
2116
.\"*********************************************************
2117
.TP
2118
.B \-\-suppress-timestamps
2119
Avoid writing timestamps to log messages, even when they
2120
otherwise would be prepended. In particular, this applies to
2121
log messages sent to stdout.
2122
.\"*********************************************************
2123
.TP
2124
.B \-\-writepid file
2125
Write OpenVPN's main process ID to
2126
.B file.
2127
.\"*********************************************************
2128
.TP
2129
.B \-\-nice n
2130
Change process priority after initialization
2131
(
2132
.B n
2133
greater than 0 is lower priority,
2134
.B n
2135
less than zero is higher priority).
2136
.\"*********************************************************
2137
.\".TP
2138
.\".B \-\-nice-work n
2139
.\"Change priority of background TLS work thread. The TLS thread
2140
.\"feature is enabled when OpenVPN is built
2141
.\"with pthread support, and you are running OpenVPN
2142
.\"in TLS mode (i.e. with
2143
.\".B \-\-tls-client
2144
.\"or
2145
.\".B \-\-tls-server
2146
.\"specified).
2147
.\"
2148
.\"Using a TLS thread offloads the CPU-intensive process of SSL/TLS-based
2149
.\"key exchange to a background thread so that it does not become
2150
.\"a latency bottleneck in the tunnel packet forwarding process.
2151
.\"
2152
.\"The parameter
2153
.\".B n
2154
.\"is interpreted exactly as with the
2155
.\".B \-\-nice
2156
.\"option above, but in relation to the work thread rather
2157
.\"than the main thread.
2158
.\"*********************************************************
2159
.TP
2160
.B \-\-fast-io
2161
(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding
2162
a call to poll/epoll/select prior to the write operation. The purpose
2163
of such a call would normally be to block until the device
2164
or socket is ready to accept the write. Such blocking is unnecessary
2165
on some platforms which don't support write blocking on UDP sockets
2166
or TUN/TAP devices. In such cases, one can optimize the event loop
2167
by avoiding the poll/epoll/select call, improving CPU efficiency
2168
by 5% to 10%.
2169
2170
This option can only be used on non-Windows systems, when
2171
.B \-\-proto udp
2172
is specified, and when
2173
.B \-\-shaper
2174
is NOT specified.
2175
.\"*********************************************************
2176
.TP
2177
.B \-\-multihome
2178
Configure a multi-homed UDP server. This option can be used when
2179
OpenVPN has been configured to listen on all interfaces, and will
2180
attempt to bind client sessions to the interface on which packets
2181
are being received, so that outgoing packets will be sent out
2182
of the same interface. Note that this option is only relevant for
2183
UDP servers and currently is only implemented on Linux.
2184
2185
Note: clients connecting to a
2186
.B \-\-multihome
2187
server should always use the
2188
.B \-\-nobind
2189
option.
2190
.\"*********************************************************
2191
.TP
2192
.B \-\-echo [parms...]
2193
Echo
2194
.B parms
2195
to log output.
2196
2197
Designed to be used to send messages to a controlling application
2198
which is receiving the OpenVPN log output.
2199
.\"*********************************************************
2200
.TP
2201
.B \-\-remap-usr1 signal
2202
Control whether internally or externally
2203
generated SIGUSR1 signals are remapped to
2204
SIGHUP (restart without persisting state) or
2205
SIGTERM (exit).
2206
2207
.B signal
2208
can be set to "SIGHUP" or "SIGTERM". By default, no remapping
2209
occurs.
2210
.\"*********************************************************
2211
.TP
2212
.B \-\-verb n
2213
Set output verbosity to
2214
.B n
2215
(default=1). Each level shows all info from the previous levels.
2216
Level 3 is recommended if you want a good summary
2217
of what's happening without being swamped by output.
2218
2219
.B 0 \-\-
2220
No output except fatal errors.
2221
.br
2222
.B 1 to 4 \-\-
2223
Normal usage range.
2224
.br
2225
.B 5 \-\-
2226
Output
2227
.B R
2228
and
2229
.B W
2230
characters to the console for each packet read and write, uppercase is
2231
used for TCP/UDP packets and lowercase is used for TUN/TAP packets.
2232
.br
2233
.B 6 to 11 \-\-
2234
Debug info range (see errlevel.h for additional
2235
information on debug levels).
2236
.\"*********************************************************
2237
.TP
2238
.B \-\-status file [n]
2239
Write operational status to
2240
.B file
2241
every
2242
.B n
2243
seconds.
2244
2245
Status can also be written to the syslog by sending a
2246
.B SIGUSR2
2247
signal.
2248
.\"*********************************************************
2249
.TP
2250
.B \-\-status-version [n]
2251
Choose the status file format version number. Currently
2252
.B n
2253
can be 1, 2, or 3 and defaults to 1.
2254
.\"*********************************************************
2255
.TP
2256
.B \-\-mute n
2257
Log at most
2258
.B n
2259
consecutive messages in the same category. This is useful to
2260
limit repetitive logging of similar message types.
2261
.\"*********************************************************
2262
.TP
2263
.B \-\-comp-lzo [mode]
2264
Use fast LZO compression \-\- may add up to 1 byte per
2265
packet for incompressible data.
2266
.B mode
2267
may be "yes", "no", or "adaptive" (default).
2268
2269
In a server mode setup, it is possible to selectively turn
2270
compression on or off for individual clients.
2271
2272
First, make sure the client-side config file enables selective
2273
compression by having at least one
2274
.B \-\-comp-lzo
2275
directive, such as
2276
.B \-\-comp-lzo no.
2277
This will turn off compression by default,
2278
but allow a future directive push from the server to
2279
dynamically change the
2280
on/off/adaptive setting.
2281
2282
Next in a
2283
.B \-\-client-config-dir
2284
file, specify the compression setting for the client,
2285
for example:
2286
2287
.nf
2288
.ft 3
2289
.in +4
2290
comp-lzo yes
2291
push "comp-lzo yes"
2292
.in -4
2293
.ft
2294
.fi
2295
2296
The first line sets the
2297
.B comp-lzo
2298
setting for the server
2299
side of the link, the second sets the client side.
2300
.\"*********************************************************
2301
.TP
2302
.B \-\-comp-noadapt
2303
When used in conjunction with
2304
.B \-\-comp-lzo,
2305
this option will disable OpenVPN's adaptive compression algorithm.
2306
Normally, adaptive compression is enabled with
2307
.B \-\-comp-lzo.
2308
2309
Adaptive compression tries to optimize the case where you have
2310
compression enabled, but you are sending predominantly uncompressible
2311
(or pre-compressed) packets over the tunnel, such as an FTP or rsync transfer
2312
of a large, compressed file. With adaptive compression,
2313
OpenVPN will periodically sample the compression process to measure its
2314
efficiency. If the data being sent over the tunnel is already compressed,
2315
the compression efficiency will be very low, triggering openvpn to disable
2316
compression for a period of time until the next re-sample test.
2317
.\"*********************************************************
2318
.TP
2319
.B \-\-management IP port [pw-file]
2320
Enable a TCP server on
2321
.B IP:port
2322
to handle daemon management functions.
2323
.B pw-file,
2324
if specified,
2325
is a password file (password on first line)
2326
or "stdin" to prompt from standard input. The password
2327
provided will set the password which TCP clients will need
2328
to provide in order to access management functions.
2329
2330
The management interface can also listen on a unix domain socket,
2331
for those platforms that support it. To use a unix domain socket, specify
2332
the unix socket pathname in place of
2333
.B IP
2334
and set
2335
.B port
2336
to 'unix'. While the default behavior is to create a unix domain socket
2337
that may be connected to by any process, the
2338
.B \-\-management-client-user
2339
and
2340
.B \-\-management-client-group
2341
directives can be used to restrict access.
2342
2343
The management interface provides a special mode where the TCP
2344
management link can operate over the tunnel itself. To enable this mode,
2345
set
2346
.B IP
2347
= "tunnel". Tunnel mode will cause the management interface
2348
to listen for a TCP connection on the local VPN address of the
2349
TUN/TAP interface.
2350
2351
While the management port is designed for programmatic control
2352
of OpenVPN by other applications, it is possible to telnet
2353
to the port, using a telnet client in "raw" mode. Once connected,
2354
type "help" for a list of commands.
2355
2356
For detailed documentation on the management interface, see
2357
the management-notes.txt file in the
2358
.B management
2359
folder of
2360
the OpenVPN source distribution.
2361
2362
It is strongly recommended that
2363
.B IP
2364
be set to 127.0.0.1
2365
(localhost) to restrict accessibility of the management
2366
server to local clients.
2367
.TP
2368
.B \-\-management-client
2369
Management interface will connect as a TCP client to
2370
.B IP:port
2371
specified by
2372
.B \-\-management
2373
rather than listen as a TCP server.
2374
.\"*********************************************************
2375
.TP
2376
.B \-\-management-query-passwords
2377
Query management channel for private key password and
2378
.B \-\-auth-user-pass
2379
username/password. Only query the management channel
2380
for inputs which ordinarily would have been queried from the
2381
console.
2382
.\"*********************************************************
2383
.TP
2384
.B \-\-management-forget-disconnect
2385
Make OpenVPN forget passwords when management session
2386
disconnects.
2387
2388
This directive does not affect the
2389
.B \-\-http-proxy
2390
username/password. It is always cached.
2391
.\"*********************************************************
2392
.TP
2393
.B \-\-management-hold
2394
Start OpenVPN in a hibernating state, until a client
2395
of the management interface explicitly starts it
2396
with the
2397
.B hold release
2398
command.
2399
.\"*********************************************************
2400
.TP
2401
.B \-\-management-signal
2402
Send SIGUSR1 signal to OpenVPN if management session disconnects.
2403
This is useful when you wish to disconnect an OpenVPN session on
2404
user logoff.
2405
.\"*********************************************************
2406
.TP
2407
.B \-\-management-log-cache n
2408
Cache the most recent
2409
.B n
2410
lines of log file history for usage
2411
by the management channel.
2412
.\"*********************************************************
2413
.TP
2414
.B \-\-management-client-auth
2415
Gives management interface client the responsibility
2416
to authenticate clients after their client certificate
2417
has been verified. See management-notes.txt in OpenVPN
2418
distribution for detailed notes.
2419
.\"*********************************************************
2420
.TP
2421
.B \-\-management-client-pf
2422
Management interface clients must specify a packet
2423
filter file for each connecting client. See management-notes.txt
2424
in OpenVPN distribution for detailed notes.
2425
.\"*********************************************************
2426
.TP
2427
.B \-\-management-client-user u
2428
When the management interface is listening on a unix domain socket,
2429
only allow connections from user
2430
.B u.
2431
.\"*********************************************************
2432
.TP
2433
.B \-\-management-client-group g
2434
When the management interface is listening on a unix domain socket,
2435
only allow connections from group
2436
.B g.
2437
.\"*********************************************************
2438
.TP
2439
.B \-\-plugin module-pathname [init-string]
2440
Load plug-in module from the file
2441
.B module-pathname,
2442
passing
2443
.B init-string
2444
as an argument
2445
to the module initialization function. Multiple
2446
plugin modules may be loaded into one OpenVPN
2447
process.
2448
2449
For more information and examples on how to build OpenVPN
2450
plug-in modules, see the README file in the
2451
.B plugin
2452
folder of the OpenVPN source distribution.
2453
2454
If you are using an RPM install of OpenVPN, see
2455
/usr/share/openvpn/plugin. The documentation is
2456
in
2457
.B doc
2458
and the actual plugin modules are in
2459
.B lib.
2460
2461
Multiple plugin modules can be cascaded, and modules can be
2462
used in tandem with scripts. The modules will be called by
2463
OpenVPN in the order that they are declared in the config
2464
file. If both a plugin and script are configured for the same
2465
callback, the script will be called last. If the
2466
return code of the module/script controls an authentication
2467
function (such as tls-verify, auth-user-pass-verify, or
2468
client-connect), then
2469
every module and script must return success (0) in order for
2470
the connection to be authenticated.
2471
.\"*********************************************************
2472
.SS Server Mode
2473
Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode
2474
is supported, and can be enabled with the
2475
.B \-\-mode server
2476
option. In server mode, OpenVPN will listen on a single
2477
port for incoming client connections. All client
2478
connections will be routed through a single tun or tap
2479
interface. This mode is designed for scalability and should
2480
be able to support hundreds or even thousands of clients
2481
on sufficiently fast hardware. SSL/TLS authentication must
2482
be used in this mode.
2483
.\"*********************************************************
2484
.TP
2485
.B \-\-server network netmask
2486
A helper directive designed to simplify the configuration
2487
of OpenVPN's server mode. This directive will set up an
2488
OpenVPN server which will allocate addresses to clients
2489
out of the given network/netmask. The server itself
2490
will take the ".1" address of the given network
2491
for use as the server-side endpoint of the local
2492
TUN/TAP interface.
2493
2494
For example,
2495
.B \-\-server 10.8.0.0 255.255.255.0
2496
expands as follows:
2497
2498
.nf
2499
.ft 3
2500
.in +4
2501
mode server
2502
tls-server
2503
push "topology [topology]"
2504
2505
if dev tun AND (topology == net30 OR topology == p2p):
2506
ifconfig 10.8.0.1 10.8.0.2
2507
if !nopool:
2508
ifconfig-pool 10.8.0.4 10.8.0.251
2509
route 10.8.0.0 255.255.255.0
2510
if client-to-client:
2511
push "route 10.8.0.0 255.255.255.0"
2512
else if topology == net30:
2513
push "route 10.8.0.1"
2514
2515
if dev tap OR (dev tun AND topology == subnet):
2516
ifconfig 10.8.0.1 255.255.255.0
2517
if !nopool:
2518
ifconfig-pool 10.8.0.2 10.8.0.254 255.255.255.0
2519
push "route-gateway 10.8.0.1"
2520
.in -4
2521
.ft
2522
.fi
2523
2524
Don't use
2525
.B \-\-server
2526
if you are ethernet bridging. Use
2527
.B \-\-server-bridge
2528
instead.
2529
.\"*********************************************************
2530
.TP
2531
.B \-\-server-bridge gateway netmask pool-start-IP pool-end-IP
2532
.TP
2533
.B \-\-server-bridge ['nogw']
2534
2535
A helper directive similar to
2536
.B \-\-server
2537
which is designed to simplify the configuration
2538
of OpenVPN's server mode in ethernet bridging configurations.
2539
2540
If
2541
.B \-\-server-bridge
2542
is used without any parameters, it will enable a DHCP-proxy
2543
mode, where connecting OpenVPN clients will receive an IP
2544
address for their TAP adapter from the DHCP server running
2545
on the OpenVPN server-side LAN.
2546
Note that only clients that support
2547
the binding of a DHCP client with the TAP adapter (such as
2548
Windows) can support this mode. The optional
2549
.B nogw
2550
flag (advanced) indicates that gateway information should not be
2551
pushed to the client.
2552
2553
To configure ethernet bridging, you
2554
must first use your OS's bridging capability
2555
to bridge the TAP interface with the ethernet
2556
NIC interface. For example, on Linux this is done
2557
with the
2558
.B brctl
2559
tool, and with Windows XP it is done in the Network
2560
Connections Panel by selecting the ethernet and
2561
TAP adapters and right-clicking on "Bridge Connections".
2562
2563
Next you you must manually set the
2564
IP/netmask on the bridge interface. The
2565
.B gateway
2566
and
2567
.B netmask
2568
parameters to
2569
.B \-\-server-bridge
2570
can be set to either the IP/netmask of the
2571
bridge interface, or the IP/netmask of the
2572
default gateway/router on the bridged
2573
subnet.
2574
2575
Finally, set aside a IP range in the bridged
2576
subnet,
2577
denoted by
2578
.B pool-start-IP
2579
and
2580
.B pool-end-IP,
2581
for OpenVPN to allocate to connecting
2582
clients.
2583
2584
For example,
2585
.B server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 10.8.0.254
2586
expands as follows:
2587
2588
.nf
2589
.ft 3
2590
.in +4
2591
mode server
2592
tls-server
2593
2594
ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0
2595
push "route-gateway 10.8.0.4"
2596
.in -4
2597
.ft
2598
.fi
2599
2600
In another example,
2601
.B \-\-server-bridge
2602
(without parameters) expands as follows:
2603
2604
.nf
2605
.ft 3
2606
.in +4
2607
mode server
2608
tls-server
2609
2610
push "route-gateway dhcp"
2611
.in -4
2612
.ft
2613
.fi
2614
2615
Or
2616
.B \-\-server-bridge nogw
2617
expands as follows:
2618
2619
.nf
2620
.ft 3
2621
.in +4
2622
mode server
2623
tls-server
2624
.in -4
2625
.ft
2626
.fi
2627
.\"*********************************************************
2628
.TP
2629
.B \-\-push "option"
2630
Push a config file option back to the client for remote
2631
execution. Note that
2632
.B
2633
option
2634
must be enclosed in double quotes (""). The client must specify
2635
.B \-\-pull
2636
in its config file. The set of options which can be
2637
pushed is limited by both feasibility and security.
2638
Some options such as those which would execute scripts
2639
are banned, since they would effectively allow a compromised
2640
server to execute arbitrary code on the client.
2641
Other options such as TLS or MTU parameters
2642
cannot be pushed because the client needs to know
2643
them before the connection to the server can be initiated.
2644
2645
This is a partial list of options which can currently be pushed:
2646
.B \-\-route, \-\-route-gateway, \-\-route-delay, \-\-redirect-gateway,
2647
.B \-\-ip-win32, \-\-dhcp-option,
2648
.B \-\-inactive, \-\-ping, \-\-ping-exit, \-\-ping-restart,
2649
.B \-\-setenv,
2650
.B \-\-persist-key, \-\-persist-tun, \-\-echo,
2651
.B \-\-comp-lzo,
2652
.B \-\-socket-flags,
2653
.B \-\-sndbuf, \-\-rcvbuf
2654
.\"*********************************************************
2655
.TP
2656
.B \-\-push-reset
2657
Don't inherit the global push list for a specific client instance.
2658
Specify this option in a client-specific context such
2659
as with a
2660
.B \-\-client-config-dir
2661
configuration file. This option will ignore
2662
.B \-\-push
2663
options at the global config file level.
2664
.\"*********************************************************
2665
.TP
2666
.B \-\-disable
2667
Disable a particular client (based on the common name)
2668
from connecting. Don't use this option to disable a client
2669
due to key or password compromise. Use a CRL (certificate
2670
revocation list) instead (see the
2671
.B \-\-crl-verify
2672
option).
2673
2674
This option must be associated with a specific client instance,
2675
which means that it must be specified either in a client
2676
instance config file using
2677
.B \-\-client-config-dir
2678
or dynamically generated using a
2679
.B \-\-client-connect
2680
script.
2681
.\"*********************************************************
2682
.TP
2683
.B \-\-ifconfig-pool start-IP end-IP [netmask]
2684
Set aside a pool of subnets to be
2685
dynamically allocated to connecting clients, similar
2686
to a DHCP server. For tun-style
2687
tunnels, each client will be given a /30 subnet (for
2688
interoperability with Windows clients). For tap-style
2689
tunnels, individual addresses will be allocated, and the
2690
optional
2691
.B netmask
2692
parameter will also be pushed to clients.
2693
2694
.\"*********************************************************
2695
.TP
2696
.B \-\-ifconfig-pool-persist file [seconds]
2697
Persist/unpersist ifconfig-pool
2698
data to
2699
.B file,
2700
at
2701
.B seconds
2702
intervals (default=600), as well as on program startup and
2703
shutdown.
2704
2705
The goal of this option is to provide a long-term association
2706
between clients (denoted by their common name) and the virtual
2707
IP address assigned to them from the ifconfig-pool.
2708
Maintaining a long-term
2709
association is good for clients because it allows them
2710
to effectively use the
2711
.B \-\-persist-tun
2712
option.
2713
2714
.B file
2715
is a comma-delimited ASCII file, formatted as
2716
<Common-Name>,<IP-address>.
2717
2718
If
2719
.B seconds
2720
= 0,
2721
.B file
2722
will be treated as read-only. This is useful if
2723
you would like to treat
2724
.B file
2725
as a configuration file.
2726
2727
Note that the entries in this file are treated by OpenVPN as
2728
suggestions only, based on past associations between
2729
a common name and IP address. They do not guarantee that the given common
2730
name will always receive the given IP address. If you want guaranteed
2731
assignment, use
2732
.B \-\-ifconfig-push
2733
.\"*********************************************************
2734
.TP
2735
.B \-\-ifconfig-pool-linear
2736
Modifies the
2737
.B \-\-ifconfig-pool
2738
directive to
2739
allocate individual TUN interface addresses for
2740
clients rather than /30 subnets. NOTE: This option
2741
is incompatible with Windows clients.
2742
2743
This option is deprecated, and should be replaced with
2744
.B \-\-topology p2p
2745
which is functionally equivalent.
2746
.\"*********************************************************
2747
.TP
2748
.B \-\-ifconfig-push local remote-netmask
2749
Push virtual IP endpoints for client tunnel,
2750
overriding the \-\-ifconfig-pool dynamic allocation.
2751
2752
The parameters
2753
.B local
2754
and
2755
.B remote-netmask
2756
are set according to the
2757
.B \-\-ifconfig
2758
directive which you want to execute on the client machine to
2759
configure the remote end of the tunnel. Note that the parameters
2760
.B local
2761
and
2762
.B remote-netmask
2763
are from the perspective of the client, not the server. They may be
2764
DNS names rather than IP addresses, in which case they will be resolved
2765
on the server at the time of client connection.
2766
2767
This option must be associated with a specific client instance,
2768
which means that it must be specified either in a client
2769
instance config file using
2770
.B \-\-client-config-dir
2771
or dynamically generated using a
2772
.B \-\-client-connect
2773
script.
2774
2775
Remember also to include a
2776
.B \-\-route
2777
directive in the main OpenVPN config file which encloses
2778
.B local,
2779
so that the kernel will know to route it
2780
to the server's TUN/TAP interface.
2781
2782
OpenVPN's internal client IP address selection algorithm works as
2783
follows:
2784
2785
.B 1
2786
\-\- Use
2787
.B \-\-client-connect script
2788
generated file for static IP (first choice).
2789
.br
2790
.B 2
2791
\-\- Use
2792
.B \-\-client-config-dir
2793
file for static IP (next choice).
2794
.br
2795
.B 3
2796
\-\- Use
2797
.B \-\-ifconfig-pool
2798
allocation for dynamic IP (last choice).
2799
.br
2800
.\"*********************************************************
2801
.TP
2802
.B \-\-iroute network [netmask]
2803
Generate an internal route to a specific
2804
client. The
2805
.B netmask
2806
parameter, if omitted, defaults to 255.255.255.255.
2807
2808
This directive can be used to route a fixed subnet from
2809
the server to a particular client, regardless
2810
of where the client is connecting from. Remember
2811
that you must also add the route to the system
2812
routing table as well (such as by using the
2813
.B \-\-route
2814
directive). The reason why two routes are needed
2815
is that the
2816
.B \-\-route
2817
directive routes the packet from the kernel
2818
to OpenVPN. Once in OpenVPN, the
2819
.B \-\-iroute
2820
directive routes to the specific client.
2821
2822
This option must be specified either in a client
2823
instance config file using
2824
.B \-\-client-config-dir
2825
or dynamically generated using a
2826
.B \-\-client-connect
2827
script.
2828
2829
The
2830
.B \-\-iroute
2831
directive also has an important interaction with
2832
.B \-\-push
2833
"route ...".
2834
.B \-\-iroute
2835
essentially defines a subnet which is owned by a
2836
particular client (we will call this client A).
2837
If you would like other clients to be able to reach A's
2838
subnet, you can use
2839
.B \-\-push
2840
"route ..."
2841
together with
2842
.B \-\-client-to-client
2843
to effect this. In order for all clients to see
2844
A's subnet, OpenVPN must push this route to all clients
2845
EXCEPT for A, since the subnet is already owned by A.
2846
OpenVPN accomplishes this by not
2847
not pushing a route to a client
2848
if it matches one of the client's iroutes.
2849
.\"*********************************************************
2850
.TP
2851
.B \-\-client-to-client
2852
Because the OpenVPN server mode handles multiple clients
2853
through a single tun or tap interface, it is effectively
2854
a router. The
2855
.B \-\-client-to-client
2856
flag tells OpenVPN to internally route client-to-client
2857
traffic rather than pushing all client-originating traffic
2858
to the TUN/TAP interface.
2859
2860
When this option is used, each client will "see" the other
2861
clients which are currently connected. Otherwise, each
2862
client will only see the server. Don't use this option
2863
if you want to firewall tunnel traffic using
2864
custom, per-client rules.
2865
.\"*********************************************************
2866
.TP
2867
.B \-\-duplicate-cn
2868
Allow multiple clients with the same common name to concurrently connect.
2869
In the absence of this option, OpenVPN will disconnect a client instance
2870
upon connection of a new client having the same common name.
2871
.\"*********************************************************
2872
.TP
2873
.B \-\-client-connect script
2874
Run
2875
.B script
2876
on client connection. The script is passed the common name
2877
and IP address of the just-authenticated client
2878
as environmental variables (see environmental variable section
2879
below). The script is also passed
2880
the pathname of a freshly created temporary file as $1
2881
(i.e. the first command line argument), to be used by the script
2882
to pass dynamically generated config file directives back to OpenVPN.
2883
2884
If the script wants to generate a dynamic config file
2885
to be applied on the server when the client connects,
2886
it should write it to the file named by $1.
2887
2888
See the
2889
.B \-\-client-config-dir
2890
option below for options which
2891
can be legally used in a dynamically generated config file.
2892
2893
Note that the return value of
2894
.B script
2895
is significant. If
2896
.B script
2897
returns a non-zero error status, it will cause the client
2898
to be disconnected.
2899
.\"*********************************************************
2900
.TP
2901
.B \-\-client-disconnect
2902
Like
2903
.B \-\-client-connect
2904
but called on client instance shutdown. Will not be called
2905
unless the
2906
.B \-\-client-connect
2907
script and plugins (if defined)
2908
were previously called on this instance with
2909
successful (0) status returns.
2910
2911
The exception to this rule is if the
2912
.B \-\-client-disconnect
2913
script or plugins are cascaded, and at least one client-connect
2914
function succeeded, then ALL of the client-disconnect functions for
2915
scripts and plugins will be called on client instance object deletion,
2916
even in cases where some of the related client-connect functions returned
2917
an error status.
2918
.B
2919
.\"*********************************************************
2920
.TP
2921
.B \-\-client-config-dir dir
2922
Specify a directory
2923
.B dir
2924
for custom client config files. After
2925
a connecting client has been authenticated, OpenVPN will
2926
look in this directory for a file having the same name
2927
as the client's X509 common name. If a matching file
2928
exists, it will be opened and parsed for client-specific
2929
configuration options. If no matching file is found, OpenVPN
2930
will instead try to open and parse a default file called
2931
"DEFAULT", which may be provided but is not required. Note that
2932
the configuration files must be readable by the OpenVPN process
2933
after it has dropped it's root privileges.
2934
2935
This file can specify a fixed IP address for a given
2936
client using
2937
.B \-\-ifconfig-push,
2938
as well as fixed subnets owned by the client using
2939
.B \-\-iroute.
2940
2941
One of the useful properties of this option is that it
2942
allows client configuration files to be conveniently
2943
created, edited, or removed while the server is live,
2944
without needing to restart the server.
2945
2946
The following
2947
options are legal in a client-specific context:
2948
.B \-\-push, \-\-push-reset, \-\-iroute, \-\-ifconfig-push,
2949
and
2950
.B \-\-config.
2951
.\"*********************************************************
2952
.TP
2953
.B \-\-ccd-exclusive
2954
Require, as a
2955
condition of authentication, that a connecting client has a
2956
.B \-\-client-config-dir
2957
file.
2958
.\"*********************************************************
2959
.TP
2960
.B \-\-tmp-dir dir
2961
Specify a directory
2962
.B dir
2963
for temporary files. This directory will be used by
2964
openvpn processes and script to communicate temporary
2965
data with openvpn main process. Note that
2966
the directory must be writable by the OpenVPN process
2967
after it has dropped it's root privileges.
2968
2969
This directory will be used by in the following cases:
2970
2971
*
2972
.B \-\-client-connect
2973
scripts to dynamically generate client-specific
2974
configuration files.
2975
2976
*
2977
.B OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY
2978
plugin hook to return success/failure via auth_control_file
2979
when using deferred auth method
2980
2981
*
2982
.B OPENVPN_PLUGIN_ENABLE_PF
2983
plugin hook to pass filtering rules via pf_file
2984
.\"*********************************************************
2985
.TP
2986
.B \-\-hash-size r v
2987
Set the size of the real address hash table to
2988
.B r
2989
and the virtual address table to
2990
.B v.
2991
By default, both tables are sized at 256 buckets.
2992
.\"*********************************************************
2993
.TP
2994
.B \-\-bcast-buffers n
2995
Allocate
2996
.B n
2997
buffers for broadcast datagrams (default=256).
2998
.\"*********************************************************
2999
.TP
3000
.B \-\-tcp-queue-limit n
3001
Maximum number of output packets queued before TCP (default=64).
3002
3003
When OpenVPN is tunneling data from a TUN/TAP device to a
3004
remote client over a TCP connection, it is possible that the TUN/TAP device
3005
might produce data at a faster rate than the TCP connection
3006
can support. When the number of output packets queued before sending to
3007
the TCP socket reaches this limit for a given client connection,
3008
OpenVPN will start to drop outgoing packets directed
3009
at this client.
3010
.\"*********************************************************
3011
.TP
3012
.B \-\-tcp-nodelay
3013
This macro sets the TCP_NODELAY socket flag on the server
3014
as well as pushes it to connecting clients. The TCP_NODELAY
3015
flag disables the Nagle algorithm on TCP sockets causing
3016
packets to be transmitted immediately with low latency,
3017
rather than waiting a short period of time in order
3018
to aggregate several packets into a larger containing
3019
packet. In VPN applications over TCP, TCP_NODELAY
3020
is generally a good latency optimization.
3021
3022
The macro expands as follows:
3023
3024
.nf
3025
.ft 3
3026
.in +4
3027
if mode server:
3028
socket-flags TCP_NODELAY
3029
push "socket-flags TCP_NODELAY"
3030
.in -4
3031
.ft
3032
.fi
3033
.\"*********************************************************
3034
.TP
3035
.B \-\-max-clients n
3036
Limit server to a maximum of
3037
.B n
3038
concurrent clients.
3039
.\"*********************************************************
3040
.TP
3041
.B \-\-max-routes-per-client n
3042
Allow a maximum of
3043
.B n
3044
internal routes per client (default=256).
3045
This is designed to
3046
help contain DoS attacks where an authenticated client floods the
3047
server with packets appearing to come from many unique MAC addresses,
3048
forcing the server to deplete
3049
virtual memory as its internal routing table expands.
3050
This directive can be used in a
3051
.B \-\-client-config-dir
3052
file or auto-generated by a
3053
.B \-\-client-connect
3054
script to override the global value for a particular client.
3055
3056
Note that this
3057
directive affects OpenVPN's internal routing table, not the
3058
kernel routing table.
3059
.\"*********************************************************
3060
.TP
3061
.B \-\-connect-freq n sec
3062
Allow a maximum of
3063
.B n
3064
new connections per
3065
.B sec
3066
seconds from clients. This is designed to contain DoS attacks which flood
3067
the server with connection requests using certificates which
3068
will ultimately fail to authenticate.
3069
3070
This is an imperfect solution however, because in a real
3071
DoS scenario, legitimate connections might also be refused.
3072
3073
For the best protection against DoS attacks in server mode,
3074
use
3075
.B \-\-proto udp
3076
and
3077
.B \-\-tls-auth.
3078
.\"*********************************************************
3079
.TP
3080
.B \-\-learn-address cmd
3081
Run script or shell command
3082
.B cmd
3083
to validate client virtual addresses or routes.
3084
3085
.B cmd
3086
will be executed with 3 parameters:
3087
3088
.B [1] operation \-\-
3089
"add", "update", or "delete" based on whether or not
3090
the address is being added to, modified, or deleted from
3091
OpenVPN's internal routing table.
3092
.br
3093
.B [2] address \-\-
3094
The address being learned or unlearned. This can be
3095
an IPv4 address such as "198.162.10.14", an IPv4 subnet
3096
such as "198.162.10.0/24", or an ethernet MAC address (when
3097
.B \-\-dev tap
3098
is being used) such as "00:FF:01:02:03:04".
3099
.br
3100
.B [3] common name \-\-
3101
The common name on the certificate associated with the
3102
client linked to this address. Only present for "add"
3103
or "update" operations, not "delete".
3104
3105
On "add" or "update" methods, if the script returns
3106
a failure code (non-zero), OpenVPN will reject the address
3107
and will not modify its internal routing table.
3108
3109
Normally, the
3110
.B cmd
3111
script will use the information provided above to set
3112
appropriate firewall entries on the VPN TUN/TAP interface.
3113
Since OpenVPN provides the association between virtual IP
3114
or MAC address and the client's authenticated common name,
3115
it allows a user-defined script to configure firewall access
3116
policies with regard to the client's high-level common name,
3117
rather than the low level client virtual addresses.
3118
.\"*********************************************************
3119
.TP
3120
.B \-\-auth-user-pass-verify script method
3121
Require the client to provide a username/password (possibly
3122
in addition to a client certificate) for authentication.
3123
3124
OpenVPN will execute
3125
.B script
3126
as a shell command to validate the username/password
3127
provided by the client.
3128
3129
If
3130
.B method
3131
is set to "via-env", OpenVPN will call
3132
.B script
3133
with the environmental variables
3134
.B username
3135
and
3136
.B password
3137
set to the username/password strings provided by the client.
3138
Be aware that this method is insecure on some platforms which
3139
make the environment of a process publicly visible to other
3140
unprivileged processes.
3141
3142
If
3143
.B method
3144
is set to "via-file", OpenVPN will write the username and
3145
password to the first two lines of a temporary file. The filename
3146
will be passed as an argument to
3147
.B script,
3148
and the file will be automatically deleted by OpenVPN after
3149
the script returns. The location of the temporary file is
3150
controlled by the
3151
.B \-\-tmp-dir
3152
option, and will default to the current directory if unspecified.
3153
For security, consider setting
3154
.B \-\-tmp-dir
3155
to a volatile storage medium such as
3156
.B /dev/shm
3157
(if available) to prevent the username/password file from touching the hard drive.
3158
3159
The script should examine the username
3160
and password,
3161
returning a success exit code (0) if the
3162
client's authentication request is to be accepted, or a failure
3163
code (1) to reject the client.
3164
3165
This directive is designed to enable a plugin-style interface
3166
for extending OpenVPN's authentication capabilities.
3167
3168
To protect against a client passing a maliciously formed
3169
username or password string, the username string must
3170
consist only of these characters: alphanumeric, underbar
3171
('_'), dash ('-'), dot ('.'), or at ('@'). The password
3172
string can consist of any printable characters except for
3173
CR or LF. Any illegal characters in either the username
3174
or password string will be converted to underbar ('_').
3175
3176
Care must be taken by any user-defined scripts to avoid
3177
creating a security vulnerability in the way that these
3178
strings are handled. Never use these strings in such a way
3179
that they might be escaped or evaluated by a shell interpreter.
3180
3181
For a sample script that performs PAM authentication, see
3182
.B sample-scripts/auth-pam.pl
3183
in the OpenVPN source distribution.
3184
.\"*********************************************************
3185
.TP
3186
.B \-\-opt-verify
3187
Clients that connect with options that are incompatible
3188
with those of the server will be disconnected.
3189
3190
Options that will be compared for compatibility include
3191
dev-type, link-mtu, tun-mtu, proto, tun-ipv6, ifconfig,
3192
comp-lzo, fragment, keydir, cipher, auth, keysize, secret,
3193
no-replay, no-iv, tls-auth, key-method, tls-server, and tls-client.
3194
3195
This option requires that
3196
.B \-\-disable-occ
3197
NOT be used.
3198
.\"*********************************************************
3199
.TP
3200
.B \-\-auth-user-pass-optional
3201
Allow connections by clients that do not specify a username/password.
3202
Normally, when
3203
.B \-\-auth-user-pass-verify
3204
or
3205
.B \-\-management-client-auth
3206
is specified (or an authentication plugin module), the
3207
OpenVPN server daemon will require connecting clients to specify a
3208
username and password. This option makes the submission of a username/password
3209
by clients optional, passing the responsibility to the user-defined authentication
3210
module/script to accept or deny the client based on other factors
3211
(such as the setting of X509 certificate fields). When this option is used,
3212
and a connecting client does not submit a username/password, the user-defined
3213
authentication module/script will see the username and password as being set
3214
to empty strings (""). The authentication module/script MUST have logic
3215
to detect this condition and respond accordingly.
3216
.\"*********************************************************
3217
.TP
3218
.B \-\-client-cert-not-required
3219
Don't require client certificate, client will authenticate
3220
using username/password only. Be aware that using this directive
3221
is less secure than requiring certificates from all clients.
3222
3223
If you use this directive, the
3224
entire responsibility of authentication will rest on your
3225
.B \-\-auth-user-pass-verify
3226
script, so keep in mind that bugs in your script
3227
could potentially compromise the security of your VPN.
3228
3229
If you don't use this directive, but you also specify an
3230
.B \-\-auth-user-pass-verify
3231
script, then OpenVPN will perform double authentication. The
3232
client certificate verification AND the
3233
.B \-\-auth-user-pass-verify
3234
script will need to succeed in order for a client to be
3235
authenticated and accepted onto the VPN.
3236
.\"*********************************************************
3237
.TP
3238
.B \-\-username-as-common-name
3239
For
3240
.B \-\-auth-user-pass-verify
3241
authentication, use
3242
the authenticated username as the common name,
3243
rather than the common name from the client cert.
3244
.\"*********************************************************
3245
.TP
3246
.B \-\-no-name-remapping
3247
Allow Common Name, X509 Subject, and username strings to include
3248
any printable character including space, but excluding control
3249
characters such as tab, newline, and carriage-return.
3250
3251
By default, OpenVPN will remap
3252
any character other than alphanumeric, underbar ('_'), dash
3253
('-'), dot ('.'), and slash ('/') to underbar ('_'). The X509
3254
Subject string as returned by the
3255
.B tls_id
3256
environmental variable, can additionally contain colon (':') or
3257
equal ('=').
3258
3259
While name remapping is performed for security reasons to reduce
3260
the possibility of introducing string expansion security vulnerabilities
3261
in user-defined authentication
3262
scripts, this option is provided for those cases where it is desirable to
3263
disable the remapping feature. Don't use this option unless you
3264
know what you are doing!
3265
.\"*********************************************************
3266
.TP
3267
.B \-\-port-share host port
3268
When run in TCP server mode, share the OpenVPN port with
3269
another application, such as an HTTPS server. If OpenVPN
3270
senses a connection to its port which is using a non-OpenVPN
3271
protocol, it will proxy the connection to the server at
3272
.B host:port.
3273
Currently only designed to work with HTTP/HTTPS,
3274
though it would be theoretically possible to extend to
3275
other protocols such as ssh.
3276
3277
Not implemented on Windows.
3278
.\"*********************************************************
3279
.SS Client Mode
3280
Use client mode when connecting to an OpenVPN server
3281
which has
3282
.B \-\-server, \-\-server-bridge,
3283
or
3284
.B \-\-mode server
3285
in it's configuration.
3286
.\"*********************************************************
3287
.TP
3288
.B \-\-client
3289
A helper directive designed to simplify the configuration
3290
of OpenVPN's client mode. This directive is equivalent to:
3291
3292
.nf
3293
.ft 3
3294
.in +4
3295
pull
3296
tls-client
3297
.in -4
3298
.ft
3299
.fi
3300
.\"*********************************************************
3301
.TP
3302
.B \-\-pull
3303
This option must be used on a client which is connecting
3304
to a multi-client server. It indicates to OpenVPN that it
3305
should accept options pushed by the server, provided they
3306
are part of the legal set of pushable options (note that the
3307
.B \-\-pull
3308
option is implied by
3309
.B \-\-client
3310
).
3311
3312
In particular,
3313
.B \-\-pull
3314
allows the server to push routes to the client, so you should
3315
not use
3316
.B \-\-pull
3317
or
3318
.B \-\-client
3319
in situations where you don't trust the server to have control
3320
over the client's routing table.
3321
.\"*********************************************************
3322
.TP
3323
.B \-\-auth-user-pass [up]
3324
Authenticate with server using username/password.
3325
.B up
3326
is a file containing username/password on 2 lines (Note: OpenVPN
3327
will only read passwords from a file if it has been built
3328
with the \-\-enable-password-save configure option, or on Windows
3329
by defining ENABLE_PASSWORD_SAVE in win/settings.in).
3330
3331
If
3332
.B up
3333
is omitted, username/password will be prompted from the
3334
console.
3335
3336
The server configuration must specify an
3337
.B \-\-auth-user-pass-verify
3338
script to verify the username/password provided by
3339
the client.
3340
.\"*********************************************************
3341
.TP
3342
.B \-\-auth-retry type
3343
Controls how OpenVPN responds to username/password verification
3344
errors such as the client-side response to an AUTH_FAILED message from the server
3345
or verification failure of the private key password.
3346
3347
Normally used to prevent auth errors from being fatal
3348
on the client side, and to permit username/password requeries in case
3349
of error.
3350
3351
An AUTH_FAILED message is generated by the server if the client
3352
fails
3353
.B \-\-auth-user-pass
3354
authentication, or if the server-side
3355
.B \-\-client-connect
3356
script returns an error status when the client
3357
tries to connect.
3358
3359
.B type
3360
can be one of:
3361
3362
.B none \-\-
3363
Client will exit with a fatal error (this is the default).
3364
.br
3365
.B nointeract \-\-
3366
Client will retry the connection without requerying for an
3367
.B \-\-auth-user-pass
3368
username/password. Use this option for unattended clients.
3369
.br
3370
.B interact \-\-
3371
Client will requery for an
3372
.B \-\-auth-user-pass
3373
username/password and/or private key password before attempting a reconnection.
3374
3375
Note that while this option cannot be pushed, it can be controlled
3376
from the management interface.
3377
.\"*********************************************************
3378
.TP
3379
.B \-\-server-poll-timeout n
3380
when polling possible remote servers to connect to
3381
in a round-robin fashion, spend no more than
3382
.B n
3383
seconds waiting for a response before trying the next server.
3384
.\"*********************************************************
3385
.TP
3386
.B \-\-explicit-exit-notify [n]
3387
In UDP client mode or point-to-point mode, send server/peer an exit notification
3388
if tunnel is restarted or OpenVPN process is exited. In client mode, on
3389
exit/restart, this
3390
option will tell the server to immediately close its client instance object
3391
rather than waiting for a timeout. The
3392
.B n
3393
parameter (default=1) controls the maximum number of attempts that the client
3394
will try to resend the exit notification message. OpenVPN will not send any exit
3395
notifications unless this option is enabled.
3396
.\"*********************************************************
3397
.SS Data Channel Encryption Options:
3398
These options are meaningful for both Static & TLS-negotiated key modes
3399
(must be compatible between peers).
3400
.\"*********************************************************
3401
.TP
3402
.B \-\-secret file [direction]
3403
Enable Static Key encryption mode (non-TLS).
3404
Use pre-shared secret
3405
.B file
3406
which was generated with
3407
.B \-\-genkey.
3408
3409
The optional
3410
.B direction
3411
parameter enables the use of 4 distinct keys
3412
(HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that
3413
each data flow direction has a different set of HMAC and cipher keys.
3414
This has a number of desirable security properties including
3415
eliminating certain kinds of DoS and message replay attacks.
3416
3417
When the
3418
.B direction
3419
parameter is omitted, 2 keys are used bidirectionally, one for HMAC
3420
and the other for encryption/decryption.
3421
3422
The
3423
.B direction
3424
parameter should always be complementary on either side of the connection,
3425
i.e. one side should use "0" and the other should use "1", or both sides
3426
should omit it altogether.
3427
3428
The
3429
.B direction
3430
parameter requires that
3431
.B file
3432
contains a 2048 bit key. While pre-1.5 versions of OpenVPN
3433
generate 1024 bit key files, any version of OpenVPN which
3434
supports the
3435
.B direction
3436
parameter, will also support 2048 bit key file generation
3437
using the
3438
.B \-\-genkey
3439
option.
3440
3441
Static key encryption mode has certain advantages,
3442
the primary being ease of configuration.
3443
3444
There are no certificates
3445
or certificate authorities or complicated negotiation handshakes and protocols.
3446
The only requirement is that you have a pre-existing secure channel with
3447
your peer (such as
3448
.B ssh
3449
) to initially copy the key. This requirement, along with the
3450
fact that your key never changes unless you manually generate a new one,
3451
makes it somewhat less secure than TLS mode (see below). If an attacker
3452
manages to steal your key, everything that was ever encrypted with
3453
it is compromised. Contrast that to the perfect forward secrecy features of
3454
TLS mode (using Diffie Hellman key exchange), where even if an attacker
3455
was able to steal your private key, he would gain no information to help
3456
him decrypt past sessions.
3457
3458
Another advantageous aspect of Static Key encryption mode is that
3459
it is a handshake-free protocol
3460
without any distinguishing signature or feature
3461
(such as a header or protocol handshake sequence)
3462
that would mark the ciphertext packets as being
3463
generated by OpenVPN. Anyone eavesdropping on the wire
3464
would see nothing
3465
but random-looking data.
3466
.\"*********************************************************
3467
.TP
3468
.B \-\-auth alg
3469
Authenticate packets with HMAC using message
3470
digest algorithm
3471
.B alg.
3472
(The default is
3473
.B SHA1
3474
).
3475
HMAC is a commonly used message authentication algorithm (MAC) that uses
3476
a data string, a secure hash algorithm, and a key, to produce
3477
a digital signature.
3478
3479
OpenVPN's usage of HMAC is to first encrypt a packet, then HMAC the resulting ciphertext.
3480
3481
In static-key encryption mode, the HMAC key
3482
is included in the key file generated by
3483
.B \-\-genkey.
3484
In TLS mode, the HMAC key is dynamically generated and shared
3485
between peers via the TLS control channel. If OpenVPN receives a packet with
3486
a bad HMAC it will drop the packet.
3487
HMAC usually adds 16 or 20 bytes per packet.
3488
Set
3489
.B alg=none
3490
to disable authentication.
3491
3492
For more information on HMAC see
3493
.I http://www.cs.ucsd.edu/users/mihir/papers/hmac.html
3494
.\"*********************************************************
3495
.TP
3496
.B \-\-cipher alg
3497
Encrypt packets with cipher algorithm
3498
.B alg.
3499
The default is
3500
.B BF-CBC,
3501
an abbreviation for Blowfish in Cipher Block Chaining mode.
3502
Blowfish has the advantages of being fast, very secure, and allowing key sizes
3503
of up to 448 bits. Blowfish is designed to be used in situations where
3504
keys are changed infrequently.
3505
3506
For more information on blowfish, see
3507
.I http://www.counterpane.com/blowfish.html
3508
3509
To see other ciphers that are available with
3510
OpenVPN, use the
3511
.B \-\-show-ciphers
3512
option.
3513
3514
OpenVPN supports the CBC, CFB, and OFB cipher modes,
3515
however CBC is recommended and CFB and OFB should
3516
be considered advanced modes.
3517
3518
Set
3519
.B alg=none
3520
to disable encryption.
3521
.\"*********************************************************
3522
.TP
3523
.B \-\-keysize n
3524
Size of cipher key in bits (optional).
3525
If unspecified, defaults to cipher-specific default. The
3526
.B \-\-show-ciphers
3527
option (see below) shows all available OpenSSL ciphers,
3528
their default key sizes, and whether the key size can
3529
be changed. Use care in changing a cipher's default
3530
key size. Many ciphers have not been extensively
3531
cryptanalyzed with non-standard key lengths, and a
3532
larger key may offer no real guarantee of greater
3533
security, or may even reduce security.
3534
.\"*********************************************************
3535
.TP
3536
.B \-\-prng alg [nsl]
3537
(Advanced) For PRNG (Pseudo-random number generator),
3538
use digest algorithm
3539
.B alg
3540
(default=sha1), and set
3541
.B nsl
3542
(default=16)
3543
to the size in bytes of the nonce secret length (between 16 and 64).
3544
3545
Set
3546
.B alg=none
3547
to disable the PRNG and use the OpenSSL RAND_bytes function
3548
instead for all of OpenVPN's pseudo-random number needs.
3549
.\"*********************************************************
3550
.TP
3551
.B \-\-engine [engine-name]
3552
Enable OpenSSL hardware-based crypto engine functionality.
3553
3554
If
3555
.B engine-name
3556
is specified,
3557
use a specific crypto engine. Use the
3558
.B \-\-show-engines
3559
standalone option to list the crypto engines which are
3560
supported by OpenSSL.
3561
.\"*********************************************************
3562
.TP
3563
.B \-\-no-replay
3564
(Advanced) Disable OpenVPN's protection against replay attacks.
3565
Don't use this option unless you are prepared to make
3566
a tradeoff of greater efficiency in exchange for less
3567
security.
3568
3569
OpenVPN provides datagram replay protection by default.
3570
3571
Replay protection is accomplished
3572
by tagging each outgoing datagram with an identifier
3573
that is guaranteed to be unique for the key being used.
3574
The peer that receives the datagram will check for
3575
the uniqueness of the identifier. If the identifier
3576
was already received in a previous datagram, OpenVPN
3577
will drop the packet. Replay protection is important
3578
to defeat attacks such as a SYN flood attack, where
3579
the attacker listens in the wire, intercepts a TCP
3580
SYN packet (identifying it by the context in which
3581
it occurs in relation to other packets), then floods
3582
the receiving peer with copies of this packet.
3583
3584
OpenVPN's replay protection is implemented in slightly
3585
different ways, depending on the key management mode
3586
you have selected.
3587
3588
In Static Key mode
3589
or when using an CFB or OFB mode cipher, OpenVPN uses a
3590
64 bit unique identifier that combines a time stamp with
3591
an incrementing sequence number.
3592
3593
When using TLS mode for key exchange and a CBC cipher
3594
mode, OpenVPN uses only a 32 bit sequence number without
3595
a time stamp, since OpenVPN can guarantee the uniqueness
3596
of this value for each key. As in IPSec, if the sequence number is
3597
close to wrapping back to zero, OpenVPN will trigger
3598
a new key exchange.
3599
3600
To check for replays, OpenVPN uses
3601
the
3602
.I sliding window
3603
algorithm used
3604
by IPSec.
3605
.\"*********************************************************
3606
.TP
3607
.B \-\-replay-window n [t]
3608
Use a replay protection sliding-window of size
3609
.B n
3610
and a time window of
3611
.B t
3612
seconds.
3613
3614
By default
3615
.B n
3616
is 64 (the IPSec default) and
3617
.B t
3618
is 15 seconds.
3619
3620
This option is only relevant in UDP mode, i.e.
3621
when either
3622
.B \-\-proto udp
3623
is specifed, or no
3624
.B \-\-proto
3625
option is specified.
3626
3627
When OpenVPN tunnels IP packets over UDP, there is the possibility that
3628
packets might be dropped or delivered out of order. Because OpenVPN, like IPSec,
3629
is emulating the physical network layer,
3630
it will accept an out-of-order packet sequence, and
3631
will deliver such packets in the same order they were received to
3632
the TCP/IP protocol stack, provided they satisfy several constraints.
3633
3634
.B (a)
3635
The packet cannot be a replay (unless
3636
.B \-\-no-replay
3637
is specified, which disables replay protection altogether).
3638
3639
.B (b)
3640
If a packet arrives out of order, it will only be accepted if the difference
3641
between its sequence number and the highest sequence number received
3642
so far is less than
3643
.B n.
3644
3645
.B (c)
3646
If a packet arrives out of order, it will only be accepted if it arrives no later
3647
than
3648
.B t
3649
seconds after any packet containing a higher sequence number.
3650
3651
If you are using a network link with a large pipeline (meaning that
3652
the product of bandwidth and latency is high), you may want to use
3653
a larger value for
3654
.B n.
3655
Satellite links in particular often require this.
3656
3657
If you run OpenVPN at
3658
.B \-\-verb 4,
3659
you will see the message "Replay-window backtrack occurred [x]"
3660
every time the maximum sequence number backtrack seen thus far
3661
increases. This can be used to calibrate
3662
.B n.
3663
3664
There is some controversy on the appropriate method of handling packet
3665
reordering at the security layer.
3666
3667
Namely, to what extent should the
3668
security layer protect the encapsulated protocol from attacks which masquerade
3669
as the kinds of normal packet loss and reordering that occur over IP networks?
3670
3671
The IPSec and OpenVPN approach is to allow packet reordering within a certain
3672
fixed sequence number window.
3673
3674
OpenVPN adds to the IPSec model by limiting the window size in time as well as
3675
sequence space.
3676
3677
OpenVPN also adds TCP transport as an option (not offered by IPSec) in which
3678
case OpenVPN can adopt a very strict attitude towards message deletion and
3679
reordering: Don't allow it. Since TCP guarantees reliability, any packet
3680
loss or reordering event can be assumed to be an attack.
3681
3682
In this sense, it could be argued that TCP tunnel transport is preferred when
3683
tunneling non-IP or UDP application protocols which might be vulnerable to a
3684
message deletion or reordering attack which falls within the normal
3685
operational parameters of IP networks.
3686
3687
So I would make the statement that one should never tunnel a non-IP protocol
3688
or UDP application protocol over UDP, if the protocol might be vulnerable to a
3689
message deletion or reordering attack that falls within the normal operating
3690
parameters of what is to be expected from the physical IP layer. The problem
3691
is easily fixed by simply using TCP as the VPN transport layer.
3692
.\"*********************************************************
3693
.TP
3694
.B \-\-mute-replay-warnings
3695
Silence the output of replay warnings, which are a common
3696
false alarm on WiFi networks. This option preserves
3697
the security of the replay protection code without
3698
the verbosity associated with warnings about duplicate
3699
packets.
3700
.\"*********************************************************
3701
.TP
3702
.B \-\-replay-persist file
3703
Persist replay-protection state across sessions using
3704
.B file
3705
to save and reload the state.
3706
3707
This option will strengthen protection against replay attacks,
3708
especially when you are using OpenVPN in a dynamic context (such
3709
as with
3710
.B \-\-inetd)
3711
when OpenVPN sessions are frequently started and stopped.
3712
3713
This option will keep a disk copy of the current replay protection
3714
state (i.e. the most recent packet timestamp and sequence number
3715
received from the remote peer), so that if an OpenVPN session
3716
is stopped and restarted, it will reject any replays of packets
3717
which were already received by the prior session.
3718
3719
This option only makes sense when replay protection is enabled
3720
(the default) and you are using either
3721
.B \-\-secret
3722
(shared-secret key mode) or TLS mode with
3723
.B \-\-tls-auth.
3724
.\"*********************************************************
3725
.TP
3726
.B \-\-no-iv
3727
(Advanced) Disable OpenVPN's use of IV (cipher initialization vector).
3728
Don't use this option unless you are prepared to make
3729
a tradeoff of greater efficiency in exchange for less
3730
security.
3731
3732
OpenVPN uses an IV by default, and requires it for CFB and
3733
OFB cipher modes (which are totally insecure without it).
3734
Using an IV is important for security when multiple
3735
messages are being encrypted/decrypted with the same key.
3736
3737
IV is implemented differently depending on the cipher mode used.
3738
3739
In CBC mode, OpenVPN uses a pseudo-random IV for each packet.
3740
3741
In CFB/OFB mode, OpenVPN uses a unique sequence number and time stamp
3742
as the IV. In fact, in CFB/OFB mode, OpenVPN uses a datagram
3743
space-saving optimization that uses the unique identifier for
3744
datagram replay protection as the IV.
3745
.\"*********************************************************
3746
.TP
3747
.B \-\-test-crypto
3748
Do a self-test of OpenVPN's crypto options by encrypting and
3749
decrypting test packets using the data channel encryption options
3750
specified above. This option does not require a peer to function,
3751
and therefore can be specified without
3752
.B \-\-dev
3753
or
3754
.B \-\-remote.
3755
3756
The typical usage of
3757
.B \-\-test-crypto
3758
would be something like this:
3759
3760
.B openvpn \-\-test-crypto \-\-secret key
3761
3762
or
3763
3764
.B openvpn \-\-test-crypto \-\-secret key \-\-verb 9
3765
3766
This option is very useful to test OpenVPN after it has been ported to
3767
a new platform, or to isolate problems in the compiler, OpenSSL
3768
crypto library, or OpenVPN's crypto code. Since it is a self-test mode,
3769
problems with encryption and authentication can be debugged independently
3770
of network and tunnel issues.
3771
.\"*********************************************************
3772
.SS TLS Mode Options:
3773
TLS mode is the most powerful crypto mode of OpenVPN in both security and flexibility.
3774
TLS mode works by establishing control and
3775
data channels which are multiplexed over a single TCP/UDP port. OpenVPN initiates
3776
a TLS session over the control channel and uses it to exchange cipher
3777
and HMAC keys to protect the data channel. TLS mode uses a robust reliability
3778
layer over the UDP connection for all control channel communication, while
3779
the data channel, over which encrypted tunnel data passes, is forwarded without
3780
any mediation. The result is the best of both worlds: a fast data channel
3781
that forwards over UDP with only the overhead of encrypt,
3782
decrypt, and HMAC functions,
3783
and a control channel that provides all of the security features of TLS,
3784
including certificate-based authentication and Diffie Hellman forward secrecy.
3785
3786
To use TLS mode, each peer that runs OpenVPN should have its own local
3787
certificate/key pair (
3788
.B \-\-cert
3789
and
3790
.B \-\-key
3791
), signed by the root certificate which is specified
3792
in
3793
.B \-\-ca.
3794
3795
When two OpenVPN peers connect, each presents its local certificate to the
3796
other. Each peer will then check that its partner peer presented a
3797
certificate which was signed by the master root certificate as specified in
3798
.B \-\-ca.
3799
3800
If that check on both peers succeeds, then the TLS negotiation
3801
will succeed, both OpenVPN
3802
peers will exchange temporary session keys, and the tunnel will begin
3803
passing data.
3804
3805
The OpenVPN distribution contains a set of scripts for
3806
managing RSA certificates & keys,
3807
located in the
3808
.I easy-rsa
3809
subdirectory.
3810
3811
The easy-rsa package is also rendered in web form here:
3812
.I http://openvpn.net/easyrsa.html
3813
.\"*********************************************************
3814
.TP
3815
.B \-\-tls-server
3816
Enable TLS and assume server role during TLS handshake. Note that
3817
OpenVPN is designed as a peer-to-peer application. The designation
3818
of client or server is only for the purpose of negotiating the TLS
3819
control channel.
3820
.\"*********************************************************
3821
.TP
3822
.B \-\-tls-client
3823
Enable TLS and assume client role during TLS handshake.
3824
.\"*********************************************************
3825
.TP
3826
.B \-\-ca file
3827
Certificate authority (CA) file in .pem format, also referred to as the
3828
.I root
3829
certificate. This file can have multiple
3830
certificates in .pem format, concatenated together. You can construct your own
3831
certificate authority certificate and private key by using a command such as:
3832
3833
.B openssl req -nodes -new -x509 -keyout ca.key -out ca.crt
3834
3835
Then edit your openssl.cnf file and edit the
3836
.B certificate
3837
variable to point to your new root certificate
3838
.B ca.crt.
3839
3840
For testing purposes only, the OpenVPN distribution includes a sample
3841
CA certificate (ca.crt).
3842
Of course you should never use
3843
the test certificates and test keys distributed with OpenVPN in a
3844
production environment, since by virtue of the fact that
3845
they are distributed with OpenVPN, they are totally insecure.
3846
.\"*********************************************************
3847
.TP
3848
.B \-\-capath dir
3849
Directory containing trusted certificates (CAs and CRLs).
3850
Available with OpenSSL version >= 0.9.7 dev.
3851
.\"*********************************************************
3852
.TP
3853
.B \-\-dh file
3854
File containing Diffie Hellman parameters
3855
in .pem format (required for
3856
.B \-\-tls-server
3857
only). Use
3858
3859
.B openssl dhparam -out dh1024.pem 1024
3860
3861
to generate your own, or use the existing dh1024.pem file
3862
included with the OpenVPN distribution. Diffie Hellman parameters
3863
may be considered public.
3864
.\"*********************************************************
3865
.TP
3866
.B \-\-cert file
3867
Local peer's signed certificate in .pem format \-\- must be signed
3868
by a certificate authority whose certificate is in
3869
.B \-\-ca file.
3870
Each peer in an OpenVPN link running in TLS mode should have its own
3871
certificate and private key file. In addition, each certificate should
3872
have been signed by the key of a certificate
3873
authority whose public key resides in the
3874
.B \-\-ca
3875
certificate authority file.
3876
You can easily make your own certificate authority (see above) or pay money
3877
to use a commercial service such as thawte.com (in which case you will be
3878
helping to finance the world's second space tourist :).
3879
To generate a certificate,
3880
you can use a command such as:
3881
3882
.B openssl req -nodes -new -keyout mycert.key -out mycert.csr
3883
3884
If your certificate authority private key lives on another machine, copy
3885
the certificate signing request (mycert.csr) to this other machine (this can
3886
be done over an insecure channel such as email). Now sign the certificate
3887
with a command such as:
3888
3889
.B openssl ca -out mycert.crt -in mycert.csr
3890
3891
Now copy the certificate (mycert.crt)
3892
back to the peer which initially generated the .csr file (this
3893
can be over a public medium).
3894
Note that the
3895
.B openssl ca
3896
command reads the location of the certificate authority key from its
3897
configuration file such as
3898
.B /usr/share/ssl/openssl.cnf
3899
\-\- note also
3900
that for certificate authority functions, you must set up the files
3901
.B index.txt
3902
(may be empty) and
3903
.B serial
3904
(initialize to
3905
.B
3906
01
3907
).
3908
.\"*********************************************************
3909
.TP
3910
.B \-\-key file
3911
Local peer's private key in .pem format. Use the private key which was generated
3912
when you built your peer's certificate (see
3913
.B -cert file
3914
above).
3915
.\"*********************************************************
3916
.TP
3917
.B \-\-pkcs12 file
3918
Specify a PKCS #12 file containing local private key,
3919
local certificate, and root CA certificate.
3920
This option can be used instead of
3921
.B \-\-ca, \-\-cert,
3922
and
3923
.B \-\-key.
3924
.\"*********************************************************
3925
.TP
3926
.B \-\-pkcs11-cert-private [0|1]...
3927
Set if access to certificate object should be performed after login.
3928
Every provider has its own setting.
3929
.\"*********************************************************
3930
.TP
3931
.B \-\-pkcs11-id name
3932
Specify the serialized certificate id to be used. The id can be gotten
3933
by the standalone
3934
.B \-\-show-pkcs11-ids
3935
option.
3936
.\"*********************************************************
3937
.TP
3938
.B \-\-pkcs11-id-management
3939
Acquire PKCS#11 id from management interface. In this case a NEED-STR 'pkcs11-id-request'
3940
real-time message will be triggered, application may use pkcs11-id-count command to
3941
retrieve available number of certificates, and pkcs11-id-get command to retrieve certificate
3942
id and certificate body.
3943
.\"*********************************************************
3944
.TP
3945
.B \-\-pkcs11-pin-cache seconds
3946
Specify how many seconds the PIN can be cached, the default is until the token is removed.
3947
.\"*********************************************************
3948
.TP
3949
.B \-\-pkcs11-protected-authentication [0|1]...
3950
Use PKCS#11 protected authentication path, useful for biometric and external
3951
keypad devices.
3952
Every provider has its own setting.
3953
.\"*********************************************************
3954
.TP
3955
.B \-\-pkcs11-providers provider...
3956
Specify a RSA Security Inc. PKCS #11 Cryptographic Token Interface (Cryptoki) providers
3957
to load.
3958
This option can be used instead of
3959
.B \-\-cert, \-\-key,
3960
and
3961
.B \-\-pkcs12.
3962
.\"*********************************************************
3963
.TP
3964
.B \-\-pkcs11-private-mode mode...
3965
Specify which method to use in order to perform private key operations.
3966
A different mode can be specified for each provider.
3967
Mode is encoded as hex number, and can be a mask one of the following:
3968
3969
.B 0
3970
(default) \-\- Try to determind automatically.
3971
.br
3972
.B 1
3973
\-\- Use sign.
3974
.br
3975
.B 2
3976
\-\- Use sign recover.
3977
.br
3978
.B 4
3979
\-\- Use decrypt.
3980
.br
3981
.B 8
3982
\-\- Use unwrap.
3983
.br
3984
.\"*********************************************************
3985
.TP
3986
.B \-\-cryptoapicert select-string
3987
Load the certificate and private key from the
3988
Windows Certificate System Store (Windows Only).
3989
3990
Use this option instead of
3991
.B \-\-cert
3992
and
3993
.B \-\-key.
3994
3995
This makes
3996
it possible to use any smart card, supported by Windows, but also any
3997
kind of certificate, residing in the Cert Store, where you have access to
3998
the private key. This option has been tested with a couple of different
3999
smart cards (GemSAFE, Cryptoflex, and Swedish Post Office eID) on the
4000
client side, and also an imported PKCS12 software certificate on the
4001
server side.
4002
4003
To select a certificate, based on a substring search in the
4004
certificate's subject:
4005
4006
.B cryptoapicert
4007
"SUBJ:Peter Runestig"
4008
4009
To select a certificate, based on certificate's thumbprint:
4010
4011
.B cryptoapicert
4012
"THUMB:f6 49 24 41 01 b4 ..."
4013
4014
The thumbprint hex string can easily be copy-and-pasted from the Windows
4015
Certificate Store GUI.
4016
4017
.\"*********************************************************
4018
.TP
4019
.B \-\-key-method m
4020
Use data channel key negotiation method
4021
.B m.
4022
The key method must match on both sides of the connection.
4023
4024
After OpenVPN negotiates a TLS session, a new set of keys
4025
for protecting the tunnel data channel is generated and
4026
exchanged over the TLS session.
4027
4028
In method 1 (the default for OpenVPN 1.x), both sides generate
4029
random encrypt and HMAC-send keys which are forwarded to
4030
the other host over the TLS channel.
4031
4032
In method 2, (the default for OpenVPN 2.0)
4033
the client generates a random key. Both client
4034
and server also generate some random seed material. All key source
4035
material is exchanged over the TLS channel. The actual
4036
keys are generated using the TLS PRF function, taking source
4037
entropy from both client and server. Method 2 is designed to
4038
closely parallel the key generation process used by TLS 1.0.
4039
4040
Note that in TLS mode, two separate levels
4041
of keying occur:
4042
4043
(1) The TLS connection is initially negotiated, with both sides
4044
of the connection producing certificates and verifying the certificate
4045
(or other authentication info provided) of
4046
the other side. The
4047
.B \-\-key-method
4048
parameter has no effect on this process.
4049
4050
(2) After the TLS connection is established, the tunnel session keys are
4051
separately negotiated over the existing secure TLS channel. Here,
4052
.B \-\-key-method
4053
determines the derivation of the tunnel session keys.
4054
.\"*********************************************************
4055
.TP
4056
.B \-\-tls-cipher l
4057
A list
4058
.B l
4059
of allowable TLS ciphers delimited by a colon (":").
4060
If you require a high level of security,
4061
you may want to set this parameter manually, to prevent a
4062
version rollback attack where a man-in-the-middle attacker tries
4063
to force two peers to negotiate to the lowest level
4064
of security they both support.
4065
Use
4066
.B \-\-show-tls
4067
to see a list of supported TLS ciphers.
4068
.\"*********************************************************
4069
.TP
4070
.B \-\-tls-timeout n
4071
Packet retransmit timeout on TLS control channel
4072
if no acknowledgment from remote within
4073
.B n
4074
seconds (default=2). When OpenVPN sends a control
4075
packet to its peer, it will expect to receive an
4076
acknowledgement within
4077
.B n
4078
seconds or it will retransmit the packet, subject
4079
to a TCP-like exponential backoff algorithm. This parameter
4080
only applies to control channel packets. Data channel
4081
packets (which carry encrypted tunnel data) are never
4082
acknowledged, sequenced, or retransmitted by OpenVPN because
4083
the higher level network protocols running on top of the tunnel
4084
such as TCP expect this role to be left to them.
4085
.\"*********************************************************
4086
.TP
4087
.B \-\-reneg-bytes n
4088
Renegotiate data channel key after
4089
.B n
4090
bytes sent or received (disabled by default).
4091
OpenVPN allows the lifetime of a key
4092
to be expressed as a number of bytes encrypted/decrypted, a number of packets, or
4093
a number of seconds. A key renegotiation will be forced
4094
if any of these three criteria are met by either peer.
4095
.\"*********************************************************
4096
.TP
4097
.B \-\-reneg-pkts n
4098
Renegotiate data channel key after
4099
.B n
4100
packets sent and received (disabled by default).
4101
.\"*********************************************************
4102
.TP
4103
.B \-\-reneg-sec n
4104
Renegotiate data channel key after
4105
.B n
4106
seconds (default=3600).
4107
4108
When using dual-factor authentication, note that this default value may
4109
cause the end user to be challenged to reauthorize once per hour.
4110
4111
Also, keep in mind that this option can be used on both the client and server,
4112
and whichever uses the lower value will be the one to trigger the renegotiation.
4113
A common mistake is to set
4114
.B \-\-reneg-sec
4115
to a higher value on either the client or server, while the other side of the connection
4116
is still using the default value of 3600 seconds, meaning that the renegotiation will
4117
still occur once per 3600 seconds. The solution is to increase \-\-reneg-sec on both the
4118
client and server, or set it to 0 on one side of the connection (to disable), and to
4119
your chosen value on the other side.
4120
.\"*********************************************************
4121
.TP
4122
.B \-\-hand-window n
4123
Handshake Window \-\- the TLS-based key exchange must finalize within
4124
.B n
4125
seconds
4126
of handshake initiation by any peer (default = 60 seconds).
4127
If the handshake fails
4128
we will attempt to reset our connection with our peer and try again.
4129
Even in the event of handshake failure we will still use
4130
our expiring key for up to
4131
.B \-\-tran-window
4132
seconds to maintain continuity of transmission of tunnel
4133
data.
4134
.\"*********************************************************
4135
.TP
4136
.B \-\-tran-window n
4137
Transition window \-\- our old key can live this many seconds
4138
after a new a key renegotiation begins (default = 3600 seconds).
4139
This feature allows for a graceful transition from old to new
4140
key, and removes the key renegotiation sequence from the critical
4141
path of tunnel data forwarding.
4142
.\"*********************************************************
4143
.TP
4144
.B \-\-single-session
4145
After initially connecting to a remote peer, disallow any new connections.
4146
Using this
4147
option means that a remote peer cannot connect, disconnect, and then
4148
reconnect.
4149
4150
If the daemon is reset by a signal or
4151
.B \-\-ping-restart,
4152
it will allow one new connection.
4153
4154
.B \-\-single-session
4155
can be used with
4156
.B \-\-ping-exit
4157
or
4158
.B \-\-inactive
4159
to create a single dynamic session that will exit when finished.
4160
.\"*********************************************************
4161
.TP
4162
.B \-\-tls-exit
4163
Exit on TLS negotiation failure.
4164
.\"*********************************************************
4165
.TP
4166
.B \-\-tls-auth file [direction]
4167
Add an additional layer of HMAC authentication on top of the TLS
4168
control channel to protect against DoS attacks.
4169
4170
In a nutshell,
4171
.B \-\-tls-auth
4172
enables a kind of "HMAC firewall" on OpenVPN's TCP/UDP port,
4173
where TLS control channel packets
4174
bearing an incorrect HMAC signature can be dropped immediately without
4175
response.
4176
4177
.B file
4178
(required) is a key file which can be in one of two formats:
4179
4180
.B (1)
4181
An OpenVPN static key file generated by
4182
.B \-\-genkey
4183
(required if
4184
.B direction
4185
parameter is used).
4186
4187
.B (2)
4188
A freeform passphrase file. In this case the HMAC key will
4189
be derived by taking a secure hash of this file, similar to
4190
the
4191
.BR md5sum (1)
4192
or
4193
.BR sha1sum (1)
4194
commands.
4195
4196
OpenVPN will first try format (1), and if the file fails to parse as
4197
a static key file, format (2) will be used.
4198
4199
See the
4200
.B \-\-secret
4201
option for more information on the optional
4202
.B direction
4203
parameter.
4204
4205
.B \-\-tls-auth
4206
is recommended when you are running OpenVPN in a mode where
4207
it is listening for packets from any IP address, such as when
4208
.B \-\-remote
4209
is not specified, or
4210
.B \-\-remote
4211
is specified with
4212
.B \-\-float.
4213
4214
The rationale for
4215
this feature is as follows. TLS requires a multi-packet exchange
4216
before it is able to authenticate a peer. During this time
4217
before authentication, OpenVPN is allocating resources (memory
4218
and CPU) to this potential peer. The potential peer is also
4219
exposing many parts of OpenVPN and the OpenSSL library to the packets
4220
it is sending. Most successful network attacks today seek
4221
to either exploit bugs in programs (such as buffer overflow attacks) or
4222
force a program to consume so many resources that it becomes unusable.
4223
Of course the first line of defense is always to produce clean,
4224
well-audited code. OpenVPN has been written with buffer overflow
4225
attack prevention as a top priority.
4226
But as history has shown, many of the most widely used
4227
network applications have, from time to time,
4228
fallen to buffer overflow attacks.
4229
4230
So as a second line of defense, OpenVPN offers
4231
this special layer of authentication on top of the TLS control channel so that
4232
every packet on the control channel is authenticated by an
4233
HMAC signature and a unique ID for replay protection.
4234
This signature will also help protect against DoS (Denial of Service) attacks.
4235
An important rule of thumb in reducing vulnerability to DoS attacks is to
4236
minimize the amount of resources a potential, but as yet unauthenticated,
4237
client is able to consume.
4238
4239
.B \-\-tls-auth
4240
does this by signing every TLS control channel packet with an HMAC signature,
4241
including packets which are sent before the TLS level has had a chance
4242
to authenticate the peer.
4243
The result is that packets without
4244
the correct signature can be dropped immediately upon reception,
4245
before they have a chance to consume additional system resources
4246
such as by initiating a TLS handshake.
4247
.B \-\-tls-auth
4248
can be strengthened by adding the
4249
.B \-\-replay-persist
4250
option which will keep OpenVPN's replay protection state
4251
in a file so that it is not lost across restarts.
4252
4253
It should be emphasized that this feature is optional and that the
4254
passphrase/key file used with
4255
.B \-\-tls-auth
4256
gives a peer nothing more than the power to initiate a TLS
4257
handshake. It is not used to encrypt or authenticate any tunnel data.
4258
.\"*********************************************************
4259
.TP
4260
.B \-\-askpass [file]
4261
Get certificate password from console or
4262
.B file
4263
before we daemonize.
4264
4265
For the extremely
4266
security conscious, it is possible to protect your private key with
4267
a password. Of course this means that every time the OpenVPN
4268
daemon is started you must be there to type the password. The
4269
.B \-\-askpass
4270
option allows you to start OpenVPN from the command line. It will
4271
query you for a password before it daemonizes. To protect a private
4272
key with a password you should omit the
4273
.B -nodes
4274
option when you use the
4275
.B openssl
4276
command line tool to manage certificates and private keys.
4277
4278
If
4279
.B file
4280
is specified, read the password from the first line of
4281
.B file.
4282
Keep in mind that storing your password in a file
4283
to a certain extent invalidates the extra security provided by
4284
using an encrypted key (Note: OpenVPN
4285
will only read passwords from a file if it has been built
4286
with the \-\-enable-password-save configure option, or on Windows
4287
by defining ENABLE_PASSWORD_SAVE in win/settings.in).
4288
.\"*********************************************************
4289
.TP
4290
.B \-\-auth-nocache
4291
Don't cache
4292
.B \-\-askpass
4293
or
4294
.B \-\-auth-user-pass
4295
username/passwords in virtual memory.
4296
4297
If specified, this directive will cause OpenVPN to immediately
4298
forget username/password inputs after they are used. As a result,
4299
when OpenVPN needs a username/password, it will prompt for input
4300
from stdin, which may be multiple times during the duration of an
4301
OpenVPN session.
4302
4303
This directive does not affect the
4304
.B \-\-http-proxy
4305
username/password. It is always cached.
4306
.\"*********************************************************
4307
.TP
4308
.B \-\-tls-verify cmd
4309
Execute shell command
4310
.B cmd
4311
to verify the X509 name of a
4312
pending TLS connection that has otherwise passed all other
4313
tests of certification (except for revocation via
4314
.B \-\-crl-verify
4315
directive; the revocation test occurs after the
4316
.B \-\-tls-verify
4317
test).
4318
4319
.B cmd
4320
should return 0 to allow the TLS handshake to proceed, or 1 to fail.
4321
4322
Note that
4323
.B cmd
4324
is a command line and as such may (if enclosed in quotes) contain
4325
whitespace separated arguments. The first word of
4326
.B cmd
4327
is the shell command to execute and the remaining words are its
4328
arguments.
4329
When
4330
.B cmd
4331
is executed two arguments are appended, as follows:
4332
4333
.B cmd certificate_depth X509_NAME_oneline
4334
4335
These arguments are, respectively, the current certificate depth and
4336
the X509 common name (cn) of the peer.
4337
4338
This feature is useful if the peer you want to trust has a certificate
4339
which was signed by a certificate authority who also signed many
4340
other certificates, where you don't necessarily want to trust all of them,
4341
but rather be selective about which
4342
peer certificate you will accept. This feature allows you to write a script
4343
which will test the X509 name on a certificate and decide whether or
4344
not it should be accepted. For a simple perl script which will test
4345
the common name field on the certificate, see the file
4346
.B verify-cn
4347
in the OpenVPN distribution.
4348
4349
See the "Environmental Variables" section below for
4350
additional parameters passed as environmental variables.
4351
.\"*********************************************************
4352
.TP
4353
.B \-\-tls-export-cert directory
4354
Store the certificates the clients uses upon connection to this
4355
directory. This will be done before --tls-verify is called. The
4356
certificates will use a temporary name and will be deleted when
4357
the tls-verify script returns. The file name used for the certificate
4358
is available via the peer_cert environment variable.
4359
.\"*********************************************************
4360
.TP
4361
.B \-\-x509-username-field fieldname
4362
Field in x509 certificate subject to be used as username (default=CN).
4363
.B Fieldname
4364
will be uppercased before matching. When this option is used, the
4365
--tls-remote option will match against the chosen fieldname instead
4366
of the CN.
4367
.\"*********************************************************
4368
.TP
4369
.B \-\-tls-remote name
4370
Accept connections only from a host with X509 name
4371
or common name equal to
4372
.B name.
4373
The remote host must also pass all other tests
4374
of verification.
4375
4376
.B NOTE:
4377
Because tls-remote may test against a common name prefix,
4378
only use this option when you are using OpenVPN with a custom CA
4379
certificate that is under your control.
4380
Never use this option when your client certificates are signed by
4381
a third party, such as a commercial web CA.
4382
4383
Name can also be a common name prefix, for example if you
4384
want a client to only accept connections to "Server-1",
4385
"Server-2", etc., you can simply use
4386
.B \-\-tls-remote Server
4387
4388
Using a common name prefix is a useful alternative to managing
4389
a CRL (Certificate Revocation List) on the client, since it allows the client
4390
to refuse all certificates except for those associated
4391
with designated servers.
4392
4393
.B \-\-tls-remote
4394
is a useful replacement for the
4395
.B \-\-tls-verify
4396
option to verify the remote host, because
4397
.B \-\-tls-remote
4398
works in a
4399
.B \-\-chroot
4400
environment too.
4401
.\"*********************************************************
4402
.TP
4403
.B \-\-ns-cert-type client|server
4404
Require that peer certificate was signed with an explicit
4405
.B nsCertType
4406
designation of "client" or "server".
4407
4408
This is a useful security option for clients, to ensure that
4409
the host they connect with is a designated server.
4410
4411
See the easy-rsa/build-key-server script for an example
4412
of how to generate a certificate with the
4413
.B nsCertType
4414
field set to "server".
4415
4416
If the server certificate's nsCertType field is set
4417
to "server", then the clients can verify this with
4418
.B \-\-ns-cert-type server.
4419
4420
This is an important security precaution to protect against
4421
a man-in-the-middle attack where an authorized client
4422
attempts to connect to another client by impersonating the server.
4423
The attack is easily prevented by having clients verify
4424
the server certificate using any one of
4425
.B \-\-ns-cert-type, \-\-tls-remote,
4426
or
4427
.B \-\-tls-verify.
4428
.\"*********************************************************
4429
.TP
4430
.B \-\-remote-cert-ku v...
4431
Require that peer certificate was signed with an explicit
4432
.B key usage.
4433
4434
This is a useful security option for clients, to ensure that
4435
the host they connect to is a designated server.
4436
4437
The key usage should be encoded in hex, more than one key
4438
usage can be specified.
4439
.\"*********************************************************
4440
.TP
4441
.B \-\-remote-cert-eku oid
4442
Require that peer certificate was signed with an explicit
4443
.B extended key usage.
4444
4445
This is a useful security option for clients, to ensure that
4446
the host they connect to is a designated server.
4447
4448
The extended key usage should be encoded in oid notation, or
4449
OpenSSL symbolic representation.
4450
.\"*********************************************************
4451
.TP
4452
.B \-\-remote-cert-tls client|server
4453
Require that peer certificate was signed with an explicit
4454
.B key usage
4455
and
4456
.B extended key usage
4457
based on RFC3280 TLS rules.
4458
4459
This is a useful security option for clients, to ensure that
4460
the host they connect to is a designated server.
4461
4462
The
4463
.B \-\-remote-cert-tls client
4464
option is equivalent to
4465
.B
4466
\-\-remote-cert-ku 80 08 88 \-\-remote-cert-eku "TLS Web Client Authentication"
4467
4468
The key usage is digitalSignature and/or keyAgreement.
4469
4470
The
4471
.B \-\-remote-cert-tls server
4472
option is equivalent to
4473
.B
4474
\-\-remote-cert-ku a0 88 \-\-remote-cert-eku "TLS Web Server Authentication"
4475
4476
The key usage is digitalSignature and ( keyEncipherment or keyAgreement ).
4477
4478
This is an important security precaution to protect against
4479
a man-in-the-middle attack where an authorized client
4480
attempts to connect to another client by impersonating the server.
4481
The attack is easily prevented by having clients verify
4482
the server certificate using any one of
4483
.B \-\-remote-cert-tls, \-\-tls-remote,
4484
or
4485
.B \-\-tls-verify.
4486
.\"*********************************************************
4487
.TP
4488
.B \-\-crl-verify crl
4489
Check peer certificate against the file
4490
.B crl
4491
in PEM format.
4492
4493
A CRL (certificate revocation list) is used when a particular key is
4494
compromised but when the overall PKI is still intact.
4495
4496
Suppose you had a PKI consisting of a CA, root certificate, and a number of
4497
client certificates. Suppose a laptop computer containing a client key and
4498
certificate was stolen. By adding the stolen certificate to the CRL file,
4499
you could reject any connection which attempts to use it, while preserving the
4500
overall integrity of the PKI.
4501
4502
The only time when it would be necessary to rebuild the entire PKI from scratch would be
4503
if the root certificate key itself was compromised.
4504
.\"*********************************************************
4505
.SS SSL Library information:
4506
.\"*********************************************************
4507
.TP
4508
.B \-\-show-ciphers
4509
(Standalone)
4510
Show all cipher algorithms to use with the
4511
.B \-\-cipher
4512
option.
4513
.\"*********************************************************
4514
.TP
4515
.B \-\-show-digests
4516
(Standalone)
4517
Show all message digest algorithms to use with the
4518
.B \-\-auth
4519
option.
4520
.\"*********************************************************
4521
.TP
4522
.B \-\-show-tls
4523
(Standalone)
4524
Show all TLS ciphers (TLS used only as a control channel). The TLS
4525
ciphers will be sorted from highest preference (most secure) to
4526
lowest.
4527
.\"*********************************************************
4528
.TP
4529
.B \-\-show-engines
4530
(Standalone)
4531
Show currently available hardware-based crypto acceleration
4532
engines supported by the OpenSSL library.
4533
.\"*********************************************************
4534
.SS Generate a random key:
4535
Used only for non-TLS static key encryption mode.
4536
.\"*********************************************************
4537
.TP
4538
.B \-\-genkey
4539
(Standalone)
4540
Generate a random key to be used as a shared secret,
4541
for use with the
4542
.B \-\-secret
4543
option. This file must be shared with the
4544
peer over a pre-existing secure channel such as
4545
.BR scp (1)
4546
.
4547
.\"*********************************************************
4548
.TP
4549
.B \-\-secret file
4550
Write key to
4551
.B file.
4552
.\"*********************************************************
4553
.SS TUN/TAP persistent tunnel config mode:
4554
Available with linux 2.4.7+. These options comprise a standalone mode
4555
of OpenVPN which can be used to create and delete persistent tunnels.
4556
.\"*********************************************************
4557
.TP
4558
.B \-\-mktun
4559
(Standalone)
4560
Create a persistent tunnel on platforms which support them such
4561
as Linux. Normally TUN/TAP tunnels exist only for
4562
the period of time that an application has them open. This option
4563
takes advantage of the TUN/TAP driver's ability to build persistent
4564
tunnels that live through multiple instantiations of OpenVPN and die
4565
only when they are deleted or the machine is rebooted.
4566
4567
One of the advantages of persistent tunnels is that they eliminate the
4568
need for separate
4569
.B \-\-up
4570
and
4571
.B \-\-down
4572
scripts to run the appropriate
4573
.BR ifconfig (8)
4574
and
4575
.BR route (8)
4576
commands. These commands can be placed in the the same shell script
4577
which starts or terminates an OpenVPN session.
4578
4579
Another advantage is that open connections through the TUN/TAP-based tunnel
4580
will not be reset if the OpenVPN peer restarts. This can be useful to
4581
provide uninterrupted connectivity through the tunnel in the event of a DHCP
4582
reset of the peer's public IP address (see the
4583
.B \-\-ipchange
4584
option above).
4585
4586
One disadvantage of persistent tunnels is that it is harder to automatically
4587
configure their MTU value (see
4588
.B \-\-link-mtu
4589
and
4590
.B \-\-tun-mtu
4591
above).
4592
4593
On some platforms such as Windows, TAP-Win32 tunnels are persistent by
4594
default.
4595
.\"*********************************************************
4596
.TP
4597
.B \-\-rmtun
4598
(Standalone)
4599
Remove a persistent tunnel.
4600
.\"*********************************************************
4601
.TP
4602
.B \-\-dev tunX | tapX
4603
TUN/TAP device
4604
.\"*********************************************************
4605
.TP
4606
.B \-\-user user
4607
Optional user to be owner of this tunnel.
4608
.\"*********************************************************
4609
.TP
4610
.B \-\-group group
4611
Optional group to be owner of this tunnel.
4612
.\"*********************************************************
4613
.SS Windows-Specific Options:
4614
.\"*********************************************************
4615
.TP
4616
.B \-\-win-sys path|'env'
4617
Set the Windows system directory pathname to use when looking for system
4618
executables such as
4619
.B route.exe
4620
and
4621
.B netsh.exe.
4622
By default, if this directive is
4623
not specified, the pathname will be set to "C:\\WINDOWS"
4624
4625
The special string
4626
.B 'env'
4627
indicates that the pathname should be read from the
4628
.B SystemRoot
4629
environmental variable.
4630
.\"*********************************************************
4631
.TP
4632
.B \-\-ip-win32 method
4633
When using
4634
.B \-\-ifconfig
4635
on Windows, set the TAP-Win32 adapter
4636
IP address and netmask using
4637
.B method.
4638
Don't use this option unless you are also using
4639
.B \-\-ifconfig.
4640
4641
.B manual \-\-
4642
Don't set the IP address or netmask automatically.
4643
Instead output a message
4644
to the console telling the user to configure the
4645
adapter manually and indicating the IP/netmask which
4646
OpenVPN expects the adapter to be set to.
4647
4648
.B dynamic [offset] [lease-time] \-\-
4649
Automatically set the IP address and netmask by replying to
4650
DHCP query messages generated by the kernel. This mode is
4651
probably the "cleanest" solution
4652
for setting the TCP/IP properties since it uses the well-known
4653
DHCP protocol. There are, however, two prerequisites for using
4654
this mode: (1) The TCP/IP properties for the TAP-Win32
4655
adapter must be set to "Obtain an IP address automatically," and
4656
(2) OpenVPN needs to claim an IP address in the subnet for use
4657
as the virtual DHCP server address. By default in
4658
.B \-\-dev tap
4659
mode, OpenVPN will
4660
take the normally unused first address in the subnet. For example,
4661
if your subnet is 192.168.4.0 netmask 255.255.255.0, then
4662
OpenVPN will take the IP address 192.168.4.0 to use as the
4663
virtual DHCP server address. In
4664
.B \-\-dev tun
4665
mode, OpenVPN will cause the DHCP server to masquerade as if it were
4666
coming from the remote endpoint. The optional offset parameter is
4667
an integer which is > -256 and < 256 and which defaults to 0.
4668
If offset is positive, the DHCP server will masquerade as the IP
4669
address at network address + offset.
4670
If offset is negative, the DHCP server will masquerade as the IP
4671
address at broadcast address + offset. The Windows
4672
.B ipconfig /all
4673
command can be used to show what Windows thinks the DHCP server
4674
address is. OpenVPN will "claim" this address, so make sure to
4675
use a free address. Having said that, different OpenVPN instantiations,
4676
including different ends of the same connection, can share the same
4677
virtual DHCP server address. The
4678
.B lease-time
4679
parameter controls the lease time of the DHCP assignment given to
4680
the TAP-Win32 adapter, and is denoted in seconds.
4681
Normally a very long lease time is preferred
4682
because it prevents routes involving the TAP-Win32 adapter from
4683
being lost when the system goes to sleep. The default
4684
lease time is one year.
4685
4686
.B netsh \-\-
4687
Automatically set the IP address and netmask using
4688
the Windows command-line "netsh"
4689
command. This method appears to work correctly on
4690
Windows XP but not Windows 2000.
4691
4692
.B ipapi \-\-
4693
Automatically set the IP address and netmask using the
4694
Windows IP Helper API. This approach
4695
does not have ideal semantics, though testing has indicated
4696
that it works okay in practice. If you use this option,
4697
it is best to leave the TCP/IP properties for the TAP-Win32
4698
adapter in their default state, i.e. "Obtain an IP address
4699
automatically."
4700
4701
.B adaptive \-\-
4702
(Default) Try
4703
.B dynamic
4704
method initially and fail over to
4705
.B netsh
4706
if the DHCP negotiation with the TAP-Win32 adapter does
4707
not succeed in 20 seconds. Such failures have been known
4708
to occur when certain third-party firewall packages installed
4709
on the client machine block the DHCP negotiation used by
4710
the TAP-Win32 adapter.
4711
Note that if the
4712
.B netsh
4713
failover occurs, the TAP-Win32 adapter
4714
TCP/IP properties will be reset from DHCP to static, and this
4715
will cause future OpenVPN startups using the
4716
.B adaptive
4717
mode to use
4718
.B netsh
4719
immediately, rather than trying
4720
.B dynamic
4721
first. To "unstick" the
4722
.B adaptive
4723
mode from using
4724
.B netsh,
4725
run OpenVPN at least once using the
4726
.B dynamic
4727
mode to restore the TAP-Win32 adapter TCP/IP properties
4728
to a DHCP configuration.
4729
.\"*********************************************************
4730
.TP
4731
.B \-\-route-method m
4732
Which method
4733
.B m
4734
to use for adding routes on Windows?
4735
4736
.B adaptive
4737
(default) \-\- Try IP helper API first. If that fails, fall
4738
back to the route.exe shell command.
4739
.br
4740
.B ipapi
4741
\-\- Use IP helper API.
4742
.br
4743
.B exe
4744
\-\- Call the route.exe shell command.
4745
.\"*********************************************************
4746
.TP
4747
.B \-\-dhcp-option type [parm]
4748
Set extended TAP-Win32 TCP/IP properties, must
4749
be used with
4750
.B \-\-ip-win32 dynamic
4751
or
4752
.B \-\-ip-win32 adaptive.
4753
This option can be used to set additional TCP/IP properties
4754
on the TAP-Win32 adapter, and is particularly useful for
4755
configuring an OpenVPN client to access a Samba server
4756
across the VPN.
4757
4758
.B DOMAIN name \-\-
4759
Set Connection-specific DNS Suffix.
4760
4761
.B DNS addr \-\-
4762
Set primary domain name server address. Repeat
4763
this option to set secondary DNS server addresses.
4764
4765
.B WINS addr \-\-
4766
Set primary WINS server address (NetBIOS over TCP/IP Name Server).
4767
Repeat this option to set secondary WINS server addresses.
4768
4769
.B NBDD addr \-\-
4770
Set primary NBDD server address (NetBIOS over TCP/IP Datagram Distribution Server)
4771
Repeat this option
4772
to set secondary NBDD server addresses.
4773
4774
.B NTP addr \-\-
4775
Set primary NTP server address (Network Time Protocol).
4776
Repeat this option
4777
to set secondary NTP server addresses.
4778
4779
.B NBT type \-\-
4780
Set NetBIOS over TCP/IP Node type. Possible options:
4781
.B 1
4782
= b-node (broadcasts),
4783
.B 2
4784
= p-node (point-to-point
4785
name queries to a WINS server),
4786
.B 4
4787
= m-node (broadcast
4788
then query name server), and
4789
.B 8
4790
= h-node (query name server, then broadcast).
4791
4792
.B NBS scope-id \-\-
4793
Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID provides an extended
4794
naming service for the NetBIOS over TCP/IP (Known as NBT) module. The
4795
primary purpose of a NetBIOS scope ID is to isolate NetBIOS traffic on
4796
a single network to only those nodes with the same NetBIOS scope ID.
4797
The NetBIOS scope ID is a character string that is appended to the NetBIOS
4798
name. The NetBIOS scope ID on two hosts must match, or the two hosts
4799
will not be able to communicate. The NetBIOS Scope ID also allows
4800
computers to use the same computer name, as they have different
4801
scope IDs. The Scope ID becomes a part of the NetBIOS name, making the name unique.
4802
(This description of NetBIOS scopes courtesy of NeonSurge@abyss.com)
4803
4804
.B DISABLE-NBT \-\-
4805
Disable Netbios-over-TCP/IP.
4806
4807
Note that if
4808
.B \-\-dhcp-option
4809
is pushed via
4810
.B \-\-push
4811
to a non-windows client, the option will be saved in the client's
4812
environment before the up script is called, under
4813
the name "foreign_option_{n}".
4814
.\"*********************************************************
4815
.TP
4816
.B \-\-tap-sleep n
4817
Cause OpenVPN to sleep for
4818
.B n
4819
seconds immediately after the TAP-Win32 adapter state
4820
is set to "connected".
4821
4822
This option is intended to be used to troubleshoot problems
4823
with the
4824
.B \-\-ifconfig
4825
and
4826
.B \-\-ip-win32
4827
options, and is used to give
4828
the TAP-Win32 adapter time to come up before
4829
Windows IP Helper API operations are applied to it.
4830
.\"*********************************************************
4831
.TP
4832
.B \-\-show-net-up
4833
Output OpenVPN's view of the system routing table and network
4834
adapter list to the syslog or log file after the TUN/TAP adapter
4835
has been brought up and any routes have been added.
4836
.\"*********************************************************
4837
.TP
4838
.B \-\-dhcp-renew
4839
Ask Windows to renew the TAP adapter lease on startup.
4840
This option is normally unnecessary, as Windows automatically
4841
triggers a DHCP renegotiation on the TAP adapter when it
4842
comes up, however if you set the TAP-Win32 adapter
4843
Media Status property to "Always Connected", you may need this
4844
flag.
4845
.\"*********************************************************
4846
.TP
4847
.B \-\-dhcp-release
4848
Ask Windows to release the TAP adapter lease on shutdown.
4849
This option has the same caveats as
4850
.B \-\-dhcp-renew
4851
above.
4852
.\"*********************************************************
4853
.TP
4854
.B \-\-register-dns
4855
Run net stop dnscache, net start dnscache, ipconfig /flushdns
4856
and ipconfig /registerdns on connection initiation.
4857
This is known to kick Windows into
4858
recognizing pushed DNS servers.
4859
.\"*********************************************************
4860
.TP
4861
.B \-\-pause-exit
4862
Put up a "press any key to continue" message on the console prior
4863
to OpenVPN program exit. This option is automatically used by the
4864
Windows explorer when OpenVPN is run on a configuration
4865
file using the right-click explorer menu.
4866
.\"*********************************************************
4867
.TP
4868
.B \-\-service exit-event [0|1]
4869
Should be used when OpenVPN is being automatically executed by another
4870
program in such
4871
a context that no interaction with the user via display or keyboard
4872
is possible. In general, end-users should never need to explicitly
4873
use this option, as it is automatically added by the OpenVPN service wrapper
4874
when a given OpenVPN configuration is being run as a service.
4875
4876
.B exit-event
4877
is the name of a Windows global event object, and OpenVPN will continuously
4878
monitor the state of this event object and exit when it becomes signaled.
4879
4880
The second parameter indicates the initial state of
4881
.B exit-event
4882
and normally defaults to 0.
4883
4884
Multiple OpenVPN processes can be simultaneously executed with the same
4885
.B exit-event
4886
parameter. In any case, the controlling process can signal
4887
.B exit-event,
4888
causing all such OpenVPN processes to exit.
4889
4890
When executing an OpenVPN process using the
4891
.B \-\-service
4892
directive, OpenVPN will probably not have a console
4893
window to output status/error
4894
messages, therefore it is useful to use
4895
.B \-\-log
4896
or
4897
.B \-\-log-append
4898
to write these messages to a file.
4899
.\"*********************************************************
4900
.TP
4901
.B \-\-show-adapters
4902
(Standalone)
4903
Show available TAP-Win32 adapters which can be selected using the
4904
.B \-\-dev-node
4905
option. On non-Windows systems, the
4906
.BR ifconfig (8)
4907
command provides similar functionality.
4908
.\"*********************************************************
4909
.TP
4910
.B \-\-allow-nonadmin [TAP-adapter]
4911
(Standalone)
4912
Set
4913
.B TAP-adapter
4914
to allow access from non-administrative accounts. If
4915
.B TAP-adapter
4916
is omitted, all TAP adapters on the system will be configured to allow
4917
non-admin access.
4918
The non-admin access setting will only persist for the length of time that
4919
the TAP-Win32 device object and driver remain loaded, and will need
4920
to be re-enabled after a reboot, or if the driver is unloaded
4921
and reloaded.
4922
This directive can only be used by an administrator.
4923
.\"*********************************************************
4924
.TP
4925
.B \-\-show-valid-subnets
4926
(Standalone)
4927
Show valid subnets for
4928
.B \-\-dev tun
4929
emulation. Since the TAP-Win32 driver
4930
exports an ethernet interface to Windows, and since TUN devices are
4931
point-to-point in nature, it is necessary for the TAP-Win32 driver
4932
to impose certain constraints on TUN endpoint address selection.
4933
4934
Namely, the point-to-point endpoints used in TUN device emulation
4935
must be the middle two addresses of a /30 subnet (netmask 255.255.255.252).
4936
.\"*********************************************************
4937
.TP
4938
.B \-\-show-net
4939
(Standalone)
4940
Show OpenVPN's view of the system routing table and network
4941
adapter list.
4942
.\"*********************************************************
4943
.SS PKCS#11 Standalone Options:
4944
.\"*********************************************************
4945
.TP
4946
.B \-\-show-pkcs11-ids provider [cert_private]
4947
(Standalone)
4948
Show PKCS#11 token object list. Specify cert_private as 1
4949
if certificates are stored as private objects.
4950
4951
.B \-\-verb
4952
option can be used BEFORE this option to produce debugging information.
4953
.\"*********************************************************
4954
.SS IPv6 Related Options
4955
.\"*********************************************************
4956
The following options exist to support IPv6 tunneling in peer-to-peer
4957
and client-server mode. As of now, this is just very basic
4958
documentation of the IPv6-related options. More documentation can be
4959
found on http://www.greenie.net/ipv6/openvpn.html.
4960
.TP
4961
.B --ifconfig-ipv6 ipv6addr/bits ipv6remote
4962
configure IPv6 address
4963
.B ipv6addr/bits
4964
on the ``tun'' device. The second parameter is used as route target for
4965
.B --route-ipv6
4966
if no gateway is specified.
4967
.TP
4968
.B --route-ipv6 ipv6addr/bits [gateway] [metric]
4969
setup IPv6 routing in the system to send the specified IPv6 network
4970
into OpenVPN's ``tun'' device
4971
.TP
4972
.B --server-ipv6 ipv6addr/bits
4973
convenience-function to enable a number of IPv6 related options at
4974
once, namely
4975
.B --ifconfig-ipv6, --ifconfig-ipv6-pool, --tun-ipv6
4976
and
4977
.B --push tun-ipv6
4978
Is only accepted if ``--mode server'' or ``--server'' is set.
4979
.TP
4980
.B --ifconfig-ipv6-pool ipv6addr/bits
4981
Specify an IPv6 address pool for dynamic assignment to clients. The
4982
pool starts at
4983
.B ipv6addr
4984
and increments by +1 for every new client (linear mode). The
4985
.B /bits
4986
setting controls the size of the pool.
4987
.TP
4988
.B --ifconfig-ipv6-push ipv6addr/bits ipv6remote
4989
for ccd/ per-client static IPv6 interface configuration, see
4990
.B --client-config-dir
4991
and
4992
.B --ifconfig-push
4993
for more details.
4994
.TP
4995
.B --iroute-ipv6 ipv6addr/bits
4996
for ccd/ per-client static IPv6 route configuration, see
4997
.B --iroute
4998
for more details how to setup and use this, and how
4999
.B --iroute
5000
and
5001
.B --route
5002
interact.
5003
5004
.\"*********************************************************
5005
.SH SCRIPTING AND ENVIRONMENTAL VARIABLES
5006
OpenVPN exports a series
5007
of environmental variables for use by user-defined scripts.
5008
.\"*********************************************************
5009
.SS Script Order of Execution
5010
.\"*********************************************************
5011
.TP
5012
.B \-\-up
5013
Executed after TCP/UDP socket bind and TUN/TAP open.
5014
.\"*********************************************************
5015
.TP
5016
.B \-\-tls-verify
5017
Executed when we have a still untrusted remote peer.
5018
.\"*********************************************************
5019
.TP
5020
.B \-\-ipchange
5021
Executed after connection authentication, or remote IP address change.
5022
.\"*********************************************************
5023
.TP
5024
.B \-\-client-connect
5025
Executed in
5026
.B \-\-mode server
5027
mode immediately after client authentication.
5028
.\"*********************************************************
5029
.TP
5030
.B \-\-route-up
5031
Executed after connection authentication, either
5032
immediately after, or some number of seconds after
5033
as defined by the
5034
.B \-\-route-delay
5035
option.
5036
.\"*********************************************************
5037
.TP
5038
.B \-\-client-disconnect
5039
Executed in
5040
.B \-\-mode server
5041
mode on client instance shutdown.
5042
.\"*********************************************************
5043
.TP
5044
.B \-\-down
5045
Executed after TCP/UDP and TUN/TAP close.
5046
.\"*********************************************************
5047
.TP
5048
.B \-\-learn-address
5049
Executed in
5050
.B \-\-mode server
5051
mode whenever an IPv4 address/route or MAC address is added to OpenVPN's
5052
internal routing table.
5053
.\"*********************************************************
5054
.TP
5055
.B \-\-auth-user-pass-verify
5056
Executed in
5057
.B \-\-mode server
5058
mode on new client connections, when the client is
5059
still untrusted.
5060
.\"*********************************************************
5061
.SS String Types and Remapping
5062
In certain cases, OpenVPN will perform remapping of characters
5063
in strings. Essentially, any characters outside the set of
5064
permitted characters for each string type will be converted
5065
to underbar ('_').
5066
5067
.B Q:
5068
Why is string remapping necessary?
5069
5070
.B A:
5071
It's an important security feature to prevent the malicious coding of
5072
strings from untrusted sources to be passed as parameters to scripts,
5073
saved in the environment, used as a common name, translated to a filename,
5074
etc.
5075
5076
.B Q:
5077
Can string remapping be disabled?
5078
5079
.B A:
5080
Yes, by using the
5081
.B \-\-no-name-remapping
5082
option, however this should be considered an advanced option.
5083
5084
Here is a brief rundown of OpenVPN's current string types and the
5085
permitted character class for each string:
5086
5087
.B X509 Names:
5088
Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), at
5089
('@'), colon (':'), slash ('/'), and equal ('='). Alphanumeric is defined
5090
as a character which will cause the C library isalnum() function to return
5091
true.
5092
5093
.B Common Names:
5094
Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), and at
5095
('@').
5096
5097
.B \-\-auth-user-pass username:
5098
Same as Common Name, with one exception: starting with OpenVPN 2.0.1,
5099
the username is passed to the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin in its raw form,
5100
without string remapping.
5101
5102
.B \-\-auth-user-pass password:
5103
Any "printable" character except CR or LF.
5104
Printable is defined to be a character which will cause the C library
5105
isprint() function to return true.
5106
5107
.B \-\-client-config-dir filename as derived from common name or username:
5108
Alphanumeric, underbar ('_'), dash ('-'), and dot ('.') except for "." or
5109
".." as standalone strings. As of 2.0.1-rc6, the at ('@') character has
5110
been added as well for compatibility with the common name character class.
5111
5112
.B Environmental variable names:
5113
Alphanumeric or underbar ('_').
5114
5115
.B Environmental variable values:
5116
Any printable character.
5117
5118
For all cases, characters in a string which are not members of the legal
5119
character class for that string type will be remapped to underbar ('_').
5120
.\"*********************************************************
5121
.SS Environmental Variables
5122
Once set, a variable is persisted
5123
indefinitely until it is reset by a new value or a restart,
5124
5125
As of OpenVPN 2.0-beta12, in server mode, environmental
5126
variables set by OpenVPN
5127
are scoped according to the client objects
5128
they are
5129
associated with, so there should not be any issues with
5130
scripts having access to stale, previously set variables
5131
which refer to different client instances.
5132
.\"*********************************************************
5133
.TP
5134
.B bytes_received
5135
Total number of bytes received from client during VPN session.
5136
Set prior to execution of the
5137
.B \-\-client-disconnect
5138
script.
5139
.\"*********************************************************
5140
.TP
5141
.B bytes_sent
5142
Total number of bytes sent to client during VPN session.
5143
Set prior to execution of the
5144
.B \-\-client-disconnect
5145
script.
5146
.\"*********************************************************
5147
.TP
5148
.B common_name
5149
The X509 common name of an authenticated client.
5150
Set prior to execution of
5151
.B \-\-client-connect, \-\-client-disconnect,
5152
and
5153
.B \-\-auth-user-pass-verify
5154
scripts.
5155
.\"*********************************************************
5156
.TP
5157
.B config
5158
Name of first
5159
.B \-\-config
5160
file.
5161
Set on program initiation and reset on SIGHUP.
5162
.\"*********************************************************
5163
.TP
5164
.B daemon
5165
Set to "1" if the
5166
.B \-\-daemon
5167
directive is specified, or "0" otherwise.
5168
Set on program initiation and reset on SIGHUP.
5169
.\"*********************************************************
5170
.TP
5171
.B daemon_log_redirect
5172
Set to "1" if the
5173
.B \-\-log
5174
or
5175
.B \-\-log-append
5176
directives are specified, or "0" otherwise.
5177
Set on program initiation and reset on SIGHUP.
5178
.\"*********************************************************
5179
.TP
5180
.B dev
5181
The actual name of the TUN/TAP device, including
5182
a unit number if it exists.
5183
Set prior to
5184
.B \-\-up
5185
or
5186
.B \-\-down
5187
script execution.
5188
.\"*********************************************************
5189
.TP
5190
.B foreign_option_{n}
5191
An option pushed via
5192
.B \-\-push
5193
to a client which does not natively support it,
5194
such as
5195
.B \-\-dhcp-option
5196
on a non-Windows system, will be recorded to this
5197
environmental variable sequence prior to
5198
.B \-\-up
5199
script execution.
5200
.\"*********************************************************
5201
.TP
5202
.B ifconfig_broadcast
5203
The broadcast address for the virtual
5204
ethernet segment which is derived from the
5205
.B \-\-ifconfig
5206
option when
5207
.B \-\-dev tap
5208
is used.
5209
Set prior to OpenVPN calling the
5210
.I ifconfig
5211
or
5212
.I netsh
5213
(windows version of ifconfig) commands which
5214
normally occurs prior to
5215
.B \-\-up
5216
script execution.
5217
.\"*********************************************************
5218
.TP
5219
.B ifconfig_local
5220
The local VPN endpoint IP address specified in the
5221
.B \-\-ifconfig
5222
option (first parameter).
5223
Set prior to OpenVPN calling the
5224
.I ifconfig
5225
or
5226
.I netsh
5227
(windows version of ifconfig) commands which
5228
normally occurs prior to
5229
.B \-\-up
5230
script execution.
5231
.\"*********************************************************
5232
.TP
5233
.B ifconfig_remote
5234
The remote VPN endpoint IP address specified in the
5235
.B \-\-ifconfig
5236
option (second parameter) when
5237
.B \-\-dev tun
5238
is used.
5239
Set prior to OpenVPN calling the
5240
.I ifconfig
5241
or
5242
.I netsh
5243
(windows version of ifconfig) commands which
5244
normally occurs prior to
5245
.B \-\-up
5246
script execution.
5247
.\"*********************************************************
5248
.TP
5249
.B ifconfig_netmask
5250
The subnet mask of the virtual ethernet segment
5251
that is specified as the second parameter to
5252
.B \-\-ifconfig
5253
when
5254
.B \-\-dev tap
5255
is being used.
5256
Set prior to OpenVPN calling the
5257
.I ifconfig
5258
or
5259
.I netsh
5260
(windows version of ifconfig) commands which
5261
normally occurs prior to
5262
.B \-\-up
5263
script execution.
5264
.\"*********************************************************
5265
.TP
5266
.B ifconfig_pool_local_ip
5267
The local
5268
virtual IP address for the TUN/TAP tunnel taken from an
5269
.B \-\-ifconfig-push
5270
directive if specified, or otherwise from
5271
the ifconfig pool (controlled by the
5272
.B \-\-ifconfig-pool
5273
config file directive).
5274
Only set for
5275
.B \-\-dev tun
5276
tunnels.
5277
This option is set on the server prior to execution
5278
of the
5279
.B \-\-client-connect
5280
and
5281
.B \-\-client-disconnect
5282
scripts.
5283
.\"*********************************************************
5284
.TP
5285
.B ifconfig_pool_netmask
5286
The
5287
virtual IP netmask for the TUN/TAP tunnel taken from an
5288
.B \-\-ifconfig-push
5289
directive if specified, or otherwise from
5290
the ifconfig pool (controlled by the
5291
.B \-\-ifconfig-pool
5292
config file directive).
5293
Only set for
5294
.B \-\-dev tap
5295
tunnels.
5296
This option is set on the server prior to execution
5297
of the
5298
.B \-\-client-connect
5299
and
5300
.B \-\-client-disconnect
5301
scripts.
5302
.\"*********************************************************
5303
.TP
5304
.B ifconfig_pool_remote_ip
5305
The remote
5306
virtual IP address for the TUN/TAP tunnel taken from an
5307
.B \-\-ifconfig-push
5308
directive if specified, or otherwise from
5309
the ifconfig pool (controlled by the
5310
.B \-\-ifconfig-pool
5311
config file directive).
5312
This option is set on the server prior to execution
5313
of the
5314
.B \-\-client-connect
5315
and
5316
.B \-\-client-disconnect
5317
scripts.
5318
.\"*********************************************************
5319
.TP
5320
.B link_mtu
5321
The maximum packet size (not including the IP header)
5322
of tunnel data in UDP tunnel transport mode.
5323
Set prior to
5324
.B \-\-up
5325
or
5326
.B \-\-down
5327
script execution.
5328
.\"*********************************************************
5329
.TP
5330
.B local
5331
The
5332
.B \-\-local
5333
parameter.
5334
Set on program initiation and reset on SIGHUP.
5335
.\"*********************************************************
5336
.TP
5337
.B local_port
5338
The local port number, specified by
5339
.B \-\-port
5340
or
5341
.B \-\-lport.
5342
Set on program initiation and reset on SIGHUP.
5343
.\"*********************************************************
5344
.TP
5345
.B password
5346
The password provided by a connecting client.
5347
Set prior to
5348
.B \-\-auth-user-pass-verify
5349
script execution only when the
5350
.B via-env
5351
modifier is specified, and deleted from the environment
5352
after the script returns.
5353
.\"*********************************************************
5354
.TP
5355
.B proto
5356
The
5357
.B \-\-proto
5358
parameter.
5359
Set on program initiation and reset on SIGHUP.
5360
.\"*********************************************************
5361
.TP
5362
.B remote_{n}
5363
The
5364
.B \-\-remote
5365
parameter.
5366
Set on program initiation and reset on SIGHUP.
5367
.\"*********************************************************
5368
.TP
5369
.B remote_port_{n}
5370
The remote port number, specified by
5371
.B \-\-port
5372
or
5373
.B \-\-rport.
5374
Set on program initiation and reset on SIGHUP.
5375
.\"*********************************************************
5376
.TP
5377
.B route_net_gateway
5378
The pre-existing default IP gateway in the system routing
5379
table.
5380
Set prior to
5381
.B \-\-up
5382
script execution.
5383
.\"*********************************************************
5384
.TP
5385
.B route_vpn_gateway
5386
The default gateway used by
5387
.B \-\-route
5388
options, as specified in either the
5389
.B \-\-route-gateway
5390
option or the second parameter to
5391
.B \-\-ifconfig
5392
when
5393
.B \-\-dev tun
5394
is specified.
5395
Set prior to
5396
.B \-\-up
5397
script execution.
5398
.\"*********************************************************
5399
.TP
5400
.B route_{parm}_{n}
5401
A set of variables which define each route to be added, and
5402
are set prior to
5403
.B \-\-up
5404
script execution.
5405
5406
.B parm
5407
will be one of "network", "netmask", "gateway", or "metric".
5408
5409
.B n
5410
is the OpenVPN route number, starting from 1.
5411
5412
If the network or gateway are resolvable DNS names,
5413
their IP address translations will be recorded rather
5414
than their names as denoted on the command line
5415
or configuration file.
5416
.\"*********************************************************
5417
.TP
5418
.B peer_cert
5419
Temporary file name containing the client certificate upon
5420
connection. Useful in conjunction with --tls-verify
5421
.\"*********************************************************
5422
.TP
5423
.B script_context
5424
Set to "init" or "restart" prior to up/down script execution.
5425
For more information, see
5426
documentation for
5427
.B \-\-up.
5428
.\"*********************************************************
5429
.TP
5430
.B script_type
5431
Prior to execution of any script, this variable is set to the type of
5432
script being run. It can be one of the following:
5433
.B up, down, ipchange, route-up, tls-verify, auth-user-pass-verify,
5434
.B client-connect, client-disconnect,
5435
or
5436
.B learn-address.
5437
.\"*********************************************************
5438
.TP
5439
.B signal
5440
The reason for exit or restart. Can be one of
5441
.B sigusr1, sighup, sigterm, sigint, inactive
5442
(controlled by
5443
.B \-\-inactive
5444
option),
5445
.B ping-exit
5446
(controlled by
5447
.B \-\-ping-exit
5448
option),
5449
.B ping-restart
5450
(controlled by
5451
.B \-\-ping-restart
5452
option),
5453
.B connection-reset
5454
(triggered on TCP connection reset),
5455
.B error,
5456
or
5457
.B unknown
5458
(unknown signal). This variable is set just prior to down script execution.
5459
.\"*********************************************************
5460
.TP
5461
.B time_ascii
5462
Client connection timestamp, formatted as a human-readable
5463
time string.
5464
Set prior to execution of the
5465
.B \-\-client-connect
5466
script.
5467
.\"*********************************************************
5468
.TP
5469
.B time_duration
5470
The duration (in seconds) of the client session which is now
5471
disconnecting.
5472
Set prior to execution of the
5473
.B \-\-client-disconnect
5474
script.
5475
.\"*********************************************************
5476
.TP
5477
.B time_unix
5478
Client connection timestamp, formatted as a unix integer
5479
date/time value.
5480
Set prior to execution of the
5481
.B \-\-client-connect
5482
script.
5483
.\"*********************************************************
5484
.TP
5485
.B tls_id_{n}
5486
A series of certificate fields from the remote peer,
5487
where
5488
.B n
5489
is the verification level. Only set for TLS connections. Set prior
5490
to execution of
5491
.B \-\-tls-verify
5492
script.
5493
.\"*********************************************************
5494
.TP
5495
.B tls_serial_{n}
5496
The serial number of the certificate from the remote peer,
5497
where
5498
.B n
5499
is the verification level. Only set for TLS connections. Set prior
5500
to execution of
5501
.B \-\-tls-verify
5502
script. This is in the form of a hex string like "37AB46E0", which is
5503
suitable for doing serial-based OCSP queries (with OpenSSL, you have
5504
to prepend "0x" to the string). If something goes wrong while reading
5505
the value from the certificate it will be an empty string, so your
5506
code should check that.
5507
See the contrib/OCSP_check/OCSP_check.sh script for an example.
5508
.\"*********************************************************
5509
.TP
5510
.B tun_mtu
5511
The MTU of the TUN/TAP device.
5512
Set prior to
5513
.B \-\-up
5514
or
5515
.B \-\-down
5516
script execution.
5517
.\"*********************************************************
5518
.TP
5519
.B trusted_ip (or trusted_ip6)
5520
Actual IP address of connecting client or peer which has been authenticated.
5521
Set prior to execution of
5522
.B \-\-ipchange, \-\-client-connect,
5523
and
5524
.B \-\-client-disconnect
5525
scripts.
5526
If using ipv6 endpoints (udp6, tcp6),
5527
.B trusted_ip6
5528
will be set instead.
5529
.\"*********************************************************
5530
.TP
5531
.B trusted_port
5532
Actual port number of connecting client or peer which has been authenticated.
5533
Set prior to execution of
5534
.B \-\-ipchange, \-\-client-connect,
5535
and
5536
.B \-\-client-disconnect
5537
scripts.
5538
.\"*********************************************************
5539
.TP
5540
.B untrusted_ip (or untrusted_ip6)
5541
Actual IP address of connecting client or peer which has not been authenticated
5542
yet. Sometimes used to
5543
.B nmap
5544
the connecting host in a
5545
.B \-\-tls-verify
5546
script to ensure it is firewalled properly.
5547
Set prior to execution of
5548
.B \-\-tls-verify
5549
and
5550
.B \-\-auth-user-pass-verify
5551
scripts.
5552
If using ipv6 endpoints (udp6, tcp6),
5553
.B untrusted_ip6
5554
will be set instead.
5555
.\"*********************************************************
5556
.TP
5557
.B untrusted_port
5558
Actual port number of connecting client or peer which has not been authenticated
5559
yet.
5560
Set prior to execution of
5561
.B \-\-tls-verify
5562
and
5563
.B \-\-auth-user-pass-verify
5564
scripts.
5565
.\"*********************************************************
5566
.TP
5567
.B username
5568
The username provided by a connecting client.
5569
Set prior to
5570
.B \-\-auth-user-pass-verify
5571
script execution only when the
5572
.B via-env
5573
modifier is specified.
5574
.\"*********************************************************
5575
.TP
5576
.B X509_{n}_{subject_field}
5577
An X509 subject field from the remote peer certificate,
5578
where
5579
.B n
5580
is the verification level. Only set for TLS connections. Set prior
5581
to execution of
5582
.B \-\-tls-verify
5583
script. This variable is similar to
5584
.B tls_id_{n}
5585
except the component X509 subject fields are broken out, and
5586
no string remapping occurs on these field values (except for remapping
5587
of control characters to "_").
5588
For example, the following variables would be set on the
5589
OpenVPN server using the sample client certificate
5590
in sample-keys (client.crt).
5591
Note that the verification level is 0 for the client certificate
5592
and 1 for the CA certificate.
5593
5594
.nf
5595
.ft 3
5596
.in +4
5597
X509_0_emailAddress=me@myhost.mydomain
5598
X509_0_CN=Test-Client
5599
X509_0_O=OpenVPN-TEST
5600
X509_0_ST=NA
5601
X509_0_C=KG
5602
X509_1_emailAddress=me@myhost.mydomain
5603
X509_1_O=OpenVPN-TEST
5604
X509_1_L=BISHKEK
5605
X509_1_ST=NA
5606
X509_1_C=KG
5607
.in -4
5608
.ft
5609
.fi
5610
.\"*********************************************************
5611
.SH SIGNALS
5612
.TP
5613
.B SIGHUP
5614
Cause OpenVPN to close all TUN/TAP and
5615
network connections,
5616
restart, re-read the configuration file (if any),
5617
and reopen TUN/TAP and network connections.
5618
.\"*********************************************************
5619
.TP
5620
.B SIGUSR1
5621
Like
5622
.B SIGHUP,
5623
except don't re-read configuration file, and possibly don't close and reopen TUN/TAP
5624
device, re-read key files, preserve local IP address/port, or preserve most recently authenticated
5625
remote IP address/port based on
5626
.B \-\-persist-tun, \-\-persist-key, \-\-persist-local-ip,
5627
and
5628
.B \-\-persist-remote-ip
5629
options respectively (see above).
5630
5631
This signal may also be internally generated by a timeout condition, governed
5632
by the
5633
.B \-\-ping-restart
5634
option.
5635
5636
This signal, when combined with
5637
.B \-\-persist-remote-ip,
5638
may be
5639
sent when the underlying parameters of the host's network interface change
5640
such as when the host is a DHCP client and is assigned a new IP address.
5641
See
5642
.B \-\-ipchange
5643
above for more information.
5644
.\"*********************************************************
5645
.TP
5646
.B SIGUSR2
5647
Causes OpenVPN to display its current statistics (to the syslog
5648
file if
5649
.B \-\-daemon
5650
is used, or stdout otherwise).
5651
.\"*********************************************************
5652
.TP
5653
.B SIGINT, SIGTERM
5654
Causes OpenVPN to exit gracefully.
5655
.\"*********************************************************
5656
.SH TUN/TAP DRIVER SETUP
5657
If you are running Linux 2.4.7 or higher, you probably have the TUN/TAP driver
5658
already installed. If so, there are still a few things you need to do:
5659
5660
Make device:
5661
.B mknod /dev/net/tun c 10 200
5662
5663
Load driver:
5664
.B modprobe tun
5665
.\"*********************************************************
5666
.SH EXAMPLES
5667
Prior to running these examples, you should have OpenVPN installed on two
5668
machines with network connectivity between them. If you have not
5669
yet installed OpenVPN, consult the INSTALL file included in the OpenVPN
5670
distribution.
5671
.\"*********************************************************
5672
.SS TUN/TAP Setup:
5673
If you are using Linux 2.4 or higher,
5674
make the tun device node and load the tun module:
5675
.IP
5676
.B mknod /dev/net/tun c 10 200
5677
.LP
5678
.IP
5679
.B modprobe tun
5680
.LP
5681
If you installed from RPM, the
5682
.B mknod
5683
step may be omitted, because the RPM install does that for you.
5684
5685
Only Linux 2.4 and newer are supported.
5686
5687
For other platforms, consult the INSTALL file at
5688
.I http://openvpn.net/install.html
5689
for more information.
5690
.\"*********************************************************
5691
.SS Firewall Setup:
5692
If firewalls exist between
5693
the two machines, they should be set to forward UDP port 1194
5694
in both directions. If you do not have control over the firewalls
5695
between the two machines, you may still be able to use OpenVPN by adding
5696
.B \-\-ping 15
5697
to each of the
5698
.B openvpn
5699
commands used below in the examples (this will cause each peer to send out
5700
a UDP ping to its remote peer once every 15 seconds which will cause many
5701
stateful firewalls to forward packets in both directions
5702
without an explicit firewall rule).
5703
5704
If you are using a Linux iptables-based firewall, you may need to enter
5705
the following command to allow incoming packets on the TUN device:
5706
.IP
5707
.B iptables -A INPUT -i tun+ -j ACCEPT
5708
.LP
5709
See the firewalls section below for more information on configuring firewalls
5710
for use with OpenVPN.
5711
.\"*********************************************************
5712
.SS VPN Address Setup:
5713
For purposes
5714
of our example, our two machines will be called
5715
.B may.kg
5716
and
5717
.B june.kg.
5718
If you are constructing a VPN over the internet, then replace
5719
.B may.kg
5720
and
5721
.B june.kg
5722
with the internet hostname or IP address that each machine will use
5723
to contact the other over the internet.
5724
5725
Now we will choose the tunnel endpoints. Tunnel endpoints are
5726
private IP addresses that only have meaning in the context of
5727
the VPN. Each machine will use the tunnel endpoint of the other
5728
machine to access it over the VPN. In our example,
5729
the tunnel endpoint for may.kg
5730
will be 10.4.0.1 and for june.kg, 10.4.0.2.
5731
5732
Once the VPN is established, you have essentially
5733
created a secure alternate path between the two hosts
5734
which is addressed by using the tunnel endpoints. You can
5735
control which network
5736
traffic passes between the hosts
5737
(a) over the VPN or (b) independently of the VPN, by choosing whether to use
5738
(a) the VPN endpoint address or (b) the public internet address,
5739
to access the remote host. For example if you are on may.kg and you wish to connect to june.kg
5740
via
5741
.B ssh
5742
without using the VPN (since
5743
.B ssh
5744
has its own built-in security) you would use the command
5745
.B ssh june.kg.
5746
However in the same scenario, you could also use the command
5747
.B telnet 10.4.0.2
5748
to create a telnet session with june.kg over the VPN, that would
5749
use the VPN to secure the session rather than
5750
.B ssh.
5751
5752
You can use any address you wish for the
5753
tunnel endpoints
5754
but make sure that they are private addresses
5755
(such as those that begin with 10 or 192.168) and that they are
5756
not part of any existing subnet on the networks of
5757
either peer, unless you are bridging. If you use an address that is part of
5758
your local subnet for either of the tunnel endpoints,
5759
you will get a weird feedback loop.
5760
.\"*********************************************************
5761
.SS Example 1: A simple tunnel without security
5762
.LP
5763
On may:
5764
.IP
5765
.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9
5766
.LP
5767
On june:
5768
.IP
5769
.B openvpn \-\-remote may.kg \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9
5770
.LP
5771
Now verify the tunnel is working by pinging across the tunnel.
5772
.LP
5773
On may:
5774
.IP
5775
.B ping 10.4.0.2
5776
.LP
5777
On june:
5778
.IP
5779
.B ping 10.4.0.1
5780
.LP
5781
The
5782
.B \-\-verb 9
5783
option will produce verbose output, similar to the
5784
.BR tcpdump (8)
5785
program. Omit the
5786
.B \-\-verb 9
5787
option to have OpenVPN run quietly.
5788
.\"*********************************************************
5789
.SS Example 2: A tunnel with static-key security (i.e. using a pre-shared secret)
5790
First build a static key on may.
5791
.IP
5792
.B openvpn \-\-genkey \-\-secret key
5793
.LP
5794
This command will build a random key file called
5795
.B key
5796
(in ascii format).
5797
Now copy
5798
.B key
5799
to june over a secure medium such as by
5800
using the
5801
.BR scp (1)
5802
program.
5803
.LP
5804
On may:
5805
.IP
5806
.B openvpn \-\-remote june.kg \-\-dev tun1 \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \-\-secret key
5807
.LP
5808
On june:
5809
.IP
5810
.B openvpn \-\-remote may.kg \-\-dev tun1 \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \-\-secret key
5811
.LP
5812
Now verify the tunnel is working by pinging across the tunnel.
5813
.LP
5814
On may:
5815
.IP
5816
.B ping 10.4.0.2
5817
.LP
5818
On june:
5819
.IP
5820
.B ping 10.4.0.1
5821
.\"*********************************************************
5822
.SS Example 3: A tunnel with full TLS-based security
5823
For this test, we will designate
5824
.B may
5825
as the TLS client and
5826
.B june
5827
as the TLS server.
5828
.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.
5829
5830
First, build a separate certificate/key pair
5831
for both may and june (see above where
5832
.B \-\-cert
5833
is discussed for more info). Then construct
5834
Diffie Hellman parameters (see above where
5835
.B \-\-dh
5836
is discussed for more info). You can also use the
5837
included test files client.crt, client.key,
5838
server.crt, server.key and ca.crt.
5839
The .crt files are certificates/public-keys, the .key
5840
files are private keys, and ca.crt is a certification
5841
authority who has signed both
5842
client.crt and server.crt. For Diffie Hellman
5843
parameters you can use the included file dh1024.pem.
5844
.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.
5845
.LP
5846
On may:
5847
.IP
5848
.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
5849
.LP
5850
On june:
5851
.IP
5852
.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
5853
.LP
5854
Now verify the tunnel is working by pinging across the tunnel.
5855
.LP
5856
On may:
5857
.IP
5858
.B ping 10.4.0.2
5859
.LP
5860
On june:
5861
.IP
5862
.B ping 10.4.0.1
5863
.LP
5864
Notice the
5865
.B \-\-reneg-sec 60
5866
option we used above. That tells OpenVPN to renegotiate
5867
the data channel keys every minute.
5868
Since we used
5869
.B \-\-verb 5
5870
above, you will see status information on each new key negotiation.
5871
5872
For production operations, a key renegotiation interval of 60 seconds
5873
is probably too frequent. Omit the
5874
.B \-\-reneg-sec 60
5875
option to use OpenVPN's default key renegotiation interval of one hour.
5876
.\"*********************************************************
5877
.SS Routing:
5878
Assuming you can ping across the tunnel,
5879
the next step is to route a real subnet over
5880
the secure tunnel. Suppose that may and june have two network
5881
interfaces each, one connected
5882
to the internet, and the other to a private
5883
network. Our goal is to securely connect
5884
both private networks. We will assume that may's private subnet
5885
is 10.0.0.0/24 and june's is 10.0.1.0/24.
5886
.LP
5887
First, ensure that IP forwarding is enabled on both peers.
5888
On Linux, enable routing:
5889
.IP
5890
.B echo 1 > /proc/sys/net/ipv4/ip_forward
5891
.LP
5892
and enable TUN packet forwarding through the firewall:
5893
.IP
5894
.B iptables -A FORWARD -i tun+ -j ACCEPT
5895
.LP
5896
On may:
5897
.IP
5898
.B route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
5899
.LP
5900
On june:
5901
.IP
5902
.B route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
5903
.LP
5904
Now any machine on the 10.0.0.0/24 subnet can
5905
access any machine on the 10.0.1.0/24 subnet
5906
over the secure tunnel (or vice versa).
5907
5908
In a production environment, you could put the route command(s)
5909
in a shell script and execute with the
5910
.B \-\-up
5911
option.
5912
.\"*********************************************************
5913
.SH FIREWALLS
5914
OpenVPN's usage of a single UDP port makes it fairly firewall-friendly.
5915
You should add an entry to your firewall rules to allow incoming OpenVPN
5916
packets. On Linux 2.4+:
5917
.IP
5918
.B iptables -A INPUT -p udp -s 1.2.3.4 \-\-dport 1194 -j ACCEPT
5919
.LP
5920
This will allow incoming packets on UDP port 1194 (OpenVPN's default UDP port)
5921
from an OpenVPN peer at 1.2.3.4.
5922
5923
If you are using HMAC-based packet authentication (the default in any of
5924
OpenVPN's secure modes), having the firewall filter on source
5925
address can be considered optional, since HMAC packet authentication
5926
is a much more secure method of verifying the authenticity of
5927
a packet source. In that case:
5928
.IP
5929
.B iptables -A INPUT -p udp \-\-dport 1194 -j ACCEPT
5930
.LP
5931
would be adequate and would not render the host inflexible with
5932
respect to its peer having a dynamic IP address.
5933
5934
OpenVPN also works well on stateful firewalls. In some cases, you may
5935
not need to add any static rules to the firewall list if you are
5936
using a stateful firewall that knows how to track UDP connections.
5937
If you specify
5938
.B \-\-ping n,
5939
OpenVPN will be guaranteed
5940
to send a packet to its peer at least once every
5941
.B n
5942
seconds. If
5943
.B n
5944
is less than the stateful firewall connection timeout, you can
5945
maintain an OpenVPN connection indefinitely without explicit
5946
firewall rules.
5947
5948
You should also add firewall rules to allow incoming IP traffic on
5949
TUN or TAP devices such as:
5950
.IP
5951
.B iptables -A INPUT -i tun+ -j ACCEPT
5952
.LP
5953
to allow input packets from tun devices,
5954
.IP
5955
.B iptables -A FORWARD -i tun+ -j ACCEPT
5956
.LP
5957
to allow input packets from tun devices to be forwarded to
5958
other hosts on the local network,
5959
.IP
5960
.B iptables -A INPUT -i tap+ -j ACCEPT
5961
.LP
5962
to allow input packets from tap devices, and
5963
.IP
5964
.B iptables -A FORWARD -i tap+ -j ACCEPT
5965
.LP
5966
to allow input packets from tap devices to be forwarded to
5967
other hosts on the local network.
5968
5969
These rules are secure if you use packet authentication,
5970
since no incoming packets will arrive on a TUN or TAP
5971
virtual device
5972
unless they first pass an HMAC authentication test.
5973
.\"*********************************************************
5974
.SH FAQ
5975
.I http://openvpn.net/faq.html
5976
.\"*********************************************************
5977
.SH HOWTO
5978
For a more comprehensive guide to setting up OpenVPN
5979
in a production setting, see the OpenVPN HOWTO at
5980
.I http://openvpn.net/howto.html
5981
.\"*********************************************************
5982
.SH PROTOCOL
5983
For a description of OpenVPN's underlying protocol,
5984
see
5985
.I http://openvpn.net/security.html
5986
.\"*********************************************************
5987
.SH WEB
5988
OpenVPN's web site is at
5989
.I http://openvpn.net/
5990
5991
Go here to download the latest version of OpenVPN, subscribe
5992
to the mailing lists, read the mailing list
5993
archives, or browse the SVN repository.
5994
.\"*********************************************************
5995
.SH BUGS
5996
Report all bugs to the OpenVPN team <info@openvpn.net>.
5997
.\"*********************************************************
5998
.SH "SEE ALSO"
5999
.BR dhcpcd (8),
6000
.BR ifconfig (8),
6001
.BR openssl (1),
6002
.BR route (8),
6003
.BR scp (1)
6004
.BR ssh (1)
6005
.\"*********************************************************
6006
.SH NOTES
6007
.LP
6008
This product includes software developed by the
6009
OpenSSL Project (
6010
.I http://www.openssl.org/
6011
)
6012
6013
For more information on the TLS protocol, see
6014
.I http://www.ietf.org/rfc/rfc2246.txt
6015
6016
For more information on the LZO real-time compression library see
6017
.I http://www.oberhumer.com/opensource/lzo/
6018
.\"*********************************************************
6019
.SH COPYRIGHT
6020
Copyright (C) 2002-2010 OpenVPN Technologies, Inc. This program is free software;
6021
you can redistribute it and/or modify
6022
it under the terms of the GNU General Public License version 2
6023
as published by the Free Software Foundation.
6024
.\"*********************************************************
6025
.SH AUTHORS
6026
James Yonan <jim@yonan.net>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1