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