1openvpn(8) System Manager's Manual openvpn(8)
2
3
4
6 openvpn - secure IP tunnel daemon.
7
9 openvpn [ options ... ]
10
12 OpenVPN is an open source VPN daemon by James Yonan. Because OpenVPN
13 tries to be a universal VPN tool offering a great deal of flexibility,
14 there are a lot of options on this manual page. If you're new to Open‐
15 VPN, you might want to skip ahead to the examples section where you
16 will see how to construct simple VPNs on the command line without even
17 needing a configuration file.
18
19 Also note that there's more documentation and examples on the OpenVPN
20 web site: http://openvpn.net/
21
22 And if you would like to see a shorter version of this manual, see the
23 openvpn usage message which can be obtained by running openvpn without
24 any parameters.
25
27 OpenVPN is a robust and highly flexible VPN daemon. OpenVPN supports
28 SSL/TLS security, ethernet bridging, TCP or UDP tunnel transport
29 through proxies or NAT, support for dynamic IP addresses and DHCP,
30 scalability to hundreds or thousands of users, and portability to most
31 major OS platforms.
32
33 OpenVPN is tightly bound to the OpenSSL library, and derives much of
34 its crypto capabilities from it.
35
36 OpenVPN supports conventional encryption using a pre-shared secret key
37 (Static Key mode) or public key security (SSL/TLS mode) using client &
38 server certificates. OpenVPN also supports non-encrypted TCP/UDP tun‐
39 nels.
40
41 OpenVPN is designed to work with the TUN/TAP virtual networking inter‐
42 face that exists on most platforms.
43
44 Overall, OpenVPN aims to offer many of the key features of IPSec but
45 with a relatively lightweight footprint.
46
48 OpenVPN allows any option to be placed either on the command line or in
49 a configuration file. Though all command line options are preceded by
50 a double-leading-dash ("--"), this prefix can be removed when an option
51 is placed in a configuration file.
52
53 --help Show options.
54
55 --config file
56 Load additional config options from file where each line corre‐
57 sponds to one command line option, but with the leading '--'
58 removed.
59
60 If --config file is the only option to the openvpn command, the
61 --config can be removed, and the command can be given as openvpn
62 file
63
64 Note that configuration files can be nested to a reasonable
65 depth.
66
67 Double quotation or single quotation characters ("", '') can be
68 used to enclose single parameters containing whitespace, and "#"
69 or ";" characters in the first column can be used to denote com‐
70 ments.
71
72 Note that OpenVPN 2.0 and higher performs backslash-based shell
73 escaping for characters not in single quotations, so the follow‐
74 ing mappings should be observed:
75
76 \\ Maps to a single backslash character (\).
77 \" Pass a literal doublequote character ("), don't
78 interpret it as enclosing a parameter.
79 \[SPACE] Pass a literal space or tab character, don't
80 interpret it as a parameter delimiter.
81
82 For example on Windows, use double backslashes to represent
83 pathnames:
84
85 secret "c:\\OpenVPN\\secret.key"
86
87 For examples of configuration files, see http://open‐
88 vpn.net/examples.html
89
90 Here is an example configuration file:
91
92 #
93 # Sample OpenVPN configuration file for
94 # using a pre-shared static key.
95 #
96 # '#' or ';' may be used to delimit comments.
97
98 # Use a dynamic tun device.
99 dev tun
100
101 # Our remote peer
102 remote mypeer.mydomain
103
104 # 10.1.0.1 is our local VPN endpoint
105 # 10.1.0.2 is our remote VPN endpoint
106 ifconfig 10.1.0.1 10.1.0.2
107
108 # Our pre-shared static key
109 secret static.key
110
111 Tunnel Options:
112 --mode m
113 Set OpenVPN major mode. By default, OpenVPN runs in point-to-
114 point mode ("p2p"). OpenVPN 2.0 introduces a new mode
115 ("server") which implements a multi-client server capability.
116
117 --local host
118 Local host name or IP address for bind. If specified, OpenVPN
119 will bind to this address only. If unspecified, OpenVPN will
120 bind to all interfaces.
121
122 --remote host [port] [proto]
123 Remote host name or IP address. On the client, multiple
124 --remote options may be specified for redundancy, each referring
125 to a different OpenVPN server. Specifying multiple --remote
126 options for this purpose is a special case of the more general
127 connection-profile feature. See the <connection> documentation
128 below.
129
130 The OpenVPN client will try to connect to a server at host:port
131 in the order specified by the list of --remote options.
132
133 proto indicates the protocol to use when connecting with the
134 remote, and may be "tcp" or "udp".
135
136 The client will move on to the next host in the list, in the
137 event of connection failure. Note that at any given time, the
138 OpenVPN client will at most be connected to one server.
139
140 Note that since UDP is connectionless, connection failure is
141 defined by the --ping and --ping-restart options.
142
143 Note the following corner case: If you use multiple --remote
144 options, AND you are dropping root privileges on the client with
145 --user and/or --group, AND the client is running a non-Windows
146 OS, if the client needs to switch to a different server, and
147 that server pushes back different TUN/TAP or route settings, the
148 client may lack the necessary privileges to close and reopen the
149 TUN/TAP interface. This could cause the client to exit with a
150 fatal error.
151
152 If --remote is unspecified, OpenVPN will listen for packets from
153 any IP address, but will not act on those packets unless they
154 pass all authentication tests. This requirement for authentica‐
155 tion is binding on all potential peers, even those from known
156 and supposedly trusted IP addresses (it is very easy to forge a
157 source IP address on a UDP packet).
158
159 When used in TCP mode, --remote will act as a filter, rejecting
160 connections from any host which does not match host.
161
162 If host is a DNS name which resolves to multiple IP addresses,
163 one will be randomly chosen, providing a sort of basic load-bal‐
164 ancing and failover capability.
165
166 <connection>
167 Define a client connection profile. Client connection profiles
168 are groups of OpenVPN options that describe how to connect to a
169 given OpenVPN server. Client connection profiles are specified
170 within an OpenVPN configuration file, and each profile is brack‐
171 eted by <connection> and </connection>.
172
173 An OpenVPN client will try each connection profile sequentially
174 until it achieves a successful connection.
175
176 --remote-random can be used to initially "scramble" the connec‐
177 tion list.
178
179 Here is an example of connection profile usage:
180
181 client
182 dev tun
183
184 <connection>
185 remote 198.19.34.56 1194 udp
186 </connection>
187
188 <connection>
189 remote 198.19.34.56 443 tcp
190 </connection>
191
192 <connection>
193 remote 198.19.34.56 443 tcp
194 http-proxy 192.168.0.8 8080
195 http-proxy-retry
196 </connection>
197
198 <connection>
199 remote 198.19.36.99 443 tcp
200 http-proxy 192.168.0.8 8080
201 http-proxy-retry
202 </connection>
203
204 persist-key
205 persist-tun
206 pkcs12 client.p12
207 ns-cert-type server
208 verb 3
209
210 First we try to connect to a server at 198.19.34.56:1194 using
211 UDP. If that fails, we then try to connect to 198.19.34.56:443
212 using TCP. If that also fails, then try connecting through an
213 HTTP proxy at 192.168.0.8:8080 to 198.19.34.56:443 using TCP.
214 Finally, try to connect through the same proxy to a server at
215 198.19.36.99:443 using TCP.
216
217 The following OpenVPN options may be used inside of a <connec‐
218 tion> block:
219
220 bind, connect-retry, connect-retry-max, connect-timeout, float,
221 http-proxy, http-proxy-option, http-proxy-retry, http-proxy-
222 timeout, local, lport, nobind, port, proto, remote, rport,
223 socks-proxy, and socks-proxy-retry.
224
225 A defaulting mechanism exists for specifying options to apply to
226 all <connection> profiles. If any of the above options (with
227 the exception of remote ) appear outside of a <connection>
228 block, but in a configuration file which has one or more <con‐
229 nection> blocks, the option setting will be used as a default
230 for <connection> blocks which follow it in the configuration
231 file.
232
233 For example, suppose the nobind option were placed in the sample
234 configuration file above, near the top of the file, before the
235 first <connection> block. The effect would be as if nobind were
236 declared in all <connection> blocks below it.
237
238
239 --remote-random
240 When multiple --remote address/ports are specified, or if con‐
241 nection profiles are being used, initially randomize the order
242 of the list as a kind of basic load-balancing measure.
243
244 --proto p
245 Use protocol p for communicating with remote host. p can be
246 udp, tcp-client, or tcp-server.
247
248 The default protocol is udp when --proto is not specified.
249
250 For UDP operation, --proto udp should be specified on both
251 peers.
252
253 For TCP operation, one peer must use --proto tcp-server and the
254 other must use --proto tcp-client. A peer started with tcp-
255 server will wait indefinitely for an incoming connection. A
256 peer started with tcp-client will attempt to connect, and if
257 that fails, will sleep for 5 seconds (adjustable via the --con‐
258 nect-retry option) and try again infinite or up to N retries
259 (adjustable via the --connect-retry-max option). Both TCP
260 client and server will simulate a SIGUSR1 restart signal if
261 either side resets the connection.
262
263 OpenVPN is designed to operate optimally over UDP, but TCP capa‐
264 bility is provided for situations where UDP cannot be used. In
265 comparison with UDP, TCP will usually be somewhat less efficient
266 and less robust when used over unreliable or congested networks.
267
268 This article outlines some of problems with tunneling IP over
269 TCP:
270
271 http://sites.inka.de/sites/bigred/devel/tcp-tcp.html
272
273 There are certain cases, however, where using TCP may be advan‐
274 tageous from a security and robustness perspective, such as tun‐
275 neling non-IP or application-level UDP protocols, or tunneling
276 protocols which don't possess a built-in reliability layer.
277
278 --connect-retry n
279 For --proto tcp-client, take n as the number of seconds to wait
280 between connection retries (default=5).
281
282 --connect-retry-max n
283 For --proto tcp-client, take n as the number of retries of con‐
284 nection attempt (default=infinite).
285
286 --auto-proxy
287 Try to sense HTTP or SOCKS proxy settings automatically. If no
288 settings are present, a direct connection will be attempted. If
289 both HTTP and SOCKS settings are present, HTTP will be pre‐
290 ferred. If the HTTP proxy server requires a password, it will
291 be queried from stdin or the management interface. If the
292 underlying OS doesn't support an API for returning proxy set‐
293 tings, a direct connection will be attempted. Currently, only
294 Windows clients support this option via the InternetQueryOption
295 API. This option exists in OpenVPN 2.1 or higher.
296
297 --http-proxy server port [authfile|'auto'] [auth-method]
298 Connect to remote host through an HTTP proxy at address server
299 and port port. If HTTP Proxy-Authenticate is required, authfile
300 is a file containing a username and password on 2 lines, or
301 "stdin" to prompt from console.
302
303 auth-method should be one of "none", "basic", or "ntlm".
304
305 The auto flag causes OpenVPN to automatically determine the
306 auth-method and query stdin or the management interface for
307 username/password credentials, if required. This flag exists on
308 OpenVPN 2.1 or higher.
309
310 --http-proxy-retry
311 Retry indefinitely on HTTP proxy errors. If an HTTP proxy error
312 occurs, simulate a SIGUSR1 reset.
313
314 --http-proxy-timeout n
315 Set proxy timeout to n seconds, default=5.
316
317 --http-proxy-option type [parm]
318 Set extended HTTP proxy options. Repeat to set multiple
319 options.
320
321 VERSION version -- Set HTTP version number to version
322 (default=1.0).
323
324 AGENT user-agent -- Set HTTP "User-Agent" string to user-agent.
325
326 --socks-proxy server [port]
327 Connect to remote host through a Socks5 proxy at address server
328 and port port (default=1080).
329
330 --socks-proxy-retry
331 Retry indefinitely on Socks proxy errors. If a Socks proxy
332 error occurs, simulate a SIGUSR1 reset.
333
334 --resolv-retry n
335 If hostname resolve fails for --remote, retry resolve for n sec‐
336 onds before failing.
337
338 Set n to "infinite" to retry indefinitely.
339
340 By default, --resolv-retry infinite is enabled. You can disable
341 by setting n=0.
342
343 --float
344 Allow remote peer to change its IP address and/or port number,
345 such as due to DHCP (this is the default if --remote is not
346 used). --float when specified with --remote allows an OpenVPN
347 session to initially connect to a peer at a known address, how‐
348 ever if packets arrive from a new address and pass all authenti‐
349 cation tests, the new address will take control of the session.
350 This is useful when you are connecting to a peer which holds a
351 dynamic address such as a dial-in user or DHCP client.
352
353 Essentially, --float tells OpenVPN to accept authenticated pack‐
354 ets from any address, not only the address which was specified
355 in the --remote option.
356
357 --ipchange cmd
358 Execute shell command cmd when our remote ip-address is ini‐
359 tially authenticated or changes.
360
361 Execute as:
362
363 cmd ip_address port_number
364
365 Don't use --ipchange in --mode server mode. Use a --client-con‐
366 nect script instead.
367
368 See the "Environmental Variables" section below for additional
369 parameters passed as environmental variables.
370
371 Note that cmd can be a shell command with multiple arguments, in
372 which case all OpenVPN-generated arguments will be appended to
373 cmd to build a command line which will be passed to the script.
374
375 If you are running in a dynamic IP address environment where the
376 IP addresses of either peer could change without notice, you can
377 use this script, for example, to edit the /etc/hosts file with
378 the current address of the peer. The script will be run every
379 time the remote peer changes its IP address.
380
381 Similarly if our IP address changes due to DHCP, we should con‐
382 figure our IP address change script (see man page for dhcpcd(8)
383 ) to deliver a SIGHUP or SIGUSR1 signal to OpenVPN. OpenVPN
384 will then reestablish a connection with its most recently
385 authenticated peer on its new IP address.
386
387 --port port
388 TCP/UDP port number for both local and remote. The current
389 default of 1194 represents the official IANA port number assign‐
390 ment for OpenVPN and has been used since version 2.0-beta17.
391 Previous versions used port 5000 as the default.
392
393 --lport port
394 TCP/UDP port number for bind.
395
396 --rport port
397 TCP/UDP port number for remote.
398
399 --bind Bind to local address and port. This is the default unless any
400 of --proto tcp-client , --http-proxy or --socks-proxy are used.
401
402 --nobind
403 Do not bind to local address and port. The IP stack will allo‐
404 cate a dynamic port for returning packets. Since the value of
405 the dynamic port could not be known in advance by a peer, this
406 option is only suitable for peers which will be initiating con‐
407 nections by using the --remote option.
408
409 --dev tunX | tapX | null
410 TUN/TAP virtual network device ( X can be omitted for a dynamic
411 device.)
412
413 See examples section below for an example on setting up a TUN
414 device.
415
416 You must use either tun devices on both ends of the connection
417 or tap devices on both ends. You cannot mix them, as they rep‐
418 resent different underlying network layers.
419
420 tun devices encapsulate IPv4 or IPv6 (OSI Layer 3) while tap
421 devices encapsulate Ethernet 802.3 (OSI Layer 2).
422
423 --dev-type device-type
424 Which device type are we using? device-type should be tun (OSI
425 Layer 3) or tap (OSI Layer 2). Use this option only if the
426 TUN/TAP device used with --dev does not begin with tun or tap.
427
428 --topology mode
429 Configure virtual addressing topology when running in --dev tun
430 mode. This directive has no meaning in --dev tap mode, which
431 always uses a subnet topology.
432
433 If you set this directive on the server, the --server and
434 --server-bridge directives will automatically push your chosen
435 topology setting to clients as well. This directive can also be
436 manually pushed to clients. Like the --dev directive, this
437 directive must always be compatible between client and server.
438
439 mode can be one of:
440
441 net30 -- Use a point-to-point topology, by allocating one /30
442 subnet per client. This is designed to allow point-to-point
443 semantics when some or all of the connecting clients might be
444 Windows systems. This is the default on OpenVPN 2.0.
445
446 p2p -- Use a point-to-point topology where the remote endpoint
447 of the client's tun interface always points to the local end‐
448 point of the server's tun interface. This mode allocates a sin‐
449 gle IP address per connecting client. Only use when none of the
450 connecting clients are Windows systems. This mode is function‐
451 ally equivalent to the --ifconfig-pool-linear directive which is
452 available in OpenVPN 2.0 and is now deprecated.
453
454 subnet -- Use a subnet rather than a point-to-point topology by
455 configuring the tun interface with a local IP address and subnet
456 mask, similar to the topology used in --dev tap and ethernet
457 bridging mode. This mode allocates a single IP address per con‐
458 necting client and works on Windows as well. Only available
459 when server and clients are OpenVPN 2.1 or higher, or OpenVPN
460 2.0.x which has been manually patched with the --topology direc‐
461 tive code. When used on Windows, requires version 8.2 or higher
462 of the TAP-Win32 driver. When used on *nix, requires that the
463 tun driver supports an ifconfig(8) command which sets a subnet
464 instead of a remote endpoint IP address.
465
466 This option exists in OpenVPN 2.1 or higher.
467
468 --tun-ipv6
469 Build a tun link capable of forwarding IPv6 traffic. Should be
470 used in conjunction with --dev tun or --dev tunX. A warning
471 will be displayed if no specific IPv6 TUN support for your OS
472 has been compiled into OpenVPN.
473
474 --dev-node node
475 Explicitly set the device node rather than using /dev/net/tun,
476 /dev/tun, /dev/tap, etc. If OpenVPN cannot figure out whether
477 node is a TUN or TAP device based on the name, you should also
478 specify --dev-type tun or --dev-type tap.
479
480 On Windows systems, select the TAP-Win32 adapter which is named
481 node in the Network Connections Control Panel or the raw GUID of
482 the adapter enclosed by braces. The --show-adapters option
483 under Windows can also be used to enumerate all available TAP-
484 Win32 adapters and will show both the network connections con‐
485 trol panel name and the GUID for each TAP-Win32 adapter.
486
487 --lladdr address
488 Specify the link layer address, more commonly known as the MAC
489 address. Only applied to TAP devices.
490
491 --iproute cmd
492 Set alternate command to execute instead of default iproute2
493 command. May be used in order to execute OpenVPN in unprivi‐
494 leged environment.
495
496 --ifconfig l rn
497 Set TUN/TAP adapter parameters. l is the IP address of the
498 local VPN endpoint. For TUN devices, rn is the IP address of
499 the remote VPN endpoint. For TAP devices, rn is the subnet mask
500 of the virtual ethernet segment which is being created or con‐
501 nected to.
502
503 For TUN devices, which facilitate virtual point-to-point IP con‐
504 nections, the proper usage of --ifconfig is to use two private
505 IP addresses which are not a member of any existing subnet which
506 is in use. The IP addresses may be consecutive and should have
507 their order reversed on the remote peer. After the VPN is
508 established, by pinging rn, you will be pinging across the VPN.
509
510 For TAP devices, which provide the ability to create virtual
511 ethernet segments, --ifconfig is used to set an IP address and
512 subnet mask just as a physical ethernet adapter would be simi‐
513 larly configured. If you are attempting to connect to a remote
514 ethernet bridge, the IP address and subnet should be set to val‐
515 ues which would be valid on the the bridged ethernet segment
516 (note also that DHCP can be used for the same purpose).
517
518 This option, while primarily a proxy for the ifconfig(8) com‐
519 mand, is designed to simplify TUN/TAP tunnel configuration by
520 providing a standard interface to the different ifconfig imple‐
521 mentations on different platforms.
522
523 --ifconfig parameters which are IP addresses can also be speci‐
524 fied as a DNS or /etc/hosts file resolvable name.
525
526 For TAP devices, --ifconfig should not be used if the TAP inter‐
527 face will be getting an IP address lease from a DHCP server.
528
529 --ifconfig-noexec
530 Don't actually execute ifconfig/netsh commands, instead pass
531 --ifconfig parameters to scripts using environmental variables.
532
533 --ifconfig-nowarn
534 Don't output an options consistency check warning if the
535 --ifconfig option on this side of the connection doesn't match
536 the remote side. This is useful when you want to retain the
537 overall benefits of the options consistency check (also see
538 --disable-occ option) while only disabling the ifconfig compo‐
539 nent of the check.
540
541 For example, if you have a configuration where the local host
542 uses --ifconfig but the remote host does not, use --ifconfig-
543 nowarn on the local host.
544
545 This option will also silence warnings about potential address
546 conflicts which occasionally annoy more experienced users by
547 triggering "false positive" warnings.
548
549 --route network/IP [netmask] [gateway] [metric]
550 Add route to routing table after connection is established.
551 Multiple routes can be specified. Routes will be automatically
552 torn down in reverse order prior to TUN/TAP device close.
553
554 This option is intended as a convenience proxy for the route(8)
555 shell command, while at the same time providing portable seman‐
556 tics across OpenVPN's platform space.
557
558 netmask default -- 255.255.255.255
559
560 gateway default -- taken from --route-gateway or the second
561 parameter to --ifconfig when --dev tun is specified.
562
563 metric default -- taken from --route-metric otherwise 0.
564
565 The default can be specified by leaving an option blank or set‐
566 ting it to "default".
567
568 The network and gateway parameters can also be specified as a
569 DNS or /etc/hosts file resolvable name, or as one of three spe‐
570 cial keywords:
571
572 vpn_gateway -- The remote VPN endpoint address (derived either
573 from --route-gateway or the second parameter to --ifconfig when
574 --dev tun is specified).
575
576 net_gateway -- The pre-existing IP default gateway, read from
577 the routing table (not supported on all OSes).
578
579 remote_host -- The --remote address if OpenVPN is being run in
580 client mode, and is undefined in server mode.
581
582 --max-routes n
583 Allow a maximum number of n --route options to be specified,
584 either in the local configuration file, or pulled from an Open‐
585 VPN server. By default, n=100.
586
587 --route-gateway gw|'dhcp'
588 Specify a default gateway gw for use with --route.
589
590 If dhcp is specified as the parameter, the gateway address will
591 be extracted from a DHCP negotiation with the OpenVPN server-
592 side LAN.
593
594 --route-metric m
595 Specify a default metric m for use with --route.
596
597 --route-delay [n] [w]
598 Delay n seconds (default=0) after connection establishment,
599 before adding routes. If n is 0, routes will be added immedi‐
600 ately upon connection establishment. If --route-delay is omit‐
601 ted, routes will be added immediately after TUN/TAP device open
602 and --up script execution, before any --user or --group privi‐
603 lege downgrade (or --chroot execution.)
604
605 This option is designed to be useful in scenarios where DHCP is
606 used to set tap adapter addresses. The delay will give the DHCP
607 handshake time to complete before routes are added.
608
609 On Windows, --route-delay tries to be more intelligent by wait‐
610 ing w seconds (w=30 by default) for the TAP-Win32 adapter to
611 come up before adding routes.
612
613 --route-up cmd
614 Execute shell command cmd after routes are added, subject to
615 --route-delay.
616
617 See the "Environmental Variables" section below for additional
618 parameters passed as environmental variables.
619
620 Note that cmd can be a shell command with multiple arguments.
621
622 --route-noexec
623 Don't add or remove routes automatically. Instead pass routes
624 to --route-up script using environmental variables.
625
626 --route-nopull
627 When used with --client or --pull, accept options pushed by
628 server EXCEPT for routes.
629
630 When used on the client, this option effectively bars the server
631 from adding routes to the client's routing table, however note
632 that this option still allows the server to set the TCP/IP prop‐
633 erties of the client's TUN/TAP interface.
634
635 --allow-pull-fqdn
636 Allow client to pull DNS names from server (rather than being
637 limited to IP address) for --ifconfig, --route, and --route-
638 gateway.
639
640 --redirect-gateway flags...
641 (Experimental) Automatically execute routing commands to cause
642 all outgoing IP traffic to be redirected over the VPN.
643
644 This option performs three steps:
645
646 [1m(1) Create a static route for the --remote address which for‐
647 wards to the pre-existing default gateway. This is done so that
648 [1m(3) will not create a routing loop.
649
650 [1m(2) Delete the default gateway route.
651
652 [1m(3) Set the new default gateway to be the VPN endpoint address
653 (derived either from --route-gateway or the second parameter to
654 --ifconfig when --dev tun is specified).
655
656 When the tunnel is torn down, all of the above steps are
657 reversed so that the original default route is restored.
658
659 Option flags:
660
661 local -- Add the local flag if both OpenVPN servers are directly
662 connected via a common subnet, such as with wireless. The local
663 flag will cause step 1 above to be omitted.
664
665 def1 -- Use this flag to override the default gateway by using
666 0.0.0.0/1 and 128.0.0.0/1 rather than 0.0.0.0/0. This has the
667 benefit of overriding but not wiping out the original default
668 gateway.
669
670 bypass-dhcp -- Add a direct route to the DHCP server (if it is
671 non-local) which bypasses the tunnel (Available on Windows
672 clients, may not be available on non-Windows clients).
673
674 bypass-dns -- Add a direct route to the DNS server(s) (if they
675 are non-local) which bypasses the tunnel (Available on Windows
676 clients, may not be available on non-Windows clients).
677
678 Using the def1 flag is highly recommended.
679
680 --link-mtu n
681 Sets an upper bound on the size of UDP packets which are sent
682 between OpenVPN peers. It's best not to set this parameter
683 unless you know what you're doing.
684
685 --tun-mtu n
686 Take the TUN device MTU to be n and derive the link MTU from it
687 (default=1500). In most cases, you will probably want to leave
688 this parameter set to its default value.
689
690 The MTU (Maximum Transmission Units) is the maximum datagram
691 size in bytes that can be sent unfragmented over a particular
692 network path. OpenVPN requires that packets on the control or
693 data channels be sent unfragmented.
694
695 MTU problems often manifest themselves as connections which hang
696 during periods of active usage.
697
698 It's best to use the --fragment and/or --mssfix options to deal
699 with MTU sizing issues.
700
701 --tun-mtu-extra n
702 Assume that the TUN/TAP device might return as many as n bytes
703 more than the --tun-mtu size on read. This parameter defaults
704 to 0, which is sufficient for most TUN devices. TAP devices may
705 introduce additional overhead in excess of the MTU size, and a
706 setting of 32 is the default when TAP devices are used. This
707 parameter only controls internal OpenVPN buffer sizing, so there
708 is no transmission overhead associated with using a larger
709 value.
710
711 --mtu-disc type
712 Should we do Path MTU discovery on TCP/UDP channel? Only sup‐
713 ported on OSes such as Linux that supports the necessary system
714 call to set.
715
716 'no' -- Never send DF (Don't Fragment) frames
717 'maybe' -- Use per-route hints
718 'yes' -- Always DF (Don't Fragment)
719
720 --mtu-test
721 To empirically measure MTU on connection startup, add the --mtu-
722 test option to your configuration. OpenVPN will send ping pack‐
723 ets of various sizes to the remote peer and measure the largest
724 packets which were successfully received. The --mtu-test
725 process normally takes about 3 minutes to complete.
726
727 --fragment max
728 Enable internal datagram fragmentation so that no UDP datagrams
729 are sent which are larger than max bytes.
730
731 The max parameter is interpreted in the same way as the --link-
732 mtu parameter, i.e. the UDP packet size after encapsulation
733 overhead has been added in, but not including the UDP header
734 itself.
735
736 The --fragment option only makes sense when you are using the
737 UDP protocol ( --proto udp ).
738
739 --fragment adds 4 bytes of overhead per datagram.
740
741 See the --mssfix option below for an important related option to
742 --fragment.
743
744 It should also be noted that this option is not meant to replace
745 UDP fragmentation at the IP stack level. It is only meant as a
746 last resort when path MTU discovery is broken. Using this
747 option is less efficient than fixing path MTU discovery for your
748 IP link and using native IP fragmentation instead.
749
750 Having said that, there are circumstances where using OpenVPN's
751 internal fragmentation capability may be your only option, such
752 as tunneling a UDP multicast stream which requires fragmenta‐
753 tion.
754
755 --mssfix max
756 Announce to TCP sessions running over the tunnel that they
757 should limit their send packet sizes such that after OpenVPN has
758 encapsulated them, the resulting UDP packet size that OpenVPN
759 sends to its peer will not exceed max bytes.
760
761 The max parameter is interpreted in the same way as the --link-
762 mtu parameter, i.e. the UDP packet size after encapsulation
763 overhead has been added in, but not including the UDP header
764 itself.
765
766 The --mssfix option only makes sense when you are using the UDP
767 protocol for OpenVPN peer-to-peer communication, i.e. --proto
768 udp.
769
770 --mssfix and --fragment can be ideally used together, where
771 --mssfix will try to keep TCP from needing packet fragmentation
772 in the first place, and if big packets come through anyhow (from
773 protocols other than TCP), --fragment will internally fragment
774 them.
775
776 Both --fragment and --mssfix are designed to work around cases
777 where Path MTU discovery is broken on the network path between
778 OpenVPN peers.
779
780 The usual symptom of such a breakdown is an OpenVPN connection
781 which successfully starts, but then stalls during active usage.
782
783 If --fragment and --mssfix are used together, --mssfix will take
784 its default max parameter from the --fragment max option.
785
786 Therefore, one could lower the maximum UDP packet size to 1300
787 (a good first try for solving MTU-related connection problems)
788 with the following options:
789
790 --tun-mtu 1500 --fragment 1300 --mssfix
791
792 --sndbuf size
793 Set the TCP/UDP socket send buffer size. Currently defaults to
794 65536 bytes.
795
796 --rcvbuf size
797 Set the TCP/UDP socket receive buffer size. Currently defaults
798 to 65536 bytes.
799
800 --socket-flags flags...
801 Apply the given flags to the OpenVPN transport socket. Cur‐
802 rently, only TCP_NODELAY is supported.
803
804 The TCP_NODELAY socket flag is useful in TCP mode, and causes
805 the kernel to send tunnel packets immediately over the TCP con‐
806 nection without trying to group several smaller packets into a
807 larger packet. This can result in a considerably improvement in
808 latency.
809
810 This option is pushable from server to client, and should be
811 used on both client and server for maximum effect.
812
813 --txqueuelen n
814 (Linux only) Set the TX queue length on the TUN/TAP interface.
815 Currently defaults to 100.
816
817 --shaper n
818 Limit bandwidth of outgoing tunnel data to n bytes per second on
819 the TCP/UDP port. If you want to limit the bandwidth in both
820 directions, use this option on both peers.
821
822 OpenVPN uses the following algorithm to implement traffic shap‐
823 ing: Given a shaper rate of n bytes per second, after a datagram
824 write of b bytes is queued on the TCP/UDP port, wait a minimum
825 of (b / n) seconds before queuing the next write.
826
827 It should be noted that OpenVPN supports multiple tunnels
828 between the same two peers, allowing you to construct full-speed
829 and reduced bandwidth tunnels at the same time, routing low-pri‐
830 ority data such as off-site backups over the reduced bandwidth
831 tunnel, and other data over the full-speed tunnel.
832
833 Also note that for low bandwidth tunnels (under 1000 bytes per
834 second), you should probably use lower MTU values as well (see
835 above), otherwise the packet latency will grow so large as to
836 trigger timeouts in the TLS layer and TCP connections running
837 over the tunnel.
838
839 OpenVPN allows n to be between 100 bytes/sec and 100 Mbytes/sec.
840
841 --inactive n [bytes]
842 Causes OpenVPN to exit after n seconds of inactivity on the
843 TUN/TAP device. The time length of inactivity is measured since
844 the last incoming tunnel packet.
845
846 If the optional bytes parameter is included, exit after n sec‐
847 onds of activity on tun/tap device produces a combined in/out
848 byte count that is less than bytes.
849
850 --ping n
851 Ping remote over the TCP/UDP control channel if no packets have
852 been sent for at least n seconds (specify --ping on both peers
853 to cause ping packets to be sent in both directions since Open‐
854 VPN ping packets are not echoed like IP ping packets). When
855 used in one of OpenVPN's secure modes (where --secret, --tls-
856 server, or --tls-client is specified), the ping packet will be
857 cryptographically secure.
858
859 This option has two intended uses:
860
861 (1) Compatibility with stateful firewalls. The periodic ping
862 will ensure that a stateful firewall rule which allows OpenVPN
863 UDP packets to pass will not time out.
864
865 (2) To provide a basis for the remote to test the existence of
866 its peer using the --ping-exit option.
867
868 --ping-exit n
869 Causes OpenVPN to exit after n seconds pass without reception of
870 a ping or other packet from remote. This option can be combined
871 with --inactive, --ping, and --ping-exit to create a two-tiered
872 inactivity disconnect.
873
874 For example,
875
876 openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60
877
878 when used on both peers will cause OpenVPN to exit within 60
879 seconds if its peer disconnects, but will exit after one hour if
880 no actual tunnel data is exchanged.
881
882 --ping-restart n
883 Similar to --ping-exit, but trigger a SIGUSR1 restart after n
884 seconds pass without reception of a ping or other packet from
885 remote.
886
887 This option is useful in cases where the remote peer has a
888 dynamic IP address and a low-TTL DNS name is used to track the
889 IP address using a service such as http://dyndns.org/ + a
890 dynamic DNS client such as ddclient.
891
892 If the peer cannot be reached, a restart will be triggered,
893 causing the hostname used with --remote to be re-resolved (if
894 --resolv-retry is also specified).
895
896 In server mode, --ping-restart, --inactive, or any other type of
897 internally generated signal will always be applied to individual
898 client instance objects, never to whole server itself. Note
899 also in server mode that any internally generated signal which
900 would normally cause a restart, will cause the deletion of the
901 client instance object instead.
902
903 In client mode, the --ping-restart parameter is set to 120 sec‐
904 onds by default. This default will hold until the client pulls
905 a replacement value from the server, based on the --keepalive
906 setting in the server configuration. To disable the 120 second
907 default, set --ping-restart 0 on the client.
908
909 See the signals section below for more information on SIGUSR1.
910
911 Note that the behavior of SIGUSR1 can be modified by the --per‐
912 sist-tun, --persist-key, --persist-local-ip, and --persist-
913 remote-ip options.
914
915 Also note that --ping-exit and --ping-restart are mutually
916 exclusive and cannot be used together.
917
918 --keepalive n m
919 A helper directive designed to simplify the expression of --ping
920 and --ping-restart in server mode configurations.
921
922 For example, --keepalive 10 60 expands as follows:
923
924 if mode server:
925 ping 10
926 ping-restart 120
927 push "ping 10"
928 push "ping-restart 60"
929 else
930 ping 10
931 ping-restart 60
932
933 --ping-timer-rem
934 Run the --ping-exit / --ping-restart timer only if we have a
935 remote address. Use this option if you are starting the daemon
936 in listen mode (i.e. without an explicit --remote peer), and you
937 don't want to start clocking timeouts until a remote peer con‐
938 nects.
939
940 --persist-tun
941 Don't close and reopen TUN/TAP device or run up/down scripts
942 across SIGUSR1 or --ping-restart restarts.
943
944 SIGUSR1 is a restart signal similar to SIGHUP, but which offers
945 finer-grained control over reset options.
946
947 --persist-key
948 Don't re-read key files across SIGUSR1 or --ping-restart.
949
950 This option can be combined with --user nobody to allow restarts
951 triggered by the SIGUSR1 signal. Normally if you drop root
952 privileges in OpenVPN, the daemon cannot be restarted since it
953 will now be unable to re-read protected key files.
954
955 This option solves the problem by persisting keys across SIGUSR1
956 resets, so they don't need to be re-read.
957
958 --persist-local-ip
959 Preserve initially resolved local IP address and port number
960 across SIGUSR1 or --ping-restart restarts.
961
962 --persist-remote-ip
963 Preserve most recently authenticated remote IP address and port
964 number across SIGUSR1 or --ping-restart restarts.
965
966 --mlock
967 Disable paging by calling the POSIX mlockall function. Requires
968 that OpenVPN be initially run as root (though OpenVPN can subse‐
969 quently downgrade its UID using the --user option).
970
971 Using this option ensures that key material and tunnel data are
972 never written to disk due to virtual memory paging operations
973 which occur under most modern operating systems. It ensures
974 that even if an attacker was able to crack the box running Open‐
975 VPN, he would not be able to scan the system swap file to
976 recover previously used ephemeral keys, which are used for a
977 period of time governed by the --reneg options (see below), then
978 are discarded.
979
980 The downside of using --mlock is that it will reduce the amount
981 of physical memory available to other applications.
982
983 --up cmd
984 Shell command to run after successful TUN/TAP device open (pre
985 --user UID change). The up script is useful for specifying
986 route commands which route IP traffic destined for private sub‐
987 nets which exist at the other end of the VPN connection into the
988 tunnel.
989
990 For --dev tun execute as:
991
992 cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifcon‐
993 fig_remote_ip [ init | restart ]
994
995 For --dev tap execute as:
996
997 cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask
998 [ init | restart ]
999
1000 See the "Environmental Variables" section below for additional
1001 parameters passed as environmental variables.
1002
1003 Note that cmd can be a shell command with multiple arguments, in
1004 which case all OpenVPN-generated arguments will be appended to
1005 cmd to build a command line which will be passed to the shell.
1006
1007 Typically, cmd will run a script to add routes to the tunnel.
1008
1009 Normally the up script is called after the TUN/TAP device is
1010 opened. In this context, the last command line parameter passed
1011 to the script will be init. If the --up-restart option is also
1012 used, the up script will be called for restarts as well. A
1013 restart is considered to be a partial reinitialization of Open‐
1014 VPN where the TUN/TAP instance is preserved (the --persist-tun
1015 option will enable such preservation). A restart can be gener‐
1016 ated by a SIGUSR1 signal, a --ping-restart timeout, or a connec‐
1017 tion reset when the TCP protocol is enabled with the --proto
1018 option. If a restart occurs, and --up-restart has been speci‐
1019 fied, the up script will be called with restart as the last
1020 parameter.
1021
1022 The following standalone example shows how the --up script can
1023 be called in both an initialization and restart context. (NOTE:
1024 for security reasons, don't run the following example unless UDP
1025 port 9999 is blocked by your firewall. Also, the example will
1026 run indefinitely, so you should abort with control-c).
1027
1028 openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 --up
1029 'echo up' --down 'echo down' --persist-tun --up-restart
1030
1031 Note that OpenVPN also provides the --ifconfig option to auto‐
1032 matically ifconfig the TUN device, eliminating the need to
1033 define an --up script, unless you also want to configure routes
1034 in the --up script.
1035
1036 If --ifconfig is also specified, OpenVPN will pass the ifconfig
1037 local and remote endpoints on the command line to the --up
1038 script so that they can be used to configure routes such as:
1039
1040 route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
1041
1042 --up-delay
1043 Delay TUN/TAP open and possible --up script execution until
1044 after TCP/UDP connection establishment with peer.
1045
1046 In --proto udp mode, this option normally requires the use of
1047 --ping to allow connection initiation to be sensed in the
1048 absence of tunnel data, since UDP is a "connectionless" proto‐
1049 col.
1050
1051 On Windows, this option will delay the TAP-Win32 media state
1052 transitioning to "connected" until connection establishment,
1053 i.e. the receipt of the first authenticated packet from the
1054 peer.
1055
1056 --down cmd
1057 Shell command to run after TUN/TAP device close (post --user UID
1058 change and/or --chroot ). Called with the same parameters and
1059 environmental variables as the --up option above.
1060
1061 Note that if you reduce privileges by using --user and/or
1062 --group, your --down script will also run at reduced privilege.
1063
1064 --down-pre
1065 Call --down cmd/script before, rather than after, TUN/TAP close.
1066
1067 --up-restart
1068 Enable the --up and --down scripts to be called for restarts as
1069 well as initial program start. This option is described more
1070 fully above in the --up option documentation.
1071
1072 --setenv name value
1073 Set a custom environmental variable name=value to pass to
1074 script.
1075
1076 --setenv FORWARD_COMPATIBLE 1
1077 Relax config file syntax checking so that unknown directives
1078 will trigger a warning but not a fatal error, on the assumption
1079 that a given unknown directive might be valid in future OpenVPN
1080 versions.
1081
1082 This option should be used with caution, as there are good secu‐
1083 rity reasons for having OpenVPN fail if it detects problems in a
1084 config file. Having said that, there are valid reasons for
1085 wanting new software features to gracefully degrade when encoun‐
1086 tered by older software versions.
1087
1088 --setenv-safe name value
1089 Set a custom environmental variable OPENVPN_name=value to pass
1090 to script.
1091
1092 This directive is designed to be pushed by the server to
1093 clients, and the prepending of "OPENVPN_" to the environmental
1094 variable is a safety precaution to prevent a LD_PRELOAD style
1095 attack from a malicious or compromised server.
1096
1097 --script-security level [method]
1098 This directive offers policy-level control over OpenVPN's usage
1099 of external programs and scripts. Lower level values are more
1100 restrictive, higher values are more permissive. Settings for
1101 level:
1102
1103 0 -- Strictly no calling of external programs.
1104 1 -- (Default) Only call built-in executables such as ifconfig,
1105 ip, route, or netsh.
1106 2 -- Allow calling of built-in executables and user-defined
1107 scripts.
1108 3 -- Allow passwords to be passed to scripts via environmental
1109 variables (potentially unsafe).
1110
1111 The method parameter indicates how OpenVPN should call external
1112 commands and scripts. Settings for method:
1113
1114 execve -- (default) Use execve() function on Unix family OSes
1115 and CreateProcess() on Windows.
1116 system -- Use system() function (deprecated and less safe since
1117 the external program command line is subject to shell expan‐
1118 sion).
1119
1120 The --script-security option was introduced in OpenVPN 2.1_rc9.
1121 For configuration file compatibility with previous OpenVPN ver‐
1122 sions, use: --script-security 3 system
1123
1124 --disable-occ
1125 Don't output a warning message if option inconsistencies are
1126 detected between peers. An example of an option inconsistency
1127 would be where one peer uses --dev tun while the other peer uses
1128 --dev tap.
1129
1130 Use of this option is discouraged, but is provided as a tempo‐
1131 rary fix in situations where a recent version of OpenVPN must
1132 connect to an old version.
1133
1134 --user user
1135 Change the user ID of the OpenVPN process to user after initial‐
1136 ization, dropping privileges in the process. This option is
1137 useful to protect the system in the event that some hostile
1138 party was able to gain control of an OpenVPN session. Though
1139 OpenVPN's security features make this unlikely, it is provided
1140 as a second line of defense.
1141
1142 By setting user to nobody or somebody similarly unprivileged,
1143 the hostile party would be limited in what damage they could
1144 cause. Of course once you take away privileges, you cannot
1145 return them to an OpenVPN session. This means, for example,
1146 that if you want to reset an OpenVPN daemon with a SIGUSR1 sig‐
1147 nal (for example in response to a DHCP reset), you should make
1148 use of one or more of the --persist options to ensure that Open‐
1149 VPN doesn't need to execute any privileged operations in order
1150 to restart (such as re-reading key files or running ifconfig on
1151 the TUN device).
1152
1153 --group group
1154 Similar to the --user option, this option changes the group ID
1155 of the OpenVPN process to group after initialization.
1156
1157 --cd dir
1158 Change directory to dir prior to reading any files such as con‐
1159 figuration files, key files, scripts, etc. dir should be an
1160 absolute path, with a leading "/", and without any references to
1161 the current directory such as "." or "..".
1162
1163 This option is useful when you are running OpenVPN in --daemon
1164 mode, and you want to consolidate all of your OpenVPN control
1165 files in one location.
1166
1167 --chroot dir
1168 Chroot to dir after initialization. --chroot essentially rede‐
1169 fines dir as being the top level directory tree (/). OpenVPN
1170 will therefore be unable to access any files outside this tree.
1171 This can be desirable from a security standpoint.
1172
1173 Since the chroot operation is delayed until after initializa‐
1174 tion, most OpenVPN options that reference files will operate in
1175 a pre-chroot context.
1176
1177 In many cases, the dir parameter can point to an empty direc‐
1178 tory, however complications can result when scripts or restarts
1179 are executed after the chroot operation.
1180
1181 --setcon context
1182 Apply SELinux context after initialization. This essentially
1183 provides the ability to restrict OpenVPN's rights to only net‐
1184 work I/O operations, thanks to SELinux. This goes further than
1185 --user and --chroot in that those two, while being great secu‐
1186 rity features, unfortunately do not protect against privilege
1187 escalation by exploitation of a vulnerable system call. You can
1188 of course combine all three, but please note that since setcon
1189 requires access to /proc you will have to provide it inside the
1190 chroot directory (e.g. with mount --bind).
1191
1192 Since the setcon operation is delayed until after initializa‐
1193 tion, OpenVPN can be restricted to just network-related system
1194 calls, whereas by applying the context before startup (such as
1195 the OpenVPN one provided in the SELinux Reference Policies) you
1196 will have to allow many things required only during initializa‐
1197 tion.
1198
1199 Like with chroot, complications can result when scripts or
1200 restarts are executed after the setcon operation, which is why
1201 you should really consider using the --persist-key and --per‐
1202 sist-tun options.
1203
1204 --daemon [progname]
1205 Become a daemon after all initialization functions are com‐
1206 pleted. This option will cause all message and error output to
1207 be sent to the syslog file (such as /var/log/messages), except
1208 for the output of shell scripts and ifconfig commands, which
1209 will go to /dev/null unless otherwise redirected. The syslog
1210 redirection occurs immediately at the point that --daemon is
1211 parsed on the command line even though the daemonization point
1212 occurs later. If one of the --log options is present, it will
1213 supercede syslog redirection.
1214
1215 The optional progname parameter will cause OpenVPN to report its
1216 program name to the system logger as progname. This can be use‐
1217 ful in linking OpenVPN messages in the syslog file with specific
1218 tunnels. When unspecified, progname defaults to "openvpn".
1219
1220 When OpenVPN is run with the --daemon option, it will try to
1221 delay daemonization until the majority of initialization func‐
1222 tions which are capable of generating fatal errors are complete.
1223 This means that initialization scripts can test the return sta‐
1224 tus of the openvpn command for a fairly reliable indication of
1225 whether the command has correctly initialized and entered the
1226 packet forwarding event loop.
1227
1228 In OpenVPN, the vast majority of errors which occur after ini‐
1229 tialization are non-fatal.
1230
1231 --syslog [progname]
1232 Direct log output to system logger, but do not become a daemon.
1233 See --daemon directive above for description of progname parame‐
1234 ter.
1235
1236 --passtos
1237 Set the TOS field of the tunnel packet to what the payload's TOS
1238 is.
1239
1240 --inetd [wait|nowait] [progname]
1241 Use this option when OpenVPN is being run from the inetd or
1242 xinetd(8) server.
1243
1244 The wait/nowait option must match what is specified in the
1245 inetd/xinetd config file. The nowait mode can only be used with
1246 --proto tcp-server. The default is wait. The nowait mode can
1247 be used to instantiate the OpenVPN daemon as a classic TCP
1248 server, where client connection requests are serviced on a sin‐
1249 gle port number. For additional information on this kind of
1250 configuration, see the OpenVPN FAQ: http://open‐
1251 vpn.net/faq.html#oneport
1252
1253 This option precludes the use of --daemon, --local, or --remote.
1254 Note that this option causes message and error output to be han‐
1255 dled in the same way as the --daemon option. The optional prog‐
1256 name parameter is also handled exactly as in --daemon.
1257
1258 Also note that in wait mode, each OpenVPN tunnel requires a sep‐
1259 arate TCP/UDP port and a separate inetd or xinetd entry. See
1260 the OpenVPN 1.x HOWTO for an example on using OpenVPN with
1261 xinetd: http://openvpn.net/1xhowto.html
1262
1263 --log file
1264 Output logging messages to file, including output to std‐
1265 out/stderr which is generated by called scripts. If file
1266 already exists it will be truncated. This option takes effect
1267 immediately when it is parsed in the command line and will
1268 supercede syslog output if --daemon or --inetd is also speci‐
1269 fied. This option is persistent over the entire course of an
1270 OpenVPN instantiation and will not be reset by SIGHUP, SIGUSR1,
1271 or --ping-restart.
1272
1273 Note that on Windows, when OpenVPN is started as a service, log‐
1274 ging occurs by default without the need to specify this option.
1275
1276 --log-append file
1277 Append logging messages to file. If file does not exist, it
1278 will be created. This option behaves exactly like --log except
1279 that it appends to rather than truncating the log file.
1280
1281 --suppress-timestamps
1282 Avoid writing timestamps to log messages, even when they other‐
1283 wise would be prepended. In particular, this applies to log mes‐
1284 sages sent to stdout.
1285
1286 --writepid file
1287 Write OpenVPN's main process ID to file.
1288
1289 --nice n
1290 Change process priority after initialization ( n greater than 0
1291 is lower priority, n less than zero is higher priority).
1292
1293 --fast-io
1294 (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a
1295 call to poll/epoll/select prior to the write operation. The
1296 purpose of such a call would normally be to block until the
1297 device or socket is ready to accept the write. Such blocking is
1298 unnecessary on some platforms which don't support write blocking
1299 on UDP sockets or TUN/TAP devices. In such cases, one can opti‐
1300 mize the event loop by avoiding the poll/epoll/select call,
1301 improving CPU efficiency by 5% to 10%.
1302
1303 This option can only be used on non-Windows systems, when
1304 --proto udp is specified, and when --shaper is NOT specified.
1305
1306 --multihome
1307 Configure a multi-homed UDP server. This option can be used
1308 when OpenVPN has been configured to listen on all interfaces,
1309 and will attempt to bind client sessions to the interface on
1310 which packets are being received, so that outgoing packets will
1311 be sent out of the same interface. Note that this option is
1312 only relevant for UDP servers and currently is only implemented
1313 on Linux.
1314
1315 Note: clients connecting to a --multihome server should always
1316 use the --nobind option.
1317
1318 --echo [parms...]
1319 Echo parms to log output.
1320
1321 Designed to be used to send messages to a controlling applica‐
1322 tion which is receiving the OpenVPN log output.
1323
1324 --remap-usr1 signal
1325 Control whether internally or externally generated SIGUSR1 sig‐
1326 nals are remapped to SIGHUP (restart without persisting state)
1327 or SIGTERM (exit).
1328
1329 signal can be set to "SIGHUP" or "SIGTERM". By default, no
1330 remapping occurs.
1331
1332 --verb n
1333 Set output verbosity to n (default=1). Each level shows all
1334 info from the previous levels. Level 3 is recommended if you
1335 want a good summary of what's happening without being swamped by
1336 output.
1337
1338 0 -- No output except fatal errors.
1339 1 to 4 -- Normal usage range.
1340 5 -- Output R and W characters to the console for each packet
1341 read and write, uppercase is used for TCP/UDP packets and lower‐
1342 case is used for TUN/TAP packets.
1343 6 to 11 -- Debug info range (see errlevel.h for additional
1344 information on debug levels).
1345
1346 --status file [n]
1347 Write operational status to file every n seconds.
1348
1349 Status can also be written to the syslog by sending a SIGUSR2
1350 signal.
1351
1352 --status-version [n]
1353 Choose the status file format version number. Currently n can
1354 be 1, 2, or 3 and defaults to 1.
1355
1356 --mute n
1357 Log at most n consecutive messages in the same category. This
1358 is useful to limit repetitive logging of similar message types.
1359
1360 --comp-lzo [mode]
1361 Use fast LZO compression -- may add up to 1 byte per packet for
1362 incompressible data. mode may be "yes", "no", or "adaptive"
1363 (default).
1364
1365 In a server mode setup, it is possible to selectively turn com‐
1366 pression on or off for individual clients.
1367
1368 First, make sure the client-side config file enables selective
1369 compression by having at least one --comp-lzo directive, such as
1370 --comp-lzo no. This will turn off compression by default, but
1371 allow a future directive push from the server to dynamically
1372 change the on/off/adaptive setting.
1373
1374 Next in a --client-config-dir file, specify the compression set‐
1375 ting for the client, for example:
1376
1377 comp-lzo yes
1378 push "comp-lzo yes"
1379
1380 The first line sets the comp-lzo setting for the server side of
1381 the link, the second sets the client side.
1382
1383 --comp-noadapt
1384 When used in conjunction with --comp-lzo, this option will dis‐
1385 able OpenVPN's adaptive compression algorithm. Normally, adap‐
1386 tive compression is enabled with --comp-lzo.
1387
1388 Adaptive compression tries to optimize the case where you have
1389 compression enabled, but you are sending predominantly uncom‐
1390 pressible (or pre-compressed) packets over the tunnel, such as
1391 an FTP or rsync transfer of a large, compressed file. With
1392 adaptive compression, OpenVPN will periodically sample the com‐
1393 pression process to measure its efficiency. If the data being
1394 sent over the tunnel is already compressed, the compression
1395 efficiency will be very low, triggering openvpn to disable com‐
1396 pression for a period of time until the next re-sample test.
1397
1398 --management IP port [pw-file]
1399 Enable a TCP server on IP:port to handle daemon management func‐
1400 tions. pw-file, if specified, is a password file (password on
1401 first line) or "stdin" to prompt from standard input. The pass‐
1402 word provided will set the password which TCP clients will need
1403 to provide in order to access management functions.
1404
1405 The management interface can also listen on a unix domain
1406 socket, for those platforms that support it. To use a unix
1407 domain socket, specify the unix socket pathname in place of IP
1408 and set port to 'unix'. While the default behavior is to create
1409 a unix domain socket that may be connected to by any process,
1410 the --management-client-user and --management-client-group
1411 directives can be used to restrict access.
1412
1413 The management interface provides a special mode where the TCP
1414 management link can operate over the tunnel itself. To enable
1415 this mode, set IP = "tunnel". Tunnel mode will cause the man‐
1416 agement interface to listen for a TCP connection on the local
1417 VPN address of the TUN/TAP interface.
1418
1419 While the management port is designed for programmatic control
1420 of OpenVPN by other applications, it is possible to telnet to
1421 the port, using a telnet client in "raw" mode. Once connected,
1422 type "help" for a list of commands.
1423
1424 For detailed documentation on the management interface, see the
1425 management-notes.txt file in the management folder of the Open‐
1426 VPN source distribution.
1427
1428 It is strongly recommended that IP be set to 127.0.0.1 (local‐
1429 host) to restrict accessibility of the management server to
1430 local clients.
1431
1432 --management-query-passwords
1433 Query management channel for private key password and --auth-
1434 user-pass username/password. Only query the management channel
1435 for inputs which ordinarily would have been queried from the
1436 console.
1437
1438 --management-forget-disconnect
1439 Make OpenVPN forget passwords when management session discon‐
1440 nects.
1441
1442 This directive does not affect the --http-proxy username/pass‐
1443 word. It is always cached.
1444
1445 --management-hold
1446 Start OpenVPN in a hibernating state, until a client of the man‐
1447 agement interface explicitly starts it with the hold release
1448 command.
1449
1450 --management-signal
1451 Send SIGUSR1 signal to OpenVPN if management session discon‐
1452 nects. This is useful when you wish to disconnect an OpenVPN
1453 session on user logoff.
1454
1455 --management-log-cache n
1456 Cache the most recent n lines of log file history for usage by
1457 the management channel.
1458
1459 --management-client-auth
1460 Gives management interface client the responsibility to authen‐
1461 ticate clients after their client certificate has been verified.
1462 See management-notes.txt in OpenVPN distribution for detailed
1463 notes.
1464
1465 --management-client-pf
1466 Management interface clients must specify a packet filter file
1467 for each connecting client. See management-notes.txt in OpenVPN
1468 distribution for detailed notes.
1469
1470 --management-client-user u
1471 When the management interface is listening on a unix domain
1472 socket, only allow connections from user u.
1473
1474 --management-client-group g
1475 When the management interface is listening on a unix domain
1476 socket, only allow connections from group g.
1477
1478 --plugin module-pathname [init-string]
1479 Load plug-in module from the file module-pathname, passing init-
1480 string as an argument to the module initialization function.
1481 Multiple plugin modules may be loaded into one OpenVPN process.
1482
1483 For more information and examples on how to build OpenVPN plug-
1484 in modules, see the README file in the plugin folder of the
1485 OpenVPN source distribution.
1486
1487 If you are using an RPM install of OpenVPN, see /usr/lib64/open‐
1488 vpn/plugin. The documentation is in doc and the actual plugin
1489 modules are in lib.
1490
1491 Multiple plugin modules can be cascaded, and modules can be used
1492 in tandem with scripts. The modules will be called by OpenVPN
1493 in the order that they are declared in the config file. If both
1494 a plugin and script are configured for the same callback, the
1495 script will be called last. If the return code of the mod‐
1496 ule/script controls an authentication function (such as tls-ver‐
1497 ify, auth-user-pass-verify, or client-connect), then every mod‐
1498 ule and script must return success (0) in order for the connec‐
1499 tion to be authenticated.
1500
1501 Server Mode
1502 Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is sup‐
1503 ported, and can be enabled with the --mode server option. In server
1504 mode, OpenVPN will listen on a single port for incoming client connec‐
1505 tions. All client connections will be routed through a single tun or
1506 tap interface. This mode is designed for scalability and should be
1507 able to support hundreds or even thousands of clients on sufficiently
1508 fast hardware. SSL/TLS authentication must be used in this mode.
1509
1510 --server network netmask
1511 A helper directive designed to simplify the configuration of
1512 OpenVPN's server mode. This directive will set up an OpenVPN
1513 server which will allocate addresses to clients out of the given
1514 network/netmask. The server itself will take the ".1" address
1515 of the given network for use as the server-side endpoint of the
1516 local TUN/TAP interface.
1517
1518 For example, --server 10.8.0.0 255.255.255.0 expands as follows:
1519
1520 mode server
1521 tls-server
1522 push "topology [topology]"
1523
1524 if dev tun AND (topology == net30 OR topology == p2p):
1525 ifconfig 10.8.0.1 10.8.0.2
1526 if !nopool:
1527 ifconfig-pool 10.8.0.4 10.8.0.251
1528 route 10.8.0.0 255.255.255.0
1529 if client-to-client:
1530 push "route 10.8.0.0 255.255.255.0"
1531 else if topology == net30:
1532 push "route 10.8.0.1"
1533
1534 if dev tap OR (dev tun AND topology == subnet):
1535 ifconfig 10.8.0.1 255.255.255.0
1536 if !nopool:
1537 ifconfig-pool 10.8.0.2 10.8.0.254 255.255.255.0
1538 push "route-gateway 10.8.0.1"
1539
1540 Don't use --server if you are ethernet bridging. Use --server-
1541 bridge instead.
1542
1543 --server-bridge gateway netmask pool-start-IP pool-end-IP
1544
1545 --server-bridge ['nogw']
1546
1547 A helper directive similar to --server which is designed to sim‐
1548 plify the configuration of OpenVPN's server mode in ethernet
1549 bridging configurations.
1550
1551 If --server-bridge is used without any parameters, it will
1552 enable a DHCP-proxy mode, where connecting OpenVPN clients will
1553 receive an IP address for their TAP adapter from the DHCP server
1554 running on the OpenVPN server-side LAN. Note that only clients
1555 that support the binding of a DHCP client with the TAP adapter
1556 (such as Windows) can support this mode. The optional nogw flag
1557 (advanced) indicates that gateway information should not be
1558 pushed to the client.
1559
1560 To configure ethernet bridging, you must first use your OS's
1561 bridging capability to bridge the TAP interface with the ether‐
1562 net NIC interface. For example, on Linux this is done with the
1563 brctl tool, and with Windows XP it is done in the Network Con‐
1564 nections Panel by selecting the ethernet and TAP adapters and
1565 right-clicking on "Bridge Connections".
1566
1567 Next you you must manually set the IP/netmask on the bridge
1568 interface. The gateway and netmask parameters to --server-
1569 bridge can be set to either the IP/netmask of the bridge inter‐
1570 face, or the IP/netmask of the default gateway/router on the
1571 bridged subnet.
1572
1573 Finally, set aside a IP range in the bridged subnet, denoted by
1574 pool-start-IP and pool-end-IP, for OpenVPN to allocate to con‐
1575 necting clients.
1576
1577 For example, server-bridge 10.8.0.4 255.255.255.0 10.8.0.128
1578 10.8.0.254 expands as follows:
1579
1580 mode server
1581 tls-server
1582
1583 ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0
1584 push "route-gateway 10.8.0.4"
1585
1586 In another example, --server-bridge (without parameters) expands
1587 as follows:
1588
1589 mode server
1590 tls-server
1591
1592 push "route-gateway dhcp"
1593
1594 Or --server-bridge nogw expands as follows:
1595
1596 mode server
1597 tls-server
1598
1599 --push option
1600 Push a config file option back to the client for remote execu‐
1601 tion. Note that option must be enclosed in double quotes ("").
1602 The client must specify --pull in its config file. The set of
1603 options which can be pushed is limited by both feasibility and
1604 security. Some options such as those which would execute
1605 scripts are banned, since they would effectively allow a compro‐
1606 mised server to execute arbitrary code on the client. Other
1607 options such as TLS or MTU parameters cannot be pushed because
1608 the client needs to know them before the connection to the
1609 server can be initiated.
1610
1611 This is a partial list of options which can currently be pushed:
1612 --route, --route-gateway, --route-delay, --redirect-gateway,
1613 --ip-win32, --dhcp-option, --inactive, --ping, --ping-exit,
1614 --ping-restart, --setenv, --persist-key, --persist-tun, --echo,
1615 --comp-lzo, --socket-flags, --sndbuf, --rcvbuf
1616
1617 --push-reset
1618 Don't inherit the global push list for a specific client
1619 instance. Specify this option in a client-specific context such
1620 as with a --client-config-dir configuration file. This option
1621 will ignore --push options at the global config file level.
1622
1623 --disable
1624 Disable a particular client (based on the common name) from con‐
1625 necting. Don't use this option to disable a client due to key
1626 or password compromise. Use a CRL (certificate revocation list)
1627 instead (see the --crl-verify option).
1628
1629 This option must be associated with a specific client instance,
1630 which means that it must be specified either in a client
1631 instance config file using --client-config-dir or dynamically
1632 generated using a --client-connect script.
1633
1634 --ifconfig-pool start-IP end-IP [netmask]
1635 Set aside a pool of subnets to be dynamically allocated to con‐
1636 necting clients, similar to a DHCP server. For tun-style tun‐
1637 nels, each client will be given a /30 subnet (for interoperabil‐
1638 ity with Windows clients). For tap-style tunnels, individual
1639 addresses will be allocated, and the optional netmask parameter
1640 will also be pushed to clients.
1641
1642
1643 --ifconfig-pool-persist file [seconds]
1644 Persist/unpersist ifconfig-pool data to file, at seconds inter‐
1645 vals (default=600), as well as on program startup and shutdown.
1646
1647 The goal of this option is to provide a long-term association
1648 between clients (denoted by their common name) and the virtual
1649 IP address assigned to them from the ifconfig-pool. Maintaining
1650 a long-term association is good for clients because it allows
1651 them to effectively use the --persist-tun option.
1652
1653 file is a comma-delimited ASCII file, formatted as <Common-
1654 Name>,<IP-address>.
1655
1656 If seconds = 0, file will be treated as read-only. This is use‐
1657 ful if you would like to treat file as a configuration file.
1658
1659 Note that the entries in this file are treated by OpenVPN as
1660 suggestions only, based on past associations between a common
1661 name and IP address. They do not guarantee that the given com‐
1662 mon name will always receive the given IP address. If you want
1663 guaranteed assignment, use --ifconfig-push
1664
1665 --ifconfig-pool-linear
1666 Modifies the --ifconfig-pool directive to allocate individual
1667 TUN interface addresses for clients rather than /30 subnets.
1668 NOTE: This option is incompatible with Windows clients.
1669
1670 This option is deprecated, and should be replaced with --topol‐
1671 ogy p2p which is functionally equivalent.
1672
1673 --ifconfig-push local remote-netmask
1674 Push virtual IP endpoints for client tunnel, overriding the
1675 --ifconfig-pool dynamic allocation.
1676
1677 The parameters local and remote-netmask are set according to the
1678 --ifconfig directive which you want to execute on the client
1679 machine to configure the remote end of the tunnel. Note that
1680 the parameters local and remote-netmask are from the perspective
1681 of the client, not the server. They may be DNS names rather
1682 than IP addresses, in which case they will be resolved on the
1683 server at the time of client connection.
1684
1685 This option must be associated with a specific client instance,
1686 which means that it must be specified either in a client
1687 instance config file using --client-config-dir or dynamically
1688 generated using a --client-connect script.
1689
1690 Remember also to include a --route directive in the main OpenVPN
1691 config file which encloses local, so that the kernel will know
1692 to route it to the server's TUN/TAP interface.
1693
1694 OpenVPN's internal client IP address selection algorithm works
1695 as follows:
1696
1697 1 -- Use --client-connect script generated file for static IP
1698 (first choice).
1699 2 -- Use --client-config-dir file for static IP (next choice).
1700 3 -- Use --ifconfig-pool allocation for dynamic IP (last
1701 choice).
1702
1703 --iroute network [netmask]
1704 Generate an internal route to a specific client. The netmask
1705 parameter, if omitted, defaults to 255.255.255.255.
1706
1707 This directive can be used to route a fixed subnet from the
1708 server to a particular client, regardless of where the client is
1709 connecting from. Remember that you must also add the route to
1710 the system routing table as well (such as by using the --route
1711 directive). The reason why two routes are needed is that the
1712 --route directive routes the packet from the kernel to OpenVPN.
1713 Once in OpenVPN, the --iroute directive routes to the specific
1714 client.
1715
1716 This option must be specified either in a client instance config
1717 file using --client-config-dir or dynamically generated using a
1718 --client-connect script.
1719
1720 The --iroute directive also has an important interaction with
1721 --push "route ...". --iroute essentially defines a subnet which
1722 is owned by a particular client (we will call this client A).
1723 If you would like other clients to be able to reach A's subnet,
1724 you can use --push "route ..." together with --client-to-client
1725 to effect this. In order for all clients to see A's subnet,
1726 OpenVPN must push this route to all clients EXCEPT for A, since
1727 the subnet is already owned by A. OpenVPN accomplishes this by
1728 not not pushing a route to a client if it matches one of the
1729 client's iroutes.
1730
1731 --client-to-client
1732 Because the OpenVPN server mode handles multiple clients through
1733 a single tun or tap interface, it is effectively a router. The
1734 --client-to-client flag tells OpenVPN to internally route
1735 client-to-client traffic rather than pushing all client-origi‐
1736 nating traffic to the TUN/TAP interface.
1737
1738 When this option is used, each client will "see" the other
1739 clients which are currently connected. Otherwise, each client
1740 will only see the server. Don't use this option if you want to
1741 firewall tunnel traffic using custom, per-client rules.
1742
1743 --duplicate-cn
1744 Allow multiple clients with the same common name to concurrently
1745 connect. In the absence of this option, OpenVPN will disconnect
1746 a client instance upon connection of a new client having the
1747 same common name.
1748
1749 --client-connect script
1750 Run script on client connection. The script is passed the com‐
1751 mon name and IP address of the just-authenticated client as
1752 environmental variables (see environmental variable section
1753 below). The script is also passed the pathname of a not-yet-
1754 created temporary file as $1 (i.e. the first command line argu‐
1755 ment), to be used by the script to pass dynamically generated
1756 config file directives back to OpenVPN.
1757
1758 If the script wants to generate a dynamic config file to be
1759 applied on the server when the client connects, it should write
1760 it to the file named by $1.
1761
1762 See the --client-config-dir option below for options which can
1763 be legally used in a dynamically generated config file.
1764
1765 Note that the return value of script is significant. If script
1766 returns a non-zero error status, it will cause the client to be
1767 disconnected.
1768
1769 --client-disconnect
1770 Like --client-connect but called on client instance shutdown.
1771 Will not be called unless the --client-connect script and plug‐
1772 ins (if defined) were previously called on this instance with
1773 successful (0) status returns.
1774
1775 The exception to this rule is if the --client-disconnect script
1776 or plugins are cascaded, and at least one client-connect func‐
1777 tion succeeded, then ALL of the client-disconnect functions for
1778 scripts and plugins will be called on client instance object
1779 deletion, even in cases where some of the related client-connect
1780 functions returned an error status.
1781
1782 --client-config-dir dir
1783 Specify a directory dir for custom client config files. After a
1784 connecting client has been authenticated, OpenVPN will look in
1785 this directory for a file having the same name as the client's
1786 X509 common name. If a matching file exists, it will be opened
1787 and parsed for client-specific configuration options. If no
1788 matching file is found, OpenVPN will instead try to open and
1789 parse a default file called "DEFAULT", which may be provided but
1790 is not required.
1791
1792 This file can specify a fixed IP address for a given client
1793 using --ifconfig-push, as well as fixed subnets owned by the
1794 client using --iroute.
1795
1796 One of the useful properties of this option is that it allows
1797 client configuration files to be conveniently created, edited,
1798 or removed while the server is live, without needing to restart
1799 the server.
1800
1801 The following options are legal in a client-specific context:
1802 --push, --push-reset, --iroute, --ifconfig-push, and --config.
1803
1804 --ccd-exclusive
1805 Require, as a condition of authentication, that a connecting
1806 client has a --client-config-dir file.
1807
1808 --tmp-dir dir
1809 Specify a directory dir for temporary files. This directory
1810 will be used by --client-connect scripts to dynamically generate
1811 client-specific configuration files.
1812
1813 --hash-size r v
1814 Set the size of the real address hash table to r and the virtual
1815 address table to v. By default, both tables are sized at 256
1816 buckets.
1817
1818 --bcast-buffers n
1819 Allocate n buffers for broadcast datagrams (default=256).
1820
1821 --tcp-queue-limit n
1822 Maximum number of output packets queued before TCP (default=64).
1823
1824 When OpenVPN is tunneling data from a TUN/TAP device to a remote
1825 client over a TCP connection, it is possible that the TUN/TAP
1826 device might produce data at a faster rate than the TCP connec‐
1827 tion can support. When the number of output packets queued
1828 before sending to the TCP socket reaches this limit for a given
1829 client connection, OpenVPN will start to drop outgoing packets
1830 directed at this client.
1831
1832 --tcp-nodelay
1833 This macro sets the TCP_NODELAY socket flag on the server as
1834 well as pushes it to connecting clients. The TCP_NODELAY flag
1835 disables the Nagle algorithm on TCP sockets causing packets to
1836 be transmitted immediately with low latency, rather than waiting
1837 a short period of time in order to aggregate several packets
1838 into a larger containing packet. In VPN applications over TCP,
1839 TCP_NODELAY is generally a good latency optimization.
1840
1841 The macro expands as follows:
1842
1843 if mode server:
1844 socket-flags TCP_NODELAY
1845 push "socket-flags TCP_NODELAY"
1846
1847 --max-clients n
1848 Limit server to a maximum of n concurrent clients.
1849
1850 --max-routes-per-client n
1851 Allow a maximum of n internal routes per client (default=256).
1852 This is designed to help contain DoS attacks where an authenti‐
1853 cated client floods the server with packets appearing to come
1854 from many unique MAC addresses, forcing the server to deplete
1855 virtual memory as its internal routing table expands. This
1856 directive can be used in a --client-config-dir file or auto-gen‐
1857 erated by a --client-connect script to override the global value
1858 for a particular client.
1859
1860 Note that this directive affects OpenVPN's internal routing ta‐
1861 ble, not the kernel routing table.
1862
1863 --connect-freq n sec
1864 Allow a maximum of n new connections per sec seconds from
1865 clients. This is designed to contain DoS attacks which flood
1866 the server with connection requests using certificates which
1867 will ultimately fail to authenticate.
1868
1869 This is an imperfect solution however, because in a real DoS
1870 scenario, legitimate connections might also be refused.
1871
1872 For the best protection against DoS attacks in server mode, use
1873 --proto udp and --tls-auth.
1874
1875 --learn-address cmd
1876 Run script or shell command cmd to validate client virtual
1877 addresses or routes.
1878
1879 cmd will be executed with 3 parameters:
1880
1881 [1] operation -- "add", "update", or "delete" based on whether
1882 or not the address is being added to, modified, or deleted from
1883 OpenVPN's internal routing table.
1884 [2] address -- The address being learned or unlearned. This can
1885 be an IPv4 address such as "198.162.10.14", an IPv4 subnet such
1886 as "198.162.10.0/24", or an ethernet MAC address (when --dev tap
1887 is being used) such as "00:FF:01:02:03:04".
1888 [3] common name -- The common name on the certificate associated
1889 with the client linked to this address. Only present for "add"
1890 or "update" operations, not "delete".
1891
1892 On "add" or "update" methods, if the script returns a failure
1893 code (non-zero), OpenVPN will reject the address and will not
1894 modify its internal routing table.
1895
1896 Normally, the cmd script will use the information provided above
1897 to set appropriate firewall entries on the VPN TUN/TAP inter‐
1898 face. Since OpenVPN provides the association between virtual IP
1899 or MAC address and the client's authenticated common name, it
1900 allows a user-defined script to configure firewall access poli‐
1901 cies with regard to the client's high-level common name, rather
1902 than the low level client virtual addresses.
1903
1904 --auth-user-pass-verify script method
1905 Require the client to provide a username/password (possibly in
1906 addition to a client certificate) for authentication.
1907
1908 OpenVPN will execute script as a shell command to validate the
1909 username/password provided by the client.
1910
1911 If method is set to "via-env", OpenVPN will call script with the
1912 environmental variables username and password set to the user‐
1913 name/password strings provided by the client. Be aware that
1914 this method is insecure on some platforms which make the envi‐
1915 ronment of a process publicly visible to other unprivileged pro‐
1916 cesses.
1917
1918 If method is set to "via-file", OpenVPN will write the username
1919 and password to the first two lines of a temporary file. The
1920 filename will be passed as an argument to script, and the file
1921 will be automatically deleted by OpenVPN after the script
1922 returns. The location of the temporary file is controlled by
1923 the --tmp-dir option, and will default to the current directory
1924 if unspecified. For security, consider setting --tmp-dir to a
1925 volatile storage medium such as /dev/shm (if available) to pre‐
1926 vent the username/password file from touching the hard drive.
1927
1928 The script should examine the username and password, returning a
1929 success exit code (0) if the client's authentication request is
1930 to be accepted, or a failure code (1) to reject the client.
1931
1932 This directive is designed to enable a plugin-style interface
1933 for extending OpenVPN's authentication capabilities.
1934
1935 To protect against a client passing a maliciously formed user‐
1936 name or password string, the username string must consist only
1937 of these characters: alphanumeric, underbar ('_'), dash ('-'),
1938 dot ('.'), or at ('@'). The password string can consist of any
1939 printable characters except for CR or LF. Any illegal charac‐
1940 ters in either the username or password string will be converted
1941 to underbar ('_').
1942
1943 Care must be taken by any user-defined scripts to avoid creating
1944 a security vulnerability in the way that these strings are han‐
1945 dled. Never use these strings in such a way that they might be
1946 escaped or evaluated by a shell interpreter.
1947
1948 For a sample script that performs PAM authentication, see sam‐
1949 ple-scripts/auth-pam.pl in the OpenVPN source distribution.
1950
1951 --opt-verify
1952 Clients that connect with options that are incompatible with
1953 those of the server will be disconnected.
1954
1955 Options that will be compared for compatibility include dev-
1956 type, link-mtu, tun-mtu, proto, tun-ipv6, ifconfig, comp-lzo,
1957 fragment, keydir, cipher, auth, keysize, secret, no-replay, no-
1958 iv, tls-auth, key-method, tls-server, and tls-client.
1959
1960 This option requires that --disable-occ NOT be used.
1961
1962 --auth-user-pass-optional
1963 Allow connections by clients that do not specify a user‐
1964 name/password. Normally, when --auth-user-pass-verify or --man‐
1965 agement-client-auth is specified (or an authentication plugin
1966 module), the OpenVPN server daemon will require connecting
1967 clients to specify a username and password. This option makes
1968 the submission of a username/password by clients optional, pass‐
1969 ing the responsibility to the user-defined authentication mod‐
1970 ule/script to accept or deny the client based on other factors
1971 (such as the setting of X509 certificate fields). When this
1972 option is used, and a connecting client does not submit a user‐
1973 name/password, the user-defined authentication module/script
1974 will see the username and password as being set to empty strings
1975 (""). The authentication module/script MUST have logic to
1976 detect this condition and respond accordingly.
1977
1978 --client-cert-not-required
1979 Don't require client certificate, client will authenticate using
1980 username/password only. Be aware that using this directive is
1981 less secure than requiring certificates from all clients.
1982
1983 If you use this directive, the entire responsibility of authen‐
1984 tication will rest on your --auth-user-pass-verify script, so
1985 keep in mind that bugs in your script could potentially compro‐
1986 mise the security of your VPN.
1987
1988 If you don't use this directive, but you also specify an --auth-
1989 user-pass-verify script, then OpenVPN will perform double
1990 authentication. The client certificate verification AND the
1991 --auth-user-pass-verify script will need to succeed in order for
1992 a client to be authenticated and accepted onto the VPN.
1993
1994 --username-as-common-name
1995 For --auth-user-pass-verify authentication, use the authenti‐
1996 cated username as the common name, rather than the common name
1997 from the client cert.
1998
1999 --no-name-remapping
2000 Allow Common Name, X509 Subject, and username strings to include
2001 any printable character including space, but excluding control
2002 characters such as tab, newline, and carriage-return.
2003
2004 By default, OpenVPN will remap any character other than alphanu‐
2005 meric, underbar ('_'), dash ('-'), dot ('.'), and slash ('/') to
2006 underbar ('_'). The X509 Subject string as returned by the
2007 tls_id environmental variable, can additionally contain colon
2008 (':') or equal ('=').
2009
2010 While name remapping is performed for security reasons to reduce
2011 the possibility of introducing string expansion security vulner‐
2012 abilities in user-defined authentication scripts, this option is
2013 provided for those cases where it is desirable to disable the
2014 remapping feature. Don't use this option unless you know what
2015 you are doing!
2016
2017 --port-share host port
2018 When run in TCP server mode, share the OpenVPN port with another
2019 application, such as an HTTPS server. If OpenVPN senses a con‐
2020 nection to its port which is using a non-OpenVPN protocol, it
2021 will proxy the connection to the server at host:port. Currently
2022 only designed to work with HTTP/HTTPS, though it would be theo‐
2023 retically possible to extend to other protocols such as ssh.
2024
2025 Not implemented on Windows.
2026
2027 Client Mode
2028 Use client mode when connecting to an OpenVPN server which has
2029 --server, --server-bridge, or --mode server in it's configuration.
2030
2031 --client
2032 A helper directive designed to simplify the configuration of
2033 OpenVPN's client mode. This directive is equivalent to:
2034
2035 pull
2036 tls-client
2037
2038 --pull This option must be used on a client which is connecting to a
2039 multi-client server. It indicates to OpenVPN that it should
2040 accept options pushed by the server, provided they are part of
2041 the legal set of pushable options (note that the --pull option
2042 is implied by --client ).
2043
2044 In particular, --pull allows the server to push routes to the
2045 client, so you should not use --pull or --client in situations
2046 where you don't trust the server to have control over the
2047 client's routing table.
2048
2049 --auth-user-pass [up]
2050 Authenticate with server using username/password. up is a file
2051 containing username/password on 2 lines (Note: OpenVPN will only
2052 read passwords from a file if it has been built with the
2053 --enable-password-save configure option, or on Windows by defin‐
2054 ing ENABLE_PASSWORD_SAVE in config-win32.h).
2055
2056 If up is omitted, username/password will be prompted from the
2057 console.
2058
2059 The server configuration must specify an --auth-user-pass-verify
2060 script to verify the username/password provided by the client.
2061
2062 --auth-retry type
2063 Controls how OpenVPN responds to username/password verification
2064 errors such as the client-side response to an AUTH_FAILED mes‐
2065 sage from the server or verification failure of the private key
2066 password.
2067
2068 Normally used to prevent auth errors from being fatal on the
2069 client side, and to permit username/password requeries in case
2070 of error.
2071
2072 An AUTH_FAILED message is generated by the server if the client
2073 fails --auth-user-pass authentication, or if the server-side
2074 --client-connect script returns an error status when the client
2075 tries to connect.
2076
2077 type can be one of:
2078
2079 none -- Client will exit with a fatal error (this is the
2080 default).
2081 nointeract -- Client will retry the connection without requery‐
2082 ing for an --auth-user-pass username/password. Use this option
2083 for unattended clients.
2084 interact -- Client will requery for an --auth-user-pass user‐
2085 name/password and/or private key password before attempting a
2086 reconnection.
2087
2088 Note that while this option cannot be pushed, it can be con‐
2089 trolled from the management interface.
2090
2091 --server-poll-timeout n
2092 when polling possible remote servers to connect to in a round-
2093 robin fashion, spend no more than n seconds waiting for a
2094 response before trying the next server.
2095
2096 --explicit-exit-notify [n]
2097 In UDP client mode or point-to-point mode, send server/peer an
2098 exit notification if tunnel is restarted or OpenVPN process is
2099 exited. In client mode, on exit/restart, this option will tell
2100 the server to immediately close its client instance object
2101 rather than waiting for a timeout. The n parameter (default=1)
2102 controls the maximum number of retries that the client will
2103 attempt to resend the exit notification message.
2104
2105 Data Channel Encryption Options:
2106 These options are meaningful for both Static & TLS-negotiated key modes
2107 (must be compatible between peers).
2108
2109 --secret file [direction]
2110 Enable Static Key encryption mode (non-TLS). Use pre-shared
2111 secret file which was generated with --genkey.
2112
2113 The optional direction parameter enables the use of 4 distinct
2114 keys (HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt),
2115 so that each data flow direction has a different set of HMAC and
2116 cipher keys. This has a number of desirable security properties
2117 including eliminating certain kinds of DoS and message replay
2118 attacks.
2119
2120 When the direction parameter is omitted, 2 keys are used bidi‐
2121 rectionally, one for HMAC and the other for encryption/decryp‐
2122 tion.
2123
2124 The direction parameter should always be complementary on either
2125 side of the connection, i.e. one side should use "0" and the
2126 other should use "1", or both sides should omit it altogether.
2127
2128 The direction parameter requires that file contains a 2048 bit
2129 key. While pre-1.5 versions of OpenVPN generate 1024 bit key
2130 files, any version of OpenVPN which supports the direction
2131 parameter, will also support 2048 bit key file generation using
2132 the --genkey option.
2133
2134 Static key encryption mode has certain advantages, the primary
2135 being ease of configuration.
2136
2137 There are no certificates or certificate authorities or compli‐
2138 cated negotiation handshakes and protocols. The only require‐
2139 ment is that you have a pre-existing secure channel with your
2140 peer (such as ssh ) to initially copy the key. This require‐
2141 ment, along with the fact that your key never changes unless you
2142 manually generate a new one, makes it somewhat less secure than
2143 TLS mode (see below). If an attacker manages to steal your key,
2144 everything that was ever encrypted with it is compromised. Con‐
2145 trast that to the perfect forward secrecy features of TLS mode
2146 (using Diffie Hellman key exchange), where even if an attacker
2147 was able to steal your private key, he would gain no information
2148 to help him decrypt past sessions.
2149
2150 Another advantageous aspect of Static Key encryption mode is
2151 that it is a handshake-free protocol without any distinguishing
2152 signature or feature (such as a header or protocol handshake
2153 sequence) that would mark the ciphertext packets as being gener‐
2154 ated by OpenVPN. Anyone eavesdropping on the wire would see
2155 nothing but random-looking data.
2156
2157 --auth alg
2158 Authenticate packets with HMAC using message digest algorithm
2159 alg. (The default is SHA1 ). HMAC is a commonly used message
2160 authentication algorithm (MAC) that uses a data string, a secure
2161 hash algorithm, and a key, to produce a digital signature.
2162
2163 OpenVPN's usage of HMAC is to first encrypt a packet, then HMAC
2164 the resulting ciphertext.
2165
2166 In static-key encryption mode, the HMAC key is included in the
2167 key file generated by --genkey. In TLS mode, the HMAC key is
2168 dynamically generated and shared between peers via the TLS con‐
2169 trol channel. If OpenVPN receives a packet with a bad HMAC it
2170 will drop the packet. HMAC usually adds 16 or 20 bytes per
2171 packet. Set alg=none to disable authentication.
2172
2173 For more information on HMAC see
2174 http://www.cs.ucsd.edu/users/mihir/papers/hmac.html
2175
2176 --cipher alg
2177 Encrypt packets with cipher algorithm alg. The default is BF-
2178 CBC, an abbreviation for Blowfish in Cipher Block Chaining mode.
2179 Blowfish has the advantages of being fast, very secure, and
2180 allowing key sizes of up to 448 bits. Blowfish is designed to
2181 be used in situations where keys are changed infrequently.
2182
2183 For more information on blowfish, see http://www.counter‐
2184 pane.com/blowfish.html
2185
2186 To see other ciphers that are available with OpenVPN, use the
2187 --show-ciphers option.
2188
2189 OpenVPN supports the CBC, CFB, and OFB cipher modes, however CBC
2190 is recommended and CFB and OFB should be considered advanced
2191 modes.
2192
2193 Set alg=none to disable encryption.
2194
2195 --keysize n
2196 Size of cipher key in bits (optional). If unspecified, defaults
2197 to cipher-specific default. The --show-ciphers option (see
2198 below) shows all available OpenSSL ciphers, their default key
2199 sizes, and whether the key size can be changed. Use care in
2200 changing a cipher's default key size. Many ciphers have not
2201 been extensively cryptanalyzed with non-standard key lengths,
2202 and a larger key may offer no real guarantee of greater secu‐
2203 rity, or may even reduce security.
2204
2205 --prng alg [nsl]
2206 (Advanced) For PRNG (Pseudo-random number generator), use digest
2207 algorithm alg (default=sha1), and set nsl (default=16) to the
2208 size in bytes of the nonce secret length (between 16 and 64).
2209
2210 Set alg=none to disable the PRNG and use the OpenSSL RAND_bytes
2211 function instead for all of OpenVPN's pseudo-random number
2212 needs.
2213
2214 --engine [engine-name]
2215 Enable OpenSSL hardware-based crypto engine functionality.
2216
2217 If engine-name is specified, use a specific crypto engine. Use
2218 the --show-engines standalone option to list the crypto engines
2219 which are supported by OpenSSL.
2220
2221 --no-replay
2222 (Advanced) Disable OpenVPN's protection against replay attacks.
2223 Don't use this option unless you are prepared to make a tradeoff
2224 of greater efficiency in exchange for less security.
2225
2226 OpenVPN provides datagram replay protection by default.
2227
2228 Replay protection is accomplished by tagging each outgoing data‐
2229 gram with an identifier that is guaranteed to be unique for the
2230 key being used. The peer that receives the datagram will check
2231 for the uniqueness of the identifier. If the identifier was
2232 already received in a previous datagram, OpenVPN will drop the
2233 packet. Replay protection is important to defeat attacks such
2234 as a SYN flood attack, where the attacker listens in the wire,
2235 intercepts a TCP SYN packet (identifying it by the context in
2236 which it occurs in relation to other packets), then floods the
2237 receiving peer with copies of this packet.
2238
2239 OpenVPN's replay protection is implemented in slightly different
2240 ways, depending on the key management mode you have selected.
2241
2242 In Static Key mode or when using an CFB or OFB mode cipher,
2243 OpenVPN uses a 64 bit unique identifier that combines a time
2244 stamp with an incrementing sequence number.
2245
2246 When using TLS mode for key exchange and a CBC cipher mode,
2247 OpenVPN uses only a 32 bit sequence number without a time stamp,
2248 since OpenVPN can guarantee the uniqueness of this value for
2249 each key. As in IPSec, if the sequence number is close to wrap‐
2250 ping back to zero, OpenVPN will trigger a new key exchange.
2251
2252 To check for replays, OpenVPN uses the sliding window algorithm
2253 used by IPSec.
2254
2255 --replay-window n [t]
2256 Use a replay protection sliding-window of size n and a time win‐
2257 dow of t seconds.
2258
2259 By default n is 64 (the IPSec default) and t is 15 seconds.
2260
2261 This option is only relevant in UDP mode, i.e. when either
2262 --proto udp is specifed, or no --proto option is specified.
2263
2264 When OpenVPN tunnels IP packets over UDP, there is the possibil‐
2265 ity that packets might be dropped or delivered out of order.
2266 Because OpenVPN, like IPSec, is emulating the physical network
2267 layer, it will accept an out-of-order packet sequence, and will
2268 deliver such packets in the same order they were received to the
2269 TCP/IP protocol stack, provided they satisfy several con‐
2270 straints.
2271
2272 (a) The packet cannot be a replay (unless --no-replay is speci‐
2273 fied, which disables replay protection altogether).
2274
2275 (b) If a packet arrives out of order, it will only be accepted
2276 if the difference between its sequence number and the highest
2277 sequence number received so far is less than n.
2278
2279 (c) If a packet arrives out of order, it will only be accepted
2280 if it arrives no later than t seconds after any packet contain‐
2281 ing a higher sequence number.
2282
2283 If you are using a network link with a large pipeline (meaning
2284 that the product of bandwidth and latency is high), you may want
2285 to use a larger value for n. Satellite links in particular
2286 often require this.
2287
2288 If you run OpenVPN at --verb 4, you will see the message
2289 "Replay-window backtrack occurred [x]" every time the maximum
2290 sequence number backtrack seen thus far increases. This can be
2291 used to calibrate n.
2292
2293 There is some controversy on the appropriate method of handling
2294 packet reordering at the security layer.
2295
2296 Namely, to what extent should the security layer protect the
2297 encapsulated protocol from attacks which masquerade as the kinds
2298 of normal packet loss and reordering that occur over IP net‐
2299 works?
2300
2301 The IPSec and OpenVPN approach is to allow packet reordering
2302 within a certain fixed sequence number window.
2303
2304 OpenVPN adds to the IPSec model by limiting the window size in
2305 time as well as sequence space.
2306
2307 OpenVPN also adds TCP transport as an option (not offered by
2308 IPSec) in which case OpenVPN can adopt a very strict attitude
2309 towards message deletion and reordering: Don't allow it. Since
2310 TCP guarantees reliability, any packet loss or reordering event
2311 can be assumed to be an attack.
2312
2313 In this sense, it could be argued that TCP tunnel transport is
2314 preferred when tunneling non-IP or UDP application protocols
2315 which might be vulnerable to a message deletion or reordering
2316 attack which falls within the normal operational parameters of
2317 IP networks.
2318
2319 So I would make the statement that one should never tunnel a
2320 non-IP protocol or UDP application protocol over UDP, if the
2321 protocol might be vulnerable to a message deletion or reordering
2322 attack that falls within the normal operating parameters of what
2323 is to be expected from the physical IP layer. The problem is
2324 easily fixed by simply using TCP as the VPN transport layer.
2325
2326 --mute-replay-warnings
2327 Silence the output of replay warnings, which are a common false
2328 alarm on WiFi networks. This option preserves the security of
2329 the replay protection code without the verbosity associated with
2330 warnings about duplicate packets.
2331
2332 --replay-persist file
2333 Persist replay-protection state across sessions using file to
2334 save and reload the state.
2335
2336 This option will strengthen protection against replay attacks,
2337 especially when you are using OpenVPN in a dynamic context (such
2338 as with --inetd) when OpenVPN sessions are frequently started
2339 and stopped.
2340
2341 This option will keep a disk copy of the current replay protec‐
2342 tion state (i.e. the most recent packet timestamp and sequence
2343 number received from the remote peer), so that if an OpenVPN
2344 session is stopped and restarted, it will reject any replays of
2345 packets which were already received by the prior session.
2346
2347 This option only makes sense when replay protection is enabled
2348 (the default) and you are using either --secret (shared-secret
2349 key mode) or TLS mode with --tls-auth.
2350
2351 --no-iv
2352 (Advanced) Disable OpenVPN's use of IV (cipher initialization
2353 vector). Don't use this option unless you are prepared to make
2354 a tradeoff of greater efficiency in exchange for less security.
2355
2356 OpenVPN uses an IV by default, and requires it for CFB and OFB
2357 cipher modes (which are totally insecure without it). Using an
2358 IV is important for security when multiple messages are being
2359 encrypted/decrypted with the same key.
2360
2361 IV is implemented differently depending on the cipher mode used.
2362
2363 In CBC mode, OpenVPN uses a pseudo-random IV for each packet.
2364
2365 In CFB/OFB mode, OpenVPN uses a unique sequence number and time
2366 stamp as the IV. In fact, in CFB/OFB mode, OpenVPN uses a data‐
2367 gram space-saving optimization that uses the unique identifier
2368 for datagram replay protection as the IV.
2369
2370 --test-crypto
2371 Do a self-test of OpenVPN's crypto options by encrypting and
2372 decrypting test packets using the data channel encryption
2373 options specified above. This option does not require a peer to
2374 function, and therefore can be specified without --dev or
2375 --remote.
2376
2377 The typical usage of --test-crypto would be something like this:
2378
2379 openvpn --test-crypto --secret key
2380
2381 or
2382
2383 openvpn --test-crypto --secret key --verb 9
2384
2385 This option is very useful to test OpenVPN after it has been
2386 ported to a new platform, or to isolate problems in the com‐
2387 piler, OpenSSL crypto library, or OpenVPN's crypto code. Since
2388 it is a self-test mode, problems with encryption and authentica‐
2389 tion can be debugged independently of network and tunnel issues.
2390
2391 TLS Mode Options:
2392 TLS mode is the most powerful crypto mode of OpenVPN in both security
2393 and flexibility. TLS mode works by establishing control and data chan‐
2394 nels which are multiplexed over a single TCP/UDP port. OpenVPN initi‐
2395 ates a TLS session over the control channel and uses it to exchange
2396 cipher and HMAC keys to protect the data channel. TLS mode uses a
2397 robust reliability layer over the UDP connection for all control chan‐
2398 nel communication, while the data channel, over which encrypted tunnel
2399 data passes, is forwarded without any mediation. The result is the
2400 best of both worlds: a fast data channel that forwards over UDP with
2401 only the overhead of encrypt, decrypt, and HMAC functions, and a con‐
2402 trol channel that provides all of the security features of TLS, includ‐
2403 ing certificate-based authentication and Diffie Hellman forward
2404 secrecy.
2405
2406 To use TLS mode, each peer that runs OpenVPN should have its own local
2407 certificate/key pair ( --cert and --key ), signed by the root certifi‐
2408 cate which is specified in --ca.
2409
2410 When two OpenVPN peers connect, each presents its local certificate to
2411 the other. Each peer will then check that its partner peer presented a
2412 certificate which was signed by the master root certificate as speci‐
2413 fied in --ca.
2414
2415 If that check on both peers succeeds, then the TLS negotiation will
2416 succeed, both OpenVPN peers will exchange temporary session keys, and
2417 the tunnel will begin passing data.
2418
2419 The OpenVPN distribution contains a set of scripts for managing RSA
2420 certificates & keys, located in the easy-rsa subdirectory.
2421
2422 The easy-rsa package is also rendered in web form here: http://open‐
2423 vpn.net/easyrsa.html
2424
2425 --tls-server
2426 Enable TLS and assume server role during TLS handshake. Note
2427 that OpenVPN is designed as a peer-to-peer application. The
2428 designation of client or server is only for the purpose of nego‐
2429 tiating the TLS control channel.
2430
2431 --tls-client
2432 Enable TLS and assume client role during TLS handshake.
2433
2434 --ca file
2435 Certificate authority (CA) file in .pem format, also referred to
2436 as the root certificate. This file can have multiple certifi‐
2437 cates in .pem format, concatenated together. You can construct
2438 your own certificate authority certificate and private key by
2439 using a command such as:
2440
2441 openssl req -nodes -new -x509 -keyout ca.key -out ca.crt
2442
2443 Then edit your openssl.cnf file and edit the certificate vari‐
2444 able to point to your new root certificate ca.crt.
2445
2446 For testing purposes only, the OpenVPN distribution includes a
2447 sample CA certificate (ca.crt). Of course you should never use
2448 the test certificates and test keys distributed with OpenVPN in
2449 a production environment, since by virtue of the fact that they
2450 are distributed with OpenVPN, they are totally insecure.
2451
2452 --dh file
2453 File containing Diffie Hellman parameters in .pem format
2454 (required for --tls-server only). Use
2455
2456 openssl dhparam -out dh1024.pem 1024
2457
2458 to generate your own, or use the existing dh1024.pem file
2459 included with the OpenVPN distribution. Diffie Hellman parame‐
2460 ters may be considered public.
2461
2462 --cert file
2463 Local peer's signed certificate in .pem format -- must be signed
2464 by a certificate authority whose certificate is in --ca file.
2465 Each peer in an OpenVPN link running in TLS mode should have its
2466 own certificate and private key file. In addition, each cer‐
2467 tificate should have been signed by the key of a certificate
2468 authority whose public key resides in the --ca certificate
2469 authority file. You can easily make your own certificate
2470 authority (see above) or pay money to use a commercial service
2471 such as thawte.com (in which case you will be helping to finance
2472 the world's second space tourist :). To generate a certificate,
2473 you can use a command such as:
2474
2475 openssl req -nodes -new -keyout mycert.key -out mycert.csr
2476
2477 If your certificate authority private key lives on another
2478 machine, copy the certificate signing request (mycert.csr) to
2479 this other machine (this can be done over an insecure channel
2480 such as email). Now sign the certificate with a command such
2481 as:
2482
2483 openssl ca -out mycert.crt -in mycert.csr
2484
2485 Now copy the certificate (mycert.crt) back to the peer which
2486 initially generated the .csr file (this can be over a public
2487 medium). Note that the openssl ca command reads the location of
2488 the certificate authority key from its configuration file such
2489 as /usr/share/ssl/openssl.cnf -- note also that for certificate
2490 authority functions, you must set up the files index.txt (may be
2491 empty) and serial (initialize to 01 ).
2492
2493 --key file
2494 Local peer's private key in .pem format. Use the private key
2495 which was generated when you built your peer's certificate (see
2496 -cert file above).
2497
2498 --pkcs12 file
2499 Specify a PKCS #12 file containing local private key, local cer‐
2500 tificate, and root CA certificate. This option can be used
2501 instead of --ca, --cert, and --key.
2502
2503 --pkcs11-cert-private [0|1]...
2504 Set if access to certificate object should be performed after
2505 login. Every provider has its own setting.
2506
2507 --pkcs11-id name
2508 Specify the serialized certificate id to be used. The id can be
2509 gotten by the standalone --show-pkcs11-ids option.
2510
2511 --pkcs11-id-management
2512 Acquire PKCS#11 id from management interface. In this case a
2513 NEED-STR 'pkcs11-id-request' real-time message will be trig‐
2514 gered, application may use pkcs11-id-count command to retrieve
2515 available number of certificates, and pkcs11-id-get command to
2516 retrieve certificate id and certificate body.
2517
2518 --pkcs11-pin-cache seconds
2519 Specify how many seconds the PIN can be cached, the default is
2520 until the token is removed.
2521
2522 --pkcs11-protected-authentication [0|1]...
2523 Use PKCS#11 protected authentication path, useful for biometric
2524 and external keypad devices. Every provider has its own set‐
2525 ting.
2526
2527 --pkcs11-providers provider...
2528 Specify a RSA Security Inc. PKCS #11 Cryptographic Token Inter‐
2529 face (Cryptoki) providers to load. This option can be used
2530 instead of --cert, --key, and --pkcs12.
2531
2532 --pkcs11-private-mode mode...
2533 Specify which method to use in order to perform private key
2534 operations. A different mode can be specified for each
2535 provider. Mode is encoded as hex number, and can be a mask one
2536 of the following:
2537
2538 0 (default) -- Try to determind automatically.
2539 1 -- Use sign.
2540 2 -- Use sign recover.
2541 4 -- Use decrypt.
2542 8 -- Use unwrap.
2543
2544 --cryptoapicert select-string
2545 Load the certificate and private key from the Windows Certifi‐
2546 cate System Store (Windows Only).
2547
2548 Use this option instead of --cert and --key.
2549
2550 This makes it possible to use any smart card, supported by Win‐
2551 dows, but also any kind of certificate, residing in the Cert
2552 Store, where you have access to the private key. This option
2553 has been tested with a couple of different smart cards (GemSAFE,
2554 Cryptoflex, and Swedish Post Office eID) on the client side, and
2555 also an imported PKCS12 software certificate on the server side.
2556
2557 To select a certificate, based on a substring search in the cer‐
2558 tificate's subject:
2559
2560 cryptoapicert "SUBJ:Peter Runestig"
2561
2562 To select a certificate, based on certificate's thumbprint:
2563
2564 cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."
2565
2566 The thumbprint hex string can easily be copy-and-pasted from the
2567 Windows Certificate Store GUI.
2568
2569
2570 --key-method m
2571 Use data channel key negotiation method m. The key method must
2572 match on both sides of the connection.
2573
2574 After OpenVPN negotiates a TLS session, a new set of keys for
2575 protecting the tunnel data channel is generated and exchanged
2576 over the TLS session.
2577
2578 In method 1 (the default for OpenVPN 1.x), both sides generate
2579 random encrypt and HMAC-send keys which are forwarded to the
2580 other host over the TLS channel.
2581
2582 In method 2, (the default for OpenVPN 2.0) the client generates
2583 a random key. Both client and server also generate some random
2584 seed material. All key source material is exchanged over the
2585 TLS channel. The actual keys are generated using the TLS PRF
2586 function, taking source entropy from both client and server.
2587 Method 2 is designed to closely parallel the key generation
2588 process used by TLS 1.0.
2589
2590 Note that in TLS mode, two separate levels of keying occur:
2591
2592 (1) The TLS connection is initially negotiated, with both sides
2593 of the connection producing certificates and verifying the cer‐
2594 tificate (or other authentication info provided) of the other
2595 side. The --key-method parameter has no effect on this process.
2596
2597 (2) After the TLS connection is established, the tunnel session
2598 keys are separately negotiated over the existing secure TLS
2599 channel. Here, --key-method determines the derivation of the
2600 tunnel session keys.
2601
2602 --tls-cipher l
2603 A list l of allowable TLS ciphers delimited by a colon (":").
2604 If you require a high level of security, you may want to set
2605 this parameter manually, to prevent a version rollback attack
2606 where a man-in-the-middle attacker tries to force two peers to
2607 negotiate to the lowest level of security they both support.
2608 Use --show-tls to see a list of supported TLS ciphers.
2609
2610 --tls-timeout n
2611 Packet retransmit timeout on TLS control channel if no acknowl‐
2612 edgment from remote within n seconds (default=2). When OpenVPN
2613 sends a control packet to its peer, it will expect to receive an
2614 acknowledgement within n seconds or it will retransmit the
2615 packet, subject to a TCP-like exponential backoff algorithm.
2616 This parameter only applies to control channel packets. Data
2617 channel packets (which carry encrypted tunnel data) are never
2618 acknowledged, sequenced, or retransmitted by OpenVPN because the
2619 higher level network protocols running on top of the tunnel such
2620 as TCP expect this role to be left to them.
2621
2622 --reneg-bytes n
2623 Renegotiate data channel key after n bytes sent or received
2624 (disabled by default). OpenVPN allows the lifetime of a key to
2625 be expressed as a number of bytes encrypted/decrypted, a number
2626 of packets, or a number of seconds. A key renegotiation will be
2627 forced if any of these three criteria are met by either peer.
2628
2629 --reneg-pkts n
2630 Renegotiate data channel key after n packets sent and received
2631 (disabled by default).
2632
2633 --reneg-sec n
2634 Renegotiate data channel key after n seconds (default=3600).
2635
2636 When using dual-factor authentication, note that this default
2637 value may cause the end user to be challenged to reauthorize
2638 once per hour.
2639
2640 Also, keep in mind that this option can be used on both the
2641 client and server, and whichever uses the lower value will be
2642 the one to trigger the renegotiation. A common mistake is to
2643 set --reneg-sec to a higher value on either the client or
2644 server, while the other side of the connection is still using
2645 the default value of 3600 seconds, meaning that the renegotia‐
2646 tion will still occur once per 3600 seconds. The solution is to
2647 increase --reneg-sec on both the client and server, or set it to
2648 0 on one side of the connection (to disable), and to your chosen
2649 value on the other side.
2650
2651 --hand-window n
2652 Handshake Window -- the TLS-based key exchange must finalize
2653 within n seconds of handshake initiation by any peer (default =
2654 60 seconds). If the handshake fails we will attempt to reset
2655 our connection with our peer and try again. Even in the event
2656 of handshake failure we will still use our expiring key for up
2657 to --tran-window seconds to maintain continuity of transmission
2658 of tunnel data.
2659
2660 --tran-window n
2661 Transition window -- our old key can live this many seconds
2662 after a new a key renegotiation begins (default = 3600 seconds).
2663 This feature allows for a graceful transition from old to new
2664 key, and removes the key renegotiation sequence from the criti‐
2665 cal path of tunnel data forwarding.
2666
2667 --single-session
2668 After initially connecting to a remote peer, disallow any new
2669 connections. Using this option means that a remote peer cannot
2670 connect, disconnect, and then reconnect.
2671
2672 If the daemon is reset by a signal or --ping-restart, it will
2673 allow one new connection.
2674
2675 --single-session can be used with --ping-exit or --inactive to
2676 create a single dynamic session that will exit when finished.
2677
2678 --tls-exit
2679 Exit on TLS negotiation failure.
2680
2681 --tls-auth file [direction]
2682 Add an additional layer of HMAC authentication on top of the TLS
2683 control channel to protect against DoS attacks.
2684
2685 In a nutshell, --tls-auth enables a kind of "HMAC firewall" on
2686 OpenVPN's TCP/UDP port, where TLS control channel packets bear‐
2687 ing an incorrect HMAC signature can be dropped immediately with‐
2688 out response.
2689
2690 file (required) is a key file which can be in one of two for‐
2691 mats:
2692
2693 [1m(1) An OpenVPN static key file generated by --genkey (required
2694 if direction parameter is used).
2695
2696 [1m(2) A freeform passphrase file. In this case the HMAC key will
2697 be derived by taking a secure hash of this file, similar to the
2698 md5sum(1) or sha1sum(1) commands.
2699
2700 OpenVPN will first try format (1), and if the file fails to
2701 parse as a static key file, format (2) will be used.
2702
2703 See the --secret option for more information on the optional
2704 direction parameter.
2705
2706 --tls-auth is recommended when you are running OpenVPN in a mode
2707 where it is listening for packets from any IP address, such as
2708 when --remote is not specified, or --remote is specified with
2709 --float.
2710
2711 The rationale for this feature is as follows. TLS requires a
2712 multi-packet exchange before it is able to authenticate a peer.
2713 During this time before authentication, OpenVPN is allocating
2714 resources (memory and CPU) to this potential peer. The poten‐
2715 tial peer is also exposing many parts of OpenVPN and the OpenSSL
2716 library to the packets it is sending. Most successful network
2717 attacks today seek to either exploit bugs in programs (such as
2718 buffer overflow attacks) or force a program to consume so many
2719 resources that it becomes unusable. Of course the first line of
2720 defense is always to produce clean, well-audited code. OpenVPN
2721 has been written with buffer overflow attack prevention as a top
2722 priority. But as history has shown, many of the most widely
2723 used network applications have, from time to time, fallen to
2724 buffer overflow attacks.
2725
2726 So as a second line of defense, OpenVPN offers this special
2727 layer of authentication on top of the TLS control channel so
2728 that every packet on the control channel is authenticated by an
2729 HMAC signature and a unique ID for replay protection. This sig‐
2730 nature will also help protect against DoS (Denial of Service)
2731 attacks. An important rule of thumb in reducing vulnerability
2732 to DoS attacks is to minimize the amount of resources a poten‐
2733 tial, but as yet unauthenticated, client is able to consume.
2734
2735 --tls-auth does this by signing every TLS control channel packet
2736 with an HMAC signature, including packets which are sent before
2737 the TLS level has had a chance to authenticate the peer. The
2738 result is that packets without the correct signature can be
2739 dropped immediately upon reception, before they have a chance to
2740 consume additional system resources such as by initiating a TLS
2741 handshake. --tls-auth can be strengthened by adding the
2742 --replay-persist option which will keep OpenVPN's replay protec‐
2743 tion state in a file so that it is not lost across restarts.
2744
2745 It should be emphasized that this feature is optional and that
2746 the passphrase/key file used with --tls-auth gives a peer noth‐
2747 ing more than the power to initiate a TLS handshake. It is not
2748 used to encrypt or authenticate any tunnel data.
2749
2750 --askpass [file]
2751 Get certificate password from console or file before we daemo‐
2752 nize.
2753
2754 For the extremely security conscious, it is possible to protect
2755 your private key with a password. Of course this means that
2756 every time the OpenVPN daemon is started you must be there to
2757 type the password. The --askpass option allows you to start
2758 OpenVPN from the command line. It will query you for a password
2759 before it daemonizes. To protect a private key with a password
2760 you should omit the -nodes option when you use the openssl com‐
2761 mand line tool to manage certificates and private keys.
2762
2763 If file is specified, read the password from the first line of
2764 file. Keep in mind that storing your password in a file to a
2765 certain extent invalidates the extra security provided by using
2766 an encrypted key (Note: OpenVPN will only read passwords from a
2767 file if it has been built with the --enable-password-save con‐
2768 figure option, or on Windows by defining ENABLE_PASSWORD_SAVE in
2769 config-win32.h).
2770
2771 --auth-nocache
2772 Don't cache --askpass or --auth-user-pass username/passwords in
2773 virtual memory.
2774
2775 If specified, this directive will cause OpenVPN to immediately
2776 forget username/password inputs after they are used. As a
2777 result, when OpenVPN needs a username/password, it will prompt
2778 for input from stdin, which may be multiple times during the
2779 duration of an OpenVPN session.
2780
2781 This directive does not affect the --http-proxy username/pass‐
2782 word. It is always cached.
2783
2784 --tls-verify cmd
2785 Execute shell command cmd to verify the X509 name of a pending
2786 TLS connection that has otherwise passed all other tests of cer‐
2787 tification (except for revocation via --crl-verify directive;
2788 the revocation test occurs after the --tls-verify test).
2789
2790 cmd should return 0 to allow the TLS handshake to proceed, or 1
2791 to fail. cmd is executed as
2792
2793 cmd certificate_depth X509_NAME_oneline
2794
2795 This feature is useful if the peer you want to trust has a cer‐
2796 tificate which was signed by a certificate authority who also
2797 signed many other certificates, where you don't necessarily want
2798 to trust all of them, but rather be selective about which peer
2799 certificate you will accept. This feature allows you to write a
2800 script which will test the X509 name on a certificate and decide
2801 whether or not it should be accepted. For a simple perl script
2802 which will test the common name field on the certificate, see
2803 the file verify-cn in the OpenVPN distribution.
2804
2805 See the "Environmental Variables" section below for additional
2806 parameters passed as environmental variables.
2807
2808 Note that cmd can be a shell command with multiple arguments, in
2809 which case all OpenVPN-generated arguments will be appended to
2810 cmd to build a command line which will be passed to the script.
2811
2812 --tls-remote name
2813 Accept connections only from a host with X509 name or common
2814 name equal to name. The remote host must also pass all other
2815 tests of verification.
2816
2817 Name can also be a common name prefix, for example if you want a
2818 client to only accept connections to "Server-1", "Server-2",
2819 etc., you can simply use --tls-remote Server
2820
2821 Using a common name prefix is a useful alternative to managing a
2822 CRL (Certificate Revocation List) on the client, since it allows
2823 the client to refuse all certificates except for those associ‐
2824 ated with designated servers.
2825
2826 --tls-remote is a useful replacement for the --tls-verify option
2827 to verify the remote host, because --tls-remote works in a
2828 --chroot environment too.
2829
2830 --ns-cert-type client|server
2831 Require that peer certificate was signed with an explicit
2832 nsCertType designation of "client" or "server".
2833
2834 This is a useful security option for clients, to ensure that the
2835 host they connect with is a designated server.
2836
2837 See the easy-rsa/build-key-server script for an example of how
2838 to generate a certificate with the nsCertType field set to
2839 "server".
2840
2841 If the server certificate's nsCertType field is set to "server",
2842 then the clients can verify this with --ns-cert-type server.
2843
2844 This is an important security precaution to protect against a
2845 man-in-the-middle attack where an authorized client attempts to
2846 connect to another client by impersonating the server. The
2847 attack is easily prevented by having clients verify the server
2848 certificate using any one of --ns-cert-type, --tls-remote, or
2849 --tls-verify.
2850
2851 --remote-cert-ku v...
2852 Require that peer certificate was signed with an explicit key
2853 usage.
2854
2855 This is a useful security option for clients, to ensure that the
2856 host they connect to is a designated server.
2857
2858 The key usage should be encoded in hex, more than one key usage
2859 can be specified.
2860
2861 --remote-cert-eku oid
2862 Require that peer certificate was signed with an explicit
2863 extended key usage.
2864
2865 This is a useful security option for clients, to ensure that the
2866 host they connect to is a designated server.
2867
2868 The extended key usage should be encoded in oid notation, or
2869 OpenSSL symbolic representation.
2870
2871 --remote-cert-tls client|server
2872 Require that peer certificate was signed with an explicit key
2873 usage and extended key usage based on RFC3280 TLS rules.
2874
2875 This is a useful security option for clients, to ensure that the
2876 host they connect to is a designated server.
2877
2878 The --remote-cert-tls client option is equivalent to --remote-
2879 cert-ku 80 08 88 --remote-cert-eku "TLS Web Client Authentica‐
2880 tion"
2881
2882 The key usage is digitalSignature and/or keyAgreement.
2883
2884 The --remote-cert-tls server option is equivalent to --remote-
2885 cert-ku a0 88 --remote-cert-eku "TLS Web Server Authentication"
2886
2887 The key usage is digitalSignature and ( keyEncipherment or keyA‐
2888 greement ).
2889
2890 This is an important security precaution to protect against a
2891 man-in-the-middle attack where an authorized client attempts to
2892 connect to another client by impersonating the server. The
2893 attack is easily prevented by having clients verify the server
2894 certificate using any one of --remote-cert-tls, --tls-remote, or
2895 --tls-verify.
2896
2897 --crl-verify crl
2898 Check peer certificate against the file crl in PEM format.
2899
2900 A CRL (certificate revocation list) is used when a particular
2901 key is compromised but when the overall PKI is still intact.
2902
2903 Suppose you had a PKI consisting of a CA, root certificate, and
2904 a number of client certificates. Suppose a laptop computer con‐
2905 taining a client key and certificate was stolen. By adding the
2906 stolen certificate to the CRL file, you could reject any connec‐
2907 tion which attempts to use it, while preserving the overall
2908 integrity of the PKI.
2909
2910 The only time when it would be necessary to rebuild the entire
2911 PKI from scratch would be if the root certificate key itself was
2912 compromised.
2913
2914 SSL Library information:
2915 --show-ciphers
2916 (Standalone) Show all cipher algorithms to use with the --cipher
2917 option.
2918
2919 --show-digests
2920 (Standalone) Show all message digest algorithms to use with the
2921 --auth option.
2922
2923 --show-tls
2924 (Standalone) Show all TLS ciphers (TLS used only as a control
2925 channel). The TLS ciphers will be sorted from highest prefer‐
2926 ence (most secure) to lowest.
2927
2928 --show-engines
2929 (Standalone) Show currently available hardware-based crypto
2930 acceleration engines supported by the OpenSSL library.
2931
2932 Generate a random key:
2933 Used only for non-TLS static key encryption mode.
2934
2935 --genkey
2936 (Standalone) Generate a random key to be used as a shared
2937 secret, for use with the --secret option. This file must be
2938 shared with the peer over a pre-existing secure channel such as
2939 scp(1)
2940
2941 --secret file
2942 Write key to file.
2943
2944 TUN/TAP persistent tunnel config mode:
2945 Available with linux 2.4.7+. These options comprise a standalone mode
2946 of OpenVPN which can be used to create and delete persistent tunnels.
2947
2948 --mktun
2949 (Standalone) Create a persistent tunnel on platforms which sup‐
2950 port them such as Linux. Normally TUN/TAP tunnels exist only
2951 for the period of time that an application has them open. This
2952 option takes advantage of the TUN/TAP driver's ability to build
2953 persistent tunnels that live through multiple instantiations of
2954 OpenVPN and die only when they are deleted or the machine is
2955 rebooted.
2956
2957 One of the advantages of persistent tunnels is that they elimi‐
2958 nate the need for separate --up and --down scripts to run the
2959 appropriate ifconfig(8) and route(8) commands. These commands
2960 can be placed in the the same shell script which starts or ter‐
2961 minates an OpenVPN session.
2962
2963 Another advantage is that open connections through the TUN/TAP-
2964 based tunnel will not be reset if the OpenVPN peer restarts.
2965 This can be useful to provide uninterrupted connectivity through
2966 the tunnel in the event of a DHCP reset of the peer's public IP
2967 address (see the --ipchange option above).
2968
2969 One disadvantage of persistent tunnels is that it is harder to
2970 automatically configure their MTU value (see --link-mtu and
2971 --tun-mtu above).
2972
2973 On some platforms such as Windows, TAP-Win32 tunnels are persis‐
2974 tent by default.
2975
2976 --rmtun
2977 (Standalone) Remove a persistent tunnel.
2978
2979 --dev tunX | tapX
2980 TUN/TAP device
2981
2982 --user user
2983 Optional user to be owner of this tunnel.
2984
2985 --group group
2986 Optional group to be owner of this tunnel.
2987
2988 Windows-Specific Options:
2989 --win-sys path|'env'
2990 Set the Windows system directory pathname to use when looking
2991 for system executables such as route.exe and netsh.exe. By
2992 default, if this directive is not specified, the pathname will
2993 be set to "C:\WINDOWS"
2994
2995 The special string 'env' indicates that the pathname should be
2996 read from the SystemRoot environmental variable.
2997
2998 --ip-win32 method
2999 When using --ifconfig on Windows, set the TAP-Win32 adapter IP
3000 address and netmask using method. Don't use this option unless
3001 you are also using --ifconfig.
3002
3003 manual -- Don't set the IP address or netmask automatically.
3004 Instead output a message to the console telling the user to con‐
3005 figure the adapter manually and indicating the IP/netmask which
3006 OpenVPN expects the adapter to be set to.
3007
3008 dynamic [offset] [lease-time] -- Automatically set the IP
3009 address and netmask by replying to DHCP query messages generated
3010 by the kernel. This mode is probably the "cleanest" solution
3011 for setting the TCP/IP properties since it uses the well-known
3012 DHCP protocol. There are, however, two prerequisites for using
3013 this mode: (1) The TCP/IP properties for the TAP-Win32 adapter
3014 must be set to "Obtain an IP address automatically," and (2)
3015 OpenVPN needs to claim an IP address in the subnet for use as
3016 the virtual DHCP server address. By default in --dev tap mode,
3017 OpenVPN will take the normally unused first address in the sub‐
3018 net. For example, if your subnet is 192.168.4.0 netmask
3019 255.255.255.0, then OpenVPN will take the IP address 192.168.4.0
3020 to use as the virtual DHCP server address. In --dev tun mode,
3021 OpenVPN will cause the DHCP server to masquerade as if it were
3022 coming from the remote endpoint. The optional offset parameter
3023 is an integer which is > -256 and < 256 and which defaults to 0.
3024 If offset is positive, the DHCP server will masquerade as the IP
3025 address at network address + offset. If offset is negative, the
3026 DHCP server will masquerade as the IP address at broadcast
3027 address + offset. The Windows ipconfig /all command can be used
3028 to show what Windows thinks the DHCP server address is. OpenVPN
3029 will "claim" this address, so make sure to use a free address.
3030 Having said that, different OpenVPN instantiations, including
3031 different ends of the same connection, can share the same vir‐
3032 tual DHCP server address. The lease-time parameter controls the
3033 lease time of the DHCP assignment given to the TAP-Win32
3034 adapter, and is denoted in seconds. Normally a very long lease
3035 time is preferred because it prevents routes involving the TAP-
3036 Win32 adapter from being lost when the system goes to sleep.
3037 The default lease time is one year.
3038
3039 netsh -- Automatically set the IP address and netmask using the
3040 Windows command-line "netsh" command. This method appears to
3041 work correctly on Windows XP but not Windows 2000.
3042
3043 ipapi -- Automatically set the IP address and netmask using the
3044 Windows IP Helper API. This approach does not have ideal seman‐
3045 tics, though testing has indicated that it works okay in prac‐
3046 tice. If you use this option, it is best to leave the TCP/IP
3047 properties for the TAP-Win32 adapter in their default state,
3048 i.e. "Obtain an IP address automatically."
3049
3050 adaptive -- (Default) Try dynamic method initially and fail over
3051 to netsh if the DHCP negotiation with the TAP-Win32 adapter does
3052 not succeed in 20 seconds. Such failures have been known to
3053 occur when certain third-party firewall packages installed on
3054 the client machine block the DHCP negotiation used by the TAP-
3055 Win32 adapter. Note that if the netsh failover occurs, the TAP-
3056 Win32 adapter TCP/IP properties will be reset from DHCP to
3057 static, and this will cause future OpenVPN startups using the
3058 adaptive mode to use netsh immediately, rather than trying
3059 dynamic first. To "unstick" the adaptive mode from using netsh,
3060 run OpenVPN at least once using the dynamic mode to restore the
3061 TAP-Win32 adapter TCP/IP properties to a DHCP configuration.
3062
3063 --route-method m
3064 Which method m to use for adding routes on Windows?
3065
3066 adaptive (default) -- Try IP helper API first. If that fails,
3067 fall back to the route.exe shell command.
3068 ipapi -- Use IP helper API.
3069 exe -- Call the route.exe shell command.
3070
3071 --dhcp-option type [parm]
3072 Set extended TAP-Win32 TCP/IP properties, must be used with
3073 --ip-win32 dynamic or --ip-win32 adaptive. This option can be
3074 used to set additional TCP/IP properties on the TAP-Win32
3075 adapter, and is particularly useful for configuring an OpenVPN
3076 client to access a Samba server across the VPN.
3077
3078 DOMAIN name -- Set Connection-specific DNS Suffix.
3079
3080 DNS addr -- Set primary domain name server address. Repeat this
3081 option to set secondary DNS server addresses.
3082
3083 WINS addr -- Set primary WINS server address (NetBIOS over
3084 TCP/IP Name Server). Repeat this option to set secondary WINS
3085 server addresses.
3086
3087 NBDD addr -- Set primary NBDD server address (NetBIOS over
3088 TCP/IP Datagram Distribution Server) Repeat this option to set
3089 secondary NBDD server addresses.
3090
3091 NTP addr -- Set primary NTP server address (Network Time Proto‐
3092 col). Repeat this option to set secondary NTP server addresses.
3093
3094 NBT type -- Set NetBIOS over TCP/IP Node type. Possible
3095 options: 1 = b-node (broadcasts), 2 = p-node (point-to-point
3096 name queries to a WINS server), 4 = m-node (broadcast then query
3097 name server), and 8 = h-node (query name server, then broad‐
3098 cast).
3099
3100 NBS scope-id -- Set NetBIOS over TCP/IP Scope. A NetBIOS Scope
3101 ID provides an extended naming service for the NetBIOS over
3102 TCP/IP (Known as NBT) module. The primary purpose of a NetBIOS
3103 scope ID is to isolate NetBIOS traffic on a single network to
3104 only those nodes with the same NetBIOS scope ID. The NetBIOS
3105 scope ID is a character string that is appended to the NetBIOS
3106 name. The NetBIOS scope ID on two hosts must match, or the two
3107 hosts will not be able to communicate. The NetBIOS Scope ID also
3108 allows computers to use the same computer name, as they have
3109 different scope IDs. The Scope ID becomes a part of the NetBIOS
3110 name, making the name unique. (This description of NetBIOS
3111 scopes courtesy of NeonSurge@abyss.com)
3112
3113 DISABLE-NBT -- Disable Netbios-over-TCP/IP.
3114
3115 Note that if --dhcp-option is pushed via --push to a non-windows
3116 client, the option will be saved in the client's environment
3117 before the up script is called, under the name "for‐
3118 eign_option_{n}".
3119
3120 --tap-sleep n
3121 Cause OpenVPN to sleep for n seconds immediately after the TAP-
3122 Win32 adapter state is set to "connected".
3123
3124 This option is intended to be used to troubleshoot problems with
3125 the --ifconfig and --ip-win32 options, and is used to give the
3126 TAP-Win32 adapter time to come up before Windows IP Helper API
3127 operations are applied to it.
3128
3129 --show-net-up
3130 Output OpenVPN's view of the system routing table and network
3131 adapter list to the syslog or log file after the TUN/TAP adapter
3132 has been brought up and any routes have been added.
3133
3134 --dhcp-renew
3135 Ask Windows to renew the TAP adapter lease on startup. This
3136 option is normally unnecessary, as Windows automatically trig‐
3137 gers a DHCP renegotiation on the TAP adapter when it comes up,
3138 however if you set the TAP-Win32 adapter Media Status property
3139 to "Always Connected", you may need this flag.
3140
3141 --dhcp-release
3142 Ask Windows to release the TAP adapter lease on shutdown. This
3143 option has the same caveats as --dhcp-renew above.
3144
3145 --pause-exit
3146 Put up a "press any key to continue" message on the console
3147 prior to OpenVPN program exit. This option is automatically
3148 used by the Windows explorer when OpenVPN is run on a configura‐
3149 tion file using the right-click explorer menu.
3150
3151 --service exit-event [0|1]
3152 Should be used when OpenVPN is being automatically executed by
3153 another program in such a context that no interaction with the
3154 user via display or keyboard is possible. In general, end-users
3155 should never need to explicitly use this option, as it is auto‐
3156 matically added by the OpenVPN service wrapper when a given
3157 OpenVPN configuration is being run as a service.
3158
3159 exit-event is the name of a Windows global event object, and
3160 OpenVPN will continuously monitor the state of this event object
3161 and exit when it becomes signaled.
3162
3163 The second parameter indicates the initial state of exit-event
3164 and normally defaults to 0.
3165
3166 Multiple OpenVPN processes can be simultaneously executed with
3167 the same exit-event parameter. In any case, the controlling
3168 process can signal exit-event, causing all such OpenVPN pro‐
3169 cesses to exit.
3170
3171 When executing an OpenVPN process using the --service directive,
3172 OpenVPN will probably not have a console window to output sta‐
3173 tus/error messages, therefore it is useful to use --log or
3174 --log-append to write these messages to a file.
3175
3176 --show-adapters
3177 (Standalone) Show available TAP-Win32 adapters which can be
3178 selected using the --dev-node option. On non-Windows systems,
3179 the ifconfig(8) command provides similar functionality.
3180
3181 --allow-nonadmin [TAP-adapter]
3182 (Standalone) Set TAP-adapter to allow access from non-adminis‐
3183 trative accounts. If TAP-adapter is omitted, all TAP adapters
3184 on the system will be configured to allow non-admin access. The
3185 non-admin access setting will only persist for the length of
3186 time that the TAP-Win32 device object and driver remain loaded,
3187 and will need to be re-enabled after a reboot, or if the driver
3188 is unloaded and reloaded. This directive can only be used by an
3189 administrator.
3190
3191 --show-valid-subnets
3192 (Standalone) Show valid subnets for --dev tun emulation. Since
3193 the TAP-Win32 driver exports an ethernet interface to Windows,
3194 and since TUN devices are point-to-point in nature, it is neces‐
3195 sary for the TAP-Win32 driver to impose certain constraints on
3196 TUN endpoint address selection.
3197
3198 Namely, the point-to-point endpoints used in TUN device emula‐
3199 tion must be the middle two addresses of a /30 subnet (netmask
3200 255.255.255.252).
3201
3202 --show-net
3203 (Standalone) Show OpenVPN's view of the system routing table and
3204 network adapter list.
3205
3206 PKCS#11 Standalone Options:
3207 --show-pkcs11-ids provider [cert_private]
3208 (Standalone) Show PKCS#11 token object list. Specify cert_pri‐
3209 vate as 1 if certificates are stored as private objects.
3210
3211 --verb option can be used BEFORE this option to produce debug‐
3212 ging information.
3213
3215 OpenVPN exports a series of environmental variables for use by user-
3216 defined scripts.
3217
3218 Script Order of Execution
3219 --up Executed after TCP/UDP socket bind and TUN/TAP open.
3220
3221 --tls-verify
3222 Executed when we have a still untrusted remote peer.
3223
3224 --ipchange
3225 Executed after connection authentication, or remote IP address
3226 change.
3227
3228 --client-connect
3229 Executed in --mode server mode immediately after client authen‐
3230 tication.
3231
3232 --route-up
3233 Executed after connection authentication, either immediately
3234 after, or some number of seconds after as defined by the
3235 --route-delay option.
3236
3237 --client-disconnect
3238 Executed in --mode server mode on client instance shutdown.
3239
3240 --down Executed after TCP/UDP and TUN/TAP close.
3241
3242 --learn-address
3243 Executed in --mode server mode whenever an IPv4 address/route or
3244 MAC address is added to OpenVPN's internal routing table.
3245
3246 --auth-user-pass-verify
3247 Executed in --mode server mode on new client connections, when
3248 the client is still untrusted.
3249
3250 String Types and Remapping
3251 In certain cases, OpenVPN will perform remapping of characters in
3252 strings. Essentially, any characters outside the set of permitted
3253 characters for each string type will be converted to underbar ('_').
3254
3255 Q: Why is string remapping necessary?
3256
3257 A: It's an important security feature to prevent the malicious coding
3258 of strings from untrusted sources to be passed as parameters to
3259 scripts, saved in the environment, used as a common name, translated to
3260 a filename, etc.
3261
3262 Q: Can string remapping be disabled?
3263
3264 A: Yes, by using the --no-name-remapping option, however this should be
3265 considered an advanced option.
3266
3267 Here is a brief rundown of OpenVPN's current string types and the per‐
3268 mitted character class for each string:
3269
3270 X509 Names: Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), at
3271 ('@'), colon (':'), slash ('/'), and equal ('='). Alphanumeric is
3272 defined as a character which will cause the C library isalnum() func‐
3273 tion to return true.
3274
3275 Common Names: Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), and
3276 at ('@').
3277
3278 --auth-user-pass username: Same as Common Name, with one exception:
3279 starting with OpenVPN 2.0.1, the username is passed to the OPEN‐
3280 VPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin in its raw form, without string
3281 remapping.
3282
3283 --auth-user-pass password: Any "printable" character except CR or LF.
3284 Printable is defined to be a character which will cause the C library
3285 isprint() function to return true.
3286
3287 --client-config-dir filename as derived from common name or username:
3288 Alphanumeric, underbar ('_'), dash ('-'), and dot ('.') except for "."
3289 or ".." as standalone strings. As of 2.0.1-rc6, the at ('@') character
3290 has been added as well for compatibility with the common name character
3291 class.
3292
3293 Environmental variable names: Alphanumeric or underbar ('_').
3294
3295 Environmental variable values: Any printable character.
3296
3297 For all cases, characters in a string which are not members of the
3298 legal character class for that string type will be remapped to underbar
3299 ('_').
3300
3301 Environmental Variables
3302 Once set, a variable is persisted indefinitely until it is reset by a
3303 new value or a restart,
3304
3305 As of OpenVPN 2.0-beta12, in server mode, environmental variables set
3306 by OpenVPN are scoped according to the client objects they are associ‐
3307 ated with, so there should not be any issues with scripts having access
3308 to stale, previously set variables which refer to different client
3309 instances.
3310
3311 bytes_received
3312 Total number of bytes received from client during VPN session.
3313 Set prior to execution of the --client-disconnect script.
3314
3315 bytes_sent
3316 Total number of bytes sent to client during VPN session. Set
3317 prior to execution of the --client-disconnect script.
3318
3319 common_name
3320 The X509 common name of an authenticated client. Set prior to
3321 execution of --client-connect, --client-disconnect, and --auth-
3322 user-pass-verify scripts.
3323
3324 config Name of first --config file. Set on program initiation and
3325 reset on SIGHUP.
3326
3327 daemon Set to "1" if the --daemon directive is specified, or "0" other‐
3328 wise. Set on program initiation and reset on SIGHUP.
3329
3330 daemon_log_redirect
3331 Set to "1" if the --log or --log-append directives are speci‐
3332 fied, or "0" otherwise. Set on program initiation and reset on
3333 SIGHUP.
3334
3335 dev The actual name of the TUN/TAP device, including a unit number
3336 if it exists. Set prior to --up or --down script execution.
3337
3338 foreign_option_{n}
3339 An option pushed via --push to a client which does not natively
3340 support it, such as --dhcp-option on a non-Windows system, will
3341 be recorded to this environmental variable sequence prior to
3342 --up script execution.
3343
3344 ifconfig_broadcast
3345 The broadcast address for the virtual ethernet segment which is
3346 derived from the --ifconfig option when --dev tap is used. Set
3347 prior to OpenVPN calling the ifconfig or netsh (windows version
3348 of ifconfig) commands which normally occurs prior to --up script
3349 execution.
3350
3351 ifconfig_local
3352 The local VPN endpoint IP address specified in the --ifconfig
3353 option (first parameter). Set prior to OpenVPN calling the
3354 ifconfig or netsh (windows version of ifconfig) commands which
3355 normally occurs prior to --up script execution.
3356
3357 ifconfig_remote
3358 The remote VPN endpoint IP address specified in the --ifconfig
3359 option (second parameter) when --dev tun is used. Set prior to
3360 OpenVPN calling the ifconfig or netsh (windows version of ifcon‐
3361 fig) commands which normally occurs prior to --up script execu‐
3362 tion.
3363
3364 ifconfig_netmask
3365 The subnet mask of the virtual ethernet segment that is speci‐
3366 fied as the second parameter to --ifconfig when --dev tap is
3367 being used. Set prior to OpenVPN calling the ifconfig or netsh
3368 (windows version of ifconfig) commands which normally occurs
3369 prior to --up script execution.
3370
3371 ifconfig_pool_local_ip
3372 The local virtual IP address for the TUN/TAP tunnel taken from
3373 an --ifconfig-push directive if specified, or otherwise from the
3374 ifconfig pool (controlled by the --ifconfig-pool config file
3375 directive). Only set for --dev tun tunnels. This option is set
3376 on the server prior to execution of the --client-connect and
3377 --client-disconnect scripts.
3378
3379 ifconfig_pool_netmask
3380 The virtual IP netmask for the TUN/TAP tunnel taken from an
3381 --ifconfig-push directive if specified, or otherwise from the
3382 ifconfig pool (controlled by the --ifconfig-pool config file
3383 directive). Only set for --dev tap tunnels. This option is set
3384 on the server prior to execution of the --client-connect and
3385 --client-disconnect scripts.
3386
3387 ifconfig_pool_remote_ip
3388 The remote virtual IP address for the TUN/TAP tunnel taken from
3389 an --ifconfig-push directive if specified, or otherwise from the
3390 ifconfig pool (controlled by the --ifconfig-pool config file
3391 directive). This option is set on the server prior to execution
3392 of the --client-connect and --client-disconnect scripts.
3393
3394 link_mtu
3395 The maximum packet size (not including the IP header) of tunnel
3396 data in UDP tunnel transport mode. Set prior to --up or --down
3397 script execution.
3398
3399 local The --local parameter. Set on program initiation and reset on
3400 SIGHUP.
3401
3402 local_port
3403 The local port number, specified by --port or --lport. Set on
3404 program initiation and reset on SIGHUP.
3405
3406 password
3407 The password provided by a connecting client. Set prior to
3408 --auth-user-pass-verify script execution only when the via-env
3409 modifier is specified, and deleted from the environment after
3410 the script returns.
3411
3412 proto The --proto parameter. Set on program initiation and reset on
3413 SIGHUP.
3414
3415 remote_{n}
3416 The --remote parameter. Set on program initiation and reset on
3417 SIGHUP.
3418
3419 remote_port_{n}
3420 The remote port number, specified by --port or --rport. Set on
3421 program initiation and reset on SIGHUP.
3422
3423 route_net_gateway
3424 The pre-existing default IP gateway in the system routing table.
3425 Set prior to --up script execution.
3426
3427 route_vpn_gateway
3428 The default gateway used by --route options, as specified in
3429 either the --route-gateway option or the second parameter to
3430 --ifconfig when --dev tun is specified. Set prior to --up
3431 script execution.
3432
3433 route_{parm}_{n}
3434 A set of variables which define each route to be added, and are
3435 set prior to --up script execution.
3436
3437 parm will be one of "network", "netmask", "gateway", or "met‐
3438 ric".
3439
3440 n is the OpenVPN route number, starting from 1.
3441
3442 If the network or gateway are resolvable DNS names, their IP
3443 address translations will be recorded rather than their names as
3444 denoted on the command line or configuration file.
3445
3446 script_context
3447 Set to "init" or "restart" prior to up/down script execution.
3448 For more information, see documentation for --up.
3449
3450 script_type
3451 One of up, down, ipchange, route-up, tls-verify, auth-user-pass-
3452 verify, client-connect, client-disconnect, or learn-address.
3453 Set prior to execution of any script.
3454
3455 signal The reason for exit or restart. Can be one of sigusr1, sighup,
3456 sigterm, sigint, inactive (controlled by --inactive option),
3457 ping-exit (controlled by --ping-exit option), ping-restart (con‐
3458 trolled by --ping-restart option), connection-reset (triggered
3459 on TCP connection reset), error, or unknown (unknown signal).
3460 This variable is set just prior to down script execution.
3461
3462 time_ascii
3463 Client connection timestamp, formatted as a human-readable time
3464 string. Set prior to execution of the --client-connect script.
3465
3466 time_duration
3467 The duration (in seconds) of the client session which is now
3468 disconnecting. Set prior to execution of the --client-discon‐
3469 nect script.
3470
3471 time_unix
3472 Client connection timestamp, formatted as a unix integer
3473 date/time value. Set prior to execution of the --client-connect
3474 script.
3475
3476 tls_id_{n}
3477 A series of certificate fields from the remote peer, where n is
3478 the verification level. Only set for TLS connections. Set
3479 prior to execution of --tls-verify script.
3480
3481 tls_serial_{n}
3482 The serial number of the certificate from the remote peer, where
3483 n is the verification level. Only set for TLS connections. Set
3484 prior to execution of --tls-verify script.
3485
3486 tun_mtu
3487 The MTU of the TUN/TAP device. Set prior to --up or --down
3488 script execution.
3489
3490 trusted_ip
3491 Actual IP address of connecting client or peer which has been
3492 authenticated. Set prior to execution of --ipchange, --client-
3493 connect, and --client-disconnect scripts.
3494
3495 trusted_port
3496 Actual port number of connecting client or peer which has been
3497 authenticated. Set prior to execution of --ipchange, --client-
3498 connect, and --client-disconnect scripts.
3499
3500 untrusted_ip
3501 Actual IP address of connecting client or peer which has not
3502 been authenticated yet. Sometimes used to nmap the connecting
3503 host in a --tls-verify script to ensure it is firewalled prop‐
3504 erly. Set prior to execution of --tls-verify and --auth-user-
3505 pass-verify scripts.
3506
3507 untrusted_port
3508 Actual port number of connecting client or peer which has not
3509 been authenticated yet. Set prior to execution of --tls-verify
3510 and --auth-user-pass-verify scripts.
3511
3512 username
3513 The username provided by a connecting client. Set prior to
3514 --auth-user-pass-verify script execution only when the via-env
3515 modifier is specified.
3516
3517 X509_{n}_{subject_field}
3518 An X509 subject field from the remote peer certificate, where n
3519 is the verification level. Only set for TLS connections. Set
3520 prior to execution of --tls-verify script. This variable is
3521 similar to tls_id_{n} except the component X509 subject fields
3522 are broken out, and no string remapping occurs on these field
3523 values (except for remapping of control characters to "_"). For
3524 example, the following variables would be set on the OpenVPN
3525 server using the sample client certificate in sample-keys
3526 (client.crt). Note that the verification level is 0 for the
3527 client certificate and 1 for the CA certificate.
3528
3529 X509_0_emailAddress=me@myhost.mydomain
3530 X509_0_CN=Test-Client
3531 X509_0_O=OpenVPN-TEST
3532 X509_0_ST=NA
3533 X509_0_C=KG
3534 X509_1_emailAddress=me@myhost.mydomain
3535 X509_1_O=OpenVPN-TEST
3536 X509_1_L=BISHKEK
3537 X509_1_ST=NA
3538 X509_1_C=KG
3539
3541 SIGHUP Cause OpenVPN to close all TUN/TAP and network connections,
3542 restart, re-read the configuration file (if any), and reopen
3543 TUN/TAP and network connections.
3544
3545 SIGUSR1
3546 Like SIGHUP, except don't re-read configuration file, and possi‐
3547 bly don't close and reopen TUN/TAP device, re-read key files,
3548 preserve local IP address/port, or preserve most recently
3549 authenticated remote IP address/port based on --persist-tun,
3550 --persist-key, --persist-local-ip, and --persist-remote-ip
3551 options respectively (see above).
3552
3553 This signal may also be internally generated by a timeout condi‐
3554 tion, governed by the --ping-restart option.
3555
3556 This signal, when combined with --persist-remote-ip, may be sent
3557 when the underlying parameters of the host's network interface
3558 change such as when the host is a DHCP client and is assigned a
3559 new IP address. See --ipchange above for more information.
3560
3561 SIGUSR2
3562 Causes OpenVPN to display its current statistics (to the syslog
3563 file if --daemon is used, or stdout otherwise).
3564
3565 SIGINT, SIGTERM
3566 Causes OpenVPN to exit gracefully.
3567
3569 If you are running Linux 2.4.7 or higher, you probably have the TUN/TAP
3570 driver already installed. If so, there are still a few things you need
3571 to do:
3572
3573 Make device: mknod /dev/net/tun c 10 200
3574
3575 Load driver: modprobe tun
3576
3577 If you have Linux 2.2 or earlier, you should obtain version 1.1 of the
3578 TUN/TAP driver from http://vtun.sourceforge.net/tun/ and follow the
3579 installation instructions.
3580
3582 Prior to running these examples, you should have OpenVPN installed on
3583 two machines with network connectivity between them. If you have not
3584 yet installed OpenVPN, consult the INSTALL file included in the OpenVPN
3585 distribution.
3586
3587 TUN/TAP Setup:
3588 If you are using Linux 2.4 or higher, make the tun device node and load
3589 the tun module:
3590
3591 mknod /dev/net/tun c 10 200
3592
3593 modprobe tun
3594
3595 If you installed from RPM, the mknod step may be omitted, because the
3596 RPM install does that for you.
3597
3598 If you have Linux 2.2, you should obtain version 1.1 of the TUN/TAP
3599 driver from http://vtun.sourceforge.net/tun/ and follow the installa‐
3600 tion instructions.
3601
3602 For other platforms, consult the INSTALL file at http://open‐
3603 vpn.net/install.html for more information.
3604
3605 Firewall Setup:
3606 If firewalls exist between the two machines, they should be set to for‐
3607 ward UDP port 1194 in both directions. If you do not have control over
3608 the firewalls between the two machines, you may still be able to use
3609 OpenVPN by adding --ping 15 to each of the openvpn commands used below
3610 in the examples (this will cause each peer to send out a UDP ping to
3611 its remote peer once every 15 seconds which will cause many stateful
3612 firewalls to forward packets in both directions without an explicit
3613 firewall rule).
3614
3615 If you are using a Linux iptables-based firewall, you may need to enter
3616 the following command to allow incoming packets on the TUN device:
3617
3618 iptables -A INPUT -i tun+ -j ACCEPT
3619
3620 See the firewalls section below for more information on configuring
3621 firewalls for use with OpenVPN.
3622
3623 VPN Address Setup:
3624 For purposes of our example, our two machines will be called may.kg and
3625 june.kg. If you are constructing a VPN over the internet, then replace
3626 may.kg and june.kg with the internet hostname or IP address that each
3627 machine will use to contact the other over the internet.
3628
3629 Now we will choose the tunnel endpoints. Tunnel endpoints are private
3630 IP addresses that only have meaning in the context of the VPN. Each
3631 machine will use the tunnel endpoint of the other machine to access it
3632 over the VPN. In our example, the tunnel endpoint for may.kg will be
3633 10.4.0.1 and for june.kg, 10.4.0.2.
3634
3635 Once the VPN is established, you have essentially created a secure
3636 alternate path between the two hosts which is addressed by using the
3637 tunnel endpoints. You can control which network traffic passes between
3638 the hosts (a) over the VPN or (b) independently of the VPN, by choosing
3639 whether to use (a) the VPN endpoint address or (b) the public internet
3640 address, to access the remote host. For example if you are on may.kg
3641 and you wish to connect to june.kg via ssh without using the VPN (since
3642 ssh has its own built-in security) you would use the command ssh
3643 june.kg. However in the same scenario, you could also use the command
3644 telnet 10.4.0.2 to create a telnet session with june.kg over the VPN,
3645 that would use the VPN to secure the session rather than ssh.
3646
3647 You can use any address you wish for the tunnel endpoints but make sure
3648 that they are private addresses (such as those that begin with 10 or
3649 192.168) and that they are not part of any existing subnet on the net‐
3650 works of either peer, unless you are bridging. If you use an address
3651 that is part of your local subnet for either of the tunnel endpoints,
3652 you will get a weird feedback loop.
3653
3654 Example 1: A simple tunnel without security
3655 On may:
3656
3657 openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2
3658 --verb 9
3659
3660 On june:
3661
3662 openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1
3663 --verb 9
3664
3665 Now verify the tunnel is working by pinging across the tunnel.
3666
3667 On may:
3668
3669 ping 10.4.0.2
3670
3671 On june:
3672
3673 ping 10.4.0.1
3674
3675 The --verb 9 option will produce verbose output, similar to the tcp‐
3676 dump(8) program. Omit the --verb 9 option to have OpenVPN run quietly.
3677
3678 Example 2: A tunnel with static-key security (i.e. using a pre-shared
3679 secret)
3680 First build a static key on may.
3681
3682 openvpn --genkey --secret key
3683
3684 This command will build a random key file called key (in ascii format).
3685 Now copy key to june over a secure medium such as by using the scp(1)
3686 program.
3687
3688 On may:
3689
3690 openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2
3691 --verb 5 --secret key
3692
3693 On june:
3694
3695 openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1
3696 --verb 5 --secret key
3697
3698 Now verify the tunnel is working by pinging across the tunnel.
3699
3700 On may:
3701
3702 ping 10.4.0.2
3703
3704 On june:
3705
3706 ping 10.4.0.1
3707
3708 Example 3: A tunnel with full TLS-based security
3709 For this test, we will designate may as the TLS client and june as the
3710 TLS server. Note that client or server designation only has meaning
3711 for the TLS subsystem. It has no bearing on OpenVPN's peer-to-peer,
3712 UDP-based communication model.
3713
3714 First, build a separate certificate/key pair for both may and june (see
3715 above where --cert is discussed for more info). Then construct Diffie
3716 Hellman parameters (see above where --dh is discussed for more info).
3717 You can also use the included test files client.crt, client.key,
3718 server.crt, server.key and ca.crt. The .crt files are certifi‐
3719 cates/public-keys, the .key files are private keys, and ca.crt is a
3720 certification authority who has signed both client.crt and server.crt.
3721 For Diffie Hellman parameters you can use the included file dh1024.pem.
3722 Note that all client, server, and certificate authority certificates
3723 and keys included in the OpenVPN distribution are totally insecure and
3724 should be used for testing only.
3725
3726 On may:
3727
3728 openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2
3729 --tls-client --ca ca.crt --cert client.crt --key client.key
3730 --reneg-sec 60 --verb 5
3731
3732 On june:
3733
3734 openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1
3735 --tls-server --dh dh1024.pem --ca ca.crt --cert server.crt --key
3736 server.key --reneg-sec 60 --verb 5
3737
3738 Now verify the tunnel is working by pinging across the tunnel.
3739
3740 On may:
3741
3742 ping 10.4.0.2
3743
3744 On june:
3745
3746 ping 10.4.0.1
3747
3748 Notice the --reneg-sec 60 option we used above. That tells OpenVPN to
3749 renegotiate the data channel keys every minute. Since we used --verb 5
3750 above, you will see status information on each new key negotiation.
3751
3752 For production operations, a key renegotiation interval of 60 seconds
3753 is probably too frequent. Omit the --reneg-sec 60 option to use Open‐
3754 VPN's default key renegotiation interval of one hour.
3755
3756 Routing:
3757 Assuming you can ping across the tunnel, the next step is to route a
3758 real subnet over the secure tunnel. Suppose that may and june have two
3759 network interfaces each, one connected to the internet, and the other
3760 to a private network. Our goal is to securely connect both private
3761 networks. We will assume that may's private subnet is 10.0.0.0/24 and
3762 june's is 10.0.1.0/24.
3763
3764 First, ensure that IP forwarding is enabled on both peers. On Linux,
3765 enable routing:
3766
3767 echo 1 > /proc/sys/net/ipv4/ip_forward
3768
3769 and enable TUN packet forwarding through the firewall:
3770
3771 iptables -A FORWARD -i tun+ -j ACCEPT
3772
3773 On may:
3774
3775 route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
3776
3777 On june:
3778
3779 route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
3780
3781 Now any machine on the 10.0.0.0/24 subnet can access any machine on the
3782 10.0.1.0/24 subnet over the secure tunnel (or vice versa).
3783
3784 In a production environment, you could put the route command(s) in a
3785 shell script and execute with the --up option.
3786
3788 OpenVPN's usage of a single UDP port makes it fairly firewall-friendly.
3789 You should add an entry to your firewall rules to allow incoming Open‐
3790 VPN packets. On Linux 2.4+:
3791
3792 iptables -A INPUT -p udp -s 1.2.3.4 --dport 1194 -j ACCEPT
3793
3794 This will allow incoming packets on UDP port 1194 (OpenVPN's default
3795 UDP port) from an OpenVPN peer at 1.2.3.4.
3796
3797 If you are using HMAC-based packet authentication (the default in any
3798 of OpenVPN's secure modes), having the firewall filter on source
3799 address can be considered optional, since HMAC packet authentication is
3800 a much more secure method of verifying the authenticity of a packet
3801 source. In that case:
3802
3803 iptables -A INPUT -p udp --dport 1194 -j ACCEPT
3804
3805 would be adequate and would not render the host inflexible with respect
3806 to its peer having a dynamic IP address.
3807
3808 OpenVPN also works well on stateful firewalls. In some cases, you may
3809 not need to add any static rules to the firewall list if you are using
3810 a stateful firewall that knows how to track UDP connections. If you
3811 specify --ping n, OpenVPN will be guaranteed to send a packet to its
3812 peer at least once every n seconds. If n is less than the stateful
3813 firewall connection timeout, you can maintain an OpenVPN connection
3814 indefinitely without explicit firewall rules.
3815
3816 You should also add firewall rules to allow incoming IP traffic on TUN
3817 or TAP devices such as:
3818
3819 iptables -A INPUT -i tun+ -j ACCEPT
3820
3821 to allow input packets from tun devices,
3822
3823 iptables -A FORWARD -i tun+ -j ACCEPT
3824
3825 to allow input packets from tun devices to be forwarded to other hosts
3826 on the local network,
3827
3828 iptables -A INPUT -i tap+ -j ACCEPT
3829
3830 to allow input packets from tap devices, and
3831
3832 iptables -A FORWARD -i tap+ -j ACCEPT
3833
3834 to allow input packets from tap devices to be forwarded to other hosts
3835 on the local network.
3836
3837 These rules are secure if you use packet authentication, since no
3838 incoming packets will arrive on a TUN or TAP virtual device unless they
3839 first pass an HMAC authentication test.
3840
3842 http://openvpn.net/faq.html
3843
3845 For a more comprehensive guide to setting up OpenVPN in a production
3846 setting, see the OpenVPN HOWTO at http://openvpn.net/howto.html
3847
3849 For a description of OpenVPN's underlying protocol, see http://open‐
3850 vpn.net/security.html
3851
3853 OpenVPN's web site is at http://openvpn.net/
3854
3855 Go here to download the latest version of OpenVPN, subscribe to the
3856 mailing lists, read the mailing list archives, or browse the SVN repos‐
3857 itory.
3858
3860 Report all bugs to the OpenVPN team <info@openvpn.net>.
3861
3863 dhcpcd(8), ifconfig(8), openssl(1), route(8), scp(1) ssh(1)
3864
3866 This product includes software developed by the OpenSSL Project (
3867 http://www.openssl.org/ )
3868
3869 For more information on the TLS protocol, see
3870 http://www.ietf.org/rfc/rfc2246.txt
3871
3872 For more information on the LZO real-time compression library see
3873 http://www.oberhumer.com/opensource/lzo/
3874
3876 Copyright (C) 2002-2009 OpenVPN Technologies, Inc. This program is free
3877 software; you can redistribute it and/or modify it under the terms of
3878 the GNU General Public License version 2 as published by the Free Soft‐
3879 ware Foundation.
3880
3882 James Yonan <jim@yonan.net>
3883
3884
3885
3886 17 November 2008 openvpn(8)