1openvpn(8)                  System Manager's Manual                 openvpn(8)
2
3
4

NAME

6       openvpn - secure IP tunnel daemon.
7

SYNOPSIS

9       openvpn [ options ... ]
10

INTRODUCTION

12       OpenVPN  is  an open source VPN daemon by James Yonan.  Because OpenVPN
13       tries to be a universal VPN tool offering a great deal of  flexibility,
14       there are a lot of options on this manual page.  If you're new to Open‐
15       VPN, you might want to skip ahead to the  examples  section  where  you
16       will  see how to construct simple VPNs on the command line without even
17       needing a configuration file.
18
19       Also note that there's more documentation and examples on  the  OpenVPN
20       web site: http://openvpn.net/
21
22       And  if you would like to see a shorter version of this manual, see the
23       openvpn usage message which can be obtained by running openvpn  without
24       any parameters.
25

DESCRIPTION

27       OpenVPN  is  a robust and highly flexible VPN daemon.  OpenVPN supports
28       SSL/TLS security,  ethernet  bridging,  TCP  or  UDP  tunnel  transport
29       through  proxies  or  NAT,  support  for dynamic IP addresses and DHCP,
30       scalability to hundreds or thousands of users, and portability to  most
31       major OS platforms.
32
33       OpenVPN  is  tightly  bound to the OpenSSL library, and derives much of
34       its crypto capabilities from it.
35
36       OpenVPN supports conventional encryption using a pre-shared secret  key
37       (Static  Key mode) or public key security (SSL/TLS mode) using client &
38       server certificates.  OpenVPN also supports non-encrypted TCP/UDP  tun‐
39       nels.
40
41       OpenVPN  is designed to work with the TUN/TAP virtual networking inter‐
42       face that exists on most platforms.
43
44       Overall, OpenVPN aims to offer many of the key features  of  IPSec  but
45       with a relatively lightweight footprint.
46

OPTIONS

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

SCRIPTING AND ENVIRONMENTAL VARIABLES

3215       OpenVPN exports a series of environmental variables for  use  by  user-
3216       defined scripts.
3217
3218   Script Order of Execution
3219       --up   Executed after TCP/UDP socket bind and TUN/TAP open.
3220
3221       --tls-verify
3222              Executed when we have a still untrusted remote peer.
3223
3224       --ipchange
3225              Executed  after  connection authentication, or remote IP address
3226              change.
3227
3228       --client-connect
3229              Executed in --mode server mode immediately after client  authen‐
3230              tication.
3231
3232       --route-up
3233              Executed  after  connection  authentication,  either immediately
3234              after, or some  number  of  seconds  after  as  defined  by  the
3235              --route-delay option.
3236
3237       --client-disconnect
3238              Executed in --mode server mode on client instance shutdown.
3239
3240       --down Executed after TCP/UDP and TUN/TAP close.
3241
3242       --learn-address
3243              Executed in --mode server mode whenever an IPv4 address/route or
3244              MAC address is added to OpenVPN's internal routing table.
3245
3246       --auth-user-pass-verify
3247              Executed in --mode server mode on new client  connections,  when
3248              the client is still untrusted.
3249
3250   String Types and Remapping
3251       In  certain  cases,  OpenVPN  will  perform  remapping of characters in
3252       strings.  Essentially, any characters  outside  the  set  of  permitted
3253       characters for each string type will be converted to underbar ('_').
3254
3255       Q: Why is string remapping necessary?
3256
3257       A:  It's  an important security feature to prevent the malicious coding
3258       of strings from  untrusted  sources  to  be  passed  as  parameters  to
3259       scripts, saved in the environment, used as a common name, translated to
3260       a filename, etc.
3261
3262       Q: Can string remapping be disabled?
3263
3264       A: Yes, by using the --no-name-remapping option, however this should be
3265       considered an advanced option.
3266
3267       Here  is a brief rundown of OpenVPN's current string types and the per‐
3268       mitted character class for each string:
3269
3270       X509 Names: Alphanumeric, underbar ('_'), dash  ('-'),  dot  ('.'),  at
3271       ('@'),  colon  (':'),  slash  ('/'),  and equal ('=').  Alphanumeric is
3272       defined as a character which will cause the C library  isalnum()  func‐
3273       tion to return true.
3274
3275       Common  Names: Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), and
3276       at ('@').
3277
3278       --auth-user-pass username: Same as Common  Name,  with  one  exception:
3279       starting  with  OpenVPN  2.0.1,  the  username  is  passed to the OPEN‐
3280       VPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin in its raw form, without string
3281       remapping.
3282
3283       --auth-user-pass  password:  Any "printable" character except CR or LF.
3284       Printable is defined to be a character which will cause the  C  library
3285       isprint() function to return true.
3286
3287       --client-config-dir  filename  as derived from common name or username:
3288       Alphanumeric, underbar ('_'), dash ('-'), and dot ('.') except for  "."
3289       or ".." as standalone strings.  As of 2.0.1-rc6, the at ('@') character
3290       has been added as well for compatibility with the common name character
3291       class.
3292
3293       Environmental variable names: Alphanumeric or underbar ('_').
3294
3295       Environmental variable values: Any printable character.
3296
3297       For  all  cases,  characters  in  a string which are not members of the
3298       legal character class for that string type will be remapped to underbar
3299       ('_').
3300
3301   Environmental Variables
3302       Once  set,  a variable is persisted indefinitely until it is reset by a
3303       new value or a restart,
3304
3305       As of OpenVPN 2.0-beta12, in server mode, environmental  variables  set
3306       by  OpenVPN are scoped according to the client objects they are associ‐
3307       ated with, so there should not be any issues with scripts having access
3308       to  stale,  previously  set  variables  which refer to different client
3309       instances.
3310
3311       bytes_received
3312              Total number of bytes received from client during  VPN  session.
3313              Set prior to execution of the --client-disconnect script.
3314
3315       bytes_sent
3316              Total  number  of  bytes sent to client during VPN session.  Set
3317              prior to execution of the --client-disconnect script.
3318
3319       common_name
3320              The X509 common name of an authenticated client.  Set  prior  to
3321              execution  of --client-connect, --client-disconnect, and --auth-
3322              user-pass-verify scripts.
3323
3324       config Name of first --config file.   Set  on  program  initiation  and
3325              reset on SIGHUP.
3326
3327       daemon Set to "1" if the --daemon directive is specified, or "0" other‐
3328              wise.  Set on program initiation and reset on SIGHUP.
3329
3330       daemon_log_redirect
3331              Set to "1" if the --log or --log-append  directives  are  speci‐
3332              fied,  or "0" otherwise.  Set on program initiation and reset on
3333              SIGHUP.
3334
3335       dev    The actual name of the TUN/TAP device, including a  unit  number
3336              if it exists.  Set prior to --up or --down script execution.
3337
3338       foreign_option_{n}
3339              An  option pushed via --push to a client which does not natively
3340              support it, such as --dhcp-option on a non-Windows system,  will
3341              be  recorded  to  this  environmental variable sequence prior to
3342              --up script execution.
3343
3344       ifconfig_broadcast
3345              The broadcast address for the virtual ethernet segment which  is
3346              derived  from the --ifconfig option when --dev tap is used.  Set
3347              prior to OpenVPN calling the ifconfig or netsh (windows  version
3348              of ifconfig) commands which normally occurs prior to --up script
3349              execution.
3350
3351       ifconfig_local
3352              The local VPN endpoint IP address specified  in  the  --ifconfig
3353              option  (first  parameter).   Set  prior  to OpenVPN calling the
3354              ifconfig or netsh (windows version of ifconfig)  commands  which
3355              normally occurs prior to --up script execution.
3356
3357       ifconfig_remote
3358              The  remote  VPN endpoint IP address specified in the --ifconfig
3359              option (second parameter) when --dev tun is used.  Set prior  to
3360              OpenVPN calling the ifconfig or netsh (windows version of ifcon‐
3361              fig) commands which normally occurs prior to --up script  execu‐
3362              tion.
3363
3364       ifconfig_netmask
3365              The  subnet  mask of the virtual ethernet segment that is speci‐
3366              fied as the second parameter to --ifconfig  when  --dev  tap  is
3367              being  used.  Set prior to OpenVPN calling the ifconfig or netsh
3368              (windows version of ifconfig)  commands  which  normally  occurs
3369              prior to --up script execution.
3370
3371       ifconfig_pool_local_ip
3372              The  local  virtual IP address for the TUN/TAP tunnel taken from
3373              an --ifconfig-push directive if specified, or otherwise from the
3374              ifconfig  pool  (controlled  by  the --ifconfig-pool config file
3375              directive).  Only set for --dev tun tunnels.  This option is set
3376              on  the  server  prior  to execution of the --client-connect and
3377              --client-disconnect scripts.
3378
3379       ifconfig_pool_netmask
3380              The virtual IP netmask for the  TUN/TAP  tunnel  taken  from  an
3381              --ifconfig-push  directive  if  specified, or otherwise from the
3382              ifconfig pool (controlled by  the  --ifconfig-pool  config  file
3383              directive).  Only set for --dev tap tunnels.  This option is set
3384              on the server prior to execution  of  the  --client-connect  and
3385              --client-disconnect scripts.
3386
3387       ifconfig_pool_remote_ip
3388              The  remote virtual IP address for the TUN/TAP tunnel taken from
3389              an --ifconfig-push directive if specified, or otherwise from the
3390              ifconfig  pool  (controlled  by  the --ifconfig-pool config file
3391              directive).  This option is set on the server prior to execution
3392              of the --client-connect and --client-disconnect scripts.
3393
3394       link_mtu
3395              The  maximum packet size (not including the IP header) of tunnel
3396              data in UDP tunnel transport mode.  Set prior to --up or  --down
3397              script execution.
3398
3399       local  The  --local  parameter.  Set on program initiation and reset on
3400              SIGHUP.
3401
3402       local_port
3403              The local port number, specified by --port or --lport.   Set  on
3404              program initiation and reset on SIGHUP.
3405
3406       password
3407              The  password  provided  by  a  connecting client.  Set prior to
3408              --auth-user-pass-verify script execution only when  the  via-env
3409              modifier  is  specified,  and deleted from the environment after
3410              the script returns.
3411
3412       proto  The --proto parameter.  Set on program initiation and  reset  on
3413              SIGHUP.
3414
3415       remote_{n}
3416              The  --remote parameter.  Set on program initiation and reset on
3417              SIGHUP.
3418
3419       remote_port_{n}
3420              The remote port number, specified by --port or --rport.  Set  on
3421              program initiation and reset on SIGHUP.
3422
3423       route_net_gateway
3424              The pre-existing default IP gateway in the system routing table.
3425              Set prior to --up script execution.
3426
3427       route_vpn_gateway
3428              The default gateway used by --route  options,  as  specified  in
3429              either  the  --route-gateway  option  or the second parameter to
3430              --ifconfig when --dev tun  is  specified.   Set  prior  to  --up
3431              script execution.
3432
3433       route_{parm}_{n}
3434              A  set of variables which define each route to be added, and are
3435              set prior to --up script execution.
3436
3437              parm will be one of "network", "netmask",  "gateway",  or  "met‐
3438              ric".
3439
3440              n is the OpenVPN route number, starting from 1.
3441
3442              If  the  network  or  gateway are resolvable DNS names, their IP
3443              address translations will be recorded rather than their names as
3444              denoted on the command line or configuration file.
3445
3446       script_context
3447              Set  to  "init"  or "restart" prior to up/down script execution.
3448              For more information, see documentation for --up.
3449
3450       script_type
3451              One of up, down, ipchange, route-up, tls-verify, auth-user-pass-
3452              verify,  client-connect,  client-disconnect,  or  learn-address.
3453              Set prior to execution of any script.
3454
3455       signal The reason for exit or restart.  Can be one of sigusr1,  sighup,
3456              sigterm,  sigint,  inactive  (controlled  by --inactive option),
3457              ping-exit (controlled by --ping-exit option), ping-restart (con‐
3458              trolled  by  --ping-restart option), connection-reset (triggered
3459              on TCP connection reset), error, or  unknown  (unknown  signal).
3460              This variable is set just prior to down script execution.
3461
3462       time_ascii
3463              Client  connection timestamp, formatted as a human-readable time
3464              string.  Set prior to execution of the --client-connect script.
3465
3466       time_duration
3467              The duration (in seconds) of the client  session  which  is  now
3468              disconnecting.   Set  prior to execution of the --client-discon‐
3469              nect script.
3470
3471       time_unix
3472              Client  connection  timestamp,  formatted  as  a  unix   integer
3473              date/time value.  Set prior to execution of the --client-connect
3474              script.
3475
3476       tls_id_{n}
3477              A series of certificate fields from the remote peer, where n  is
3478              the  verification  level.   Only  set  for TLS connections.  Set
3479              prior to execution of --tls-verify script.
3480
3481       tls_serial_{n}
3482              The serial number of the certificate from the remote peer, where
3483              n is the verification level.  Only set for TLS connections.  Set
3484              prior to execution of --tls-verify script.
3485
3486       tun_mtu
3487              The MTU of the TUN/TAP device.  Set  prior  to  --up  or  --down
3488              script execution.
3489
3490       trusted_ip
3491              Actual  IP  address  of connecting client or peer which has been
3492              authenticated.  Set prior to execution of --ipchange,  --client-
3493              connect, and --client-disconnect scripts.
3494
3495       trusted_port
3496              Actual  port  number of connecting client or peer which has been
3497              authenticated.  Set prior to execution of --ipchange,  --client-
3498              connect, and --client-disconnect scripts.
3499
3500       untrusted_ip
3501              Actual  IP  address  of  connecting client or peer which has not
3502              been authenticated yet.  Sometimes used to nmap  the  connecting
3503              host  in  a --tls-verify script to ensure it is firewalled prop‐
3504              erly.  Set prior to execution of --tls-verify  and  --auth-user-
3505              pass-verify scripts.
3506
3507       untrusted_port
3508              Actual  port  number  of connecting client or peer which has not
3509              been authenticated yet.  Set prior to execution of  --tls-verify
3510              and --auth-user-pass-verify scripts.
3511
3512       username
3513              The  username  provided  by  a  connecting client.  Set prior to
3514              --auth-user-pass-verify script execution only when  the  via-env
3515              modifier is specified.
3516
3517       X509_{n}_{subject_field}
3518              An  X509 subject field from the remote peer certificate, where n
3519              is the verification level.  Only set for TLS  connections.   Set
3520              prior  to  execution  of  --tls-verify script.  This variable is
3521              similar to tls_id_{n} except the component X509  subject  fields
3522              are  broken  out,  and no string remapping occurs on these field
3523              values (except for remapping of control characters to "_").  For
3524              example,  the  following  variables  would be set on the OpenVPN
3525              server  using  the  sample  client  certificate  in  sample-keys
3526              (client.crt).   Note  that  the  verification level is 0 for the
3527              client certificate and 1 for the CA certificate.
3528
3529                  X509_0_emailAddress=me@myhost.mydomain
3530                  X509_0_CN=Test-Client
3531                  X509_0_O=OpenVPN-TEST
3532                  X509_0_ST=NA
3533                  X509_0_C=KG
3534                  X509_1_emailAddress=me@myhost.mydomain
3535                  X509_1_O=OpenVPN-TEST
3536                  X509_1_L=BISHKEK
3537                  X509_1_ST=NA
3538                  X509_1_C=KG
3539

SIGNALS

3541       SIGHUP Cause OpenVPN to close  all  TUN/TAP  and  network  connections,
3542              restart,  re-read  the  configuration  file (if any), and reopen
3543              TUN/TAP and network connections.
3544
3545       SIGUSR1
3546              Like SIGHUP, except don't re-read configuration file, and possi‐
3547              bly  don't  close  and reopen TUN/TAP device, re-read key files,
3548              preserve  local  IP  address/port,  or  preserve  most  recently
3549              authenticated  remote  IP  address/port  based on --persist-tun,
3550              --persist-key,   --persist-local-ip,   and   --persist-remote-ip
3551              options respectively (see above).
3552
3553              This signal may also be internally generated by a timeout condi‐
3554              tion, governed by the --ping-restart option.
3555
3556              This signal, when combined with --persist-remote-ip, may be sent
3557              when  the  underlying parameters of the host's network interface
3558              change such as when the host is a DHCP client and is assigned  a
3559              new IP address.  See --ipchange above for more information.
3560
3561       SIGUSR2
3562              Causes  OpenVPN to display its current statistics (to the syslog
3563              file if --daemon is used, or stdout otherwise).
3564
3565       SIGINT, SIGTERM
3566              Causes OpenVPN to exit gracefully.
3567

TUN/TAP DRIVER SETUP

3569       If you are running Linux 2.4.7 or higher, you probably have the TUN/TAP
3570       driver already installed.  If so, there are still a few things you need
3571       to do:
3572
3573       Make device: mknod /dev/net/tun c 10 200
3574
3575       Load driver: modprobe tun
3576
3577       If you have Linux 2.2 or earlier, you should obtain version 1.1 of  the
3578       TUN/TAP  driver  from  http://vtun.sourceforge.net/tun/  and follow the
3579       installation instructions.
3580

EXAMPLES

3582       Prior to running these examples, you should have OpenVPN  installed  on
3583       two  machines  with network connectivity between them.  If you have not
3584       yet installed OpenVPN, consult the INSTALL file included in the OpenVPN
3585       distribution.
3586
3587   TUN/TAP Setup:
3588       If you are using Linux 2.4 or higher, make the tun device node and load
3589       the tun module:
3590
3591              mknod /dev/net/tun c 10 200
3592
3593              modprobe tun
3594
3595       If you installed from RPM, the mknod step may be omitted,  because  the
3596       RPM install does that for you.
3597
3598       If  you  have  Linux  2.2, you should obtain version 1.1 of the TUN/TAP
3599       driver from http://vtun.sourceforge.net/tun/ and follow  the  installa‐
3600       tion instructions.
3601
3602       For   other   platforms,  consult  the  INSTALL  file  at  http://open
3603       vpn.net/install.html for more information.
3604
3605   Firewall Setup:
3606       If firewalls exist between the two machines, they should be set to for‐
3607       ward UDP port 1194 in both directions.  If you do not have control over
3608       the firewalls between the two machines, you may still be  able  to  use
3609       OpenVPN  by adding --ping 15 to each of the openvpn commands used below
3610       in the examples (this will cause each peer to send out a  UDP  ping  to
3611       its  remote  peer  once every 15 seconds which will cause many stateful
3612       firewalls to forward packets in both  directions  without  an  explicit
3613       firewall rule).
3614
3615       If you are using a Linux iptables-based firewall, you may need to enter
3616       the following command to allow incoming packets on the TUN device:
3617
3618              iptables -A INPUT -i tun+ -j ACCEPT
3619
3620       See the firewalls section below for  more  information  on  configuring
3621       firewalls for use with OpenVPN.
3622
3623   VPN Address Setup:
3624       For purposes of our example, our two machines will be called may.kg and
3625       june.kg.  If you are constructing a VPN over the internet, then replace
3626       may.kg  and  june.kg with the internet hostname or IP address that each
3627       machine will use to contact the other over the internet.
3628
3629       Now we will choose the tunnel endpoints.  Tunnel endpoints are  private
3630       IP  addresses  that  only have meaning in the context of the VPN.  Each
3631       machine will use the tunnel endpoint of the other machine to access  it
3632       over  the  VPN.  In our example, the tunnel endpoint for may.kg will be
3633       10.4.0.1 and for june.kg, 10.4.0.2.
3634
3635       Once the VPN is established, you  have  essentially  created  a  secure
3636       alternate  path  between  the two hosts which is addressed by using the
3637       tunnel endpoints.  You can control which network traffic passes between
3638       the hosts (a) over the VPN or (b) independently of the VPN, by choosing
3639       whether to use (a) the VPN endpoint address or (b) the public  internet
3640       address,  to  access  the remote host. For example if you are on may.kg
3641       and you wish to connect to june.kg via ssh without using the VPN (since
3642       ssh  has  its  own  built-in  security)  you  would use the command ssh
3643       june.kg.  However in the same scenario, you could also use the  command
3644       telnet  10.4.0.2  to create a telnet session with june.kg over the VPN,
3645       that would use the VPN to secure the session rather than ssh.
3646
3647       You can use any address you wish for the tunnel endpoints but make sure
3648       that  they  are  private addresses (such as those that begin with 10 or
3649       192.168) and that they are not part of any existing subnet on the  net‐
3650       works  of  either peer, unless you are bridging.  If you use an address
3651       that is part of your local subnet for either of the  tunnel  endpoints,
3652       you will get a weird feedback loop.
3653
3654   Example 1: A simple tunnel without security
3655       On may:
3656
3657              openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2
3658              --verb 9
3659
3660       On june:
3661
3662              openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2  10.4.0.1
3663              --verb 9
3664
3665       Now verify the tunnel is working by pinging across the tunnel.
3666
3667       On may:
3668
3669              ping 10.4.0.2
3670
3671       On june:
3672
3673              ping 10.4.0.1
3674
3675       The  --verb  9  option will produce verbose output, similar to the tcp‐
3676       dump(8) program.  Omit the --verb 9 option to have OpenVPN run quietly.
3677
3678   Example 2: A tunnel with  static-key  security  (i.e.  using  a  pre-shared
3679       secret)
3680       First build a static key on may.
3681
3682              openvpn --genkey --secret key
3683
3684       This command will build a random key file called key (in ascii format).
3685       Now copy key to june over a secure medium such as by using  the  scp(1)
3686       program.
3687
3688       On may:
3689
3690              openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2
3691              --verb 5 --secret key
3692
3693       On june:
3694
3695              openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2  10.4.0.1
3696              --verb 5 --secret key
3697
3698       Now verify the tunnel is working by pinging across the tunnel.
3699
3700       On may:
3701
3702              ping 10.4.0.2
3703
3704       On june:
3705
3706              ping 10.4.0.1
3707
3708   Example 3: A tunnel with full TLS-based security
3709       For  this test, we will designate may as the TLS client and june as the
3710       TLS server.  Note that client or server designation  only  has  meaning
3711       for  the  TLS  subsystem.  It has no bearing on OpenVPN's peer-to-peer,
3712       UDP-based communication model.
3713
3714       First, build a separate certificate/key pair for both may and june (see
3715       above  where --cert is discussed for more info).  Then construct Diffie
3716       Hellman parameters (see above where --dh is discussed for  more  info).
3717       You  can  also  use  the  included  test  files client.crt, client.key,
3718       server.crt,  server.key  and  ca.crt.   The  .crt  files  are  certifi‐
3719       cates/public-keys,  the  .key  files  are private keys, and ca.crt is a
3720       certification authority who has signed both client.crt and  server.crt.
3721       For Diffie Hellman parameters you can use the included file dh1024.pem.
3722       Note that all client, server, and  certificate  authority  certificates
3723       and  keys included in the OpenVPN distribution are totally insecure and
3724       should be used for testing only.
3725
3726       On may:
3727
3728              openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2
3729              --tls-client  --ca  ca.crt  --cert  client.crt  --key client.key
3730              --reneg-sec 60 --verb 5
3731
3732       On june:
3733
3734              openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2  10.4.0.1
3735              --tls-server --dh dh1024.pem --ca ca.crt --cert server.crt --key
3736              server.key --reneg-sec 60 --verb 5
3737
3738       Now verify the tunnel is working by pinging across the tunnel.
3739
3740       On may:
3741
3742              ping 10.4.0.2
3743
3744       On june:
3745
3746              ping 10.4.0.1
3747
3748       Notice the --reneg-sec 60 option we used above.  That tells OpenVPN  to
3749       renegotiate the data channel keys every minute.  Since we used --verb 5
3750       above, you will see status information on each new key negotiation.
3751
3752       For production operations, a key renegotiation interval of  60  seconds
3753       is  probably too frequent.  Omit the --reneg-sec 60 option to use Open‐
3754       VPN's default key renegotiation interval of one hour.
3755
3756   Routing:
3757       Assuming you can ping across the tunnel, the next step is  to  route  a
3758       real subnet over the secure tunnel.  Suppose that may and june have two
3759       network interfaces each, one connected to the internet, and  the  other
3760       to  a  private  network.   Our goal is to securely connect both private
3761       networks.  We will assume that may's private subnet is 10.0.0.0/24  and
3762       june's is 10.0.1.0/24.
3763
3764       First,  ensure  that IP forwarding is enabled on both peers.  On Linux,
3765       enable routing:
3766
3767              echo 1 > /proc/sys/net/ipv4/ip_forward
3768
3769       and enable TUN packet forwarding through the firewall:
3770
3771              iptables -A FORWARD -i tun+ -j ACCEPT
3772
3773       On may:
3774
3775              route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
3776
3777       On june:
3778
3779              route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
3780
3781       Now any machine on the 10.0.0.0/24 subnet can access any machine on the
3782       10.0.1.0/24 subnet over the secure tunnel (or vice versa).
3783
3784       In  a  production  environment, you could put the route command(s) in a
3785       shell script and execute with the --up option.
3786

FIREWALLS

3788       OpenVPN's usage of a single UDP port makes it fairly firewall-friendly.
3789       You  should add an entry to your firewall rules to allow incoming Open‐
3790       VPN packets.  On Linux 2.4+:
3791
3792              iptables -A INPUT -p udp -s 1.2.3.4 --dport 1194 -j ACCEPT
3793
3794       This will allow incoming packets on UDP port  1194  (OpenVPN's  default
3795       UDP port) from an OpenVPN peer at 1.2.3.4.
3796
3797       If  you  are using HMAC-based packet authentication (the default in any
3798       of OpenVPN's secure  modes),  having  the  firewall  filter  on  source
3799       address can be considered optional, since HMAC packet authentication is
3800       a much more secure method of verifying the  authenticity  of  a  packet
3801       source.  In that case:
3802
3803              iptables -A INPUT -p udp --dport 1194 -j ACCEPT
3804
3805       would be adequate and would not render the host inflexible with respect
3806       to its peer having a dynamic IP address.
3807
3808       OpenVPN also works well on stateful firewalls.  In some cases, you  may
3809       not  need to add any static rules to the firewall list if you are using
3810       a stateful firewall that knows how to track UDP  connections.   If  you
3811       specify  --ping  n,  OpenVPN will be guaranteed to send a packet to its
3812       peer at least once every n seconds.  If n is  less  than  the  stateful
3813       firewall  connection  timeout,  you  can maintain an OpenVPN connection
3814       indefinitely without explicit firewall rules.
3815
3816       You should also add firewall rules to allow incoming IP traffic on  TUN
3817       or TAP devices such as:
3818
3819              iptables -A INPUT -i tun+ -j ACCEPT
3820
3821       to allow input packets from tun devices,
3822
3823              iptables -A FORWARD -i tun+ -j ACCEPT
3824
3825       to  allow input packets from tun devices to be forwarded to other hosts
3826       on the local network,
3827
3828              iptables -A INPUT -i tap+ -j ACCEPT
3829
3830       to allow input packets from tap devices, and
3831
3832              iptables -A FORWARD -i tap+ -j ACCEPT
3833
3834       to allow input packets from tap devices to be forwarded to other  hosts
3835       on the local network.
3836
3837       These  rules  are  secure  if  you  use packet authentication, since no
3838       incoming packets will arrive on a TUN or TAP virtual device unless they
3839       first pass an HMAC authentication test.
3840

FAQ

3842       http://openvpn.net/faq.html
3843

HOWTO

3845       For  a  more  comprehensive guide to setting up OpenVPN in a production
3846       setting, see the OpenVPN HOWTO at http://openvpn.net/howto.html
3847

PROTOCOL

3849       For a description of OpenVPN's underlying  protocol,  see  http://open
3850       vpn.net/security.html
3851

WEB

3853       OpenVPN's web site is at http://openvpn.net/
3854
3855       Go  here  to  download  the latest version of OpenVPN, subscribe to the
3856       mailing lists, read the mailing list archives, or browse the SVN repos‐
3857       itory.
3858

BUGS

3860       Report all bugs to the OpenVPN team <info@openvpn.net>.
3861

SEE ALSO

3863       dhcpcd(8), ifconfig(8), openssl(1), route(8), scp(1) ssh(1)
3864

NOTES

3866       This  product  includes  software  developed  by  the OpenSSL Project (
3867       http://www.openssl.org/ )
3868
3869       For    more    information     on     the     TLS     protocol,     see
3870       http://www.ietf.org/rfc/rfc2246.txt
3871
3872       For  more  information  on  the  LZO  real-time compression library see
3873       http://www.oberhumer.com/opensource/lzo/
3874
3876       Copyright (C) 2002-2009 OpenVPN Technologies, Inc. This program is free
3877       software;  you  can redistribute it and/or modify it under the terms of
3878       the GNU General Public License version 2 as published by the Free Soft‐
3879       ware Foundation.
3880

AUTHORS

3882       James Yonan <jim@yonan.net>
3883
3884
3885
3886                               17 November 2008                     openvpn(8)
Impressum