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

NAME

6       openvpn - Secure IP tunnel daemon
7

SYNOPSIS

9       openvpn [ options ... ]
10       openvpn  --help
11
12

INTRODUCTION

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

DESCRIPTION

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

OPTIONS

50       OpenVPN allows any option to be placed either on the command line or in
51       a configuration file. Though all command line options are preceded by a
52       double-leading-dash  ("--"),  this prefix can be removed when an option
53       is placed in a configuration file.
54
55   Generic Options
56       This section covers generic options which are accessible regardless  of
57       which mode OpenVPN is configured as.
58
59       --help Show options.
60
61       --auth-nocache
62              Don't  cache --askpass or --auth-user-pass username/passwords in
63              virtual memory.
64
65              If specified, this directive will cause OpenVPN  to  immediately
66              forget  username/password  inputs  after they are used. As a re‐
67              sult, when OpenVPN needs a username/password, it will prompt for
68              input  from  stdin, which may be multiple times during the dura‐
69              tion of an OpenVPN session.
70
71              When using --auth-nocache in combination  with  a  user/password
72              file  and  --chroot  or  --daemon,  make sure to use an absolute
73              path.
74
75              This directive does not affect the  --http-proxy  username/pass‐
76              word.  It is always cached.
77
78       --cd dir
79              Change  directory to dir prior to reading any files such as con‐
80              figuration files, key files, scripts, etc. dir should be an  ab‐
81              solute  path,  with a leading "/", and without any references to
82              the current directory such as . or ...
83
84              This option is useful when you are running OpenVPN  in  --daemon
85              mode,  and  you  want to consolidate all of your OpenVPN control
86              files in one location.
87
88       --chroot dir
89              Chroot to dir after initialization. --chroot  essentially  rede‐
90              fines  dir  as  being  the top level directory tree (/). OpenVPN
91              will therefore be unable to access any files outside this  tree.
92              This can be desirable from a security standpoint.
93
94              Since  the  chroot  operation is delayed until after initializa‐
95              tion, most OpenVPN options that reference files will operate  in
96              a pre-chroot context.
97
98              In  many  cases,  the dir parameter can point to an empty direc‐
99              tory, however complications can result when scripts or  restarts
100              are executed after the chroot operation.
101
102              Note:  The  SSL  library  will  probably need /dev/urandom to be
103              available inside the chroot directory dir. This is  because  SSL
104              libraries occasionally need to collect fresh random. Newer linux
105              kernels and some BSDs implement a  getrandom()  or  getentropy()
106              syscall that removes the need for /dev/urandom to be available.
107
108       --config file
109              Load  additional config options from file where each line corre‐
110              sponds to one command line option, but with the leading '--' re‐
111              moved.
112
113              If  --config file is the only option to the openvpn command, the
114              --config can be removed, and the command can be given as openvpn
115              file
116
117              Note  that  configuration  files  can  be nested to a reasonable
118              depth.
119
120              Double quotation or single quotation characters ("", '') can  be
121              used to enclose single parameters containing whitespace, and "#"
122              or ";" characters in the first column can be used to denote com‐
123              ments.
124
125              Note  that OpenVPN 2.0 and higher performs backslash-based shell
126              escaping for characters not in single quotations, so the follow‐
127              ing mappings should be observed:
128
129                 \\       Maps to a single backslash character (\).
130                 \"       Pass a literal doublequote character ("), don't
131                          interpret it as enclosing a parameter.
132                 \[SPACE] Pass a literal space or tab character, don't
133                          interpret it as a parameter delimiter.
134
135              For  example  on  Windows,  use  double backslashes to represent
136              pathnames:
137
138                 secret "c:\\OpenVPN\\secret.key"
139
140              For     examples      of      configuration      files,      see
141              https://openvpn.net/community-resources/how-to/
142
143              Here is an example configuration file:
144
145                 #
146                 # Sample OpenVPN configuration file for
147                 # using a pre-shared static key.
148                 #
149                 # '#' or ';' may be used to delimit comments.
150
151                 # Use a dynamic tun device.
152                 dev tun
153
154                 # Our remote peer
155                 remote mypeer.mydomain
156
157                 # 10.1.0.1 is our local VPN endpoint
158                 # 10.1.0.2 is our remote VPN endpoint
159                 ifconfig 10.1.0.1 10.1.0.2
160
161                 # Our pre-shared static key
162                 secret static.key
163
164       --daemon progname
165              Become  a  daemon  after  all  initialization functions are com‐
166              pleted. This option will cause all message and error  output  to
167              be  sent  to the syslog file (such as /var/log/messages), except
168              for the output of scripts and ifconfig commands, which  will  go
169              to /dev/null unless otherwise redirected. The syslog redirection
170              occurs immediately at the point that --daemon is parsed  on  the
171              command  line  even though the daemonization point occurs later.
172              If one of the --log options is present, it will supersede syslog
173              redirection.
174
175              The optional progname parameter will cause OpenVPN to report its
176              program name to the system logger as progname. This can be  use‐
177              ful in linking OpenVPN messages in the syslog file with specific
178              tunnels. When unspecified, progname defaults to "openvpn".
179
180              When OpenVPN is run with the --daemon option, it will try to de‐
181              lay daemonization until the majority of initialization functions
182              which are capable of generating fatal errors are complete.  This
183              means  that initialization scripts can test the return status of
184              the openvpn command for a fairly reliable indication of  whether
185              the  command  has  correctly  initialized and entered the packet
186              forwarding event loop.
187
188              In OpenVPN, the vast majority of errors which occur  after  ini‐
189              tialization are non-fatal.
190
191              Note:  as  soon  as  OpenVPN  has daemonized, it can not ask for
192              usernames, passwords, or key pass phrases anymore. This has cer‐
193              tain  consequences,  namely that using a password-protected pri‐
194              vate key will fail unless the --askpass option is used  to  tell
195              OpenVPN  to  ask for the pass phrase (this requirement is new in
196              v2.3.7, and is a consequence of calling daemon() before initial‐
197              izing the crypto layer).
198
199              Further,  using --daemon together with --auth-user-pass (entered
200              on console) and --auth-nocache will fail as soon as key  renego‐
201              tiation (and reauthentication) occurs.
202
203       --disable-occ
204              Don't output a warning message if option inconsistencies are de‐
205              tected between peers. An  example  of  an  option  inconsistency
206              would be where one peer uses --dev tun while the other peer uses
207              --dev tap.
208
209              Use of this option is discouraged, but is provided as  a  tempo‐
210              rary  fix  in  situations where a recent version of OpenVPN must
211              connect to an old version.
212
213       --engine engine-name
214              Enable OpenSSL hardware-based crypto engine functionality.
215
216              If engine-name is specified, use a specific crypto  engine.  Use
217              the  --show-engines standalone option to list the crypto engines
218              which are supported by OpenSSL.
219
220       --fast-io
221              (Experimental) Optimize TUN/TAP/UDP I/O  writes  by  avoiding  a
222              call to poll/epoll/select prior to the write operation. The pur‐
223              pose of such a call would normally be to block until the  device
224              or  socket is ready to accept the write. Such blocking is unnec‐
225              essary on some platforms which don't support write  blocking  on
226              UDP  sockets or TUN/TAP devices. In such cases, one can optimize
227              the event loop by avoiding the poll/epoll/select call, improving
228              CPU efficiency by 5% to 10%.
229
230              This  option  can  only  be  used  on  non-Windows systems, when
231              --proto udp is specified, and when --shaper is NOT specified.
232
233       --group group
234              Similar to the --user option, this option changes the  group  ID
235              of the OpenVPN process to group after initialization.
236
237       --ignore-unknown-option args
238              Valid syntax:
239
240                 ignore-unknown-options opt1 opt2 opt3 ... optN
241
242              When one of options opt1 ... optN is encountered in the configu‐
243              ration file the configuration file parsing does not fail if this
244              OpenVPN  version  does  not  support  the option. Multiple --ig‐
245              nore-unknown-option options can be given  to  support  a  larger
246              number of options to ignore.
247
248              This option should be used with caution, as there are good secu‐
249              rity reasons for having OpenVPN fail if it detects problems in a
250              config  file.   Having  said  that,  there are valid reasons for
251              wanting new software features to gracefully degrade when encoun‐
252              tered by older software versions.
253
254              --ignore-unknown-option is available since OpenVPN 2.3.3.
255
256       --iproute cmd
257              Set  alternate  command  to  execute instead of default iproute2
258              command.  May be used in order to execute  OpenVPN  in  unprivi‐
259              leged environment.
260
261       --keying-material-exporter args
262              Save  Exported  Keying  Material [RFC5705] of len bytes (must be
263              between 16 and 4095  bytes)  using  label  in  environment  (ex‐
264              ported_keying_material)    for   use   by   plugins   in   OPEN‐
265              VPN_PLUGIN_TLS_FINAL callback.
266
267              Valid syntax:
268
269                 keying-material-exporter label len
270
271              Note that exporter labels have the potential to collide with ex‐
272              isting  PRF  labels. In order to prevent this, labels MUST begin
273              with EXPORTER.
274
275       --mlock
276              Disable paging by calling the POSIX mlockall function.  Requires
277              that OpenVPN be initially run as root (though OpenVPN can subse‐
278              quently downgrade its UID using the --user option).
279
280              Using this option ensures that key material and tunnel data  are
281              never  written  to  disk due to virtual memory paging operations
282              which occur under most modern operating systems. It ensures that
283              even  if  an attacker was able to crack the box running OpenVPN,
284              he would not be able to scan the system  swap  file  to  recover
285              previously  used  ephemeral keys, which are used for a period of
286              time governed by the --reneg options (see below), then are  dis‐
287              carded.
288
289              The  downside of using --mlock is that it will reduce the amount
290              of physical memory available to other applications.
291
292              The limit on how much memory can be locked and how that limit is
293              enforced  are  OS-dependent.  On Linux the default limit that an
294              unprivileged process may lock (RLIMIT_MEMLOCK) is  low,  and  if
295              privileges  are  dropped  later,  future memory allocations will
296              very likely fail. The limit can be  increased  using  ulimit  or
297              systemd directives depending on how OpenVPN is started.
298
299       --nice n
300              Change  process  priority after initialization (n greater than 0
301              is lower priority, n less than zero is higher priority).
302
303       --persist-key
304              Don't re-read key files across SIGUSR1 or --ping-restart.
305
306              This option can be combined with --user nobody to allow restarts
307              triggered by the SIGUSR1 signal. Normally if you drop root priv‐
308              ileges in OpenVPN, the daemon cannot be restarted since it  will
309              now be unable to re-read protected key files.
310
311              This option solves the problem by persisting keys across SIGUSR1
312              resets, so they don't need to be re-read.
313
314       --providers providers
315              Load the list of (OpenSSL) providers. This is mainly useful  for
316              using  an external provider for key management like tpm2-openssl
317              or to load the legacy provider with
318
319                 --providers legacy default
320
321              Behaviour of changing this option between SIGHUP  might  not  be
322              well  behaving.   If  you need to change/add/remove this option,
323              fully restart OpenVPN.
324
325       --remap-usr1 signal
326              Control whether internally or externally generated SIGUSR1  sig‐
327              nals  are  remapped to SIGHUP (restart without persisting state)
328              or SIGTERM (exit).
329
330              signal can be set to SIGHUP or SIGTERM. By default, no remapping
331              occurs.
332
333       --script-security level
334              This  directive offers policy-level control over OpenVPN's usage
335              of external programs and scripts. Lower level  values  are  more
336              restrictive,  higher  values  are  more permissive. Settings for
337              level:
338
339              0      Strictly no calling of external programs.
340
341              1      (Default) Only call built-in executables such  as  ifcon‐
342                     fig, ip, route, or netsh.
343
344              2      Allow  calling  of  built-in executables and user-defined
345                     scripts.
346
347              3      Allow passwords to be passed to scripts via environmental
348                     variables (potentially unsafe).
349
350              OpenVPN  releases before v2.3 also supported a method flag which
351              indicated how OpenVPN should call external commands and scripts.
352              This  could  be either execve or system. As of OpenVPN 2.3, this
353              flag is no longer accepted. In most *nix  environments  the  ex‐
354              ecve() approach has been used without any issues.
355
356              Some  directives  such as --up allow options to be passed to the
357              external script. In these cases make sure the script  name  does
358              not  contain  any  spaces or the configuration parser will choke
359              because it can't determine where the script name ends and script
360              options start.
361
362              To run scripts in Windows in earlier OpenVPN versions you needed
363              to either add a full path to the script  interpreter  which  can
364              parse the script or use the system flag to run these scripts. As
365              of OpenVPN 2.3 it is now a strict requirement to have full  path
366              to  the  script  interpreter when running non-executables files.
367              This is not needed for executable files,  such  as  .exe,  .com,
368              .bat  or  .cmd  files.  For  example, if you have a Visual Basic
369              script, you must use this syntax now:
370
371                 --up 'C:\\Windows\\System32\\wscript.exe C:\\Program\ Files\\OpenVPN\\config\\my-up-script.vbs'
372
373              Please note the single quote marks and the escaping of the back‐
374              slashes (\) and the space character.
375
376              The reason the support for the system flag was removed is due to
377              the security implications with shell expansions  when  executing
378              scripts via the system() call.
379
380       --setcon context
381              Apply  SELinux  context  after  initialization. This essentially
382              provides the ability to restrict OpenVPN's rights to  only  net‐
383              work  I/O  operations, thanks to SELinux. This goes further than
384              --user and --chroot in that those two, while being  great  secu‐
385              rity  features,  unfortunately  do not protect against privilege
386              escalation by exploitation of a vulnerable system call. You  can
387              of  course  combine all three, but please note that since setcon
388              requires access to /proc you will have to provide it inside  the
389              chroot directory (e.g. with mount --bind).
390
391              Since  the  setcon  operation is delayed until after initializa‐
392              tion, OpenVPN can be restricted to just  network-related  system
393              calls,  whereas  by applying the context before startup (such as
394              the OpenVPN one provided in the SELinux Reference Policies)  you
395              will  have to allow many things required only during initializa‐
396              tion.
397
398              Like with chroot,  complications  can  result  when  scripts  or
399              restarts  are  executed after the setcon operation, which is why
400              you should really consider using the  --persist-key  and  --per‐
401              sist-tun options.
402
403       --status args
404              Write operational status to file every n seconds.
405
406              Valid syntaxes:
407
408                 status file
409                 status file n
410
411              Status  can  also  be written to the syslog by sending a SIGUSR2
412              signal.
413
414              With multi-client capability enabled on  a  server,  the  status
415              file  includes a list of clients and a routing table. The output
416              format can be controlled by the --status-version option in  that
417              case.
418
419              For clients or instances running in point-to-point mode, it will
420              contain the traffic statistics.
421
422       --status-version n
423              Set the status file format version number to n.
424
425              This only affects the status file on servers  with  multi-client
426              capability enabled.  Valid status version values:
427
428              1      Traditional  format  (default).  The client list contains
429                     the following fields comma-separated: Common  Name,  Real
430                     Address, Bytes Received, Bytes Sent, Connected Since.
431
432              2      A  more reliable format for external processing. Compared
433                     to version 1, the client list  contains  some  additional
434                     fields:  Virtual Address, Virtual IPv6 Address, Username,
435                     Client ID, Peer ID, Data Channel Cipher. Future  versions
436                     may extend the number of fields.
437
438              3      Identical to 2, but fields are tab-separated.
439
440       --test-crypto
441              Do a self-test of OpenVPN's crypto options by encrypting and de‐
442              crypting test packets using the data channel encryption  options
443              specified  above.   This option does not require a peer to func‐
444              tion, and therefore can be specified without --dev or --remote.
445
446              The typical usage of --test-crypto would be something like this:
447
448                 openvpn --test-crypto --secret key
449
450              or
451
452                 openvpn --test-crypto --secret key --verb 9
453
454              This option is very useful to test OpenVPN  after  it  has  been
455              ported  to  a  new  platform, or to isolate problems in the com‐
456              piler, OpenSSL crypto library, or OpenVPN's crypto  code.  Since
457              it is a self-test mode, problems with encryption and authentica‐
458              tion can be debugged independently of network and tunnel issues.
459
460       --tmp-dir dir
461              Specify a directory dir for temporary files. This directory will
462              be used by openvpn processes and script to communicate temporary
463              data with openvpn main process. Note that the directory must  be
464              writable  by  the OpenVPN process after it has dropped it's root
465              privileges.
466
467              This directory will be used by in the following cases:
468
469--client-connect  scripts  and   OPENVPN_PLUGIN_CLIENT_CONNECT
470                plug-in  hook to dynamically generate client-specific configu‐
471                ration client_connect_config_file and  return  success/failure
472                via  client_connect_deferred_file  when  using deferred client
473                connect method
474
475OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY  plug-in  hooks   returns
476                success/failure via auth_control_file when using deferred auth
477                method
478
479OPENVPN_PLUGIN_ENABLE_PF plugin hook to pass  filtering  rules
480                via pf_file
481
482       --use-prediction-resistance
483              Enable prediction resistance on mbed TLS's RNG.
484
485              Enabling  prediction resistance causes the RNG to reseed in each
486              call for random. Reseeding this often can  quickly  deplete  the
487              kernel entropy pool.
488
489              If  you  need this option, please consider running a daemon that
490              adds entropy to the kernel pool.
491
492       --user user
493              Change the user ID of the OpenVPN process to user after initial‐
494              ization, dropping privileges in the process. This option is use‐
495              ful to protect the system in the event that some  hostile  party
496              was able to gain control of an OpenVPN session. Though OpenVPN's
497              security features make this unlikely, it is provided as a second
498              line of defense.
499
500              By  setting  user  to nobody or somebody similarly unprivileged,
501              the hostile party would be limited in  what  damage  they  could
502              cause.  Of  course once you take away privileges, you cannot re‐
503              turn them to an OpenVPN session. This means, for  example,  that
504              if  you  want  to  reset an OpenVPN daemon with a SIGUSR1 signal
505              (for example in response to a DHCP reset), you should  make  use
506              of  one  or more of the --persist options to ensure that OpenVPN
507              doesn't need to execute any privileged operations  in  order  to
508              restart (such as re-reading key files or running ifconfig on the
509              TUN device).
510
511       --writepid file
512              Write OpenVPN's main process ID to file.
513
514   Log options
515       --echo parms
516              Echo parms to log output.
517
518              Designed to be used to send messages to a  controlling  applica‐
519              tion which is receiving the OpenVPN log output.
520
521       --errors-to-stderr
522              Output  errors  to stderr instead of stdout unless log output is
523              redirected by one of the --log options.
524
525       --log file
526              Output logging  messages  to  file,  including  output  to  std‐
527              out/stderr which is generated by called scripts. If file already
528              exists it will be truncated. This option  takes  effect  immedi‐
529              ately  when  it is parsed in the command line and will supersede
530              syslog output if --daemon or --inetd is also specified. This op‐
531              tion  is persistent over the entire course of an OpenVPN instan‐
532              tiation  and  will  not  be  reset  by   SIGHUP,   SIGUSR1,   or
533              --ping-restart.
534
535              Note that on Windows, when OpenVPN is started as a service, log‐
536              ging occurs by default without the need to specify this option.
537
538       --log-append file
539              Append logging messages to file.  If file  does  not  exist,  it
540              will  be  created. This option behaves exactly like --log except
541              that it appends to rather than truncating the log file.
542
543       --machine-readable-output
544              Always write timestamps and message flags to log messages,  even
545              when  they  otherwise would not be prefixed. In particular, this
546              applies to log messages sent to stdout.
547
548       --mute n
549              Log at most n consecutive messages in the same category. This is
550              useful to limit repetitive logging of similar message types.
551
552       --mute-replay-warnings
553              Silence  the output of replay warnings, which are a common false
554              alarm on WiFi networks. This option preserves  the  security  of
555              the replay protection code without the verbosity associated with
556              warnings about duplicate packets.
557
558       --suppress-timestamps
559              Avoid writing timestamps to log messages, even when they  other‐
560              wise would be prepended. In particular, this applies to log mes‐
561              sages sent to stdout.
562
563       --syslog progname
564              Direct log output to system logger, but do not become a  daemon.
565              See --daemon directive above for description of progname parame‐
566              ter.
567
568       --verb n
569              Set output verbosity to n (default 1). Each level shows all info
570              from  the  previous levels. Level 3 is recommended if you want a
571              good summary of what's happening without being swamped  by  out‐
572              put.
573
574              0      No output except fatal errors.
575
576              1 to 4 Normal usage range.
577
578              5      Outputs R and W characters to the console for each packet
579                     read and write, uppercase is used for TCP/UDP packets and
580                     lowercase is used for TUN/TAP packets.
581
582              6 to 11
583                     Debug  info  range (see errlevel.h in the source code for
584                     additional information on debug levels).
585
586   Protocol options
587       Options in this section affect features available in the  OpenVPN  wire
588       protocol.   Many of these options also define the encryption options of
589       the data channel in the OpenVPN wire protocol.  These options  must  be
590       configured in a compatible way between both the local and remote side.
591
592       --allow-compression mode
593              As  described  in the --compress option, compression is a poten‐
594              tially dangerous option.  This option allows controlling the be‐
595              haviour of OpenVPN when compression is used and allowed.
596
597              Valid syntaxes:
598
599                 allow-compression
600                 allow-compression mode
601
602              The mode argument can be one of the following values:
603
604              asym (default)
605                     OpenVPN  will  only  decompress  downlink packets but not
606                     compress uplink packets.  This also allows  migrating  to
607                     disable  compression when changing both server and client
608                     configurations to remove compression at the same time  is
609                     not a feasible option.
610
611              no     OpenVPN will refuse any non-stub compression.
612
613              yes    OpenVPN will send and receive compressed packets.
614
615       --auth alg
616              Authenticate data channel packets and (if enabled) tls-auth con‐
617              trol channel packets with HMAC using  message  digest  algorithm
618              alg. (The default is SHA1 ). HMAC is a commonly used message au‐
619              thentication algorithm (MAC) that uses a data string,  a  secure
620              hash algorithm and a key to produce a digital signature.
621
622              The  OpenVPN  data  channel protocol uses encrypt-then-mac (i.e.
623              first encrypt a packet  then  HMAC  the  resulting  ciphertext),
624              which prevents padding oracle attacks.
625
626              If  an  AEAD cipher mode (e.g. GCM) is chosen then the specified
627              --auth algorithm is ignored for the data channel and the authen‐
628              tication  method  of  the AEAD cipher is used instead. Note that
629              alg still specifies the digest used for tls-auth.
630
631              In static-key encryption mode, the HMAC key is included  in  the
632              key file generated by --genkey. In TLS mode, the HMAC key is dy‐
633              namically generated and shared between peers via the TLS control
634              channel.  If  OpenVPN  receives a packet with a bad HMAC it will
635              drop the packet. HMAC usually adds 16 or 20  bytes  per  packet.
636              Set alg=none to disable authentication.
637
638              For        more        information       on       HMAC       see
639              http://www.cs.ucsd.edu/users/mihir/papers/hmac.html
640
641       --cipher alg
642              This option is deprecated for server-client mode. --data-ciphers
643              or possibly --data-ciphers-fallback` should be used instead.
644
645              Encrypt data channel packets with cipher algorithm alg.
646
647              The  default  is  BF-CBC, an abbreviation for Blowfish in Cipher
648              Block Chaining mode. When cipher negotiation (NCP)  is  allowed,
649              OpenVPN  2.4 and newer on both client and server side will auto‐
650              matically  upgrade  to  AES-256-GCM.   See  --data-ciphers   and
651              --ncp-disable for more details on NCP.
652
653              Using  BF-CBC  is  no  longer recommended, because of its 64-bit
654              block size. This small block size allows attacks based on colli‐
655              sions,       as      demonstrated      by      SWEET32.      See
656              https://community.openvpn.net/openvpn/wiki/SWEET32 for  details.
657              Due  to  this,  support for BF-CBC, DES, CAST5, IDEA and RC2 ci‐
658              phers will be removed in OpenVPN 2.6.
659
660              To see other ciphers that are available with  OpenVPN,  use  the
661              --show-ciphers option.
662
663              Set alg to none to disable encryption.
664
665       --compress algorithm
666              DEPRECATED  Enable a compression algorithm.  Compression is gen‐
667              erally not recommended.  VPN tunnels which use  compression  are
668              susceptible to the VORALCE attack vector.
669
670              The  algorithm  parameter may be lzo, lz4, lz4-v2, stub, stub-v2
671              or empty.  LZO and LZ4  are  different  compression  algorithms,
672              with  LZ4 generally offering the best performance with least CPU
673              usage.
674
675              The lz4-v2 and stub-v2 variants implement a better framing  that
676              does  not  add  overhead  when packets cannot be compressed. All
677              other variants always add one extra framing byte compared to  no
678              compression framing.
679
680              If  the  algorithm parameter is stub, stub-v2 or empty, compres‐
681              sion will be turned off, but the packet framing for  compression
682              will still be enabled, allowing a different setting to be pushed
683              later.  Additionally, stub and stub-v2  wil  disable  announcing
684              lzo and lz4 compression support via IV_ variables to the server.
685
686              Note:  the  stub  (or  empty)  option is NOT compatible with the
687              older option --comp-lzo no.
688
689              *Security Considerations*
690
691              Compression and encryption is a tricky combination.  If  an  at‐
692              tacker  knows or is able to control (parts of) the plain-text of
693              packets that contain secrets, the attacker might be able to  ex‐
694              tract  the  secret if compression is enabled. See e.g. the CRIME
695              and BREACH attacks on TLS and VORACLE on VPNs which also  lever‐
696              age  to  break encryption. If you are not entirely sure that the
697              above does not apply to your traffic, you are advised to not en‐
698              able compression.
699
700       --comp-lzo mode
701              DEPRECATED  Enable  LZO  compression  algorithm.  Compression is
702              generally not recommended.  VPN tunnels which  uses  compression
703              are suspectible to the VORALCE attack vector.
704
705              Use  LZO  compression -- may add up to 1 byte per packet for in‐
706              compressible data. mode may be yes, no, or adaptive (default).
707
708              In a server mode setup, it is possible to selectively turn  com‐
709              pression on or off for individual clients.
710
711              First,  make  sure the client-side config file enables selective
712              compression by having at least one --comp-lzo directive, such as
713              --comp-lzo  no.  This  will turn off compression by default, but
714              allow a future directive push from  the  server  to  dynamically
715              change the on/off/adaptive setting.
716
717              Next in a --client-config-dir file, specify the compression set‐
718              ting for the client, for example:
719
720                 comp-lzo yes
721                 push "comp-lzo yes"
722
723              The first line sets the comp-lzo setting for the server side  of
724              the link, the second sets the client side.
725
726       --comp-noadapt
727              DEPRECATED When used in conjunction with --comp-lzo, this option
728              will disable OpenVPN's adaptive compression algorithm. Normally,
729              adaptive compression is enabled with --comp-lzo.
730
731              Adaptive  compression  tries to optimize the case where you have
732              compression enabled, but you are  sending  predominantly  incom‐
733              pressible  (or  pre-compressed) packets over the tunnel, such as
734              an FTP or rsync transfer of a large, compressed file. With adap‐
735              tive  compression, OpenVPN will periodically sample the compres‐
736              sion process to measure its efficiency. If the data  being  sent
737              over  the  tunnel  is  already compressed, the compression effi‐
738              ciency will be very low, triggering openvpn to disable  compres‐
739              sion for a period of time until the next re-sample test.
740
741       --key-direction
742              Alternative  way  of specifying the optional direction parameter
743              for the --tls-auth and --secret options. Useful when  using  in‐
744              line files (See section on inline files).
745
746       --keysize n
747              DEPRECATED This option will be removed in OpenVPN 2.6.
748
749              Size  of cipher key in bits (optional). If unspecified, defaults
750              to cipher-specific default. The --show-ciphers option  (see  be‐
751              low)  shows  all  available  OpenSSL  ciphers, their default key
752              sizes, and whether the key size can  be  changed.  Use  care  in
753              changing a cipher's default key size. Many ciphers have not been
754              extensively cryptanalyzed with non-standard key lengths,  and  a
755              larger  key  may offer no real guarantee of greater security, or
756              may even reduce security.
757
758       --data-ciphers cipher-list
759              Restrict the allowed ciphers to be negotiated to the ciphers  in
760              cipher-list.  cipher-list  is a colon-separated list of ciphers,
761              and defaults to AES-256-GCM:AES-128-GCM.
762
763              For servers, the first cipher from cipher-list that is also sup‐
764              ported  by the client will be pushed to clients that support ci‐
765              pher negotiation.
766
767              Cipher negotiation is enabled in client-server mode  only.  I.e.
768              if  --mode  is  set to 'server' (server-side, implied by setting
769              --server ), or if --pull is specified (client-side,  implied  by
770              setting --client).
771
772              If no common cipher is found during cipher negotiation, the con‐
773              nection is terminated. To support old clients/old  servers  that
774              do  not  provide  any  cipher negotiation support see --data-ci‐
775              phers-fallback.
776
777              Additionally, to allow for more smooth transition, if NCP is en‐
778              abled,  OpenVPN  will inherit the cipher of the peer if that ci‐
779              pher is different from the local --cipher setting, but the  peer
780              cipher is one of the ciphers specified in --data-ciphers. E.g. a
781              non-NCP client (<=v2.3, or with --ncp-disabled  set)  connecting
782              to  a NCP server (v2.4+) with --cipher BF-CBC and --data-ciphers
783              AES-256-GCM:AES-256-CBC set can either specify  --cipher  BF-CBC
784              or --cipher AES-256-CBC and both will work.
785
786              Note  for using NCP with an OpenVPN 2.4 peer: This list must in‐
787              clude the AES-256-GCM and AES-128-GCM ciphers.
788
789              This list is restricted to be 127 chars long after conversion to
790              OpenVPN ciphers.
791
792              This option was called --ncp-ciphers in OpenVPN 2.4 but has been
793              renamed to --data-ciphers in OpenVPN 2.5 to more accurately  re‐
794              flect its meaning.
795
796       --data-ciphers-fallback alg
797              Configure  a cipher that is used to fall back to if we could not
798              determine which cipher the peer is willing to use.
799
800              This option should only be needed to connect to peers  that  are
801              running  OpenVPN 2.3 and older version, and have been configured
802              with --enable-small (typically used on routers or other embedded
803              devices).
804
805       --ncp-disable
806              DEPRECATED  Disable  "Negotiable  Crypto  Parameters". This com‐
807              pletely disables cipher negotiation.
808
809       --secret args
810              Enable Static Key encryption mode (non-TLS). Use pre-shared  se‐
811              cret file which was generated with --genkey.
812
813              Valid syntaxes:
814
815                 secret file
816                 secret file direction
817
818              The  optional  direction parameter enables the use of 4 distinct
819              keys (HMAC-send, cipher-encrypt, HMAC-receive,  cipher-decrypt),
820              so that each data flow direction has a different set of HMAC and
821              cipher keys. This has a number of desirable security  properties
822              including  eliminating  certain  kinds of DoS and message replay
823              attacks.
824
825              When the direction parameter is omitted, 2 keys are  used  bidi‐
826              rectionally,  one  for HMAC and the other for encryption/decryp‐
827              tion.
828
829              The direction parameter should always be complementary on either
830              side of the connection, i.e. one side should use 0 and the other
831              should use 1, or both sides should omit it altogether.
832
833              The direction parameter requires that file contains a  2048  bit
834              key.  While  pre-1.5  versions  of OpenVPN generate 1024 bit key
835              files, any version of OpenVPN which supports the  direction  pa‐
836              rameter,  will  also  support 2048 bit key file generation using
837              the --genkey option.
838
839              Static key encryption mode has certain advantages,  the  primary
840              being ease of configuration.
841
842              There  are no certificates or certificate authorities or compli‐
843              cated negotiation handshakes and protocols. The only requirement
844              is  that  you  have a pre-existing secure channel with your peer
845              (such as ssh) to initially copy the key. This requirement, along
846              with  the  fact  that your key never changes unless you manually
847              generate a new one, makes it somewhat less secure than TLS  mode
848              (see  below).  If  an attacker manages to steal your key, every‐
849              thing that was ever encrypted with it is  compromised.  Contrast
850              that  to the perfect forward secrecy features of TLS mode (using
851              Diffie Hellman key exchange), where even if an attacker was able
852              to  steal your private key, he would gain no information to help
853              him decrypt past sessions.
854
855              Another advantageous aspect of Static  Key  encryption  mode  is
856              that  it is a handshake-free protocol without any distinguishing
857              signature or feature (such as a header or protocol handshake se‐
858              quence)  that  would mark the ciphertext packets as being gener‐
859              ated by OpenVPN. Anyone eavesdropping  on  the  wire  would  see
860              nothing but random-looking data.
861
862       --tran-window n
863              Transition  window -- our old key can live this many seconds af‐
864              ter a new a key renegotiation  begins  (default  3600  seconds).
865              This  feature  allows  for a graceful transition from old to new
866              key, and removes the key renegotiation sequence from the  criti‐
867              cal path of tunnel data forwarding.
868
869   Client Options
870       The  client  options are used when connecting to an OpenVPN server con‐
871       figured to use --server, --server-bridge, or --mode server in its  con‐
872       figuration.
873
874       --allow-pull-fqdn
875              Allow  client  to  pull DNS names from server (rather than being
876              limited  to   IP   address)   for   --ifconfig,   --route,   and
877              --route-gateway.
878
879       --allow-recursive-routing
880              When  this  option  is  set,  OpenVPN will not drop incoming tun
881              packets with same destination as host.
882
883       --auth-token token
884              This is not an option to be used directly in  any  configuration
885              files,  but  rather  push  this  option  from a --client-connect
886              script   or   a   --plugin   which   hooks   into   the    OPEN‐
887              VPN_PLUGIN_CLIENT_CONNECT   or  OPENVPN_PLUGIN_CLIENT_CONNECT_V2
888              calls. This option provides a possibility to replace the clients
889              password with an authentication token during the lifetime of the
890              OpenVPN client.
891
892              Whenever   the    connection    is    renegotiated    and    the
893              --auth-user-pass-verify  script  or  --plugin  making use of the
894              OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY hook is triggered, it  will
895              pass over this token as the password instead of the password the
896              user provided. The authentication token can only be reset  by  a
897              full  reconnect  where  the  server  can push new options to the
898              client. The password the user entered is never preserved once an
899              authentication  token  has  been set. If the OpenVPN server side
900              rejects the authentication token then the client will receive an
901              AUTH_FAILED and disconnect.
902
903              The purpose of this is to enable two factor authentication meth‐
904              ods, such as HOTP or TOTP, to be used  without  needing  to  re‐
905              trieve  a new OTP code each time the connection is renegotiated.
906              Another use case is to cache authentication data on  the  client
907              without needing to have the users password cached in memory dur‐
908              ing the life time of the session.
909
910              To make use of this  feature,  the  --client-connect  script  or
911              --plugin needs to put
912
913                 push "auth-token UNIQUE_TOKEN_VALUE"
914
915              into  the  file/buffer for dynamic configuration data. This will
916              then make the OpenVPN server to push this value to  the  client,
917              which replaces the local password with the UNIQUE_TOKEN_VALUE.
918
919              Newer  clients  (2.4.7+) will fall back to the original password
920              method after a failed auth. Older clients will  keep  using  the
921              token value and react according to --auth-retry
922
923       --auth-token-user base64username
924              Companion  option  to --auth-token. This options allows to over‐
925              ride the username used by the client when reauthenticating  with
926              the  auth-token.   It  also allows to use --auth-token in setups
927              that normally do not use username and password.
928
929              The username has to be base64 encoded.
930
931       --auth-user-pass
932              Authenticate with server using username/password.
933
934              Valid syntaxes:
935
936                 auth-user-pass
937                 auth-user-pass up
938
939              If up is present, it must be a file containing username/password
940              on 2 lines. If the password line is missing, OpenVPN will prompt
941              for one.
942
943              If up is omitted, username/password will be  prompted  from  the
944              console.
945
946              The server configuration must specify an --auth-user-pass-verify
947              script to verify the username/password provided by the client.
948
949       --auth-retry type
950              Controls how OpenVPN responds to username/password  verification
951              errors  such  as the client-side response to an AUTH_FAILED mes‐
952              sage from the server or verification failure of the private  key
953              password.
954
955              Normally  used  to  prevent  auth errors from being fatal on the
956              client side, and to permit username/password requeries  in  case
957              of error.
958
959              An  AUTH_FAILED message is generated by the server if the client
960              fails --auth-user-pass authentication,  or  if  the  server-side
961              --client-connect  script returns an error status when the client
962              tries to connect.
963
964              type can be one of:
965
966              none   Client will exit with a fatal  error  (this  is  the  de‐
967                     fault).
968
969              nointeract
970                     Client  will  retry the connection without requerying for
971                     an --auth-user-pass username/password.  Use  this  option
972                     for unattended clients.
973
974              interact
975                     Client   will   requery  for  an  --auth-user-pass  user‐
976                     name/password and/or private key password before attempt‐
977                     ing a reconnection.
978
979              Note  that  while  this  option cannot be pushed, it can be con‐
980              trolled from the management interface.
981
982       --client
983              A helper directive designed to  simplify  the  configuration  of
984              OpenVPN's client mode. This directive is equivalent to:
985
986                 pull
987                 tls-client
988
989       --client-nat args
990              This  pushable  client option sets up a stateless one-to-one NAT
991              rule on packet addresses (not ports), and  is  useful  in  cases
992              where  routes  or  ifconfig  settings pushed to the client would
993              create an IP numbering conflict.
994
995              Examples:
996
997                 client-nat snat 192.168.0.0/255.255.0.0
998                 client-nat dnat 10.64.0.0/255.255.0.0
999
1000              network/netmask (for  example  192.168.0.0/255.255.0.0)  defines
1001              the  local view of a resource from the client perspective, while
1002              alias/netmask (for example  10.64.0.0/255.255.0.0)  defines  the
1003              remote view from the server perspective.
1004
1005              Use snat (source NAT) for resources owned by the client and dnat
1006              (destination NAT) for remote resources.
1007
1008              Set --verb 6 for debugging info showing  the  transformation  of
1009              src/dest addresses in packets.
1010
1011       --connect-retry n
1012              Wait  n  seconds  between  connection attempts (default 5).  Re‐
1013              peated reconnection attempts are slowed down after 5 retries per
1014              remote  by  doubling  the  wait time after each unsuccessful at‐
1015              tempt. An optional argument max specifies the maximum  value  of
1016              wait time in seconds at which it gets capped (default 300).
1017
1018       --connect-retry-max n
1019              n  specifies  the  number of times each --remote or <connection>
1020              entry is tried. Specifying n as 1 would try each  entry  exactly
1021              once.  A successful connection resets the counter.  (default un‐
1022              limited).
1023
1024       --connect-timeout n
1025              See --server-poll-timeout.
1026
1027       --explicit-exit-notify n
1028              In UDP client mode or point-to-point mode, send  server/peer  an
1029              exit  notification  if tunnel is restarted or OpenVPN process is
1030              exited. In client mode, on exit/restart, this option  will  tell
1031              the  server  to  immediately  close  its  client instance object
1032              rather than waiting for a timeout.
1033
1034              The n parameter (default 1 if not present) controls the  maximum
1035              number  of  attempts that the client will try to resend the exit
1036              notification message.
1037
1038              In UDP server mode, send RESTART control channel command to con‐
1039              nected  clients. The n parameter (default 1 if not present) con‐
1040              trols client behavior. With n = 1 client will attempt to  recon‐
1041              nect  to  the same server, with n = 2 client will advance to the
1042              next server.
1043
1044              OpenVPN will not send any exit notifications unless this  option
1045              is enabled.
1046
1047       --inactive args
1048              Causes  OpenVPN  to  exit  after  n seconds of inactivity on the
1049              TUN/TAP device. The time length of inactivity is measured  since
1050              the  last  incoming or outgoing tunnel packet. The default value
1051              is 0 seconds, which disables this feature.
1052
1053              Valid syntaxes:
1054
1055                 inactive n
1056                 inactive n bytes
1057
1058              If the optional bytes parameter is included, exit if  less  than
1059              bytes of combined in/out traffic are produced on the tun/tap de‐
1060              vice in n seconds.
1061
1062              In any case, OpenVPN's internal ping  packets  (which  are  just
1063              keepalives)  and  TLS control packets are not considered "activ‐
1064              ity", nor are they counted as traffic, as they are  used  inter‐
1065              nally by OpenVPN and are not an indication of actual user activ‐
1066              ity.
1067
1068       --proto-force p
1069              When iterating through connection profiles, only  consider  pro‐
1070              files using protocol p (tcp | udp).
1071
1072              Note  that this specifically only filters by the transport layer
1073              protocol, i.e. UDP or TCP. This does not affect whether IPv4  or
1074              IPv6 is used as IP protocol.
1075
1076              For  implementation  reasons the option accepts the 4 and 6 suf‐
1077              fixes when specifying the protocol (i.e. udp4 / udp6  /  tcp4  /
1078              tcp6).  However, these behave the same as without the suffix and
1079              should be avoided to prevent confusion.
1080
1081       --pull This option must be used on a client which is  connecting  to  a
1082              multi-client  server. It indicates to OpenVPN that it should ac‐
1083              cept options pushed by the server, provided they are part of the
1084              legal  set  of  pushable options (note that the --pull option is
1085              implied by --client ).
1086
1087              In particular, --pull allows the server to push  routes  to  the
1088              client,  so  you should not use --pull or --client in situations
1089              where you don't trust  the  server  to  have  control  over  the
1090              client's routing table.
1091
1092       --pull-filter args
1093              Filter options on the client pushed by the server to the client.
1094
1095              Valid syntaxes:
1096
1097                 pull-filter accept text
1098                 pull-filter ignore text
1099                 pull-filter reject text
1100
1101              Filter  options  received  from  the server if the option starts
1102              with text.  The action flag accept allows the option, ignore re‐
1103              moves  it  and  reject  flags  an  error  and triggers a SIGUSR1
1104              restart. The filters may be specified multiple times,  and  each
1105              filter is applied in the order it is specified. The filtering of
1106              each option stops as soon as a match is found. Unmatched options
1107              are accepted by default.
1108
1109              Prefix comparison is used to match text against the received op‐
1110              tion so that
1111
1112                 pull-filter ignore "route"
1113
1114              would remove all pushed options starting with route which  would
1115              include,  for  example, route-gateway. Enclose text in quotes to
1116              embed spaces.
1117
1118                 pull-filter accept "route 192.168.1."
1119                 pull-filter ignore "route "
1120
1121              would remove all routes that do not start with 192.168.1.
1122
1123              Note that reject may result in a repeated cycle of  failure  and
1124              reconnect,  unless multiple remotes are specified and connection
1125              to the next remote succeeds. To silently ignore an option pushed
1126              by the server, use ignore.
1127
1128       --push-peer-info
1129              Push additional information about the client to server. The fol‐
1130              lowing data is always pushed to the server:
1131
1132              IV_VER=<version>
1133                     The client OpenVPN version
1134
1135              IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]
1136                     The client OS platform
1137
1138              IV_LZO_STUB=1
1139                     If client was built with LZO stub capability
1140
1141              IV_LZ4=1
1142                     If the client supports LZ4 compressions.
1143
1144              IV_PROTO
1145                     Details about protocol extensions that the peer supports.
1146                     The  variable  is  a bitfield and the bits are defined as
1147                     follows (starting a bit 0 for the first (unused) bit:
1148
1149                     • bit 1: The peer supports peer-id floating mechanism
1150
1151                     • bit 2: The client expects a push-reply and  the  server
1152                       may  send this reply without waiting for a push-request
1153                       first.
1154
1155                     • bit 3: The client is capable of  doing  key  derivation
1156                       using RFC5705 key material exporter.
1157
1158                     • bit  4:  The  client is capable of accepting additional
1159                       arguments to the AUTH_PENDING message.
1160
1161              IV_NCP=2
1162                     Negotiable ciphers, client supports  --cipher  pushed  by
1163                     the server, a value of 2 or greater indicates client sup‐
1164                     ports AES-GCM-128 and AES-GCM-256.
1165
1166              IV_CIPHERS=<ncp-ciphers>
1167                     The client announces the list of supported  ciphers  con‐
1168                     figured with the --data-ciphers option to the server.
1169
1170              IV_GUI_VER=<gui_id> <version>
1171                     The  UI  version  of  a UI if one is running, for example
1172                     de.blinkt.openvpn 0.5.47 for the Android app.
1173
1174              IV_SSO=[crtext,][openurl,][proxy_url]
1175                     Additional  authentication  methods  supported   by   the
1176                     client.   This  may  be  set  by  the client UI/GUI using
1177                     --setenv
1178
1179              When --push-peer-info is enabled the additional information con‐
1180              sists of the following data:
1181
1182              IV_HWADDR=<string>
1183                     This  is intended to be a unique and persistent ID of the
1184                     client.  The string  value  can  be  any  readable  ASCII
1185                     string up to 64 bytes.  OpenVPN 2.x and some other imple‐
1186                     mentations use the MAC address of the client's  interface
1187                     used to reach the default gateway. If this string is gen‐
1188                     erated by the client, it should be  consistent  and  pre‐
1189                     served  across  independent session and preferably re-in‐
1190                     stallations and upgrades.
1191
1192              IV_SSL=<version string>
1193                     The ssl version used by the client, e.g.  OpenSSL  1.0.2f
1194                     28 Jan 2016.
1195
1196              IV_PLAT_VER=x.y
1197                     The version of the operating system, e.g. 6.1 for Windows
1198                     7.
1199
1200              UV_<name>=<value>
1201                     Client environment variables whose names start with UV_
1202
1203       --remote args
1204              Remote host name or IP address, port and protocol.
1205
1206              Valid syntaxes:
1207
1208                 remote host
1209                 remote host port
1210                 remote host port proto
1211
1212              The port and proto arguments are optional.  The  OpenVPN  client
1213              will  try  to connect to a server at host:port.  The proto argu‐
1214              ment indicates the protocol to use when connecting with the  re‐
1215              mote,  and  may  be tcp or udp.  To enforce IPv4 or IPv6 connec‐
1216              tions add a 4 or 6 suffix; like udp4 / udp6 / tcp4 / tcp6.
1217
1218              On the client, multiple --remote options may  be  specified  for
1219              redundancy, each referring to a different OpenVPN server, in the
1220              order specified by the list of --remote options. Specifying mul‐
1221              tiple --remote options for this purpose is a special case of the
1222              more general connection-profile feature.  See  the  <connection>
1223              documentation below.
1224
1225              The  client  will  move  on to the next host in the list, in the
1226              event of connection failure. Note that at any  given  time,  the
1227              OpenVPN client will at most be connected to one server.
1228
1229              Examples:
1230
1231                 remote server1.example.net
1232                 remote server1.example.net 1194
1233                 remote server2.example.net 1194 tcp
1234
1235              Note:  Since  UDP  is  connectionless, connection failure is de‐
1236                     fined by the --ping and --ping-restart options.
1237
1238                     Also, if you use multiple --remote options, AND  you  are
1239                     dropping root privileges on the client with --user and/or
1240                     --group AND the client is running a  non-Windows  OS,  if
1241                     the  client  needs  to  switch to a different server, and
1242                     that server pushes back different TUN/TAP or  route  set‐
1243                     tings,  the  client  may lack the necessary privileges to
1244                     close and reopen the TUN/TAP interface. This could  cause
1245                     the client to exit with a fatal error.
1246
1247              If --remote is unspecified, OpenVPN will listen for packets from
1248              any IP address, but will not act on those  packets  unless  they
1249              pass  all authentication tests. This requirement for authentica‐
1250              tion is binding on all potential peers, even  those  from  known
1251              and  supposedly trusted IP addresses (it is very easy to forge a
1252              source IP address on a UDP packet).
1253
1254              When used in TCP mode, --remote will act as a filter,  rejecting
1255              connections from any host which does not match host.
1256
1257              If  host  is a DNS name which resolves to multiple IP addresses,
1258              OpenVPN will try them in the order that the system getaddrinfo()
1259              presents  them, so priorization and DNS randomization is done by
1260              the system library. Unless an IP version is forced by the proto‐
1261              col  specification  (4/6 suffix), OpenVPN will try both IPv4 and
1262              IPv6 addresses, in the order getaddrinfo() returns them.
1263
1264       --remote-random
1265              When multiple --remote address/ports are specified, or  if  con‐
1266              nection  profiles  are being used, initially randomize the order
1267              of the list as a kind of basic load-balancing measure.
1268
1269       --remote-random-hostname
1270              Prepend a random string (6 bytes, 12 hex characters) to hostname
1271              to prevent DNS caching. For example, "foo.bar.gov" would be mod‐
1272              ified to "<random-chars>.foo.bar.gov".
1273
1274       --resolv-retry n
1275              If hostname resolve fails for --remote, retry resolve for n sec‐
1276              onds before failing.
1277
1278              Set n to "infinite" to retry indefinitely.
1279
1280              By  default, --resolv-retry infinite is enabled. You can disable
1281              by setting n=0.
1282
1283       --single-session
1284              After initially connecting to a remote peer,  disallow  any  new
1285              connections.  Using  this option means that a remote peer cannot
1286              connect, disconnect, and then reconnect.
1287
1288              If the daemon is reset by a signal or  --ping-restart,  it  will
1289              allow one new connection.
1290
1291              --single-session  can  be used with --ping-exit or --inactive to
1292              create a single dynamic session that will exit when finished.
1293
1294       --server-poll-timeout n
1295              When connecting to a remote server do not wait for more  than  n
1296              seconds  for  a  response before trying the next server. The de‐
1297              fault value is 120s. This timeout includes proxy and TCP connect
1298              timeouts.
1299
1300       --static-challenge args
1301              Enable static challenge/response protocol
1302
1303              Valid syntax:
1304
1305                 static-challenge text echo
1306
1307              The text challenge text is presented to the user which describes
1308              what information is requested.  The echo flag indicates  if  the
1309              user's  input should be echoed on the screen.  Valid echo values
1310              are 0 or 1.
1311
1312              See management-notes.txt in the OpenVPN distribution for  a  de‐
1313              scription of the OpenVPN challenge/response protocol.
1314
1315       --show-proxy-settings
1316              Show  sensed  HTTP or SOCKS proxy settings. Currently, only Win‐
1317              dows clients support this option.
1318
1319       --http-proxy args
1320              Connect to remote host through an HTTP proxy.  This requires  at
1321              least  an  address  server and port argument.  If HTTP Proxy-Au‐
1322              thenticate is required, a file name to an authfile file contain‐
1323              ing a username and password on 2 lines can be given, or stdin to
1324              prompt from console. Its content can also be  specified  in  the
1325              config file with the --http-proxy-user-pass option. (See section
1326              on inline files)
1327
1328              The last optional argument is an auth-method which should be one
1329              of none, basic, or ntlm.
1330
1331              HTTP  Digest  authentication  is supported as well, but only via
1332              the auto or auto-nct flags (below).  This must replace the auth‐
1333              file argument.
1334
1335              The  auto  flag  causes  OpenVPN  to automatically determine the
1336              auth-method and query stdin  or  the  management  interface  for
1337              username/password  credentials, if required. This flag exists on
1338              OpenVPN 2.1 or higher.
1339
1340              The auto-nct flag (no clear-text auth) instructs OpenVPN to  au‐
1341              tomatically  determine  the authentication method, but to reject
1342              weak authentication protocols such as HTTP Basic Authentication.
1343
1344              Examples:
1345
1346                 http-proxy proxy.example.net 3128
1347                 http-proxy proxy.example.net 3128 authfile.txt
1348                 http-proxy proxy.example.net 3128 stdin
1349                 http-proxy proxy.example.net 3128 auto basic
1350                 http-proxy proxy.example.net 3128 auto-nct ntlm
1351
1352       --http-proxy-option args
1353              Set extended HTTP proxy options. Requires an option type as  ar‐
1354              gument  and  an  optional  parameter to the type.  Repeat to set
1355              multiple options.
1356
1357              VERSION version
1358                     Set HTTP version number to version (default 1.0).
1359
1360              AGENT user-agent
1361                     Set HTTP "User-Agent" string to user-agent.
1362
1363              CUSTOM-HEADER name content
1364                     Adds the custom Header with name as name and  content  as
1365                     the content of the custom HTTP header.
1366
1367              Examples:
1368
1369                 http-proxy-option VERSION 1.1
1370                 http-proxy-option AGENT OpenVPN/2.4
1371                 http-proxy-option X-Proxy-Flag some-flags
1372
1373       --socks-proxy args
1374              Connect  to  remote  host  through  a  Socks5 proxy.  A required
1375              server argument is needed.  Optionally a port (default 1080) and
1376              authfile  can  be  given.   The  authfile is a file containing a
1377              username and password on 2 lines, or stdin can be used to prompt
1378              from console.
1379
1380   Server Options
1381       Starting  with  OpenVPN 2.0, a multi-client TCP/UDP server mode is sup‐
1382       ported, and can be enabled with the --mode  server  option.  In  server
1383       mode,  OpenVPN will listen on a single port for incoming client connec‐
1384       tions. All client connections will be routed through a  single  tun  or
1385       tap interface. This mode is designed for scalability and should be able
1386       to support hundreds or even thousands of clients on  sufficiently  fast
1387       hardware. SSL/TLS authentication must be used in this mode.
1388
1389       --auth-gen-token args
1390              Returns  an  authentication  token to successfully authenticated
1391              clients.
1392
1393              Valid syntax:
1394
1395                 auth-gen-token [lifetime] [external-auth]
1396
1397              After  successful  user/password  authentication,  the   OpenVPN
1398              server will with this option generate a temporary authentication
1399              token and push that to the client. On the  following  renegotia‐
1400              tions,  the  OpenVPN  client will pass this token instead of the
1401              users password. On the server side the server will do the  token
1402              authentication  internally and it will NOT do any additional au‐
1403              thentications against configured external user/password  authen‐
1404              tication mechanisms.
1405
1406              The  tokens  implemented  by  this  mechanism include an initial
1407              timestamp and a renew timestamp and are secured by HMAC.
1408
1409              The lifetime argument defines how long the  generated  token  is
1410              valid.   The  lifetime is defined in seconds. If lifetime is not
1411              set or it is set to 0, the token will never expire.
1412
1413              The token will expire either after the  configured  lifetime  of
1414              the  token is reached or after not being renewed for more than 2
1415              * reneg-sec seconds. Clients will be sent renewed tokens on  ev‐
1416              ery  TLS renogiation to keep the client's token updated. This is
1417              done to invalidate a token if a client  is  disconnected  for  a
1418              sufficently  long  time,  while at the same time permitting much
1419              longer token lifetimes for active clients.
1420
1421              This feature is useful for environments which are configured  to
1422              use  One  Time  Passwords (OTP) as part of the user/password au‐
1423              thentications and that authentication mechanism does not  imple‐
1424              ment any auth-token support.
1425
1426              When the external-auth keyword is present the normal authentica‐
1427              tion method will always be called even if  auth-token  succeeds.
1428              Normally  other authentications method are skipped if auth-token
1429              verification suceeds or fails.
1430
1431              This option postpones this decision to the external  authentica‐
1432              tion methods and checks the validity of the account and do other
1433              checks.
1434
1435              In this mode the environment will  have  a  session_id  variable
1436              that  holds the session id from auth-gen-token. Also an environ‐
1437              ment variable session_state is present. This variable  indicates
1438              whether  the  auth-token  has  succeeded or not. It can have the
1439              following values:
1440
1441              Initial
1442                     No token from client.
1443
1444              Authenticated
1445                     Token is valid and not expired.
1446
1447              Expired
1448                     Token is valid but has expired.
1449
1450              Invalid
1451                     Token is invalid (failed HMAC or wrong length)
1452
1453              AuthenticatedEmptyUser / ExpiredEmptyUser
1454                     The token is not valid with the username  sent  from  the
1455                     client  but  would  be valid (or expired) if we assume an
1456                     empty username was used instead.  These two cases  are  a
1457                     workaround  for  behaviour  in  OpenVPN 3.  If this work‐
1458                     around is not needed these two cases should be handled in
1459                     the same way as Invalid.
1460
1461              Warning:  Use  this feature only if you want your authentication
1462              method called on every verification. Since the external  authen‐
1463              tication  is called it needs to also indicate a success or fail‐
1464              ure of the authentication. It is strongly recommended to  return
1465              an  authentication  failure  in  the case of the Invalid/Expired
1466              auth-token with the external-auth option unless the client could
1467              authenticate  in  another  acceptable  way (e.g. client certifi‐
1468              cate), otherwise returning success will lead  to  authentication
1469              bypass  (as  does  returning  success on a wrong password from a
1470              script).
1471
1472       --auth-gen-token-secret file
1473              Specifies a file that holds  a  secret  for  the  HMAC  used  in
1474              --auth-gen-token  If file is not present OpenVPN will generate a
1475              random secret on startup. This file should be used if auth-token
1476              should validate after restarting a server or if client should be
1477              able  to  roam  between  multiple  OpenVPN  servers  with  their
1478              auth-token.
1479
1480       --auth-user-pass-optional
1481              Allow  connections  by  clients  that  do  not  specify  a user‐
1482              name/password.  Normally, when --auth-user-pass-verify or --man‐
1483              agement-client-auth  are  specified (or an authentication plugin
1484              module), the  OpenVPN  server  daemon  will  require  connecting
1485              clients  to  specify  a username and password. This option makes
1486              the submission of a username/password by clients optional, pass‐
1487              ing  the  responsibility to the user-defined authentication mod‐
1488              ule/script to accept or deny the client based on  other  factors
1489              (such as the setting of X509 certificate fields).  When this op‐
1490              tion is used, and a connecting client does not  submit  a  user‐
1491              name/password,  the  user-defined  authentication  module/script
1492              will see the username and password as being set to empty strings
1493              (""). The authentication module/script MUST have logic to detect
1494              this condition and respond accordingly.
1495
1496       --ccd-exclusive
1497              Require, as a condition of  authentication,  that  a  connecting
1498              client has a --client-config-dir file.
1499
1500       --client-config-dir dir
1501              Specify  a directory dir for custom client config files. After a
1502              connecting client has been authenticated, OpenVPN will  look  in
1503              this  directory  for a file having the same name as the client's
1504              X509 common name. If a matching file exists, it will  be  opened
1505              and  parsed  for  client-specific  configuration  options. If no
1506              matching file is found, OpenVPN will instead  try  to  open  and
1507              parse a default file called "DEFAULT", which may be provided but
1508              is not required. Note that the configuration files must be read‐
1509              able by the OpenVPN process after it has dropped it's root priv‐
1510              ileges.
1511
1512              This file can specify a fixed IP address for a given client  us‐
1513              ing  --ifconfig-push,  as  well  as  fixed  subnets owned by the
1514              client using --iroute.
1515
1516              One of the useful properties of this option is  that  it  allows
1517              client  configuration  files to be conveniently created, edited,
1518              or removed while the server is live, without needing to  restart
1519              the server.
1520
1521              The  following  options  are legal in a client-specific context:
1522              --push, --push-reset, --push-remove, --iroute,  --ifconfig-push,
1523              --vlan-pvid and --config.
1524
1525       --client-to-client
1526              Because the OpenVPN server mode handles multiple clients through
1527              a single tun or tap interface, it is effectively a  router.  The
1528              --client-to-client   flag  tells  OpenVPN  to  internally  route
1529              client-to-client traffic rather than pushing  all  client-origi‐
1530              nating traffic to the TUN/TAP interface.
1531
1532              When  this  option  is  used,  each  client will "see" the other
1533              clients which are currently connected.  Otherwise,  each  client
1534              will  only  see the server. Don't use this option if you want to
1535              firewall tunnel traffic using custom, per-client rules.
1536
1537       --disable
1538              Disable a particular client (based on the common name) from con‐
1539              necting.   Don't  use this option to disable a client due to key
1540              or password compromise. Use a CRL (certificate revocation  list)
1541              instead (see the --crl-verify option).
1542
1543              This  option must be associated with a specific client instance,
1544              which means that it must be specified either  in  a  client  in‐
1545              stance config file using --client-config-dir or dynamically gen‐
1546              erated using a --client-connect script.
1547
1548       --connect-freq args
1549              Allow a maximum of  n  new  connections  per  sec  seconds  from
1550              clients.
1551
1552              Valid syntax:
1553
1554                 connect-freq n sec
1555
1556              This  is  designed to contain DoS attacks which flood the server
1557              with connection requests using  certificates  which  will  ulti‐
1558              mately fail to authenticate.
1559
1560              This  is  an  imperfect  solution however, because in a real DoS
1561              scenario, legitimate connections might also be refused.
1562
1563              For the best protection against DoS attacks in server mode,  use
1564              --proto udp and either --tls-auth or --tls-crypt.
1565
1566       --duplicate-cn
1567              Allow multiple clients with the same common name to concurrently
1568              connect. In the absence of this option, OpenVPN will  disconnect
1569              a  client  instance  upon  connection of a new client having the
1570              same common name.
1571
1572       --ifconfig-pool args
1573              Set aside a pool of subnets to be dynamically allocated to  con‐
1574              necting clients, similar to a DHCP server.
1575
1576              Valid syntax:
1577
1578                 ifconfig-pool start-IP end-IP [netmask]
1579
1580              For  tun-style  tunnels,  each client will be given a /30 subnet
1581              (for interoperability with Windows clients).  For tap-style tun‐
1582              nels,  individual  addresses will be allocated, and the optional
1583              netmask parameter will also be pushed to clients.
1584
1585       --ifconfig-ipv6-pool args
1586              Specify an IPv6 address pool for dynamic assignment to clients.
1587
1588              Valid args:
1589
1590                 ifconfig-ipv6-pool ipv6addr/bits
1591
1592              The pool starts at ipv6addr and matches  the  offset  determined
1593              from  the start of the IPv4 pool.  If the host part of the given
1594              IPv6 address is 0, the pool starts at ipv6addr +1.
1595
1596       --ifconfig-pool-persist args
1597              Persist/unpersist ifconfig-pool data to file, at seconds  inter‐
1598              vals (default 600), as well as on program startup and shutdown.
1599
1600              Valid syntax:
1601
1602                 ifconfig-pool-persist file [seconds]
1603
1604              The  goal  of  this option is to provide a long-term association
1605              between clients (denoted by their common name) and  the  virtual
1606              IP  address assigned to them from the ifconfig-pool. Maintaining
1607              a long-term association is good for clients  because  it  allows
1608              them to effectively use the --persist-tun option.
1609
1610              file  is  a  comma-delimited  ASCII  file,  formatted  as  <Com‐
1611              mon-Name>,<IP-address>.
1612
1613              If seconds = 0, file will be treated as read-only. This is  use‐
1614              ful if you would like to treat file as a configuration file.
1615
1616              Note  that  the  entries  in this file are treated by OpenVPN as
1617              suggestions only, based on past associations  between  a  common
1618              name  and IP address.  They do not guarantee that the given com‐
1619              mon name will always receive the given IP address. If  you  want
1620              guaranteed assignment, use --ifconfig-push
1621
1622       --ifconfig-push args
1623              Push  virtual  IP  endpoints  for  client tunnel, overriding the
1624              --ifconfig-pool dynamic allocation.
1625
1626              Valid syntax:
1627
1628                 ifconfig-push local remote-netmask [alias]
1629
1630              The parameters local and remote-netmask are set according to the
1631              --ifconfig directive which you want to execute on the client ma‐
1632              chine to configure the remote end of the tunnel. Note  that  the
1633              parameters  local and remote-netmask are from the perspective of
1634              the client, not the server. They may be DNS names rather than IP
1635              addresses,  in which case they will be resolved on the server at
1636              the time of client connection.
1637
1638              The optional alias parameter may be  used  in  cases  where  NAT
1639              causes  the client view of its local endpoint to differ from the
1640              server view. In this case local/remote-netmask will refer to the
1641              server  view while alias/remote-netmask will refer to the client
1642              view.
1643
1644              This option must be associated with a specific client  instance,
1645              which  means  that  it  must be specified either in a client in‐
1646              stance config file using --client-config-dir or dynamically gen‐
1647              erated using a --client-connect script.
1648
1649              Remember also to include a --route directive in the main OpenVPN
1650              config file which encloses local, so that the kernel  will  know
1651              to route it to the server's TUN/TAP interface.
1652
1653              OpenVPN's  internal  client IP address selection algorithm works
1654              as follows:
1655
1656              1. Use --client-connect script  generated  file  for  static  IP
1657                 (first choice).
1658
1659              2. Use --client-config-dir file for static IP (next choice).
1660
1661              3. Use --ifconfig-pool allocation for dynamic IP (last choice).
1662
1663       --ifconfig-ipv6-push args
1664              for --client-config-dir per-client static IPv6 interface config‐
1665              uration, see --client-config-dir and  --ifconfig-push  for  more
1666              details.
1667
1668              Valid syntax:
1669
1670                 ifconfig-ipv6-push ipv6addr/bits ipv6remote
1671
1672       --inetd args
1673              Valid syntaxes:
1674
1675                 inetd
1676                 inetd wait
1677                 inetd nowait
1678                 inetd wait progname
1679
1680              Use  this  option  when  OpenVPN  is being run from the inetd or
1681              xinetd(8) server.
1682
1683              The wait and nowait option must match what is specified  in  the
1684              inetd/xinetd  config file. The nowait mode can only be used with
1685              --proto tcp-server The default is wait.  The nowait mode can  be
1686              used  to instantiate the OpenVPN daemon as a classic TCP server,
1687              where client connection requests are serviced on a  single  port
1688              number.  For  additional  information on this kind of configura‐
1689              tion,          see          the           OpenVPN           FAQ:
1690              https://community.openvpn.net/openvpn/wiki/325-openvpn-as-a--forking-tcp-server-which-can-service-multiple-clients-over-a-single-tcp-port
1691
1692              This option precludes the use of --daemon, --local or  --remote.
1693              Note that this option causes message and error output to be han‐
1694              dled in the same way as the --daemon option. The optional  prog‐
1695              name parameter is also handled exactly as in --daemon.
1696
1697              Also note that in wait mode, each OpenVPN tunnel requires a sep‐
1698              arate TCP/UDP port and a separate inetd or xinetd entry. See the
1699              OpenVPN  1.x  HOWTO for an example on using OpenVPN with xinetd:
1700              https://openvpn.net/community-resources/1xhowto/
1701
1702       --multihome
1703              Configure a multi-homed UDP server. This option needs to be used
1704              when a server has more than one IP address (e.g. multiple inter‐
1705              faces, or secondary IP addresses), and is not using  --local  to
1706              force binding to one specific address only. This option will add
1707              some extra lookups to the packet path to ensure that the UDP re‐
1708              ply  packets are always sent from the address that the client is
1709              talking to. This is not supported on all platforms, and it  adds
1710              more processing, so it's not enabled by default.
1711
1712              Notes:
1713
1714                     • This option is only relevant for UDP servers.
1715
1716                     • If  you  do an IPv6+IPv4 dual-stack bind on a Linux ma‐
1717                       chine with multiple IPv4 address, connections  to  IPv4
1718                       addresses  will  not work right on kernels before 3.15,
1719                       due to missing kernel support for the IPv4-mapped  case
1720                       (some  distributions have ported this to earlier kernel
1721                       versions, though).
1722
1723       --iroute args
1724              Generate an internal route to a specific client. The netmask pa‐
1725              rameter, if omitted, defaults to 255.255.255.255.
1726
1727              Valid syntax:
1728
1729                 iroute network [netmask]
1730
1731              This  directive  can  be  used  to route a fixed subnet from the
1732              server to a particular client, regardless of where the client is
1733              connecting  from.   Remember that you must also add the route to
1734              the system routing table as well (such as by using  the  --route
1735              directive).  The  reason  why  two routes are needed is that the
1736              --route directive routes the packet from the kernel to  OpenVPN.
1737              Once  in  OpenVPN, the --iroute directive routes to the specific
1738              client.
1739
1740              This option must be specified either in a client instance config
1741              file  using --client-config-dir or dynamically generated using a
1742              --client-connect script.
1743
1744              The --iroute directive also has an  important  interaction  with
1745              --push  "route ...". --iroute essentially defines a subnet which
1746              is owned by a particular client (we will call this client A). If
1747              you would like other clients to be able to reach A's subnet, you
1748              can use --push "route ..." together with  --client-to-client  to
1749              effect this. In order for all clients to see A's subnet, OpenVPN
1750              must push this route to all clients EXCEPT for A, since the sub‐
1751              net  is already owned by A. OpenVPN accomplishes this by not not
1752              pushing a route to a client if it matches one  of  the  client's
1753              iroutes.
1754
1755       --iroute-ipv6 args
1756              for  --client-config-dir per-client static IPv6 route configura‐
1757              tion, see --iroute for more details how to setup and  use  this,
1758              and how --iroute and --route interact.
1759
1760              Valid syntax:
1761
1762                 iroute-ipv6 ipv6addr/bits
1763
1764       --max-clients n
1765              Limit server to a maximum of n concurrent clients.
1766
1767       --max-routes-per-client n
1768              Allow  a  maximum of n internal routes per client (default 256).
1769              This is designed to help contain DoS attacks where an  authenti‐
1770              cated  client  floods  the server with packets appearing to come
1771              from many unique MAC addresses, forcing the  server  to  deplete
1772              virtual  memory  as its internal routing table expands. This di‐
1773              rective can be used in a --client-config-dir file or auto-gener‐
1774              ated  by  a --client-connect script to override the global value
1775              for a particular client.
1776
1777              Note that this directive affects OpenVPN's internal routing  ta‐
1778              ble, not the kernel routing table.
1779
1780       --opt-verify
1781              Clients  that  connect  with  options that are incompatible with
1782              those of the server will be disconnected.
1783
1784              Options  that  will  be  compared  for   compatibility   include
1785              dev-type,  link-mtu,  tun-mtu,  proto, ifconfig, comp-lzo, frag‐
1786              ment,  keydir,  cipher,  auth,   keysize,   secret,   no-replay,
1787              tls-auth, key-method, tls-server and tls-client.
1788
1789              This option requires that --disable-occ NOT be used.
1790
1791       --port-share args
1792              Share OpenVPN TCP with another service
1793
1794              Valid syntax:
1795
1796                 port-share host port [dir]
1797
1798              When run in TCP server mode, share the OpenVPN port with another
1799              application, such as an HTTPS server. If OpenVPN senses  a  con‐
1800              nection  to  its  port which is using a non-OpenVPN protocol, it
1801              will proxy the connection to the server at host:port.  Currently
1802              only  designed to work with HTTP/HTTPS, though it would be theo‐
1803              retically possible to extend to other protocols such as ssh.
1804
1805              dir specifies an optional directory where a temporary file  with
1806              name  N  containing  content C will be dynamically generated for
1807              each proxy connection, where N is  the  source  IP:port  of  the
1808              client  connection and C is the source IP:port of the connection
1809              to the proxy receiver. This directory can be used as  a  dictio‐
1810              nary  by  the proxy receiver to determine the origin of the con‐
1811              nection. Each generated file will be automatically deleted  when
1812              the proxied connection is torn down.
1813
1814              Not implemented on Windows.
1815
1816       --push option
1817              Push  a  config file option back to the client for remote execu‐
1818              tion. Note that option must be enclosed in double  quotes  ("").
1819              The  client  must  specify --pull in its config file. The set of
1820              options which can be pushed is limited by both  feasibility  and
1821              security. Some options such as those which would execute scripts
1822              are banned, since they would  effectively  allow  a  compromised
1823              server  to  execute  arbitrary code on the client. Other options
1824              such as TLS or MTU  parameters  cannot  be  pushed  because  the
1825              client  needs  to  know them before the connection to the server
1826              can be initiated.
1827
1828              This is a partial list of options which can currently be pushed:
1829              --route,   --route-gateway,  --route-delay,  --redirect-gateway,
1830              --ip-win32,  --dhcp-option,  --inactive,  --ping,   --ping-exit,
1831              --ping-restart,  --setenv,  --auth-token,  --persist-key, --per‐
1832              sist-tun, --echo, --comp-lzo, --socket-flags, --sndbuf, --rcvbuf
1833
1834       --push-remove opt
1835              Selectively remove all --push options matching  "opt"  from  the
1836              option  list for a client. opt is matched as a substring against
1837              the  whole  option  string  to-be-pushed  to  the   client,   so
1838              --push-remove route would remove all --push route ... and --push
1839              route-ipv6  ...   statements,  while  --push-remove  "route-ipv6
1840              2001:" would only remove IPv6 routes for 2001:... networks.
1841
1842              --push-remove  can  only  be  used in a client-specific context,
1843              like in a --client-config-dir file, or  --client-connect  script
1844              or plugin -- similar to --push-reset, just more selective.
1845
1846              NOTE:  to  change  an option, --push-remove can be used to first
1847              remove the old value, and then add a new --push option with  the
1848              new value.
1849
1850              NOTE  2:  due  to implementation details, 'ifconfig' and 'ifcon‐
1851              fig-ipv6' can only be removed with an exact match on the  option
1852              (  push-remove  ifconfig), no substring matching and no matching
1853              on the IPv4/IPv6 address argument is possible.
1854
1855       --push-reset
1856              Don't inherit the global push list for  a  specific  client  in‐
1857              stance.   Specify  this option in a client-specific context such
1858              as with a --client-config-dir configuration  file.  This  option
1859              will ignore --push options at the global config file level.
1860
1861              NOTE:  --push-reset  is very thorough: it will remove almost all
1862              options from the list of to-be-pushed options.  In  many  cases,
1863              some of these options will need to be re-configured afterwards -
1864              specifically, --topology subnet  and  --route-gateway  will  get
1865              lost  and  this  will break client configs in many cases.  Thus,
1866              for most purposes, --push-remove is better suited to selectively
1867              remove push options for individual clients.
1868
1869       --server args
1870              A  helper  directive  designed  to simplify the configuration of
1871              OpenVPN's server mode. This directive will  set  up  an  OpenVPN
1872              server which will allocate addresses to clients out of the given
1873              network/netmask. The server itself will take the .1  address  of
1874              the given network for use as the server-side endpoint of the lo‐
1875              cal TUN/TAP interface. If the optional nopool flag is given,  no
1876              dynamic IP address pool will prepared for VPN clients.
1877
1878              Valid syntax:
1879
1880                 server network netmask [nopool]
1881
1882              For example, --server 10.8.0.0 255.255.255.0 expands as follows:
1883
1884                 mode server
1885                 tls-server
1886                 push "topology [topology]"
1887
1888                 if dev tun AND (topology == net30 OR topology == p2p):
1889                   ifconfig 10.8.0.1 10.8.0.2
1890                   if !nopool:
1891                     ifconfig-pool 10.8.0.4 10.8.0.251
1892                   route 10.8.0.0 255.255.255.0
1893                   if client-to-client:
1894                     push "route 10.8.0.0 255.255.255.0"
1895                   else if topology == net30:
1896                     push "route 10.8.0.1"
1897
1898                 if dev tap OR (dev tun AND topology == subnet):
1899                   ifconfig 10.8.0.1 255.255.255.0
1900                   if !nopool:
1901                     ifconfig-pool 10.8.0.2 10.8.0.253 255.255.255.0
1902                   push "route-gateway 10.8.0.1"
1903                   if route-gateway unset:
1904                     route-gateway 10.8.0.2
1905
1906              Don't   use   --server   if   you  are  ethernet  bridging.  Use
1907              --server-bridge instead.
1908
1909       --server-bridge args
1910              A helper directive similar to --server which is designed to sim‐
1911              plify  the  configuration  of  OpenVPN's server mode in ethernet
1912              bridging configurations.
1913
1914              Valid syntaxes:
1915
1916                 server-bridge gateway netmask pool-start-IP pool-end-IP
1917                 server-bridge [nogw]
1918
1919              If --server-bridge is used without any parameters, it  will  en‐
1920              able  a  DHCP-proxy  mode, where connecting OpenVPN clients will
1921              receive an IP address for their TAP adapter from the DHCP server
1922              running  on  the OpenVPN server-side LAN. Note that only clients
1923              that support the binding of a DHCP client with the  TAP  adapter
1924              (such  as Windows) can support this mode. The optional nogw flag
1925              (advanced) indicates that  gateway  information  should  not  be
1926              pushed to the client.
1927
1928              To  configure  ethernet  bridging,  you must first use your OS's
1929              bridging capability to bridge the TAP interface with the  ether‐
1930              net  NIC interface.  For example, on Linux this is done with the
1931              brctl tool, and with Windows XP it is done in the  Network  Con‐
1932              nections  Panel  by  selecting the ethernet and TAP adapters and
1933              right-clicking on "Bridge Connections".
1934
1935              Next you you must manually set the IP/netmask on the bridge  in‐
1936              terface.   The gateway and netmask parameters to --server-bridge
1937              can be set to either the IP/netmask of the bridge interface,  or
1938              the IP/netmask of the default gateway/router on the bridged sub‐
1939              net.
1940
1941              Finally, set aside a IP range in the bridged subnet, denoted  by
1942              pool-start-IP  and  pool-end-IP, for OpenVPN to allocate to con‐
1943              necting clients.
1944
1945              For example,  server-bridge  10.8.0.4  255.255.255.0  10.8.0.128
1946              10.8.0.254 expands as follows:
1947
1948                 mode server
1949                 tls-server
1950
1951                 ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0
1952                 push "route-gateway 10.8.0.4"
1953
1954              In another example, --server-bridge (without parameters) expands
1955              as follows:
1956
1957                 mode server
1958                 tls-server
1959
1960                 push "route-gateway dhcp"
1961
1962              Or --server-bridge nogw expands as follows:
1963
1964                 mode server
1965                 tls-server
1966
1967       --server-ipv6 args
1968              Convenience-function to enable a number of IPv6 related  options
1969              at once, namely --ifconfig-ipv6, --ifconfig-ipv6-pool and --push
1970              tun-ipv6.
1971
1972              Valid syntax:
1973
1974                 server-ipv6 ipv6addr/bits
1975
1976              Pushing of the --tun-ipv6 directive is done  for  older  clients
1977              which require an explicit --tun-ipv6 in their configuration.
1978
1979       --stale-routes-check args
1980              Remove routes which haven't had activity for n seconds (i.e. the
1981              ageing time).  This check is run every t seconds (i.e. check in‐
1982              terval).
1983
1984              Valid syntax:
1985
1986                 stale-routes-check n [t]
1987
1988              If t is not present it defaults to n.
1989
1990              This  option  helps to keep the dynamic routing table small. See
1991              also --max-routes-per-client
1992
1993       --username-as-common-name
1994              Use the authenticated username as the common-name,  rather  than
1995              the  common-name from the client certificate. Requires that some
1996              form of --auth-user-pass verification is in effect. As  the  re‐
1997              placement happens after --auth-user-pass verification, the veri‐
1998              fication script or plugin will  still  receive  the  common-name
1999              from the certificate.
2000
2001              The common_name environment variable passed to scripts and plug‐
2002              ins invoked after authentication  (e.g,  client-connect  script)
2003              and  file names parsed in client-config directory will match the
2004              username.
2005
2006       --verify-client-cert mode
2007              Specify whether the client is required to supply  a  valid  cer‐
2008              tificate.
2009
2010              Possible mode options are:
2011
2012              none   A client certificate is not required. the client needs to
2013                     authenticate using username/password only. Be aware  that
2014                     using  this  directive is less secure than requiring cer‐
2015                     tificates from all clients.
2016
2017                     If you use this directive, the entire  responsibility  of
2018                     authentication  will rest on your --auth-user-pass-verify
2019                     script, so keep in mind that bugs in  your  script  could
2020                     potentially compromise the security of your VPN.
2021
2022                     --verify-client-cert  none  is functionally equivalent to
2023                     --client-cert-not-required.
2024
2025              optional
2026                     A client may present a certificate but it is not required
2027                     to do so.  When using this directive, you should also use
2028                     a --auth-user-pass-verify script to ensure  that  clients
2029                     are  authenticated  using  a  certificate, a username and
2030                     password, or possibly even both.
2031
2032                     Again, the entire responsibility of  authentication  will
2033                     rest  on  your --auth-user-pass-verify script, so keep in
2034                     mind that bugs in your script could  potentially  compro‐
2035                     mise the security of your VPN.
2036
2037              require
2038                     This  is  the  default  option.  A  client is required to
2039                     present a certificate, otherwise VPN access is refused.
2040
2041              If you don't use this directive (or use --verify-client-cert re‐
2042              quire)  but  you also specify an --auth-user-pass-verify script,
2043              then OpenVPN will perform double authentication. The client cer‐
2044              tificate  verification  AND  the  --auth-user-pass-verify script
2045              will need to succeed in order for a client to  be  authenticated
2046              and accepted onto the VPN.
2047
2048       --vlan-tagging
2049              Server-only  option.  Turns  the  OpenVPN server instance into a
2050              switch that understands VLAN-tagging, based on IEEE 802.1Q.
2051
2052              The server TAP device and each of the connecting clients is seen
2053              as  a  port of the switch. All client ports are in untagged mode
2054              and the server TAP device is VLAN-tagged,  untagged  or  accepts
2055              both, depending on the --vlan-accept setting.
2056
2057              Ethernet frames with a prepended 802.1Q tag are called "tagged".
2058              If the VLAN Identifier (VID) field in such a  tag  is  non-zero,
2059              the  frame  is called "VLAN-tagged". If the VID is zero, but the
2060              Priority Control Point (PCP) field is  non-zero,  the  frame  is
2061              called  "prio-tagged".  If  there is no 802.1Q tag, the frame is
2062              "untagged".
2063
2064              Using  the  --vlan-pvid  v   option   once   per   client   (see
2065              --client-config-dir), each port can be associated with a certain
2066              VID.  Packets can only be forwarded  between  ports  having  the
2067              same VID.  Therefore, clients with differing VIDs are completely
2068              separated from one-another, even if --client-to-client is  acti‐
2069              vated.
2070
2071              The  packet filtering takes place in the OpenVPN server. Clients
2072              should not have any VLAN tagging configuration applied.
2073
2074              The --vlan-tagging option is off by default. While  turned  off,
2075              OpenVPN accepts any Ethernet frame and does not perform any spe‐
2076              cial processing for VLAN-tagged packets.
2077
2078              This option can only be activated in --dev tap mode.
2079
2080       --vlan-accept args
2081              Configure the VLAN tagging policy for the server TAP device.
2082
2083              Valid syntax:
2084
2085                 vlan-accept  all|tagged|untagged
2086
2087              The following modes are available:
2088
2089              tagged Admit only VLAN-tagged frames. Only  VLAN-tagged  packets
2090                     are  accepted,  while untagged or priority-tagged packets
2091                     are dropped when entering the server TAP device.
2092
2093              untagged
2094                     Admit only untagged and prio-tagged frames.   VLAN-tagged
2095                     packets  are  not  accepted,  while  untagged  or  prior‐
2096                     ity-tagged packets entering the  server  TAP  device  are
2097                     tagged   with   the   value  configured  for  the  global
2098                     --vlan-pvid setting.
2099
2100              all (default)
2101                     Admit all frames.  All  packets  are  admitted  and  then
2102                     treated like untagged or tagged mode respectively.
2103
2104              Note:  Some vendors refer to switch ports running in tagged mode
2105                     as "trunk ports" and switch  ports  running  in  untagged
2106                     mode as "access ports".
2107
2108              Packets  forwarded  from  clients  to the server are VLAN-tagged
2109              with the originating client's PVID, unless the VID  matches  the
2110              global --vlan-pvid, in which case the tag is removed.
2111
2112              If  no  PVID  is configured for a given client (see --vlan-pvid)
2113              packets are tagged with 1 by default.
2114
2115       --vlan-pvid v
2116              Specifies which VLAN identifier a  "port"  is  associated  with.
2117              Only valid when --vlan-tagging is speficied.
2118
2119              In  the  client  context,  the setting specifies which VLAN ID a
2120              client is associated with. In the global context, the VLAN ID of
2121              the  server  TAP  device is set. The latter only makes sense for
2122              --vlan-accept untagged and --vlan-accept all modes.
2123
2124              Valid values for v go from 1 through to 4094. The  global  value
2125              defaults to 1. If no --vlan-pvid is specified in the client con‐
2126              text, the global value is inherited.
2127
2128              In some switch implementations, the PVID is also referred to  as
2129              "Native VLAN".
2130

ENCRYPTION OPTIONS

2132   SSL Library information
2133       --show-ciphers
2134              (Standalone) Show all cipher algorithms to use with the --cipher
2135              option.
2136
2137       --show-digests
2138              (Standalone) Show all message digest algorithms to use with  the
2139              --auth option.
2140
2141       --show-tls
2142              (Standalone)  Show  all  TLS ciphers supported by the crypto li‐
2143              brary.  OpenVPN uses TLS to secure  the  control  channel,  over
2144              which  the  keys that are used to protect the actual VPN traffic
2145              are exchanged. The TLS ciphers will be sorted from highest pref‐
2146              erence (most secure) to lowest.
2147
2148              Be  aware  that whether a cipher suite in this list can actually
2149              work depends on the specific setup  of  both  peers  (e.g.  both
2150              peers  must  support  the cipher, and an ECDSA cipher suite will
2151              not work if you are using an RSA certificate, etc.).
2152
2153       --show-engines
2154              (Standalone) Show currently available hardware-based crypto  ac‐
2155              celeration engines supported by the OpenSSL library.
2156
2157       --show-groups
2158              (Standalone)  Show  all  available elliptic curves/groups to use
2159              with the --ecdh-curve and tls-groups options.
2160
2161   Generating key material
2162       --genkey args
2163              (Standalone) Generate a key to be used of the type  keytype.  if
2164              keyfile  is  left out or empty the key will be output on stdout.
2165              See the following sections for the different keytypes.
2166
2167              Valid syntax:
2168
2169                 --genkey keytype keyfile
2170
2171              Valid keytype arguments are:
2172
2173              secret                Standard OpenVPN shared secret keys
2174
2175              tls-crypt             Alias for secret
2176
2177              tls-auth              Alias for secret
2178
2179              auth-token            Key used for --auth-gen-token-key
2180
2181              tls-crypt-v2-server   TLS Crypt v2 server key
2182
2183              tls-crypt-v2-client   TLS Crypt v2 client key
2184
2185              Examples:
2186
2187                 $ openvpn --genkey secret shared.key
2188                 $ openvpn --genkey tls-crypt shared.key
2189                 $ openvpn --genkey tls-auth shared.key
2190                 $ openvpn --genkey tls-crypt-v2-server v2crypt-server.key
2191                 $ openvpn --tls-crypt-v2 v2crypt-server.key --genkey tls-crypt-v2-client v2crypt-client-1.key
2192
2193              • Generating Shared Secret Keys Generate a  shared  secret,  for
2194                use with the --secret, --tls-auth or --tls-crypt options.
2195
2196                Syntax:
2197
2198                   $ openvpn --genkey secret|tls-crypt|tls-auth keyfile
2199
2200                The  key  is  saved  in keyfile. All three variants (--secret,
2201                tls-crypt and tls-auth) generate the same  type  of  key.  The
2202                aliases are added for convenience.
2203
2204                If  using this for --secret, this file must be shared with the
2205                peer over a pre-existing secure channel such as scp(1).
2206
2207              • Generating TLS Crypt v2 Server key Generate  a  --tls-crypt-v2
2208                key  to  be  used  by an OpenVPN server.  The key is stored in
2209                keyfile.
2210
2211                Syntax:
2212
2213                   --genkey tls-crypt-v2-server keyfile
2214
2215              • Generating TLS Crypt v2 Client key Generate  a  --tls-crypt-v2
2216                key  to be used by OpenVPN clients.  The key is stored in key‐
2217                file.
2218
2219                Syntax
2220
2221                   --genkey tls-crypt-v2-client keyfile [metadata]
2222
2223                If supplied, include the  supplied  metadata  in  the  wrapped
2224                client  key.  This metadata must be supplied in base64-encoded
2225                form. The metadata must be at most 735 bytes long  (980  bytes
2226                in base64).
2227
2228                If  no  metadata  is  supplied, OpenVPN will use a 64-bit unix
2229                timestamp representing the current time  in  UTC,  encoded  in
2230                network order, as metadata for the generated key.
2231
2232                A  tls-crypt-v2  client  key is wrapped using a server key. To
2233                generate a client key, the  user  must  therefore  supply  the
2234                server key using the --tls-crypt-v2 option.
2235
2236                Servers  can  use  --tls-crypt-v2-verify to specify a metadata
2237                verification command.
2238
2239              • Generate Authentication Token key Generate a new  secret  that
2240                can be used with --auth-gen-token-secret
2241
2242                Syntax:
2243
2244                   --genkey auth-token [keyfile]
2245
2246                Note:  This file should be kept secret to the server as anyone
2247                       that has access to this file will be able  to  generate
2248                       auth  tokens  that  the  OpenVPN  server will accept as
2249                       valid.
2250
2251   Data Channel Renegotiation
2252       When running OpenVPN in client/server mode, the data channel will use a
2253       separate  ephemeral  encryption  key which is rotated at regular inter‐
2254       vals.
2255
2256       --reneg-bytes n
2257              Renegotiate data channel key after  n  bytes  sent  or  received
2258              (disabled  by default with an exception, see below). OpenVPN al‐
2259              lows the lifetime of a key to be expressed as a number of  bytes
2260              encrypted/decrypted,  a  number  of packets, or a number of sec‐
2261              onds. A key renegotiation will be forced if any of  these  three
2262              criteria are met by either peer.
2263
2264              If  using  ciphers  with  cipher block sizes less than 128-bits,
2265              --reneg-bytes is set to 64MB by default, unless it is explicitly
2266              disabled  by setting the value to 0, but this is HIGHLY DISCOUR‐
2267              AGED as this is designed to  add  some  protection  against  the
2268              SWEET32 attack vector. For more information see the --cipher op‐
2269              tion.
2270
2271       --reneg-pkts n
2272              Renegotiate data channel key after n packets sent  and  received
2273              (disabled by default).
2274
2275       --reneg-sec args
2276              Renegotiate  data channel key after at most max seconds (default
2277              3600) and at least min  seconds  (default  is  90%  of  max  for
2278              servers, and equal to max for clients).
2279
2280                 reneg-sec max [min]
2281
2282              The  effective --reneg-sec value used is per session pseudo-uni‐
2283              form-randomized between min and max.
2284
2285              With the default value of 3600 this results in an effective  per
2286              session  value in the range of 3240 .. 3600 seconds for servers,
2287              or just 3600 for clients.
2288
2289              When using dual-factor authentication, note  that  this  default
2290              value  may  cause  the  end user to be challenged to reauthorize
2291              once per hour.
2292
2293              Also, keep in mind that this option can  be  used  on  both  the
2294              client  and  server,  and whichever uses the lower value will be
2295              the one to trigger the renegotiation. A common mistake is to set
2296              --reneg-sec  to  a  higher value on either the client or server,
2297              while the other side of the connection is still  using  the  de‐
2298              fault value of 3600 seconds, meaning that the renegotiation will
2299              still occur once per 3600 seconds. The solution is  to  increase
2300              --reneg-sec on both the client and server, or set it to 0 on one
2301              side of the connection (to disable), and to your chosen value on
2302              the other side.
2303
2304   TLS Mode Options
2305       TLS  mode  is the most powerful crypto mode of OpenVPN in both security
2306       and flexibility. TLS mode works by establishing control and data  chan‐
2307       nels  which  are multiplexed over a single TCP/UDP port. OpenVPN initi‐
2308       ates a TLS session over the control channel and uses it to exchange ci‐
2309       pher  and HMAC keys to protect the data channel. TLS mode uses a robust
2310       reliability layer over the UDP connection for all control channel  com‐
2311       munication,  while  the  data channel, over which encrypted tunnel data
2312       passes, is forwarded without any mediation. The result is the  best  of
2313       both  worlds:  a fast data channel that forwards over UDP with only the
2314       overhead of encrypt, decrypt, and HMAC functions, and a control channel
2315       that  provides  all of the security features of TLS, including certifi‐
2316       cate-based authentication and Diffie Hellman forward secrecy.
2317
2318       To use TLS mode, each peer that runs OpenVPN should have its own  local
2319       certificate/key pair (--cert and --key), signed by the root certificate
2320       which is specified in --ca.
2321
2322       When two OpenVPN peers connect, each presents its local certificate  to
2323       the  other. Each peer will then check that its partner peer presented a
2324       certificate which was signed by the master root certificate  as  speci‐
2325       fied in --ca.
2326
2327       If  that  check  on  both peers succeeds, then the TLS negotiation will
2328       succeed, both OpenVPN peers will exchange temporary session  keys,  and
2329       the tunnel will begin passing data.
2330
2331       The OpenVPN project provides a set of scripts for managing RSA certifi‐
2332       cates and keys: https://github.com/OpenVPN/easy-rsa
2333
2334       --askpass file
2335              Get certificate password from console or file before  we  daemo‐
2336              nize.
2337
2338              Valid syntaxes:
2339
2340                 askpass
2341                 askpass file
2342
2343              For  the extremely security conscious, it is possible to protect
2344              your private key with a password. Of course this means that  ev‐
2345              ery time the OpenVPN daemon is started you must be there to type
2346              the password. The --askpass option allows you to  start  OpenVPN
2347              from  the command line.  It will query you for a password before
2348              it daemonizes. To protect a private  key  with  a  password  you
2349              should  omit  the -nodes option when you use the openssl command
2350              line tool to manage certificates and private keys.
2351
2352              If file is specified, read the password from the first  line  of
2353              file.  Keep  in  mind  that storing your password in a file to a
2354              certain extent invalidates the extra security provided by  using
2355              an encrypted key.
2356
2357       --ca file
2358              Certificate authority (CA) file in .pem format, also referred to
2359              as the root certificate. This file can  have  multiple  certifi‐
2360              cates  in  .pem format, concatenated together. You can construct
2361              your own certificate authority certificate and  private  key  by
2362              using a command such as:
2363
2364                 openssl req -nodes -new -x509 -keyout ca.key -out ca.crt
2365
2366              Then  edit  your openssl.cnf file and edit the certificate vari‐
2367              able to point to your new root certificate ca.crt.
2368
2369              For testing purposes only, the OpenVPN distribution  includes  a
2370              sample  CA  certificate (ca.crt). Of course you should never use
2371              the test certificates and test keys distributed with OpenVPN  in
2372              a  production environment, since by virtue of the fact that they
2373              are distributed with OpenVPN, they are totally insecure.
2374
2375       --capath dir
2376              Directory containing trusted certificates (CAs  and  CRLs).  Not
2377              available with mbed TLS.
2378
2379              CAs in the capath directory are expected to be named <hash>.<n>.
2380              CRLs are expected to be named <hash>.r<n>. See the  -CApath  op‐
2381              tion  of  openssl  verify, and the -hash option of openssl x509,
2382              openssl crl and X509_LOOKUP_hash_dir()(3) for more information.
2383
2384              Similar to the --crl-verify option, CRLs  are  not  mandatory  -
2385              OpenVPN  will  log the usual warning in the logs if the relevant
2386              CRL is missing, but the connection will be allowed.
2387
2388       --cert file
2389              Local peer's signed certificate in .pem format -- must be signed
2390              by  a  certificate  authority whose certificate is in --ca file.
2391              Each peer in an OpenVPN link running in TLS mode should have its
2392              own certificate and private key file. In addition, each certifi‐
2393              cate should have been signed by the key of a certificate author‐
2394              ity  whose  public key resides in the --ca certificate authority
2395              file. You can easily make your own  certificate  authority  (see
2396              above)  or  pay  money  to  use  a  commercial  service  such as
2397              thawte.com (in which case you will be  helping  to  finance  the
2398              world's  second space tourist :). To generate a certificate, you
2399              can use a command such as:
2400
2401                 openssl req -nodes -new -keyout mycert.key -out mycert.csr
2402
2403              If your certificate authority private key lives on  another  ma‐
2404              chine, copy the certificate signing request (mycert.csr) to this
2405              other machine (this can be done over an insecure channel such as
2406              email). Now sign the certificate with a command such as:
2407
2408                 openssl ca -out mycert.crt -in mycert.csr
2409
2410              Now  copy  the  certificate  (mycert.crt) back to the peer which
2411              initially generated the .csr file (this can  be  over  a  public
2412              medium).  Note that the openssl ca command reads the location of
2413              the certificate authority key from its configuration  file  such
2414              as  /usr/share/ssl/openssl.cnf -- note also that for certificate
2415              authority functions, you must set up the files index.txt (may be
2416              empty) and serial (initialize to 01).
2417
2418       --crl-verify args
2419              Check peer certificate against a Certificate Revocation List.
2420
2421              Valid syntax:
2422
2423                 crl-verify file/directory flag
2424
2425              Examples:
2426
2427                 crl-verify crl-file.pem
2428                 crl-verify /etc/openvpn/crls dir
2429
2430              A  CRL  (certificate  revocation list) is used when a particular
2431              key is compromised but when the overall PKI is still intact.
2432
2433              Suppose you had a PKI consisting of a CA, root certificate,  and
2434              a  number of client certificates. Suppose a laptop computer con‐
2435              taining a client key and certificate was stolen. By  adding  the
2436              stolen certificate to the CRL file, you could reject any connec‐
2437              tion which attempts to use it, while preserving the overall  in‐
2438              tegrity of the PKI.
2439
2440              The  only  time when it would be necessary to rebuild the entire
2441              PKI from scratch would be if the root certificate key itself was
2442              compromised.
2443
2444              The  option  is  not mandatory - if the relevant CRL is missing,
2445              OpenVPN will log a warning in the logs - e.g.
2446
2447                 VERIFY WARNING: depth=0, unable to get certificate CRL
2448
2449              but the connection will be allowed.  If the optional dir flag is
2450              specified,  enable  a  different  mode  where  the crl-verify is
2451              pointed at a directory containing files named as revoked  serial
2452              numbers  (the  files may be empty, the contents are never read).
2453              If a client requests a connection, where the client  certificate
2454              serial  number (decimal string) is the name of a file present in
2455              the directory, it will be rejected.
2456
2457              Note:  As the crl file (or directory) is read every time a  peer
2458                     connects,  if  you  are  dropping  root  privileges  with
2459                     --user, make sure that this user  has  sufficient  privi‐
2460                     leges to read the file.
2461
2462       --dh file
2463              File  containing  Diffie  Hellman parameters in .pem format (re‐
2464              quired for --tls-server only).
2465
2466              Set file to none to disable Diffie Hellman key exchange (and use
2467              ECDH only). Note that this requires peers to be using an SSL li‐
2468              brary that supports ECDH TLS cipher suites (e.g. OpenSSL 1.0.1+,
2469              or mbed TLS 2.0+).
2470
2471              Use openssl dhparam -out dh2048.pem 2048 to generate 2048-bit DH
2472              parameters. Diffie Hellman parameters may be considered public.
2473
2474       --ecdh-curve name
2475              Specify the curve to use  for  elliptic  curve  Diffie  Hellman.
2476              Available curves can be listed with --show-curves. The specified
2477              curve will only be used for ECDH TLS-ciphers.
2478
2479              This option is not supported in mbed TLS builds of OpenVPN.
2480
2481       --extra-certs file
2482              Specify a file containing one or more  PEM  certs  (concatenated
2483              together) that complete the local certificate chain.
2484
2485              This  option  is useful for "split" CAs, where the CA for server
2486              certs is different than the CA for client certs.  Putting  certs
2487              in  this  file allows them to be used to complete the local cer‐
2488              tificate chain without trusting them to verify the  peer-submit‐
2489              ted  certificate,  as would be the case if the certs were placed
2490              in the ca file.
2491
2492       --hand-window n
2493              Handshake Window -- the TLS-based  key  exchange  must  finalize
2494              within n seconds of handshake initiation by any peer (default 60
2495              seconds). If the handshake fails we will attempt  to  reset  our
2496              connection  with  our  peer  and try again. Even in the event of
2497              handshake failure we will still use our expiring key for  up  to
2498              --tran-window  seconds to maintain continuity of transmission of
2499              tunnel data.
2500
2501       --key file
2502              Local peer's private key in .pem format.  Use  the  private  key
2503              which  was generated when you built your peer's certificate (see
2504              --cert file above).
2505
2506       --pkcs12 file
2507              Specify a PKCS #12 file containing local private key, local cer‐
2508              tificate,  and  root CA certificate. This option can be used in‐
2509              stead of --ca, --cert, and --key.  Not available with mbed TLS.
2510
2511       --remote-cert-eku oid
2512              Require that peer certificate was signed with  an  explicit  ex‐
2513              tended key usage.
2514
2515              This is a useful security option for clients, to ensure that the
2516              host they connect to is a designated server.
2517
2518              The extended key usage should be encoded  in  oid  notation,  or
2519              OpenSSL symbolic representation.
2520
2521       --remote-cert-ku key-usage
2522              Require  that  peer  certificate  was  signed  with  an explicit
2523              key-usage.
2524
2525              If present in the certificate, the keyUsage value  is  validated
2526              by the TLS library during the TLS handshake. Specifying this op‐
2527              tion without arguments requires this extension to be present (so
2528              the TLS library will verify it).
2529
2530              If  key-usage  is  a list of usage bits, the keyUsage field must
2531              have at least the same bits set as the bits in one of the values
2532              supplied in the key-usage list.
2533
2534              The key-usage values in the list must be encoded in hex, e.g.
2535
2536                 remote-cert-ku a0
2537
2538       --remote-cert-tls type
2539              Require  that  peer  certificate was signed with an explicit key
2540              usage and extended key usage based on RFC3280 TLS rules.
2541
2542              Valid syntaxes:
2543
2544                 remote-cert-tls server
2545                 remote-cert-tls client
2546
2547              This is a useful security option for clients, to ensure that the
2548              host  they  connect  to is a designated server. Or the other way
2549              around; for a server to verify that only  hosts  with  a  client
2550              certificate can connect.
2551
2552              The --remote-cert-tls client option is equivalent to
2553
2554                 remote-cert-ku
2555                 remote-cert-eku "TLS Web Client Authentication"
2556
2557              The --remote-cert-tls server option is equivalent to
2558
2559                 remote-cert-ku
2560                 remote-cert-eku "TLS Web Server Authentication"
2561
2562              This  is  an  important security precaution to protect against a
2563              man-in-the-middle attack where an authorized client attempts  to
2564              connect  to  another client by impersonating the server. The at‐
2565              tack is easily prevented by having  clients  verify  the  server
2566              certificate   using   any   one   of  --remote-cert-tls,  --ver‐
2567              ify-x509-name, or --tls-verify.
2568
2569       --tls-auth args
2570              Add an additional layer of HMAC authentication on top of the TLS
2571              control  channel  to mitigate DoS attacks and attacks on the TLS
2572              stack.
2573
2574              Valid syntaxes:
2575
2576                 tls-auth file
2577                 tls-auth file 0
2578                 tls-auth file 1
2579
2580              In a nutshell, --tls-auth enables a kind of "HMAC  firewall"  on
2581              OpenVPN's  TCP/UDP port, where TLS control channel packets bear‐
2582              ing an incorrect HMAC signature can be dropped immediately with‐
2583              out response.
2584
2585              file (required) is a file in OpenVPN static key format which can
2586              be generated by --genkey.
2587
2588              Older  versions  (up  to  OpenVPN  2.3)  supported  a   freeform
2589              passphrase  file.  This is no longer supported in newer versions
2590              (v2.4+).
2591
2592              See the --secret option for more information on the optional di‐
2593              rection parameter.
2594
2595              --tls-auth is recommended when you are running OpenVPN in a mode
2596              where it is listening for packets from any IP address,  such  as
2597              when  --remote  is  not specified, or --remote is specified with
2598              --float.
2599
2600              The rationale for this feature is as  follows.  TLS  requires  a
2601              multi-packet  exchange before it is able to authenticate a peer.
2602              During this time before authentication,  OpenVPN  is  allocating
2603              resources (memory and CPU) to this potential peer. The potential
2604              peer is also exposing many parts of OpenVPN and the OpenSSL  li‐
2605              brary  to the packets it is sending. Most successful network at‐
2606              tacks today seek to either exploit bugs  in  programs  (such  as
2607              buffer  overflow  attacks) or force a program to consume so many
2608              resources that it becomes unusable. Of course the first line  of
2609              defense  is  always to produce clean, well-audited code. OpenVPN
2610              has been written with buffer overflow attack prevention as a top
2611              priority. But as history has shown, many of the most widely used
2612              network applications have, from time to time, fallen  to  buffer
2613              overflow attacks.
2614
2615              So  as  a  second  line  of defense, OpenVPN offers this special
2616              layer of authentication on top of the  TLS  control  channel  so
2617              that  every packet on the control channel is authenticated by an
2618              HMAC signature and a unique ID for replay protection. This  sig‐
2619              nature  will  also  help protect against DoS (Denial of Service)
2620              attacks. An important rule of thumb in reducing vulnerability to
2621              DoS  attacks is to minimize the amount of resources a potential,
2622              but as yet unauthenticated, client is able to consume.
2623
2624              --tls-auth does this by signing every TLS control channel packet
2625              with  an HMAC signature, including packets which are sent before
2626              the TLS level has had a chance to authenticate the peer. The re‐
2627              sult  is  that  packets  without  the  correct  signature can be
2628              dropped immediately upon reception, before they have a chance to
2629              consume  additional system resources such as by initiating a TLS
2630              handshake. --tls-auth can be strengthened by  adding  the  --re‐
2631              play-persist  option which will keep OpenVPN's replay protection
2632              state in a file so that it is not lost across restarts.
2633
2634              It should be emphasized that this feature is optional  and  that
2635              the key file used with --tls-auth gives a peer nothing more than
2636              the power to initiate a TLS handshake. It is not used to encrypt
2637              or authenticate any tunnel data.
2638
2639              Use  --tls-crypt  instead if you want to use the key file to not
2640              only authenticate, but also encrypt the TLS control channel.
2641
2642       --tls-groups list
2643              A list of allowable groups/curves in order of preference.
2644
2645              Set the allowed elliptic  curves/groups  for  the  TLS  session.
2646              These  groups  are  allowed to be used in signatures and key ex‐
2647              change.
2648
2649              mbedTLS currently allows all known curves per default.
2650
2651              OpenSSL 1.1+ restricts the list per default to
2652
2653                 "X25519:secp256r1:X448:secp521r1:secp384r1".
2654
2655              If you use certificates that use non-standard curves, you  might
2656              need to add them here. If you do not force the ecdh curve by us‐
2657              ing --ecdh-curve, the groups for ecdh will also be  picked  from
2658              this list.
2659
2660              OpenVPN  maps  the  curve  name secp256r1 to prime256v1 to allow
2661              specifying the same tls-groups option for mbedTLS and OpenSSL.
2662
2663              Warning: this option not only affects  elliptic  curve  certifi‐
2664              cates but also the key exchange in TLS 1.3 and using this option
2665              improperly will disable TLS 1.3.
2666
2667       --tls-cert-profile profile
2668              Set the allowed cryptographic algorithms  for  certificates  ac‐
2669              cording to profile.
2670
2671              The following profiles are supported:
2672
2673              insecure
2674                     Identical for mbed TLS to legacy
2675
2676              legacy (default)
2677                     SHA1 and newer, RSA 2048-bit+, any elliptic curve.
2678
2679              preferred
2680                     SHA2 and newer, RSA 2048-bit+, any elliptic curve.
2681
2682              suiteb SHA256/SHA384, ECDSA with P-256 or P-384.
2683
2684              This option is only fully supported for mbed TLS builds. OpenSSL
2685              builds use the following approximation:
2686
2687              insecure
2688                     sets "security level 0"
2689
2690              legacy (default)
2691                     sets "security level 1"
2692
2693              preferred
2694                     sets "security level 2"
2695
2696              suiteb sets "security level 3" and --tls-cipher "SUITEB128".
2697
2698              OpenVPN will migrate to 'preferred' as default  in  the  future.
2699              Please ensure that your keys already comply.
2700
2701       WARNING: --tls-ciphers, --tls-ciphersuites and tls-groups
2702              These  options  are expert features, which - if used correctly -
2703              can improve the security of your VPN connection. But it is  also
2704              easy  to unwittingly use them to carefully align a gun with your
2705              foot, or just break your connection. Use with care!
2706
2707       --tls-cipher l
2708              A list l of allowable TLS ciphers delimited by a colon (":").
2709
2710              These setting can be used to ensure that certain  cipher  suites
2711              are  used (or not used) for the TLS connection. OpenVPN uses TLS
2712              to secure the control channel, over which the keys that are used
2713              to protect the actual VPN traffic are exchanged.
2714
2715              The  supplied  list  of ciphers is (after potential OpenSSL/IANA
2716              name translation) simply supplied to the crypto library.  Please
2717              see the OpenSSL and/or mbed TLS documentation for details on the
2718              cipher list interpretation.
2719
2720              For OpenSSL, the --tls-cipher is used for TLS 1.2 and below.
2721
2722              Use --show-tls to see a list of TLS ciphers  supported  by  your
2723              crypto library.
2724
2725              The default for --tls-cipher is to use mbed TLS's default cipher
2726              list      when      using      mbed       TLS       or       DE‐
2727              FAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA    when
2728              using OpenSSL.
2729
2730       --tls-ciphersuites l
2731              Same as --tls-cipher but for TLS 1.3 and up. mbed TLS has no TLS
2732              1.3 support yet and only the --tls-cipher setting is used.
2733
2734              The  default  for  --tls-ciphersuites  is  to use the crypto li‐
2735              brary's default.
2736
2737       --tls-client
2738              Enable TLS and assume client role during TLS handshake.
2739
2740       --tls-crypt keyfile
2741              Encrypt and authenticate all control channel  packets  with  the
2742              key from keyfile. (See --tls-auth for more background.)
2743
2744              Encrypting (and authenticating) control channel packets:
2745
2746              • provides  more  privacy by hiding the certificate used for the
2747                TLS connection,
2748
2749              • makes it harder to identify OpenVPN traffic as such,
2750
2751              • provides "poor-man's" post-quantum security, against attackers
2752                who  will  never  know the pre-shared key (i.e. no forward se‐
2753                crecy).
2754
2755              In contrast to --tls-auth, --tls-crypt does not require the user
2756              to set --key-direction.
2757
2758              Security Considerations
2759
2760              All  peers  use the same --tls-crypt pre-shared group key to au‐
2761              thenticate and encrypt control channel messages. To ensure  that
2762              IV  collisions  remain  unlikely, this key should not be used to
2763              encrypt more than 2^48 client-to-server or 2^48 server-to-client
2764              control channel messages. A typical initial negotiation is about
2765              10 packets in each direction. Assuming both initial  negotiation
2766              and  renegotiations are at most 2^16 (65536) packets (to be con‐
2767              servative), and (re)negotiations happen  each  minute  for  each
2768              user  (24/7),  this  limits  the  tls-crypt key lifetime to 8171
2769              years divided by the number of users. So a setup with 1000 users
2770              should  rotate  the  key  at least once each eight years. (And a
2771              setup with 8000 users each year.)
2772
2773              If IV collisions were to occur, this could result in  the  secu‐
2774              rity  of  --tls-crypt  degrading  to  the same security as using
2775              --tls-auth.  That is, the control channel  still  benefits  from
2776              the  extra  protection  against active man-in-the-middle-attacks
2777              and DoS attacks, but may  no  longer  offer  extra  privacy  and
2778              post-quantum security on top of what TLS itself offers.
2779
2780              For  large  setups or setups where clients are not trusted, con‐
2781              sider using --tls-crypt-v2 instead. That uses per-client  unique
2782              keys, and thereby improves the bounds to 'rotate a client key at
2783              least once per 8000 years'.
2784
2785       --tls-crypt-v2 keyfile
2786              Use client-specific tls-crypt keys.
2787
2788              For clients, keyfile is a client-specific tls-crypt key. Such  a
2789              key  can be generated using the --genkey tls-crypt-v2-client op‐
2790              tion.
2791
2792              For servers, keyfile is used to unwrap client-specific keys sup‐
2793              plied  by  the  client during connection setup. This key must be
2794              the same as the key used to  generate  the  client-specific  key
2795              (see --genkey tls-crypt-v2-client).
2796
2797              On servers, this option can be used together with the --tls-auth
2798              or --tls-crypt option. In that  case,  the  server  will  detect
2799              whether  the client is using client-specific keys, and automati‐
2800              cally select the right mode.
2801
2802       --tls-crypt-v2-verify cmd
2803              Run command cmd to verify the metadata  of  the  client-specific
2804              tls-crypt-v2  key of a connecting client. This allows server ad‐
2805              ministrators to reject client connections, before  exposing  the
2806              TLS  stack  (including the notoriously dangerous X.509 and ASN.1
2807              stacks) to the connecting client.
2808
2809              OpenVPN supplies the following environment variables to the com‐
2810              mand:
2811
2812script_type is set to tls-crypt-v2-verify
2813
2814metadata_type  is  set to 0 if the metadata was user supplied,
2815                or 1 if it's a 64-bit unix timestamp representing the key cre‐
2816                ation time.
2817
2818metadata_file  contains  the filename of a temporary file that
2819                contains the client metadata.
2820
2821              The command can reject the connection by exiting with a non-zero
2822              exit code.
2823
2824       --tls-exit
2825              Exit on TLS negotiation failure.
2826
2827       --tls-export-cert directory
2828              Store  the  certificates the clients use upon connection to this
2829              directory. This will be done before --tls-verify is called.  The
2830              certificates  will use a temporary name and will be deleted when
2831              the tls-verify script returns. The file name used for  the  cer‐
2832              tificate is available via the peer_cert environment variable.
2833
2834       --tls-server
2835              Enable  TLS  and  assume  server role during TLS handshake. Note
2836              that OpenVPN is designed as a peer-to-peer application. The des‐
2837              ignation  of client or server is only for the purpose of negoti‐
2838              ating the TLS control channel.
2839
2840       --tls-timeout n
2841              Packet retransmit timeout on TLS control channel if no  acknowl‐
2842              edgment  from  remote within n seconds (default 2). When OpenVPN
2843              sends a control packet to its peer, it will expect to receive an
2844              acknowledgement  within  n  seconds  or  it  will retransmit the
2845              packet, subject to a  TCP-like  exponential  backoff  algorithm.
2846              This  parameter  only  applies  to control channel packets. Data
2847              channel packets (which carry encrypted tunnel  data)  are  never
2848              acknowledged, sequenced, or retransmitted by OpenVPN because the
2849              higher level network protocols running on top of the tunnel such
2850              as TCP expect this role to be left to them.
2851
2852       --tls-version-min args
2853              Sets  the  minimum TLS version we will accept from the peer (de‐
2854              fault is "1.0").
2855
2856              Valid syntax:
2857
2858                 tls-version-min version ['or-highest']
2859
2860              Examples for version include 1.0, 1.1, or 1.2. If or-highest  is
2861              specified and version is not recognized, we will only accept the
2862              highest TLS version supported by the local SSL implementation.
2863
2864       --tls-version-max version
2865              Set the maximum TLS version we will use (default is the  highest
2866              version  supported).  Examples  for version include 1.0, 1.1, or
2867              1.2.
2868
2869       --verify-hash args
2870              Specify SHA1 or SHA256 fingerprint for level-1 cert.
2871
2872              Valid syntax:
2873
2874                 verify-hash hash [algo]
2875
2876              The level-1 cert is the CA (or intermediate cert) that signs the
2877              leaf  certificate,  and is one removed from the leaf certificate
2878              in the direction of the root. When accepting a connection from a
2879              peer,  the  level-1 cert fingerprint must match hash or certifi‐
2880              cate verification will fail. Hash is specified as XX:XX:...  For
2881              example:
2882
2883                 AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16
2884
2885              The  algo flag can be either SHA1 or SHA256. If not provided, it
2886              defaults to SHA1.
2887
2888       --verify-x509-name args
2889              Accept connections only if a host's X.509 name is equal to name.
2890              The remote host must also pass all other tests of verification.
2891
2892              Valid syntax:
2893
2894                 verify-x509 name type
2895
2896              Which  X.509  name is compared to name depends on the setting of
2897              type.  type can be subject to match the complete subject DN (de‐
2898              fault),  name  to  match a subject RDN or name-prefix to match a
2899              subject RDN prefix. Which RDN is verified as name depends on the
2900              --x509-username-field option. But it defaults to the common name
2901              (CN), e.g. a certificate with a subject DN
2902
2903                 C=KG, ST=NA, L=Bishkek, CN=Server-1
2904
2905              would be matched by:
2906
2907                 verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1'
2908                 verify-x509-name Server-1 name
2909                 verify-x509-name Server- name-prefix
2910
2911              The last example is useful if you want a client to  only  accept
2912              connections to Server-1, Server-2, etc.
2913
2914              --verify-x509-name  is a useful replacement for the --tls-verify
2915              option to verify the  remote  host,  because  --verify-x509-name
2916              works in a --chroot environment without any dependencies.
2917
2918              Using  a  name  prefix is a useful alternative to managing a CRL
2919              (Certificate Revocation List) on the client, since it allows the
2920              client  to  refuse  all certificates except for those associated
2921              with designated servers.
2922
2923              NOTE:  Test against a name prefix only when you are using  Open‐
2924                     VPN  with a custom CA certificate that is under your con‐
2925                     trol. Never use this option with  type  name-prefix  when
2926                     your  client  certificates  are  signed by a third party,
2927                     such as a commercial web CA.
2928
2929       --x509-track attribute
2930              Save peer X509 attribute value in environment for use by plugins
2931              and  management interface. Prepend a + to attribute to save val‐
2932              ues  from  full  cert  chain.  Values   will   be   encoded   as
2933              X509_<depth>_<attribute>=<value>.  Multiple --x509-track options
2934              can be defined to track multiple attributes.
2935
2936       --x509-username-field args
2937              Field in the X.509 certificate subject to be used as  the  user‐
2938              name (default CN).
2939
2940              Valid syntax:
2941
2942                 x509-username-field [ext:]fieldname
2943
2944              Typically,  this option is specified with fieldname as either of
2945              the following:
2946
2947                 x509-username-field emailAddress
2948                 x509-username-field ext:subjectAltName
2949
2950              The first example uses the value of the  emailAddress  attribute
2951              in  the  certificate's Subject field as the username. The second
2952              example uses the ext: prefix to signify that the X.509 extension
2953              fieldname  subjectAltName  be searched for an rfc822Name (email)
2954              field to be used as the username. In cases where there are  mul‐
2955              tiple  email  addresses in ext:fieldname, the last occurrence is
2956              chosen.
2957
2958              When this option is used,  the  --verify-x509-name  option  will
2959              match against the chosen fieldname instead of the Common Name.
2960
2961              Only  the  subjectAltName and issuerAltName X.509 extensions are
2962              supported.
2963
2964              Please note: This option has a feature  which  will  convert  an
2965              all-lowercase fieldname to uppercase characters, e.g., ou -> OU.
2966              A mixed-case fieldname or one having the  ext:  prefix  will  be
2967              left  as-is.  This  automatic upcasing feature is deprecated and
2968              will be removed in a future release.
2969
2970   PKCS#11 / SmartCard options
2971       --pkcs11-cert-private args
2972              Set if access to certificate object should  be  performed  after
2973              login.  Every provider has its own setting.
2974
2975              Valid syntaxes:
2976
2977                 pkcs11-cert-private 0
2978                 pkcs11-cert-private 1
2979
2980       --pkcs11-id name
2981              Specify  the serialized certificate id to be used. The id can be
2982              gotten by the standalone --show-pkcs11-ids option.
2983
2984       --pkcs11-id-management
2985              Acquire PKCS#11 id from management interface.  In  this  case  a
2986              NEED-STR  'pkcs11-id-request'  real-time  message  will be trig‐
2987              gered, application may use pkcs11-id-count command  to  retrieve
2988              available  number  of certificates, and pkcs11-id-get command to
2989              retrieve certificate id and certificate body.
2990
2991       --pkcs11-pin-cache seconds
2992              Specify how many seconds the PIN can be cached, the  default  is
2993              until the token is removed.
2994
2995       --pkcs11-private-mode mode
2996              Specify  which method to use in order to perform private key op‐
2997              erations.  A different mode can be specified for each  provider.
2998              Mode is encoded as hex number, and can be a mask one of the fol‐
2999              lowing:
3000
3001              0 (default)   Try to determine automatically.
3002
3003              1             Use sign.
3004
3005              2             Use sign recover.
3006
3007              4             Use decrypt.
3008
3009              8             Use unwrap.
3010
3011       --pkcs11-protected-authentication args
3012              Use PKCS#11 protected authentication path, useful for  biometric
3013              and external keypad devices. Every provider has its own setting.
3014
3015              Valid syntaxes:
3016
3017                 pkcs11-protected-authentication 0
3018                 pkcs11-protected-authentication 1
3019
3020       --pkcs11-providers provider
3021              Specify an RSA Security Inc. PKCS #11 Cryptographic Token Inter‐
3022              face (Cryptoki) providers to load. This option can be  used  in‐
3023              stead of --cert, --key and --pkcs12.
3024
3025              If p11-kit is present on the system, its p11-kit-proxy.so module
3026              will  be  loaded  by  default  if  either  the  --pkcs11-id   or
3027              --pkcs11-id-management    options    are    specified    without
3028              --pkcs11-provider being given.
3029
3030       --show-pkcs11-ids args
3031              (Standalone) Show PKCS#11 token object list.
3032
3033              Valid syntax:
3034
3035                 show-pkcs11 [provider] [cert_private]
3036
3037              Specify cert_private as 1 if certificates are stored as  private
3038              objects.
3039
3040              If  p11-kit  is  present on the system, the provider argument is
3041              optional; if omitted the default p11-kit-proxy.so module will be
3042              queried.
3043
3044              --verb  option  can be used BEFORE this option to produce debug‐
3045              ging information.
3046

DATA CHANNEL CIPHER NEGOTIATION

3048       OpenVPN 2.4 and higher have the capability to negotiate the data cipher
3049       that is used to encrypt data packets. This section describes the mecha‐
3050       nism in more detail and the different backwards compatibility mechanism
3051       with older server and clients.
3052
3053   OpenVPN 2.5 and higher behaviour
3054       When  both client and server are at least running OpenVPN 2.5, that the
3055       order of the ciphers of the server's --data-ciphers is used to pick the
3056       the data cipher.  That means that the first cipher in that list that is
3057       also in the client's --data-ciphers list is chosen. If no common cipher
3058       is  found the client is rejected with a AUTH_FAILED message (as seen in
3059       client log):
3060          AUTH: Received control message: AUTH_FAILED,Data channel cipher  ne‐
3061          gotiation failed (no shared cipher)
3062
3063       OpenVPN 2.5 will only allow the ciphers specified in --data-ciphers. To
3064       ensure backwards compatibility also if a cipher is specified using  the
3065       --cipher option it is automatically added to this list. If both options
3066       are unset the default is AES-256-GCM:AES-128-GCM.
3067
3068   OpenVPN 2.4 clients
3069       The negotiation support in OpenVPN 2.4 was the first iteration  of  the
3070       implementation and still had some quirks. Its main goal was "upgrade to
3071       AES-256-GCM when possible".   An  OpenVPN  2.4  client  that  is  built
3072       against  a  crypto  library  that supports AES in GCM mode and does not
3073       have --ncp-disable will always announce  support  for  AES-256-GCM  and
3074       AES-128-GCM to a server by sending IV_NCP=2.
3075
3076       This  only  causes  a  problem if --ncp-ciphers option has been changed
3077       from the default of AES-256-GCM:AES-128-GCM to a value  that  does  not
3078       include   these  two  ciphers.  When  a  OpenVPN  servers  try  to  use
3079       AES-256-GCM or AES-128-GCM the connection will then fail. It is  there‐
3080       fore recommended to always have the AES-256-GCM and AES-128-GCM ciphers
3081       to the --ncp-ciphers options to avoid this behaviour.
3082
3083   OpenVPN 3 clients
3084       Clients     based     on     the     OpenVPN     3.x     library     (‐
3085       https://github.com/openvpn/openvpn3/)   do   not  have  a  configurable
3086       --ncp-ciphers or --data-ciphers option. Instead these clients will  an‐
3087       nounce  support  for  all  their  supported  AEAD ciphers (AES-256-GCM,
3088       AES-128-GCM and in newer versions also Chacha20-Poly1305).
3089
3090       To support OpenVPN 3.x based clients at  least  one  of  these  ciphers
3091       needs to be included in the server's --data-ciphers option.
3092
3093   OpenVPN 2.3 and older clients (and clients with --ncp-disable)
3094       When  a  client without cipher negotiation support connects to a server
3095       the cipher specified with the --cipher option in the client  configura‐
3096       tion must be included in the --data-ciphers option of the server to al‐
3097       low the client to connect.  Otherwise  the  client  will  be  sent  the
3098       AUTH_FAILED message that indicates no shared cipher.
3099
3100       If  the  client  is 2.3 or older and has been configured with the --en‐
3101       able-small  ./configure argument, using data-ciphers-fallback cipher in
3102       the  server  config file with the explicit cipher used by the client is
3103       necessary.
3104
3105   OpenVPN 2.4 server
3106       When a client indicates support for AES-128-GCM and  AES-256-GCM  (with
3107       IV_NCP=2)  an  OpenVPN  2.4  server  will  send the first cipher of the
3108       --ncp-ciphers to the OpenVPN client regardless of what the  cipher  is.
3109       To  emulate the behaviour of an OpenVPN 2.4 client as close as possible
3110       and have compatibility to a setup that depends on  this  quirk,  adding
3111       AES-128-GCM  and  AES-256-GCM  to the client's --data-ciphers option is
3112       required. OpenVPN 2.5+ will only announce the IV_NCP=2  flag  if  those
3113       ciphers are present.
3114
3115   OpenVPN 2.3 and older servers (and servers with --ncp-disable)
3116       The cipher used by the server must be included in --data-ciphers to al‐
3117       low the client connecting to a server without cipher  negotiation  sup‐
3118       port.   (For  compatibility OpenVPN 2.5 will also accept the cipher set
3119       with --cipher)
3120
3121       If the server is 2.3 or older and  has been configured with  the  --en‐
3122       able-small ./configure argument, adding data-ciphers-fallback cipher to
3123       the client config with the explicit cipher used by the server is neces‐
3124       sary.
3125
3126   Blowfish in CBC mode (BF-CBC) deprecation
3127       The  --cipher  option defaulted to BF-CBC in OpenVPN 2.4 and older ver‐
3128       sion. The default was never changed to ensure backwards  compatibility.
3129       In OpenVPN 2.5 this behaviour has now been changed so that if the --ci‐
3130       pher is not explicitly set it does not allow the weak BF-CBC cipher any
3131       more  and  needs  to  explicitly  added as --cipher BFC-CBC or added to
3132       --data-ciphers.
3133
3134       We strongly recommend to switching away from BF-CBC to  a  more  secure
3135       cipher as soon as possible instead.
3136

NETWORK CONFIGURATION

3138       OpenVPN  consists  of  two sides of network configuration.  One side is
3139       the link between the local and remote side, the other side is the  vir‐
3140       tual network adapter (tun/tap device).
3141
3142   Link Options
3143       This  link options section covers options related to the connection be‐
3144       tween the local and the remote host.
3145
3146       --bind keywords
3147              Bind to local address and port. This is the default  unless  any
3148              of --proto tcp-client , --http-proxy or --socks-proxy are used.
3149
3150              If  the  optional  ipv6only keyword is present OpenVPN will bind
3151              only to IPv6 (as opposed to IPv6 and IPv4) when a IPv6 socket is
3152              opened.
3153
3154       --float
3155              Allow  remote  peer to change its IP address and/or port number,
3156              such as due to DHCP (this is the  default  if  --remote  is  not
3157              used).   --float  when specified with --remote allows an OpenVPN
3158              session to initially connect to a peer at a known address,  how‐
3159              ever if packets arrive from a new address and pass all authenti‐
3160              cation tests, the new address will take control of the  session.
3161              This  is  useful when you are connecting to a peer which holds a
3162              dynamic address such as a dial-in user or DHCP client.
3163
3164              Essentially, --float tells OpenVPN to accept authenticated pack‐
3165              ets  from  any address, not only the address which was specified
3166              in the --remote option.
3167
3168       --fragment max
3169              Enable internal datagram fragmentation so that no UDP  datagrams
3170              are sent which are larger than max bytes.
3171
3172              The  max  parameter  is  interpreted  in  the  same  way  as the
3173              --link-mtu parameter, i.e. the UDP packet size after  encapsula‐
3174              tion  overhead  has  been  added  in,  but not including the UDP
3175              header itself.
3176
3177              The --fragment option only makes sense when you  are  using  the
3178              UDP protocol (--proto udp).
3179
3180              --fragment adds 4 bytes of overhead per datagram.
3181
3182              See the --mssfix option below for an important related option to
3183              --fragment.
3184
3185              It should also be noted that this option is not meant to replace
3186              UDP  fragmentation  at the IP stack level. It is only meant as a
3187              last resort when path MTU discovery is broken. Using this option
3188              is  less  efficient  than  fixing path MTU discovery for your IP
3189              link and using native IP fragmentation instead.
3190
3191              Having said that, there are circumstances where using  OpenVPN's
3192              internal  fragmentation capability may be your only option, such
3193              as tunneling a UDP multicast stream  which  requires  fragmenta‐
3194              tion.
3195
3196       --keepalive args
3197              A helper directive designed to simplify the expression of --ping
3198              and --ping-restart.
3199
3200              Valid syntax:
3201
3202                 keepalive interval timeout
3203
3204              This option can be used on both client and server side,  but  it
3205              is  enough to add this on the server side as it will push appro‐
3206              priate --ping and --ping-restart options to the client. If  used
3207              on  both  server  and client, the values pushed from server will
3208              override the client local values.
3209
3210              The timeout argument will be twice as long on the  server  side.
3211              This  ensures  that  a timeout is detected on client side before
3212              the server side drops the connection.
3213
3214              For example, --keepalive 10 60 expands as follows:
3215
3216                 if mode server:
3217                     ping 10                    # Argument: interval
3218                     ping-restart 120           # Argument: timeout*2
3219                     push "ping 10"             # Argument: interval
3220                     push "ping-restart 60"     # Argument: timeout
3221                 else
3222                     ping 10                    # Argument: interval
3223                     ping-restart 60            # Argument: timeout
3224
3225       --link-mtu n
3226              Sets an upper bound on the size of UDP packets  which  are  sent
3227              between  OpenVPN  peers. It's best not to set this parameter un‐
3228              less you know what you're doing.
3229
3230       --local host
3231              Local host name or IP address for bind.  If  specified,  OpenVPN
3232              will  bind  to  this  address only. If unspecified, OpenVPN will
3233              bind to all interfaces.
3234
3235       --lport port
3236              Set local TCP/UDP port number or name. Cannot be  used  together
3237              with --nobind option.
3238
3239       --mark value
3240              Mark encrypted packets being sent with value. The mark value can
3241              be matched in policy routing and packetfilter rules. This option
3242              is  only  supported in Linux and does nothing on other operating
3243              systems.
3244
3245       --mode m
3246              Set  OpenVPN  major  mode.   By   default,   OpenVPN   runs   in
3247              point-to-point  mode  (p2p).  OpenVPN  2.0 introduces a new mode
3248              (server) which implements a multi-client server capability.
3249
3250       --mssfix max
3251              Announce to TCP sessions  running  over  the  tunnel  that  they
3252              should limit their send packet sizes such that after OpenVPN has
3253              encapsulated them, the resulting UDP packet  size  that  OpenVPN
3254              sends  to  its peer will not exceed max bytes. The default value
3255              is 1450.
3256
3257              The max  parameter  is  interpreted  in  the  same  way  as  the
3258              --link-mtu  parameter, i.e. the UDP packet size after encapsula‐
3259              tion overhead has been added  in,  but  not  including  the  UDP
3260              header  itself.   Resulting  packet  would  be  at most 28 bytes
3261              larger for IPv4 and 48 bytes for IPv6 (20/40 bytes for IP header
3262              and  8  bytes for UDP header). Default value of 1450 allows IPv4
3263              packets to be transmitted over a link with MTU  1473  or  higher
3264              without IP level fragmentation.
3265
3266              The  --mssfix option only makes sense when you are using the UDP
3267              protocol for OpenVPN peer-to-peer  communication,  i.e.  --proto
3268              udp.
3269
3270              --mssfix  and  --fragment  can  be  ideally used together, where
3271              --mssfix will try to keep TCP from needing packet  fragmentation
3272              in the first place, and if big packets come through anyhow (from
3273              protocols other than TCP), --fragment will  internally  fragment
3274              them.
3275
3276              Both  --fragment  and --mssfix are designed to work around cases
3277              where Path MTU discovery is broken on the network  path  between
3278              OpenVPN peers.
3279
3280              The  usual  symptom of such a breakdown is an OpenVPN connection
3281              which successfully starts, but then stalls during active usage.
3282
3283              If --fragment and --mssfix are used together, --mssfix will take
3284              its default max parameter from the --fragment max option.
3285
3286              Therefore,  one  could lower the maximum UDP packet size to 1300
3287              (a good first try for solving MTU-related  connection  problems)
3288              with the following options:
3289
3290                 --tun-mtu 1500 --fragment 1300 --mssfix
3291
3292       --mtu-disc type
3293              Should  we  do  Path MTU discovery on TCP/UDP channel? Only sup‐
3294              ported on OSes such as Linux that supports the necessary  system
3295              call to set.
3296
3297              Valid types:
3298
3299              no      Never send DF (Don't Fragment) frames
3300
3301              maybe   Use per-route hints
3302
3303              yes     Always DF (Don't Fragment)
3304
3305       --mtu-test
3306              To  empirically  measure  MTU  on  connection  startup,  add the
3307              --mtu-test option to your configuration. OpenVPN will send  ping
3308              packets  of  various  sizes  to  the remote peer and measure the
3309              largest packets which were successfully received. The --mtu-test
3310              process normally takes about 3 minutes to complete.
3311
3312       --nobind
3313              Do  not  bind to local address and port. The IP stack will allo‐
3314              cate a dynamic port for returning packets. Since  the  value  of
3315              the  dynamic  port could not be known in advance by a peer, this
3316              option is only suitable for peers which will be initiating  con‐
3317              nections by using the --remote option.
3318
3319       --passtos
3320              Set the TOS field of the tunnel packet to what the payload's TOS
3321              is.
3322
3323       --ping n
3324              Ping remote over the TCP/UDP control channel if no packets  have
3325              been  sent  for at least n seconds (specify --ping on both peers
3326              to cause ping packets to be sent in both directions since  Open‐
3327              VPN ping packets are not echoed like IP ping packets). When used
3328              in one of OpenVPN's secure modes (where  --secret,  --tls-server
3329              or  --tls-client  is specified), the ping packet will be crypto‐
3330              graphically secure.
3331
3332              This option has two intended uses:
3333
3334              1. Compatibility with stateful firewalls. The periodic ping will
3335                 ensure that a stateful firewall rule which allows OpenVPN UDP
3336                 packets to pass will not time out.
3337
3338              2. To provide a basis for the remote to test  the  existence  of
3339                 its peer using the --ping-exit option.
3340
3341       --ping-exit n
3342              Causes OpenVPN to exit after n seconds pass without reception of
3343              a ping or other packet from remote. This option can be  combined
3344              with  --inactive,  --ping and --ping-exit to create a two-tiered
3345              inactivity disconnect.
3346
3347              For example,
3348
3349                 openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60
3350
3351              when used on both peers will cause OpenVPN  to  exit  within  60
3352              seconds if its peer disconnects, but will exit after one hour if
3353              no actual tunnel data is exchanged.
3354
3355       --ping-restart n
3356              Similar to --ping-exit, but trigger a SIGUSR1  restart  after  n
3357              seconds  pass  without  reception of a ping or other packet from
3358              remote.
3359
3360              This option is useful in cases where the remote peer has  a  dy‐
3361              namic  IP address and a low-TTL DNS name is used to track the IP
3362              address using a service such as https://www.nsupdate.info/  +  a
3363              dynamic DNS client such as ddclient.
3364
3365              If  the  peer  cannot  be  reached, a restart will be triggered,
3366              causing the hostname used with --remote to  be  re-resolved  (if
3367              --resolv-retry is also specified).
3368
3369              In  server mode, --ping-restart, --inactive or any other type of
3370              internally generated signal will always be applied to individual
3371              client instance objects, never to whole server itself. Note also
3372              in server mode that any internally generated signal which  would
3373              normally  cause a restart, will cause the deletion of the client
3374              instance object instead.
3375
3376              In client mode, the --ping-restart parameter is set to 120  sec‐
3377              onds by default. This default will hold until the client pulls a
3378              replacement value from the server, based on the --keepalive set‐
3379              ting  in the server configuration. To disable the 120 second de‐
3380              fault, set --ping-restart 0 on the client.
3381
3382              See the signals section below for more information on SIGUSR1.
3383
3384              Note that the behavior of SIGUSR1 can be modified by the  --per‐
3385              sist-tun,  --persist-key,  --persist-local-ip  and --persist-re‐
3386              mote-ip options.
3387
3388              Also note that --ping-exit and --ping-restart are  mutually  ex‐
3389              clusive and cannot be used together.
3390
3391       --ping-timer-rem
3392              Run the --ping-exit / --ping-restart timer only if we have a re‐
3393              mote address. Use this option if you are starting the daemon  in
3394              listen  mode  (i.e.  without an explicit --remote peer), and you
3395              don't want to start clocking timeouts until a remote  peer  con‐
3396              nects.
3397
3398       --proto p
3399              Use protocol p for communicating with remote host. p can be udp,
3400              tcp-client, or tcp-server. You can also  limit  OpenVPN  to  use
3401              only  IPv4  or  only  IPv6 by specifying p as udp4, tcp4-client,
3402              tcp4-server or udp6, tcp6-client, tcp6-server, respectively.
3403
3404              The default protocol is udp when --proto is not specified.
3405
3406              For UDP operation, --proto  udp  should  be  specified  on  both
3407              peers.
3408
3409              For  TCP operation, one peer must use --proto tcp-server and the
3410              other  must  use  --proto  tcp-client.  A  peer   started   with
3411              tcp-server  will wait indefinitely for an incoming connection. A
3412              peer started with tcp-client will attempt  to  connect,  and  if
3413              that  fails, will sleep for 5 seconds (adjustable via the --con‐
3414              nect-retry option) and try again infinite or  up  to  N  retries
3415              (adjustable via the --connect-retry-max option). Both TCP client
3416              and server will simulate a SIGUSR1 restart signal if either side
3417              resets the connection.
3418
3419              OpenVPN is designed to operate optimally over UDP, but TCP capa‐
3420              bility is provided for situations where UDP cannot be  used.  In
3421              comparison with UDP, TCP will usually be somewhat less efficient
3422              and less robust when used over unreliable or congested networks.
3423
3424              This article outlines some of problems with  tunneling  IP  over
3425              TCP: http://sites.inka.de/sites/bigred/devel/tcp-tcp.html
3426
3427              There  are certain cases, however, where using TCP may be advan‐
3428              tageous from a security and robustness perspective, such as tun‐
3429              neling  non-IP  or application-level UDP protocols, or tunneling
3430              protocols which don't possess a built-in reliability layer.
3431
3432       --port port
3433              TCP/UDP port number or port name for both local and remote (sets
3434              both --lport and --rport options to given port). The current de‐
3435              fault of 1194 represents the official IANA port  number  assign‐
3436              ment  for  OpenVPN  and  has been used since version 2.0-beta17.
3437              Previous versions used port 5000 as the default.
3438
3439       --rport port
3440              Set TCP/UDP port number or name used by the --remote option. The
3441              port can also be set directly using the --remote option.
3442
3443       --replay-window args
3444              Modify  the  replay protection sliding-window size and time win‐
3445              dow.
3446
3447              Valid syntax:
3448
3449                 replay-window n [t]
3450
3451              Use a replay protection sliding-window of size n and a time win‐
3452              dow of t seconds.
3453
3454              By default n is 64 (the IPSec default) and t is 15 seconds.
3455
3456              This  option  is  only  relevant  in  UDP mode, i.e. when either
3457              --proto udp is specified, or no --proto option is specified.
3458
3459              When OpenVPN tunnels IP packets over UDP, there is the possibil‐
3460              ity that packets might be dropped or delivered out of order. Be‐
3461              cause OpenVPN, like IPSec, is  emulating  the  physical  network
3462              layer,  it will accept an out-of-order packet sequence, and will
3463              deliver such packets in the same order they were received to the
3464              TCP/IP  protocol  stack,  provided  they  satisfy  several  con‐
3465              straints.
3466
3467              a. The packet cannot be a replay (unless --no-replay  is  speci‐
3468                 fied, which disables replay protection altogether).
3469
3470              b. If a packet arrives out of order, it will only be accepted if
3471                 the difference between its sequence number  and  the  highest
3472                 sequence number received so far is less than n.
3473
3474              c. If a packet arrives out of order, it will only be accepted if
3475                 it arrives no later than t seconds after any packet  contain‐
3476                 ing a higher sequence number.
3477
3478              If  you  are using a network link with a large pipeline (meaning
3479              that the product of bandwidth and latency is high), you may want
3480              to use a larger value for n. Satellite links in particular often
3481              require this.
3482
3483              If you run OpenVPN at --verb 4, you will see  the  message  "Re‐
3484              play-window  backtrack  occurred [x]" every time the maximum se‐
3485              quence number backtrack seen thus far  increases.  This  can  be
3486              used to calibrate n.
3487
3488              There  is some controversy on the appropriate method of handling
3489              packet reordering at the security layer.
3490
3491              Namely, to what extent should the security layer protect the en‐
3492              capsulated  protocol  from attacks which masquerade as the kinds
3493              of normal packet loss and reordering that  occur  over  IP  net‐
3494              works?
3495
3496              The  IPSec  and  OpenVPN  approach is to allow packet reordering
3497              within a certain fixed sequence number window.
3498
3499              OpenVPN adds to the IPSec model by limiting the window  size  in
3500              time as well as sequence space.
3501
3502              OpenVPN  also  adds  TCP  transport as an option (not offered by
3503              IPSec) in which case OpenVPN can adopt a  very  strict  attitude
3504              towards  message  deletion and reordering: Don't allow it. Since
3505              TCP guarantees reliability, any packet loss or reordering  event
3506              can be assumed to be an attack.
3507
3508              In  this  sense, it could be argued that TCP tunnel transport is
3509              preferred when tunneling non-IP  or  UDP  application  protocols
3510              which  might  be  vulnerable to a message deletion or reordering
3511              attack which falls within the normal operational  parameters  of
3512              IP networks.
3513
3514              So  I  would  make  the statement that one should never tunnel a
3515              non-IP protocol or UDP application protocol  over  UDP,  if  the
3516              protocol might be vulnerable to a message deletion or reordering
3517              attack that falls within the normal operating parameters of what
3518              is  to  be  expected  from the physical IP layer. The problem is
3519              easily fixed by simply using TCP as the VPN transport layer.
3520
3521       --replay-persist file
3522              Persist replay-protection state across sessions  using  file  to
3523              save and reload the state.
3524
3525              This  option  will strengthen protection against replay attacks,
3526              especially when you are using OpenVPN in a dynamic context (such
3527              as  with  --inetd)  when OpenVPN sessions are frequently started
3528              and stopped.
3529
3530              This option will keep a disk copy of the current replay  protec‐
3531              tion  state  (i.e. the most recent packet timestamp and sequence
3532              number received from the remote peer), so  that  if  an  OpenVPN
3533              session  is stopped and restarted, it will reject any replays of
3534              packets which were already received by the prior session.
3535
3536              This option only makes sense when replay protection  is  enabled
3537              (the  default)  and you are using either --secret (shared-secret
3538              key mode) or TLS mode with --tls-auth.
3539
3540       --socket-flags flags
3541              Apply the given flags to  the  OpenVPN  transport  socket.  Cur‐
3542              rently, only TCP_NODELAY is supported.
3543
3544              The  TCP_NODELAY  socket  flag is useful in TCP mode, and causes
3545              the kernel to send tunnel packets immediately over the TCP  con‐
3546              nection  without  trying to group several smaller packets into a
3547              larger packet.  This can result in a considerably improvement in
3548              latency.
3549
3550              This  option  is  pushable  from server to client, and should be
3551              used on both client and server for maximum effect.
3552
3553       --tcp-nodelay
3554              This macro sets the TCP_NODELAY socket flag  on  the  server  as
3555              well  as  pushes  it to connecting clients. The TCP_NODELAY flag
3556              disables the Nagle algorithm on TCP sockets causing  packets  to
3557              be transmitted immediately with low latency, rather than waiting
3558              a short period of time in order  to  aggregate  several  packets
3559              into  a larger containing packet.  In VPN applications over TCP,
3560              TCP_NODELAY is generally a good latency optimization.
3561
3562              The macro expands as follows:
3563
3564                 if mode server:
3565                     socket-flags TCP_NODELAY
3566                     push "socket-flags TCP_NODELAY"
3567
3568   Virtual Network Adapter (VPN interface)
3569       Options in this section relates to configuration of the virtual tun/tap
3570       network  interface,  including  setting  the VPN IP address and network
3571       routing.
3572
3573       --bind-dev device
3574              (Linux only) Set device to bind the server socket to  a  Virtual
3575              Routing and Forwarding device
3576
3577       --block-ipv6
3578              On the client, instead of sending IPv6 packets over the VPN tun‐
3579              nel, all IPv6 packets are answered with an ICMPv6 no route  host
3580              message.  On  the  server, all IPv6 packets from clients are an‐
3581              swered with an ICMPv6 no route to host message. This options  is
3582              intended for cases when IPv6 should be blocked and other options
3583              are not available. --block-ipv6 will  use  the  remote  IPv6  as
3584              source  address of the ICMPv6 packets if set, otherwise will use
3585              fe80::7 as source address.
3586
3587              For this option to make sense you actually have to route traffic
3588              to  the  tun interface. The following example config block would
3589              send all IPv6 traffic to OpenVPN and answer all requests with no
3590              route  to host, effectively blocking IPv6 (to avoid IPv6 connec‐
3591              tions from dual-stacked clients  leaking  around  IPv4-only  VPN
3592              services).
3593
3594              Client config
3595
3596                        --ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1
3597                        --redirect-gateway ipv6
3598                        --block-ipv6
3599
3600              Server config
3601                     Push a "valid" ipv6 config to the client and block on the
3602                     server
3603
3604                        --push "ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1"
3605                        --push "redirect-gateway ipv6"
3606                        --block-ipv6
3607
3608              Note: this option does  not  influence  traffic  sent  from  the
3609              server  towards  the  client  (neither  on the server nor on the
3610              client side).  This is not seen as necessary,  as  such  traffic
3611              can be most easily avoided by not configuring IPv6 on the server
3612              tun, or setting up a server-side firewall rule.
3613
3614       --dev device
3615              TUN/TAP virtual network device which can be tunX, tapX, null  or
3616              an  arbitrary  name  string  (X can be omitted for a dynamic de‐
3617              vice.)
3618
3619              See examples section below for an example on setting  up  a  TUN
3620              device.
3621
3622              You  must  use either tun devices on both ends of the connection
3623              or tap devices on both ends. You cannot mix them, as they repre‐
3624              sent different underlying network layers:
3625
3626              tun    devices encapsulate IPv4 or IPv6 (OSI Layer 3)
3627
3628              tap    devices encapsulate Ethernet 802.3 (OSI Layer 2).
3629
3630              Valid syntaxes:
3631
3632                 dev tun2
3633                 dev tap4
3634                 dev ovpn
3635
3636              When  the device name starts with tun or tap, the device type is
3637              extracted automatically.  Otherwise the --dev-type option  needs
3638              to be added as well.
3639
3640       --dev-node node
3641              Explicitly  set  the device node rather than using /dev/net/tun,
3642              /dev/tun, /dev/tap, etc. If OpenVPN cannot  figure  out  whether
3643              node  is  a TUN or TAP device based on the name, you should also
3644              specify --dev-type tun or --dev-type tap.
3645
3646              Under Mac OS X this option can be used to  specify  the  default
3647              tun  implementation.  Using  --dev-node utun forces usage of the
3648              native Darwin tun kernel support. Use --dev-node utunN to select
3649              a   specific   utun   instance.  To  force  using  the  tun.kext
3650              (/dev/tunX) use --dev-node tun. When not specifying a --dev-node
3651              option  openvpn  will  first  try to open utun, and fall back to
3652              tun.kext.
3653
3654              On Windows systems, select the TAP-Win32 adapter which is  named
3655              node in the Network Connections Control Panel or the raw GUID of
3656              the adapter enclosed by braces. The --show-adapters option under
3657              Windows  can  also  be used to enumerate all available TAP-Win32
3658              adapters and will show  both  the  network  connections  control
3659              panel name and the GUID for each TAP-Win32 adapter.
3660
3661       --dev-type device-type
3662              Which  device  type are we using? device-type should be tun (OSI
3663              Layer 3) or tap (OSI Layer 2).  Use  this  option  only  if  the
3664              TUN/TAP device used with --dev does not begin with tun or tap.
3665
3666       --dhcp-option args
3667              Set additional network parameters on supported platforms. May be
3668              specified on the client or pushed from the  server.  On  Windows
3669              these  options are handled by the tap-windows6 driver by default
3670              or directly by OpenVPN if dhcp is disabled or the wintun  driver
3671              is  in use. The OpenVPN for Android client also handles them in‐
3672              ternally.
3673
3674              On all other platforms these  options  are  only  saved  in  the
3675              client's  environment  under  the name foreign_option_{n} before
3676              the --up script is called. A plugin or an --up  script  must  be
3677              used to pick up and interpret these as required. Many Linux dis‐
3678              tributions include such scripts and some third-party user inter‐
3679              faces  such  as  tunnelblick also come with scripts that process
3680              these options.
3681
3682              Valid syntax:
3683
3684                 dhcp-options type [parm]
3685
3686              DOMAIN name
3687                     Set Connection-specific DNS Suffix to name.
3688
3689              ADAPTER_DOMAIN_SUFFIX name
3690                     Alias to DOMAIN.  This  is  a  compatibility  option,  it
3691                     should not be used in new deployments.
3692
3693              DOMAIN-SEARCH name
3694                     Add  name  to the domain search list.  Repeat this option
3695                     to add more entries. Up to 10 domains are supported.
3696
3697              DNS address
3698                     Set primary domain name server IPv4 or IPv6 address.  Re‐
3699                     peat this option to set secondary DNS server addresses.
3700
3701                     Note: DNS IPv6 servers are currently set using netsh (the
3702                     existing DHCP code can only do IPv4 DHCP, and that proto‐
3703                     col  only  permits  IPv4  addresses anywhere). The option
3704                     will be put into the environment, so an --up script could
3705                     act upon it if needed.
3706
3707              WINS address
3708                     Set primary WINS server address (NetBIOS over TCP/IP Name
3709                     Server).  Repeat this option to set secondary WINS server
3710                     addresses.
3711
3712              NBDD address
3713                     Set  primary  NBDD  server  address  (NetBIOS over TCP/IP
3714                     Datagram Distribution Server). Repeat this option to  set
3715                     secondary NBDD server addresses.
3716
3717              NTP address
3718                     Set  primary  NTP server address (Network Time Protocol).
3719                     Repeat this option to set secondary NTP server addresses.
3720
3721              NBT type
3722                     Set NetBIOS over TCP/IP Node type. Possible options:
3723
3724                     1      b-node (broadcasts)
3725
3726                     2      p-node (point-to-point  name  queries  to  a  WINS
3727                            server)
3728
3729                     4      m-node (broadcast then query name server)
3730
3731                     8      h-node (query name server, then broadcast).
3732
3733              NBS scope-id
3734                     Set  NetBIOS  over  TCP/IP Scope. A NetBIOS Scope ID pro‐
3735                     vides an extended naming service  for  the  NetBIOS  over
3736                     TCP/IP  (Known  as  NBT) module. The primary purpose of a
3737                     NetBIOS scope ID is to isolate NetBIOS traffic on a  sin‐
3738                     gle  network  to  only  those nodes with the same NetBIOS
3739                     scope ID. The NetBIOS scope ID is a character string that
3740                     is  appended to the NetBIOS name. The NetBIOS scope ID on
3741                     two hosts must match, or the two hosts will not  be  able
3742                     to communicate.  The NetBIOS Scope ID also allows comput‐
3743                     ers to use the same computer name, as they have different
3744                     scope  IDs.  The  Scope  ID becomes a part of the NetBIOS
3745                     name, making the name unique. (This description  of  Net‐
3746                     BIOS scopes courtesy of NeonSurge@abyss.com)
3747
3748              DISABLE-NBT
3749                     Disable Netbios-over-TCP/IP.
3750
3751       --ifconfig args
3752              Set  TUN/TAP  adapter  parameters. It requires the IP address of
3753              the local VPN endpoint. For TUN devices in point-to-point  mode,
3754              the  next  argument must be the VPN IP address of the remote VPN
3755              endpoint. For TAP devices, or TUN devices used  with  --topology
3756              subnet,  the  second  argument is the subnet mask of the virtual
3757              network segment which is being created or connected to.
3758
3759              For TUN devices, which facilitate virtual point-to-point IP con‐
3760              nections (when used in --topology net30 or p2p mode), the proper
3761              usage of --ifconfig is to use two private IP addresses which are
3762              not  a member of any existing subnet which is in use. The IP ad‐
3763              dresses may be consecutive and should have their order  reversed
3764              on  the  remote  peer.  After the VPN is established, by pinging
3765              rn, you will be pinging across the VPN.
3766
3767              For TAP devices, which provide the  ability  to  create  virtual
3768              ethernet  segments,  or  TUN  devices  in --topology subnet mode
3769              (which create virtual "multipoint networks"), --ifconfig is used
3770              to set an IP address and subnet mask just as a physical ethernet
3771              adapter would be similarly configured. If you are attempting  to
3772              connect  to  a remote ethernet bridge, the IP address and subnet
3773              should be set to values which would be valid on the the  bridged
3774              ethernet  segment  (note also that DHCP can be used for the same
3775              purpose).
3776
3777              This option, while primarily a proxy for  the  ifconfig(8)  com‐
3778              mand,  is  designed  to simplify TUN/TAP tunnel configuration by
3779              providing a standard interface to the different ifconfig  imple‐
3780              mentations on different platforms.
3781
3782              --ifconfig  parameters which are IP addresses can also be speci‐
3783              fied as a DNS or /etc/hosts file resolvable name.
3784
3785              For TAP devices, --ifconfig should not be used if the TAP inter‐
3786              face will be getting an IP address lease from a DHCP server.
3787
3788              Examples:
3789
3790                 # tun device in net30/p2p mode
3791                 ifconfig 10.8.0.2 10.8.0.1
3792
3793                 # tun/tap device in subnet mode
3794                 ifconfig 10.8.0.2 255.255.255.0
3795
3796       --ifconfig-ipv6 args
3797              Configure an IPv6 address on the tun device.
3798
3799              Valid syntax:
3800
3801                 ifconfig-ipv6 ipv6addr/bits [ipv6remote]
3802
3803              The  ipv6addr/bits argument is the IPv6 address to use. The sec‐
3804              ond parameter is used as route target  for  --route-ipv6  if  no
3805              gateway is specified.
3806
3807              The --topology option has no influence with --ifconfig-ipv6
3808
3809       --ifconfig-noexec
3810              Don't  actually  execute  ifconfig/netsh  commands, instead pass
3811              --ifconfig parameters to scripts using environmental variables.
3812
3813       --ifconfig-nowarn
3814              Don't output an options consistency check warning if  the  --if‐
3815              config  option  on this side of the connection doesn't match the
3816              remote side.  This is useful when you want to retain the overall
3817              benefits  of  the  options  consistency  check  (also see --dis‐
3818              able-occ option) while only disabling the ifconfig component  of
3819              the check.
3820
3821              For  example,  if  you have a configuration where the local host
3822              uses --ifconfig but the  remote  host  does  not,  use  --ifcon‐
3823              fig-nowarn on the local host.
3824
3825              This  option  will also silence warnings about potential address
3826              conflicts which occasionally annoy  more  experienced  users  by
3827              triggering "false positive" warnings.
3828
3829       --lladdr address
3830              Specify  the  link layer address, more commonly known as the MAC
3831              address.  Only applied to TAP devices.
3832
3833       --persist-tun
3834              Don't close and reopen TUN/TAP device  or  run  up/down  scripts
3835              across SIGUSR1 or --ping-restart restarts.
3836
3837              SIGUSR1  is a restart signal similar to SIGHUP, but which offers
3838              finer-grained control over reset options.
3839
3840       --redirect-gateway flags
3841              Automatically execute routing commands to cause all outgoing  IP
3842              traffic to be redirected over the VPN. This is a client-side op‐
3843              tion.
3844
3845              This option performs three steps:
3846
3847              1. Create a static route for the --remote address which forwards
3848                 to the pre-existing default gateway. This is done so that (3)
3849                 will not create a routing loop.
3850
3851              2. Delete the default gateway route.
3852
3853              3. Set the new default gateway to be the  VPN  endpoint  address
3854                 (derived  either from --route-gateway or the second parameter
3855                 to --ifconfig when --dev tun is specified).
3856
3857              When the tunnel is torn down, all of the  above  steps  are  re‐
3858              versed so that the original default route is restored.
3859
3860              Option flags:
3861
3862              local  Add  the  local  flag  if both OpenVPN peers are directly
3863                     connected via a common subnet, such as with wireless. The
3864                     local flag will cause step (1) above to be omitted.
3865
3866              autolocal
3867                     Try  to  automatically  determine whether to enable local
3868                     flag above.
3869
3870              def1   Use this flag to override the default  gateway  by  using
3871                     0.0.0.0/1 and 128.0.0.0/1 rather than 0.0.0.0/0. This has
3872                     the benefit of overriding but not wiping out the original
3873                     default gateway.
3874
3875              bypass-dhcp
3876                     Add  a  direct route to the DHCP server (if it is non-lo‐
3877                     cal) which bypasses  the  tunnel  (Available  on  Windows
3878                     clients, may not be available on non-Windows clients).
3879
3880              bypass-dns
3881                     Add  a  direct  route  to  the DNS server(s) (if they are
3882                     non-local) which bypasses the tunnel (Available  on  Win‐
3883                     dows   clients,  may  not  be  available  on  non-Windows
3884                     clients).
3885
3886              block-local
3887                     Block access to local LAN when the tunnel is active,  ex‐
3888                     cept  for the LAN gateway itself. This is accomplished by
3889                     routing the local LAN (except for  the  LAN  gateway  ad‐
3890                     dress) into the tunnel.
3891
3892              ipv6   Redirect IPv6 routing into the tunnel. This works similar
3893                     to the def1 flag, that is, more specific IPv6 routes  are
3894                     added  (2000::/4, 3000::/4), covering the whole IPv6 uni‐
3895                     cast space.
3896
3897              !ipv4  Do not redirect IPv4 traffic - typically used in the flag
3898                     pair ipv6 !ipv4 to redirect IPv6-only.
3899
3900       --redirect-private flags
3901              Like  --redirect-gateway, but omit actually changing the default
3902              gateway.  Useful when pushing private subnets.
3903
3904       --route args
3905              Add route to routing table after connection is established. Mul‐
3906              tiple routes can be specified. Routes will be automatically torn
3907              down in reverse order prior to TUN/TAP device close.
3908
3909              Valid syntaxes:
3910
3911                 route network/IP
3912                 route network/IP netmask
3913                 route network/IP netmask gateway
3914                 route network/IP netmask gateway metric
3915
3916              This option is intended as a convenience proxy for the  route(8)
3917              shell  command, while at the same time providing portable seman‐
3918              tics across OpenVPN's platform space.
3919
3920              netmask
3921                     defaults to 255.255.255.255 when not given
3922
3923              gateway
3924                     default taken from --route-gateway or the second  parame‐
3925                     ter to --ifconfig when --dev tun is specified.
3926
3927              metric default taken from --route-metric if set, otherwise 0.
3928
3929              The  default can be specified by leaving an option blank or set‐
3930              ting it to default.
3931
3932              The network and gateway parameters can also be  specified  as  a
3933              DNS  or /etc/hosts file resolvable name, or as one of three spe‐
3934              cial keywords:
3935
3936              vpn_gateway
3937                     The remote VPN  endpoint  address  (derived  either  from
3938                     --route-gateway  or  the  second  parameter to --ifconfig
3939                     when --dev tun is specified).
3940
3941              net_gateway
3942                     The pre-existing IP default gateway, read from the  rout‐
3943                     ing table (not supported on all OSes).
3944
3945              remote_host
3946                     The  --remote  address  if OpenVPN is being run in client
3947                     mode, and is undefined in server mode.
3948
3949       --route-delay args
3950              Valid syntaxes:
3951
3952                 route-delay
3953                 route-delay n
3954                 route-delay n m
3955
3956              Delay n seconds (default 0) after connection establishment,  be‐
3957              fore  adding routes. If n is 0, routes will be added immediately
3958              upon connection  establishment.  If  --route-delay  is  omitted,
3959              routes  will  be added immediately after TUN/TAP device open and
3960              --up script execution, before any --user  or  --group  privilege
3961              downgrade (or --chroot execution.)
3962
3963              This  option is designed to be useful in scenarios where DHCP is
3964              used to set tap adapter addresses. The delay will give the  DHCP
3965              handshake time to complete before routes are added.
3966
3967              On  Windows, --route-delay tries to be more intelligent by wait‐
3968              ing w seconds (default 30 by default) for the TAP-Win32  adapter
3969              to come up before adding routes.
3970
3971       --route-ipv6 args
3972              Setup IPv6 routing in the system to send the specified IPv6 net‐
3973              work into OpenVPN's tun.
3974
3975              Valid syntax:
3976
3977                 route-ipv6 ipv6addr/bits [gateway] [metric]
3978
3979              The gateway parameter is only used for IPv6  routes  across  tap
3980              devices,  and  if  missing,  the  ipv6remote field from --ifcon‐
3981              fig-ipv6 or --route-ipv6-gateway is used.
3982
3983       --route-gateway arg
3984              Specify a default gateway for use with --route.
3985
3986              If dhcp is specified as the parameter, the gateway address  will
3987              be   extracted   from   a  DHCP  negotiation  with  the  OpenVPN
3988              server-side LAN.
3989
3990              Valid syntaxes:
3991
3992                 route-gateway gateway
3993                 route-gateway dhcp
3994
3995       --route-ipv6-gateway gw
3996              Specify a default gateway gw for use with --route-ipv6.
3997
3998       --route-metric m
3999              Specify a default metric m for use with --route.
4000
4001       --route-noexec
4002              Don't add or remove routes automatically. Instead pass routes to
4003              --route-up script using environmental variables.
4004
4005       --route-nopull
4006              When  used  with  --client  or  --pull, accept options pushed by
4007              server EXCEPT for routes,  block-outside-dns  and  dhcp  options
4008              like DNS servers.
4009
4010              When used on the client, this option effectively bars the server
4011              from adding routes to the client's routing table,  however  note
4012              that this option still allows the server to set the TCP/IP prop‐
4013              erties of the client's TUN/TAP interface.
4014
4015       --topology mode
4016              Configure virtual addressing topology when running in --dev  tun
4017              mode. This directive has no meaning in --dev tap mode, which al‐
4018              ways uses a subnet topology.
4019
4020              If you set this  directive  on  the  server,  the  --server  and
4021              --server-bridge  directives  will automatically push your chosen
4022              topology setting to clients as well. This directive can also  be
4023              manually  pushed  to clients. Like the --dev directive, this di‐
4024              rective must always be compatible between client and server.
4025
4026              mode can be one of:
4027
4028              net30  Use a point-to-point topology, by allocating one /30 sub‐
4029                     net  per client. This is designed to allow point-to-point
4030                     semantics when some or  all  of  the  connecting  clients
4031                     might  be Windows systems. This is the default on OpenVPN
4032                     2.0.
4033
4034              p2p    Use a point-to-point topology where the  remote  endpoint
4035                     of  the client's tun interface always points to the local
4036                     endpoint of the server's tun interface. This  mode  allo‐
4037                     cates a single IP address per connecting client. Only use
4038                     when none of the connecting clients are Windows systems.
4039
4040              subnet Use a subnet rather than  a  point-to-point  topology  by
4041                     configuring the tun interface with a local IP address and
4042                     subnet mask, similar to the topology used  in  --dev  tap
4043                     and  ethernet bridging mode. This mode allocates a single
4044                     IP address per connecting client and works on Windows  as
4045                     well.  Only available when server and clients are OpenVPN
4046                     2.1 or higher, or OpenVPN 2.0.x which has  been  manually
4047                     patched  with the --topology directive code. When used on
4048                     Windows, requires version 8.2 or higher of the  TAP-Win32
4049                     driver.  When  used on *nix, requires that the tun driver
4050                     supports an ifconfig(8) command which sets a  subnet  in‐
4051                     stead of a remote endpoint IP address.
4052
4053              Note:  Using --topology subnet changes the interpretation of the
4054              arguments of --ifconfig to mean  "address  netmask",  no  longer
4055              "local remote".
4056
4057       --tun-mtu n
4058              Take  the TUN device MTU to be n and derive the link MTU from it
4059              (default 1500). In most cases, you will probably want  to  leave
4060              this parameter set to its default value.
4061
4062              The  MTU  (Maximum  Transmission  Units) is the maximum datagram
4063              size in bytes that can be sent unfragmented  over  a  particular
4064              network  path.  OpenVPN requires that packets on the control and
4065              data channels be sent unfragmented.
4066
4067              MTU problems often manifest themselves as connections which hang
4068              during periods of active usage.
4069
4070              It's  best to use the --fragment and/or --mssfix options to deal
4071              with MTU sizing issues.
4072
4073       --tun-mtu-extra n
4074              Assume that the TUN/TAP device might return as many as  n  bytes
4075              more than the --tun-mtu size on read. This parameter defaults to
4076              0, which is sufficient for most TUN devices. TAP devices may in‐
4077              troduce  additional  overhead  in  excess of the MTU size, and a
4078              setting of 32 is the default when TAP devices are used. This pa‐
4079              rameter  only  controls internal OpenVPN buffer sizing, so there
4080              is no transmission  overhead  associated  with  using  a  larger
4081              value.
4082
4083   TUN/TAP standalone operations
4084       These  two  standalone  operations  will  require  --dev and optionally
4085       --user and/or --group.
4086
4087       --mktun
4088              (Standalone) Create a persistent tunnel on platforms which  sup‐
4089              port them such as Linux. Normally TUN/TAP tunnels exist only for
4090              the period of time that an application has them open.  This  op‐
4091              tion  takes  advantage  of the TUN/TAP driver's ability to build
4092              persistent tunnels that live through multiple instantiations  of
4093              OpenVPN and die only when they are deleted or the machine is re‐
4094              booted.
4095
4096              One of the advantages of persistent tunnels is that they  elimi‐
4097              nate  the  need  for separate --up and --down scripts to run the
4098              appropriate ifconfig(8) and route(8)  commands.  These  commands
4099              can  be placed in the the same shell script which starts or ter‐
4100              minates an OpenVPN session.
4101
4102              Another  advantage  is  that  open   connections   through   the
4103              TUN/TAP-based  tunnel  will  not  be  reset  if the OpenVPN peer
4104              restarts. This can be useful to provide uninterrupted connectiv‐
4105              ity  through  the  tunnel  in  the  event of a DHCP reset of the
4106              peer's public IP address (see the --ipchange option above).
4107
4108              One disadvantage of persistent tunnels is that it is  harder  to
4109              automatically  configure  their  MTU  value  (see --link-mtu and
4110              --tun-mtu above).
4111
4112              On some platforms such as Windows, TAP-Win32 tunnels are persis‐
4113              tent by default.
4114
4115       --rmtun
4116              (Standalone) Remove a persistent tunnel.
4117
4118   Virtual Routing and Forwarding
4119       Options in this section relates to configuration of virtual routing and
4120       forwarding in combination with the underlying operating system.
4121
4122       As of today this is only supported on Linux, a kernel >= 4.9 is  recom‐
4123       mended.
4124
4125       This  could  come in handy when for example the external network should
4126       be only used as a means to connect to some VPN endpoints and all  regu‐
4127       lar traffic should only be routed through any tunnel(s).  This could be
4128       achieved by setting up a VRF and configuring the interface connected to
4129       the  external  network  to  be part of the VRF. The examples below will
4130       cover this setup.
4131
4132       Another option would be to put the tun/tap interface into a  VRF.  This
4133       could  be done by an up-script which uses the ip link set command shown
4134       below.
4135
4136   VRF setup with iproute2
4137       Create VRF vrf_external and map it to routing table 1023
4138
4139          ip link add vrf_external type vrf table 1023
4140
4141       Move eth0 into vrf_external
4142
4143          ip link set master vrf_external dev eth0
4144
4145       Any prefixes configured on eth0 will  be  moved  from  the  :code`main`
4146       routing table into routing table 1023
4147
4148   VRF setup with ifupdown
4149       For Debian based Distributions ifupdown2 provides an almost drop-in re‐
4150       placement for ifupdown including VRFs and other features.  A configura‐
4151       tion  for  an  interface eth0 being part of VRF code:vrf_external could
4152       look like this:
4153
4154          auto eth0
4155          iface eth0
4156              address 192.0.2.42/24
4157              address 2001:db8:08:15::42/64
4158              gateway 192.0.2.1
4159              gateway 2001:db8:08:15::1
4160              vrf vrf_external
4161
4162          auto vrf_external
4163          iface vrf_external
4164              vrf-table 1023
4165
4166   OpenVPN configuration
4167       The OpenVPN configuration needs to contain this line:
4168
4169          bind-dev vrf_external
4170
4171   Further reading
4172       Wikipedia        has        nice         page         one         VRFs:
4173       https://en.wikipedia.org/wiki/Virtual_routing_and_forwarding
4174
4175       This  talk  from the Network Track of FrOSCon 2018 provides an overview
4176       about advanced layer 2 and layer 3 features of Linux
4177
4178          • Slides:
4179            https://www.slideshare.net/BarbarossaTM/l2l3-fr-fortgeschrittene-helle-und-dunkle-magie-im-linuxnetzwerkstack
4180
4181          • Video                                                    (german):
4182            https://media.ccc.de/v/froscon2018-2247-l2_l3_fur_fortgeschrittene_-_helle_und_dunkle_magie_im_linux-netzwerkstack
4183

SCRIPTING INTEGRATION

4185       OpenVPN can execute external scripts in various phases of the  lifetime
4186       of the OpenVPN process.
4187
4188   Script Order of Execution
4189       1.  --up
4190
4191           Executed after TCP/UDP socket bind and TUN/TAP open.
4192
4193       2.  --tls-verify
4194
4195           Executed when we have a still untrusted remote peer.
4196
4197       3.  --ipchange
4198
4199           Executed  after  connection  authentication,  or  remote IP address
4200           change.
4201
4202       4.  --client-connect
4203
4204           Executed in --mode server mode immediately after client authentica‐
4205           tion.
4206
4207       5.  --route-up
4208
4209           Executed after connection authentication, either immediately after,
4210           or some number of seconds after as defined by the --route-delay op‐
4211           tion.
4212
4213       6.  --route-pre-down
4214
4215           Executed right before the routes are removed.
4216
4217       7.  --client-disconnect
4218
4219           Executed in --mode server mode on client instance shutdown.
4220
4221       8.  --down
4222
4223           Executed after TCP/UDP and TUN/TAP close.
4224
4225       9.  --learn-address
4226
4227           Executed  in  --mode  server mode whenever an IPv4 address/route or
4228           MAC address is added to OpenVPN's internal routing table.
4229
4230       10. --auth-user-pass-verify
4231
4232           Executed in --mode server mode on new client connections, when  the
4233           client is still untrusted.
4234
4235   SCRIPT HOOKS
4236       --auth-user-pass-verify args
4237              Require  the  client to provide a username/password (possibly in
4238              addition to a client certificate) for authentication.
4239
4240              Valid syntax:
4241
4242                 auth-user-pass-verify cmd method
4243
4244              OpenVPN will run command cmd to validate  the  username/password
4245              provided by the client.
4246
4247              cmd  consists of a path to a script (or executable program), op‐
4248              tionally followed by arguments. The path and  arguments  may  be
4249              single-  or  double-quoted and/or escaped using a backslash, and
4250              should be separated by one or more spaces.
4251
4252              If method is set to via-env, OpenVPN will call script  with  the
4253              environmental  variables  username and password set to the user‐
4254              name/password strings provided by the client. Beware  that  this
4255              method  is insecure on some platforms which make the environment
4256              of a process publicly visible to other unprivileged processes.
4257
4258              If method is set to via-file, OpenVPN will  write  the  username
4259              and  password  to  the  first two lines of a temporary file. The
4260              filename will be passed as an argument to script, and  the  file
4261              will  be  automatically  deleted by OpenVPN after the script re‐
4262              turns. The location of the temporary file is controlled  by  the
4263              --tmp-dir  option,  and will default to the current directory if
4264              unspecified. For  security,  consider  setting  --tmp-dir  to  a
4265              volatile  storage medium such as /dev/shm (if available) to pre‐
4266              vent the username/password file from touching the hard drive.
4267
4268              The script should examine the username and password, returning a
4269              success  exit code (0) if the client's authentication request is
4270              to be accepted, or a failure code (1) to reject the client.
4271
4272              This directive is designed to enable  a  plugin-style  interface
4273              for extending OpenVPN's authentication capabilities.
4274
4275              To  protect  against a client passing a maliciously formed user‐
4276              name or password string, the username string must  consist  only
4277              of  these  characters: alphanumeric, underbar ('_'), dash ('-'),
4278              dot ('.'), or at ('@'). The password string can consist  of  any
4279              printable characters except for CR or LF. Any illegal characters
4280              in either the username or password string will be  converted  to
4281              underbar ('_').
4282
4283              Care must be taken by any user-defined scripts to avoid creating
4284              a security vulnerability in the way that these strings are  han‐
4285              dled.  Never  use these strings in such a way that they might be
4286              escaped or evaluated by a shell interpreter.
4287
4288              For a sample script that performs PAM authentication,  see  sam‐
4289              ple-scripts/auth-pam.pl in the OpenVPN source distribution.
4290
4291       --client-connect cmd
4292              Run command cmd on client connection.
4293
4294              cmd  consists of a path to a script (or executable program), op‐
4295              tionally followed by arguments. The path and  arguments  may  be
4296              single-  or  double-quoted and/or escaped using a backslash, and
4297              should be separated by one or more spaces.
4298
4299              The command is passed the common name  and  IP  address  of  the
4300              just-authenticated  client as environmental variables (see envi‐
4301              ronmental variable section below). The command  is  also  passed
4302              the pathname of a freshly created temporary file as the last ar‐
4303              gument (after any arguments specified in cmd ), to  be  used  by
4304              the command to pass dynamically generated config file directives
4305              back to OpenVPN.
4306
4307              If the script wants to generate a dynamic config file to be  ap‐
4308              plied on the server when the client connects, it should write it
4309              to the file named by the last argument.
4310
4311              See the --client-config-dir option below for options  which  can
4312              be legally used in a dynamically generated config file.
4313
4314              Note  that  the return value of script is significant. If script
4315              returns a non-zero error status, it will cause the client to  be
4316              disconnected.
4317
4318              If  a --client-connect wants to defer the generating of the con‐
4319              figuration then the script needs to use  the  client_connect_de‐
4320              ferred_file  and  client_connect_config_file  environment  vari‐
4321              ables, and write status accordingly into these files.   See  the
4322              Environmental Variables section for more details.
4323
4324       --client-disconnect cmd
4325              Like  --client-connect  but  called on client instance shutdown.
4326              Will not be called unless the --client-connect script and  plug‐
4327              ins  (if  defined)  were previously called on this instance with
4328              successful (0) status returns.
4329
4330              The exception to this rule is if the --client-disconnect command
4331              or  plugins  are cascaded, and at least one client-connect func‐
4332              tion succeeded, then ALL of the client-disconnect functions  for
4333              scripts  and  plugins  will  be called on client instance object
4334              deletion, even in cases where some of the related client-connect
4335              functions returned an error status.
4336
4337              The  --client-disconnect  command  is not passed any extra argu‐
4338              ments (only those arguments specified in cmd, if any).
4339
4340       --down cmd
4341              Run command cmd after TUN/TAP  device  close  (post  --user  UID
4342              change  and/or  --chroot ). cmd consists of a path to script (or
4343              executable program), optionally followed by arguments. The  path
4344              and arguments may be single- or double-quoted and/or escaped us‐
4345              ing a backslash, and should be separated by one or more spaces.
4346
4347              Called with the same parameters and environmental  variables  as
4348              the --up option above.
4349
4350              Note  that  if  you  reduce  privileges  by  using --user and/or
4351              --group, your --down script will also run at reduced privilege.
4352
4353       --down-pre
4354              Call --down cmd/script before, rather than after, TUN/TAP close.
4355
4356       --ipchange cmd
4357              Run command cmd when our remote ip-address is initially  authen‐
4358              ticated or changes.
4359
4360              cmd  consists of a path to a script (or executable program), op‐
4361              tionally followed by arguments. The path and  arguments  may  be
4362              single-  or  double-quoted and/or escaped using a backslash, and
4363              should be separated by one or more spaces.
4364
4365              When cmd is executed two arguments are appended after any  argu‐
4366              ments specified in cmd , as follows:
4367
4368                 cmd ip address port number
4369
4370              Don't  use --ipchange in --mode server mode. Use a --client-con‐
4371              nect script instead.
4372
4373              See the Environmental Variables section below for additional pa‐
4374              rameters passed as environmental variables.
4375
4376              If you are running in a dynamic IP address environment where the
4377              IP addresses of either peer could change without notice, you can
4378              use  this  script, for example, to edit the /etc/hosts file with
4379              the current address of the peer. The script will  be  run  every
4380              time the remote peer changes its IP address.
4381
4382              Similarly  if our IP address changes due to DHCP, we should con‐
4383              figure our IP address change script (see man page for dhcpcd(8))
4384              to  deliver  a SIGHUP or SIGUSR1 signal to OpenVPN. OpenVPN will
4385              then re-establish a connection with its most recently  authenti‐
4386              cated peer on its new IP address.
4387
4388       --learn-address cmd
4389              Run command cmd to validate client virtual addresses or routes.
4390
4391              cmd  consists of a path to a script (or executable program), op‐
4392              tionally followed by arguments. The path and  arguments  may  be
4393              single-  or  double-quoted and/or escaped using a backslash, and
4394              should be separated by one or more spaces.
4395
4396              Three arguments will be appended to any arguments in cmd as fol‐
4397              lows:
4398
4399              $1 - [operation]
4400                     "add",  "update", or "delete" based on whether or not the
4401                     address is being added  to,  modified,  or  deleted  from
4402                     OpenVPN's internal routing table.
4403
4404              $2 - [address]
4405                     The  address  being  learned or unlearned. This can be an
4406                     IPv4 address such as "198.162.10.14", an IPv4 subnet such
4407                     as  "198.162.10.0/24",  or  an ethernet MAC address (when
4408                     --dev tap is being used) such as "00:FF:01:02:03:04".
4409
4410              $3 - [common name]
4411                     The common name on the certificate  associated  with  the
4412                     client  linked to this address. Only present for "add" or
4413                     "update" operations, not "delete".
4414
4415              On "add" or "update" methods, if the script  returns  a  failure
4416              code  (non-zero),  OpenVPN  will reject the address and will not
4417              modify its internal routing table.
4418
4419              Normally, the cmd script will use the information provided above
4420              to  set  appropriate  firewall entries on the VPN TUN/TAP inter‐
4421              face. Since OpenVPN provides the association between virtual  IP
4422              or  MAC  address  and the client's authenticated common name, it
4423              allows a user-defined script to configure firewall access  poli‐
4424              cies  with regard to the client's high-level common name, rather
4425              than the low level client virtual addresses.
4426
4427       --route-up cmd
4428              Run command cmd after routes are added, subject  to  --route-de‐
4429              lay.
4430
4431              cmd  consists of a path to a script (or executable program), op‐
4432              tionally followed by arguments. The path and  arguments  may  be
4433              single-  or  double-quoted and/or escaped using a backslash, and
4434              should be separated by one or more spaces.
4435
4436              See the Environmental Variables section below for additional pa‐
4437              rameters passed as environmental variables.
4438
4439       --route-pre-down cmd
4440              Run command cmd before routes are removed upon disconnection.
4441
4442              cmd  consists of a path to a script (or executable program), op‐
4443              tionally followed by arguments. The path and  arguments  may  be
4444              single-  or  double-quoted and/or escaped using a backslash, and
4445              should be separated by one or more spaces.
4446
4447              See the Environmental Variables section below for additional pa‐
4448              rameters passed as environmental variables.
4449
4450       --setenv args
4451              Set  a  custom  environmental  variable  name=value  to  pass to
4452              script.
4453
4454              Valid syntaxes:
4455
4456                 setenv name value
4457                 setenv FORWARD_COMPATIBLE 1
4458                 setenv opt config_option
4459
4460              By setting FORWARD_COMPATIBLE  to  1,  the  config  file  syntax
4461              checking  is  relaxed  so that unknown directives will trigger a
4462              warning but not a fatal error, on the assumption  that  a  given
4463              unknown directive might be valid in future OpenVPN versions.
4464
4465              This option should be used with caution, as there are good secu‐
4466              rity reasons for having OpenVPN fail if it detects problems in a
4467              config  file.   Having  said  that,  there are valid reasons for
4468              wanting new software features to gracefully degrade when encoun‐
4469              tered by older software versions.
4470
4471              It is also possible to tag a single directive so as not to trig‐
4472              ger a fatal error if the directive isn't recognized. To do this,
4473              prepend the following before the directive: setenv opt
4474
4475              Versions  prior  to OpenVPN 2.3.3 will always ignore options set
4476              with the setenv opt directive.
4477
4478              See also --ignore-unknown-option
4479
4480       --setenv-safe args
4481              Set a custom environmental variable  OPENVPN_name  to  value  to
4482              pass to scripts.
4483
4484              Valid syntaxes:
4485
4486                 setenv-safe name value
4487
4488              This  directive  is  designed  to  be  pushed  by  the server to
4489              clients, and the prepending of  OPENVPN_  to  the  environmental
4490              variable  is  a  safety precaution to prevent a LD_PRELOAD style
4491              attack from a malicious or compromised server.
4492
4493       --tls-verify cmd
4494              Run command cmd to verify the X509 name of a pending TLS connec‐
4495              tion  that has otherwise passed all other tests of certification
4496              (except for revocation via --crl-verify directive;  the  revoca‐
4497              tion test occurs after the --tls-verify test).
4498
4499              cmd  should return 0 to allow the TLS handshake to proceed, or 1
4500              to fail.
4501
4502              cmd consists of a path to a script (or executable program),  op‐
4503              tionally  followed  by  arguments. The path and arguments may be
4504              single- or double-quoted and/or escaped using a  backslash,  and
4505              should be separated by one or more spaces.
4506
4507              When  cmd is executed two arguments are appended after any argu‐
4508              ments specified in cmd, as follows:
4509
4510                 cmd certificate_depth subject
4511
4512              These arguments are, respectively, the current certificate depth
4513              and the X509 subject distinguished name (dn) of the peer.
4514
4515              This  feature is useful if the peer you want to trust has a cer‐
4516              tificate which was signed by a certificate  authority  who  also
4517              signed many other certificates, where you don't necessarily want
4518              to trust all of them, but rather be selective about  which  peer
4519              certificate  you will accept. This feature allows you to write a
4520              script which will test the X509 name on a certificate and decide
4521              whether  or  not it should be accepted. For a simple perl script
4522              which will test the common name field on  the  certificate,  see
4523              the file verify-cn in the OpenVPN distribution.
4524
4525              See the Environmental Variables section below for additional pa‐
4526              rameters passed as environmental variables.
4527
4528       --up cmd
4529              Run command cmd after successful TUN/TAP device open (pre --user
4530              UID change).
4531
4532              cmd  consists of a path to a script (or executable program), op‐
4533              tionally followed by arguments. The path and  arguments  may  be
4534              single-  or  double-quoted and/or escaped using a backslash, and
4535              should be separated by one or more spaces.
4536
4537              The up command is useful for  specifying  route  commands  which
4538              route IP traffic destined for private subnets which exist at the
4539              other end of the VPN connection into the tunnel.
4540
4541              For --dev tun execute as:
4542
4543                 cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [init | restart]
4544
4545              For --dev tap execute as:
4546
4547                 cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [init | restart]
4548
4549              See the Environmental Variables section below for additional pa‐
4550              rameters passed as environmental variables.
4551
4552              Note that if cmd includes arguments, all OpenVPN-generated argu‐
4553              ments will be appended to them to build an  argument  list  with
4554              which the executable will be called.
4555
4556              Typically, cmd will run a script to add routes to the tunnel.
4557
4558              Normally  the  up  script  is called after the TUN/TAP device is
4559              opened. In this context, the last command line parameter  passed
4560              to  the  script will be init. If the --up-restart option is also
4561              used, the up script will be  called  for  restarts  as  well.  A
4562              restart  is considered to be a partial reinitialization of Open‐
4563              VPN where the TUN/TAP instance is preserved  (the  --persist-tun
4564              option  will enable such preservation).  A restart can be gener‐
4565              ated by a SIGUSR1 signal, a --ping-restart timeout, or a connec‐
4566              tion reset when the TCP protocol is enabled with the --proto op‐
4567              tion. If a restart occurs, and --up-restart has been  specified,
4568              the up script will be called with restart as the last parameter.
4569
4570              NOTE:  On  restart,  OpenVPN will not pass the full set of envi‐
4571                     ronment variables to the script. Namely,  everything  re‐
4572                     lated  to  routing  and  gateways  will not be passed, as
4573                     nothing needs to be done anyway - all the  routing  setup
4574                     is  already in place. Additionally, the up-restart script
4575                     will run with the downgraded UID/GID settings (if config‐
4576                     ured).
4577
4578              The  following  standalone example shows how the --up script can
4579              be called in both an initialization and restart context.  (NOTE:
4580              for security reasons, don't run the following example unless UDP
4581              port 9999 is blocked by your firewall. Also,  the  example  will
4582              run indefinitely, so you should abort with control-c).
4583
4584                 openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 \
4585                         --up 'echo up' --down 'echo down' --persist-tun  \
4586                         --up-restart
4587
4588              Note  that  OpenVPN also provides the --ifconfig option to auto‐
4589              matically ifconfig the TUN device, eliminating the need  to  de‐
4590              fine an --up script, unless you also want to configure routes in
4591              the --up script.
4592
4593              If --ifconfig is also specified, OpenVPN will pass the  ifconfig
4594              local  and  remote  endpoints  on  the  command line to the --up
4595              script so that they can be used to configure routes such as:
4596
4597                 route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
4598
4599       --up-delay
4600              Delay TUN/TAP open and possible --up script execution until  af‐
4601              ter TCP/UDP connection establishment with peer.
4602
4603              In  --proto  udp  mode, this option normally requires the use of
4604              --ping to allow connection initiation to be sensed  in  the  ab‐
4605              sence of tunnel data, since UDP is a "connectionless" protocol.
4606
4607              On  Windows,  this  option  will delay the TAP-Win32 media state
4608              transitioning to  "connected"  until  connection  establishment,
4609              i.e.  the  receipt  of  the  first authenticated packet from the
4610              peer.
4611
4612       --up-restart
4613              Enable the --up and --down scripts to be called for restarts  as
4614              well  as  initial  program  start. This option is described more
4615              fully above in the --up option documentation.
4616
4617   String Types and Remapping
4618       In certain cases, OpenVPN  will  perform  remapping  of  characters  in
4619       strings. Essentially, any characters outside the set of permitted char‐
4620       acters for each string type will be converted to underbar ('_').
4621
4622       Q: Why is string remapping necessary?
4623              It's an important security feature to prevent the malicious cod‐
4624              ing of strings from untrusted sources to be passed as parameters
4625              to scripts, saved in the environment, used  as  a  common  name,
4626              translated to a filename, etc.
4627
4628       Q: Can string remapping be disabled?
4629              Yes,  by  using  the  --no-name-remapping  option,  however this
4630              should be considered an advanced option.
4631
4632       Here is a brief rundown of OpenVPN's current string types and the  per‐
4633       mitted character class for each string:
4634
4635       X509 Names
4636              Alphanumeric,  underbar  ('_'), dash ('-'), dot ('.'), at ('@'),
4637              colon (':'), slash ('/'), and equal ('='). Alphanumeric  is  de‐
4638              fined  as  a  character which will cause the C library isalnum()
4639              function to return true.
4640
4641       Common Names
4642              Alphanumeric, underbar ('_'), dash  ('-'),  dot  ('.'),  and  at
4643              ('@').
4644
4645       --auth-user-pass username
4646              Same  as  Common Name, with one exception: starting with OpenVPN
4647              2.0.1,    the    username    is    passed    to    the     OPEN‐
4648              VPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin in its raw form, without
4649              string remapping.
4650
4651       --auth-user-pass password
4652              Any "printable" character except CR or LF. Printable is  defined
4653              to be a character which will cause the C library isprint() func‐
4654              tion to return true.
4655
4656       --client-config-dir filename as derived from common name or`username
4657              Alphanumeric, underbar ('_'), dash ('-'), and dot  ('.')  except
4658              for "."  or ".." as standalone strings. As of v2.0.1-rc6, the at
4659              ('@') character has been added as well  for  compatibility  with
4660              the common name character class.
4661
4662       Environmental variable names
4663              Alphanumeric or underbar ('_').
4664
4665       Environmental variable values
4666              Any printable character.
4667
4668       For  all cases, characters in a string which are not members of the le‐
4669       gal character class for that string type will be remapped  to  underbar
4670       ('_').
4671
4672   Environmental Variables
4673       Once  set,  a variable is persisted indefinitely until it is reset by a
4674       new value or a restart,
4675
4676       As of OpenVPN 2.0-beta12, in server mode, environmental  variables  set
4677       by  OpenVPN are scoped according to the client objects they are associ‐
4678       ated with, so there should not be any issues with scripts having access
4679       to  stale, previously set variables which refer to different client in‐
4680       stances.
4681
4682       bytes_received
4683              Total number of bytes received from client during  VPN  session.
4684              Set prior to execution of the --client-disconnect script.
4685
4686       bytes_sent
4687              Total  number  of  bytes  sent to client during VPN session. Set
4688              prior to execution of the --client-disconnect script.
4689
4690       client_connect_config_file
4691              The path to the configuration file that should be written to  by
4692              the --client-connect script (optional, if per-session configura‐
4693              tion is desired).  This is the same file name as passed via com‐
4694              mand line argument on the call to the --client-connect script.
4695
4696       client_connect_deferred_file
4697              This  file  can be optionally written to in order to to communi‐
4698              cate a status code of  the  --client-connect  script  or  plgin.
4699              Only  the  first  character in the file is relevant.  It must be
4700              either 1 to indicate normal script execution, 0 indicates an er‐
4701              ror  (in  the same way that a non zero exit status does) or 2 to
4702              indicate that the script deferred returning the config file.
4703
4704              For deferred (background) handling, the script  or  plugin  MUST
4705              write  2  to  the  file to indicate the deferral and then return
4706              with exit code 0 to signal deferred handler started OK.
4707
4708              A background process or similar must then take care  of  writing
4709              the  configuration  to  the  file  indicated  by the client_con‐
4710              nect_config_file environment variable and when  finished,  write
4711              the a 1 to this file (or 0 in case of an error).
4712
4713              The  absence  of  any character in the file when the script fin‐
4714              ishes executing is  interpreted  the  same  as  1.  This  allows
4715              scripts  that  are not written to support the defer mechanism to
4716              be used unmodified.
4717
4718       common_name
4719              The X509 common name of an authenticated client.  Set  prior  to
4720              execution    of    --client-connect,   --client-disconnect   and
4721              --auth-user-pass-verify scripts.
4722
4723       config Name of first --config file. Set on program initiation and reset
4724              on SIGHUP.
4725
4726       daemon Set to "1" if the --daemon directive is specified, or "0" other‐
4727              wise.  Set on program initiation and reset on SIGHUP.
4728
4729       daemon_log_redirect
4730              Set to "1" if the --log or --log-append  directives  are  speci‐
4731              fied,  or  "0" otherwise. Set on program initiation and reset on
4732              SIGHUP.
4733
4734       dev    The actual name of the TUN/TAP device, including a  unit  number
4735              if it exists. Set prior to --up or --down script execution.
4736
4737       dev_idx
4738              On  Windows, the device index of the TUN/TAP adapter (to be used
4739              in netsh.exe calls which sometimes just do not work  right  with
4740              interface names). Set prior to --up or --down script execution.
4741
4742       foreign_option_{n}
4743              An  option pushed via --push to a client which does not natively
4744              support it, such as --dhcp-option on a non-Windows system,  will
4745              be  recorded  to  this  environmental variable sequence prior to
4746              --up script execution.
4747
4748       ifconfig_broadcast
4749              The broadcast address for the virtual ethernet segment which  is
4750              derived  from  the --ifconfig option when --dev tap is used. Set
4751              prior to OpenVPN calling the ifconfig or netsh (windows  version
4752              of ifconfig) commands which normally occurs prior to --up script
4753              execution.
4754
4755       ifconfig_ipv6_local
4756              The local VPN endpoint IPv6 address specified  in  the  --ifcon‐
4757              fig-ipv6  option (first parameter). Set prior to OpenVPN calling
4758              the ifconfig or code:netsh (windows version  of  ifconfig)  com‐
4759              mands which normally occurs prior to --up script execution.
4760
4761       ifconfig_ipv6_netbits
4762              The  prefix length of the IPv6 network on the VPN interface. De‐
4763              rived from the /nnn parameter of the IPv6 address in  the  --if‐
4764              config-ipv6 option (first parameter). Set prior to OpenVPN call‐
4765              ing the ifconfig or netsh (windows version of ifconfig) commands
4766              which normally occurs prior to --up script execution.
4767
4768       ifconfig_ipv6_remote
4769              The  remote  VPN endpoint IPv6 address specified in the --ifcon‐
4770              fig-ipv6 option (second parameter). Set prior to OpenVPN calling
4771              the  ifconfig  or  netsh  (windows version of ifconfig) commands
4772              which normally occurs prior to --up script execution.
4773
4774       ifconfig_local
4775              The local VPN endpoint IP address specified  in  the  --ifconfig
4776              option  (first  parameter). Set prior to OpenVPN calling the if‐
4777              config or netsh (windows version  of  ifconfig)  commands  which
4778              normally occurs prior to --up script execution.
4779
4780       ifconfig_remote
4781              The  remote  VPN endpoint IP address specified in the --ifconfig
4782              option (second parameter) when --dev tun is used. Set  prior  to
4783              OpenVPN calling the ifconfig or netsh (windows version of ifcon‐
4784              fig) commands which normally occurs prior to --up script  execu‐
4785              tion.
4786
4787       ifconfig_netmask
4788              The  subnet  mask of the virtual ethernet segment that is speci‐
4789              fied as the second parameter to --ifconfig when --dev tap is be‐
4790              ing  used.  Set  prior  to OpenVPN calling the ifconfig or netsh
4791              (windows version of ifconfig)  commands  which  normally  occurs
4792              prior to --up script execution.
4793
4794       ifconfig_pool_local_ip
4795              The  local  virtual IP address for the TUN/TAP tunnel taken from
4796              an --ifconfig-push directive if specified, or otherwise from the
4797              ifconfig pool (controlled by the --ifconfig-pool config file di‐
4798              rective). Only set for --dev tun tunnels. This option is set  on
4799              the  server  prior  to  execution  of  the  --client-connect and
4800              --client-disconnect scripts.
4801
4802       ifconfig_pool_netmask
4803              The virtual IP netmask for the  TUN/TAP  tunnel  taken  from  an
4804              --ifconfig-push  directive  if  specified, or otherwise from the
4805              ifconfig pool (controlled by the --ifconfig-pool config file di‐
4806              rective).  Only set for --dev tap tunnels. This option is set on
4807              the server  prior  to  execution  of  the  --client-connect  and
4808              --client-disconnect scripts.
4809
4810       ifconfig_pool_remote_ip
4811              The  remote virtual IP address for the TUN/TAP tunnel taken from
4812              an --ifconfig-push directive if specified, or otherwise from the
4813              ifconfig pool (controlled by the --ifconfig-pool config file di‐
4814              rective). This option is set on the server prior to execution of
4815              the --client-connect and --client-disconnect scripts.
4816
4817       link_mtu
4818              The  maximum packet size (not including the IP header) of tunnel
4819              data in UDP tunnel transport mode. Set prior to --up  or  --down
4820              script execution.
4821
4822       local  The  --local  parameter.  Set on program initiation and reset on
4823              SIGHUP.
4824
4825       local_port
4826              The local port number or name, specified by --port  or  --lport.
4827              Set on program initiation and reset on SIGHUP.
4828
4829       password
4830              The  password  provided  by  a  connecting  client. Set prior to
4831              --auth-user-pass-verify script execution only when  the  via-env
4832              modifier  is  specified,  and deleted from the environment after
4833              the script returns.
4834
4835       proto  The --proto parameter. Set on program initiation  and  reset  on
4836              SIGHUP.
4837
4838       remote_{n}
4839              The  --remote  parameter. Set on program initiation and reset on
4840              SIGHUP.
4841
4842       remote_port_{n}
4843              The remote port number, specified by --port or --rport.  Set  on
4844              program initiation and reset on SIGHUP.
4845
4846       route_net_gateway
4847              The pre-existing default IP gateway in the system routing table.
4848              Set prior to --up script execution.
4849
4850       route_vpn_gateway
4851              The default gateway used by --route options, as specified in ei‐
4852              ther the --route-gateway option or the second parameter to --if‐
4853              config when --dev tun is specified. Set prior to --up script ex‐
4854              ecution.
4855
4856       route_{parm}_{n}
4857              A  set of variables which define each route to be added, and are
4858              set prior to --up script execution.
4859
4860              parm will be one of network, netmask", gateway, or metric.
4861
4862              n is the OpenVPN route number, starting from 1.
4863
4864              If the network or gateway are resolvable DNS names, their IP ad‐
4865              dress  translations  will be recorded rather than their names as
4866              denoted on the command line or configuration file.
4867
4868       route_ipv6_{parm}_{n}
4869              A set of variables which define each IPv6 route to be added, and
4870              are set prior to --up script execution.
4871
4872              parm  will be one of network, gateway or metric. route_ipv6_net‐
4873              work_{n} contains netmask as  /nnn,  unlike  IPv4  where  it  is
4874              passed in a separate environment variable.
4875
4876              n is the OpenVPN route number, starting from 1.
4877
4878              If the network or gateway are resolvable DNS names, their IP ad‐
4879              dress translations will be recorded rather than their  names  as
4880              denoted on the command line or configuration file.
4881
4882       peer_cert
4883              Temporary  file name containing the client certificate upon con‐
4884              nection.  Useful in conjunction with --tls-verify.
4885
4886       script_context
4887              Set to "init" or "restart" prior to  up/down  script  execution.
4888              For more information, see documentation for --up.
4889
4890       script_type
4891              Prior  to  execution  of any script, this variable is set to the
4892              type of script being run. It can be one of  the  following:  up,
4893              down,  ipchange,  route-up,  tls-verify,  auth-user-pass-verify,
4894              client-connect, client-disconnect or learn-address. Set prior to
4895              execution of any script.
4896
4897       signal The  reason  for exit or restart. Can be one of sigusr1, sighup,
4898              sigterm, sigint, inactive  (controlled  by  --inactive  option),
4899              ping-exit (controlled by --ping-exit option), ping-restart (con‐
4900              trolled by --ping-restart option),  connection-reset  (triggered
4901              on  TCP  connection  reset),  error or unknown (unknown signal).
4902              This variable is set just prior to down script execution.
4903
4904       time_ascii
4905              Client connection timestamp, formatted as a human-readable  time
4906              string.  Set prior to execution of the --client-connect script.
4907
4908       time_duration
4909              The  duration  (in  seconds)  of the client session which is now
4910              disconnecting. Set prior to execution of the --client-disconnect
4911              script.
4912
4913       time_unix
4914              Client   connection  timestamp,  formatted  as  a  unix  integer
4915              date/time value. Set prior to execution of the  --client-connect
4916              script.
4917
4918       tls_digest_{n} / tls_digest_sha256_{n}
4919              Contains  the  certificate SHA1 / SHA256 fingerprint, where n is
4920              the verification level. Only set for TLS connections. Set  prior
4921              to execution of --tls-verify script.
4922
4923       tls_id_{n}
4924              A  series of certificate fields from the remote peer, where n is
4925              the verification level. Only set for TLS connections. Set  prior
4926              to execution of --tls-verify script.
4927
4928       tls_serial_{n}
4929              The serial number of the certificate from the remote peer, where
4930              n is the verification level. Only set for TLS  connections.  Set
4931              prior  to  execution of --tls-verify script. This is in the form
4932              of a decimal string like "933971680", which is suitable for  do‐
4933              ing serial-based OCSP queries (with OpenSSL, do not prepend "0x"
4934              to the string) If something goes wrong while reading  the  value
4935              from  the  certificate  it will be an empty string, so your code
4936              should  check  that.  See  the  contrib/OCSP_check/OCSP_check.sh
4937              script for an example.
4938
4939       tls_serial_hex_{n}
4940              Like tls_serial_{n}, but in hex form (e.g.  12:34:56:78:9A).
4941
4942       tun_mtu
4943              The  MTU  of  the  TUN/TAP  device.  Set prior to --up or --down
4944              script execution.
4945
4946       trusted_ip / trusted_ip6)
4947              Actual IP address of connecting client or peer  which  has  been
4948              authenticated.   Set   prior   to   execution   of   --ipchange,
4949              --client-connect and --client-disconnect scripts. If using  ipv6
4950              endpoints (udp6, tcp6), trusted_ip6 will be set instead.
4951
4952       trusted_port
4953              Actual  port  number of connecting client or peer which has been
4954              authenticated.   Set   prior   to   execution   of   --ipchange,
4955              --client-connect and --client-disconnect scripts.
4956
4957       untrusted_ip / untrusted_ip6
4958              Actual  IP  address  of  connecting client or peer which has not
4959              been authenticated yet. Sometimes used to  nmap  the  connecting
4960              host  in  a --tls-verify script to ensure it is firewalled prop‐
4961              erly.   Set   prior   to   execution   of    --tls-verify    and
4962              --auth-user-pass-verify  scripts. If using ipv6 endpoints (udp6,
4963              tcp6), untrusted_ip6 will be set instead.
4964
4965       untrusted_port
4966              Actual port number of connecting client or peer  which  has  not
4967              been  authenticated  yet. Set prior to execution of --tls-verify
4968              and --auth-user-pass-verify scripts.
4969
4970       username
4971              The username provided by  a  connecting  client.  Set  prior  to
4972              --auth-user-pass-verify  script  execution only when the via-env
4973              modifier is specified.
4974
4975       X509_{n}_{subject_field}
4976              An X509 subject field from the remote peer certificate, where  n
4977              is  the  verification  level.  Only set for TLS connections. Set
4978              prior to execution of --tls-verify script. This variable is sim‐
4979              ilar  to tls_id_{n} except the component X509 subject fields are
4980              broken out, and no string remapping occurs on these field values
4981              (except  for  remapping of control characters to "_"). For exam‐
4982              ple, the following variables would be set on the OpenVPN  server
4983              using the sample client certificate in sample-keys (client.crt).
4984              Note that the verification level is 0 for the client certificate
4985              and 1 for the CA certificate.
4986
4987                 X509_0_emailAddress=me@myhost.mydomain
4988                 X509_0_CN=Test-Client
4989                 X509_0_O=OpenVPN-TEST
4990                 X509_0_ST=NA
4991                 X509_0_C=KG
4992                 X509_1_emailAddress=me@myhost.mydomain
4993                 X509_1_O=OpenVPN-TEST
4994                 X509_1_L=BISHKEK
4995                 X509_1_ST=NA
4996                 X509_1_C=KG
4997
4998   Management Interface Options
4999       OpenVPN  provides  a feature rich socket based management interface for
5000       both server and client mode operations.
5001
5002       --management args
5003              Enable a management server on a socket-name Unix socket on those
5004              platforms supporting it, or on a designated TCP port.
5005
5006              Valid syntaxes:
5007
5008                 management socket-name unix          #
5009                 management socket-name unix pw-file  # (recommended)
5010                 management IP port                   # (INSECURE)
5011                 management IP port pw-file           #
5012
5013              pw-file,  if  specified,  is  a password file where the password
5014              must be on first line. Instead of a filename it can use the key‐
5015              word stdin which will prompt the user for a password to use when
5016              OpenVPN is starting.
5017
5018              For unix sockets, the default behaviour is to create a unix  do‐
5019              main  socket  that  may  be connected to by any process. Use the
5020              --management-client-user  and  --management-client-group  direc‐
5021              tives to restrict access.
5022
5023              The  management  interface provides a special mode where the TCP
5024              management link can operate over the tunnel  itself.  To  enable
5025              this  mode, set IP to tunnel. Tunnel mode will cause the manage‐
5026              ment interface to listen for a TCP connection on the  local  VPN
5027              address of the TUN/TAP interface.
5028
5029              *BEWARE* of enabling the management interface over TCP. In these
5030              cases you should ALWAYS make use of pw-file to password  protect
5031              the  management  interface. Any user who can connect to this TCP
5032              IP:port will be able to manage and control (and interfere  with)
5033              the  OpenVPN  process. It is also strongly recommended to set IP
5034              to 127.0.0.1 (localhost) to restrict accessibility of  the  man‐
5035              agement server to local clients.
5036
5037              While  the  management port is designed for programmatic control
5038              of OpenVPN by other applications, it is possible  to  telnet  to
5039              the  port,  using a telnet client in "raw" mode. Once connected,
5040              type help for a list of commands.
5041
5042              For detailed documentation on the management interface, see  the
5043              management-notes.txt  file in the management folder of the Open‐
5044              VPN source distribution.
5045
5046       --management-client
5047              Management interface will connect as a TCP/unix domain client to
5048              IP:port  specified  by  --management rather than listen as a TCP
5049              server or on a unix domain socket.
5050
5051              If the client connection fails to connect or is disconnected,  a
5052              SIGTERM signal will be generated causing OpenVPN to quit.
5053
5054       --management-client-auth
5055              Gives  management interface client the responsibility to authen‐
5056              ticate clients after their client certificate has been verified.
5057              See  management-notes.txt  in  OpenVPN distribution for detailed
5058              notes.
5059
5060       --management-client-group g
5061              When the management interface is  listening  on  a  unix  domain
5062              socket, only allow connections from group g.
5063
5064       --management-client-pf
5065              Management  interface  clients must specify a packet filter file
5066              for each connecting client. See management-notes.txt in  OpenVPN
5067              distribution for detailed notes.
5068
5069       --management-client-user u
5070              When  the  management  interface  is  listening on a unix domain
5071              socket, only allow connections from user u.
5072
5073       --management-external-cert certificate-hint
5074              Allows usage for external certificate instead of  --cert  option
5075              (client-only).  certificate-hint is an arbitrary string which is
5076              passed to a  management  interface  client  as  an  argument  of
5077              NEED-CERTIFICATE   notification.   Requires  --management-exter‐
5078              nal-key.
5079
5080       --management-external-key args
5081              Allows usage for external private key file instead of --key  op‐
5082              tion (client-only).
5083
5084              Valid syntaxes:
5085
5086                 management-external-key
5087                 management-external-key nopadding
5088                 management-external-key pkcs1
5089                 management-external-key nopadding pkcs1
5090
5091              The  optional  parameters nopadding and pkcs1 signal support for
5092              different padding algorithms. See doc/mangement-notes.txt for  a
5093              complete description of this feature.
5094
5095       --management-forget-disconnect
5096              Make  OpenVPN  forget  passwords when management session discon‐
5097              nects.
5098
5099              This directive does not affect the  --http-proxy  username/pass‐
5100              word.  It is always cached.
5101
5102       --management-hold
5103              Start OpenVPN in a hibernating state, until a client of the man‐
5104              agement interface explicitly starts it  with  the  hold  release
5105              command.
5106
5107       --management-log-cache n
5108              Cache  the  most recent n lines of log file history for usage by
5109              the management channel.
5110
5111       --management-query-passwords
5112              Query  management  channel  for   private   key   password   and
5113              --auth-user-pass  username/password.  Only  query the management
5114              channel for inputs which ordinarily would have been queried from
5115              the console.
5116
5117       --management-query-proxy
5118              Query management channel for proxy server information for a spe‐
5119              cific --remote (client-only).
5120
5121       --management-query-remote
5122              Allow  management  interface  to  override  --remote  directives
5123              (client-only).
5124
5125       --management-signal
5126              Send  SIGUSR1  signal  to  OpenVPN if management session discon‐
5127              nects. This is useful when you wish  to  disconnect  an  OpenVPN
5128              session  on user logoff.  For --management-client this option is
5129              not needed since a disconnect will always generate a SIGTERM.
5130
5131       --management-up-down
5132              Report tunnel up/down events to management interface.
5133
5134   Plug-in Interface Options
5135       OpenVPN can be extended by loading external plug-in modules at runtime.
5136       These plug-ins must be prebuilt and adhere to the OpenVPN Plug-In API.
5137
5138       --plugin args
5139              Loads an OpenVPN plug-in module.
5140
5141              Valid syntax:
5142
5143                 plugin module-name
5144                 plugin module-name "arguments"
5145
5146              The  module-name  needs to be the first argument, indicating the
5147              plug-in to load.  The second argument is an optional init string
5148              which  will be passed directly to the plug-in.  If the init con‐
5149              sists of multiple arguments it must be enclosed in double-quotes
5150              (").   Multiple  plugin  modules  may be loaded into one OpenVPN
5151              process.
5152
5153              The module-name argument can be just a filename  or  a  filename
5154              with a relative or absolute path. The format of the filename and
5155              path defines if the  plug-in  will  be  loaded  from  a  default
5156              plug-in directory or outside this directory.
5157
5158                 --plugin path         Effective directory used
5159                 ===================== =============================
5160                  myplug.so            DEFAULT_DIR/myplug.so
5161                  subdir/myplug.so     DEFAULT_DIR/subdir/myplug.so
5162                  ./subdir/myplug.so   CWD/subdir/myplug.so
5163                  /usr/lib/my/plug.so  /usr/lib/my/plug.so
5164
5165              DEFAULT_DIR  is replaced by the default plug-in directory, which
5166              is configured at the build time of OpenVPN. CWD is  the  current
5167              directory  where  OpenVPN  was  started or the directory OpenVPN
5168              have switched into via the --cd option before the  --plugin  op‐
5169              tion.
5170
5171              For  more  information  and  examples  on  how  to build OpenVPN
5172              plug-in modules, see the README file in the plugin folder of the
5173              OpenVPN source distribution.
5174
5175              If you are using an RPM install of OpenVPN, see /usr/share/open‐
5176              vpn/plugin. The documentation is in doc and  the  actual  plugin
5177              modules are in lib.
5178
5179              Multiple plugin modules can be cascaded, and modules can be used
5180              in tandem with scripts. The modules will be called by OpenVPN in
5181              the  order  that they are declared in the config file. If both a
5182              plugin and script are configured  for  the  same  callback,  the
5183              script  will  be  called  last.  If  the return code of the mod‐
5184              ule/script controls an authentication function (such as tls-ver‐
5185              ify,  auth-user-pass-verify, or client-connect), then every mod‐
5186              ule and script must return success (0) in order for the  connec‐
5187              tion to be authenticated.
5188
5189              WARNING:
5190                     Plug-ins  may  do deferred execution, meaning the plug-in
5191                     will return the control back to the main OpenVPN  process
5192                     and  provide  the plug-in result later on via a different
5193                     thread or process.  OpenVPN does NOT support multiple au‐
5194                     thentication plug-ins where more than one plugin tries to
5195                     do deferred authentication.  If  this  behaviour  is  de‐
5196                     tected, OpenVPN will shut down upon first authentication.
5197
5198   Windows-Specific Options
5199       --allow-nonadmin TAP-adapter
5200              (Standalone)  Set  TAP-adapter to allow access from non-adminis‐
5201              trative accounts. If TAP-adapter is omitted, all TAP adapters on
5202              the  system  will  be  configured to allow non-admin access. The
5203              non-admin access setting will only persist  for  the  length  of
5204              time  that the TAP-Win32 device object and driver remain loaded,
5205              and will need to be re-enabled after a reboot, or if the  driver
5206              is  unloaded and reloaded. This directive can only be used by an
5207              administrator.
5208
5209       --block-outside-dns
5210              Block DNS servers on  other  network  adapters  to  prevent  DNS
5211              leaks.  This  option prevents any application from accessing TCP
5212              or UDP port 53 except one inside the  tunnel.  It  uses  Windows
5213              Filtering Platform (WFP) and works on Windows Vista or later.
5214
5215              This  option  is considered unknown on non-Windows platforms and
5216              unsupported on Windows XP, resulting in  fatal  error.  You  may
5217              want  to  use --setenv opt or --ignore-unknown-option (not suit‐
5218              able for Windows XP) to ignore said error. Note that pushing un‐
5219              known options from server does not trigger fatal errors.
5220
5221       --cryptoapicert select-string
5222              (Windows/OpenSSL Only) Load the certificate and private key from
5223              the Windows Certificate System Store.
5224
5225              Use this option instead of --cert and --key.
5226
5227              This makes it possible to use any smart card, supported by  Win‐
5228              dows,  but  also  any  kind of certificate, residing in the Cert
5229              Store, where you have access to the private key. This option has
5230              been  tested  with  a  couple of different smart cards (GemSAFE,
5231              Cryptoflex, and Swedish Post Office eID) on the client side, and
5232              also an imported PKCS12 software certificate on the server side.
5233
5234              To select a certificate, based on a substring search in the cer‐
5235              tificate's subject:
5236
5237                 cryptoapicert "SUBJ:Peter Runestig"
5238
5239              To select a certificate, based on certificate's thumbprint:
5240
5241                 cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."
5242
5243              The thumbprint hex string can easily be copy-and-pasted from the
5244              Windows Certificate Store GUI.
5245
5246       --dhcp-release
5247              Ask  Windows  to release the TAP adapter lease on shutdown. This
5248              option has no effect now, as it is enabled by  default  starting
5249              with OpenVPN 2.4.1.
5250
5251       --dhcp-renew
5252              Ask  Windows to renew the TAP adapter lease on startup. This op‐
5253              tion is normally unnecessary, as Windows automatically  triggers
5254              a  DHCP  renegotiation on the TAP adapter when it comes up, how‐
5255              ever if you set the TAP-Win32 adapter Media Status  property  to
5256              "Always Connected", you may need this flag.
5257
5258       --ip-win32 method
5259              When  using  --ifconfig on Windows, set the TAP-Win32 adapter IP
5260              address and netmask using method. Don't use this  option  unless
5261              you are also using --ifconfig.
5262
5263              manual Don't  set  the  IP address or netmask automatically. In‐
5264                     stead output a message to the console telling the user to
5265                     configure the adapter manually and indicating the IP/net‐
5266                     mask which OpenVPN expects the adapter to be set to.
5267
5268              dynamic [offset] [lease-time]
5269                     Automatically set the IP address and netmask by  replying
5270                     to  DHCP  query  messages  generated by the kernel.  This
5271                     mode is probably the "cleanest" solution for setting  the
5272                     TCP/IP  properties since it uses the well-known DHCP pro‐
5273                     tocol. There are, however, two  prerequisites  for  using
5274                     this mode:
5275
5276                     1. The  TCP/IP  properties for the TAP-Win32 adapter must
5277                        be set to "Obtain an IP address automatically", and
5278
5279                     2. OpenVPN needs to claim an IP address in the subnet for
5280                        use as the virtual DHCP server address.
5281
5282                     By  default in --dev tap mode, OpenVPN will take the nor‐
5283                     mally unused first address in the subnet. For example, if
5284                     your  subnet  is  192.168.4.0 netmask 255.255.255.0, then
5285                     OpenVPN will take the IP address 192.168.4.0  to  use  as
5286                     the  virtual  DHCP  server  address.   In --dev tun mode,
5287                     OpenVPN will cause the DHCP server to masquerade as if it
5288                     were coming from the remote endpoint.
5289
5290                     The  optional  offset  parameter is an integer which is >
5291                     -256 and < 256 and which defaults to 0. If offset is pos‐
5292                     itive,  the DHCP server will masquerade as the IP address
5293                     at network address + offset. If offset is  negative,  the
5294                     DHCP  server  will masquerade as the IP address at broad‐
5295                     cast address + offset.
5296
5297                     The Windows ipconfig /all command can  be  used  to  show
5298                     what  Windows  thinks the DHCP server address is. OpenVPN
5299                     will "claim" this address, so make sure to use a free ad‐
5300                     dress.  Having  said  that,  different OpenVPN instantia‐
5301                     tions, including different ends of the  same  connection,
5302                     can share the same virtual DHCP server address.
5303
5304                     The  lease-time  parameter controls the lease time of the
5305                     DHCP assignment given to the TAP-Win32  adapter,  and  is
5306                     denoted  in  seconds.  Normally a very long lease time is
5307                     preferred  because  it  prevents  routes  involving   the
5308                     TAP-Win32 adapter from being lost when the system goes to
5309                     sleep. The default lease time is one year.
5310
5311              netsh  Automatically set the IP address and  netmask  using  the
5312                     Windows command-line "netsh" command. This method appears
5313                     to work correctly on Windows XP but not Windows 2000.
5314
5315              ipapi  Automatically set the IP address and  netmask  using  the
5316                     Windows  IP Helper API. This approach does not have ideal
5317                     semantics, though testing has  indicated  that  it  works
5318                     okay  in  practice. If you use this option, it is best to
5319                     leave the TCP/IP properties for the TAP-Win32 adapter  in
5320                     their default state, i.e. "Obtain an IP address automati‐
5321                     cally."
5322
5323              adaptive (Default)
5324                     Try dynamic method initially and fail over  to  netsh  if
5325                     the  DHCP negotiation with the TAP-Win32 adapter does not
5326                     succeed in 20 seconds. Such failures have been  known  to
5327                     occur  when  certain  third-party  firewall  packages in‐
5328                     stalled on the client machine block the DHCP  negotiation
5329                     used  by  the  TAP-Win32  adapter. Note that if the netsh
5330                     failover occurs, the TAP-Win32 adapter TCP/IP  properties
5331                     will  be  reset  from DHCP to static, and this will cause
5332                     future OpenVPN startups using the adaptive  mode  to  use
5333                     netsh immediately, rather than trying dynamic first.
5334
5335                     To  "unstick"  the  adaptive  mode  from using netsh, run
5336                     OpenVPN at least once using the dynamic mode  to  restore
5337                     the TAP-Win32 adapter TCP/IP properties to a DHCP config‐
5338                     uration.
5339
5340       --pause-exit
5341              Put up a "press any key to  continue"  message  on  the  console
5342              prior to OpenVPN program exit. This option is automatically used
5343              by the Windows explorer when OpenVPN is run on  a  configuration
5344              file using the right-click explorer menu.
5345
5346       --register-dns
5347              Run  ipconfig  /flushdns and ipconfig /registerdns on connection
5348              initiation. This is  known  to  kick  Windows  into  recognizing
5349              pushed DNS servers.
5350
5351       --route-method m
5352              Which method m to use for adding routes on Windows?
5353
5354              adaptive (default)
5355                     Try  IP helper API first. If that fails, fall back to the
5356                     route.exe shell command.
5357
5358              ipapi  Use IP helper API.
5359
5360              exe    Call the route.exe shell command.
5361
5362       --service args
5363              Should be used when OpenVPN is being automatically  executed  by
5364              another  program  in such a context that no interaction with the
5365              user via display or keyboard is possible.
5366
5367              Valid syntax:
5368
5369                 service exit-event [0|1]
5370
5371              In general, end-users should never need to explicitly  use  this
5372              option,  as  it  is  automatically  added by the OpenVPN service
5373              wrapper when a given OpenVPN configuration is  being  run  as  a
5374              service.
5375
5376              exit-event  is  the  name  of a Windows global event object, and
5377              OpenVPN will continuously monitor the state of this event object
5378              and exit when it becomes signaled.
5379
5380              The  second  parameter indicates the initial state of exit-event
5381              and normally defaults to 0.
5382
5383              Multiple OpenVPN processes can be simultaneously  executed  with
5384              the  same  exit-event  parameter.  In  any case, the controlling
5385              process can signal exit-event, causing  all  such  OpenVPN  pro‐
5386              cesses to exit.
5387
5388              When executing an OpenVPN process using the --service directive,
5389              OpenVPN will probably not have a console window to  output  sta‐
5390              tus/error  messages,  therefore  it  is  useful  to use --log or
5391              --log-append to write these messages to a file.
5392
5393       --show-adapters
5394              (Standalone) Show available TAP-Win32 adapters which can be  se‐
5395              lected  using the --dev-node option. On non-Windows systems, the
5396              ifconfig(8) command provides similar functionality.
5397
5398       --show-net
5399              (Standalone) Show OpenVPN's view of the system routing table and
5400              network adapter list.
5401
5402       --show-net-up
5403              Output  OpenVPN's  view  of the system routing table and network
5404              adapter list to the syslog or log file after the TUN/TAP adapter
5405              has been brought up and any routes have been added.
5406
5407       --show-valid-subnets
5408              (Standalone)  Show  valid subnets for --dev tun emulation. Since
5409              the TAP-Win32 driver exports an ethernet interface  to  Windows,
5410              and since TUN devices are point-to-point in nature, it is neces‐
5411              sary for the TAP-Win32 driver to impose certain  constraints  on
5412              TUN endpoint address selection.
5413
5414              Namely,  the  point-to-point endpoints used in TUN device emula‐
5415              tion must be the middle two addresses of a /30  subnet  (netmask
5416              255.255.255.252).
5417
5418       --tap-sleep n
5419              Cause  OpenVPN  to  sleep  for  n  seconds immediately after the
5420              TAP-Win32 adapter state is set to "connected".
5421
5422              This option is intended to be used to troubleshoot problems with
5423              the  --ifconfig  and --ip-win32 options, and is used to give the
5424              TAP-Win32 adapter time to come up before Windows IP  Helper  API
5425              operations are applied to it.
5426
5427       --win-sys path
5428              Set  the  Windows  system directory pathname to use when looking
5429              for system executables such as route.exe and netsh.exe.  By  de‐
5430              fault,  if this directive is not specified, OpenVPN will use the
5431              SystemRoot environment variable.
5432
5433              This option has changed behaviour since OpenVPN 2.3. Earlier you
5434              had  to  define  --win-sys env to use the SystemRoot environment
5435              variable, otherwise it  defaulted  to  C:\\WINDOWS.  It  is  not
5436              needed  to use the env keyword any more, and it will just be ig‐
5437              nored. A warning is logged when this is found in the  configura‐
5438              tion file.
5439
5440       --windows-driver drv
5441              Specifies  which tun driver to use. Values are tap-windows6 (de‐
5442              fault) and wintun.  This is a Windows-only option.  wintun"  re‐
5443              quires  --dev tun and the OpenVPN process to run elevated, or be
5444              invoked using the Interactive Service.
5445
5446   Standalone Debug Options
5447       --show-gateway args
5448              (Standalone) Show current IPv4 and IPv6 default gateway and  in‐
5449              terface  towards the gateway (if the protocol in question is en‐
5450              abled).
5451
5452              Valid syntax:
5453
5454                 --show-gateway
5455                 --show-gateway IPv6-target
5456
5457              For IPv6 this queries the route towards ::/128, or the specified
5458              IPv6  target  address if passed as argument.  For IPv4 on Linux,
5459              Windows, MacOS and BSD it looks for a 0.0.0.0/0 route.  If there
5460              are more specific routes, the result will not always be matching
5461              the route of the IPv4 packets to the VPN gateway.
5462
5463   Advanced Expert Options
5464       These are options only required when special tweaking is needed,  often
5465       used when debugging or testing out special usage scenarios.
5466
5467       --hash-size args
5468              Set the size of the real address hash table to r and the virtual
5469              address table to v.
5470
5471              Valid syntax:
5472
5473                 hash-size r v
5474
5475              By default, both tables are sized at 256 buckets.
5476
5477       --bcast-buffers n
5478              Allocate n buffers for broadcast datagrams (default 256).
5479
5480       --persist-local-ip
5481              Preserve initially resolved local IP  address  and  port  number
5482              across SIGUSR1 or --ping-restart restarts.
5483
5484       --persist-remote-ip
5485              Preserve  most recently authenticated remote IP address and port
5486              number across SIGUSR1 or --ping-restart restarts.
5487
5488       --prng args
5489              (Advanced) Change the PRNG (Pseudo-random number generator)  pa‐
5490              rameters
5491
5492              Valid syntaxes:
5493
5494                 prng alg
5495                 prng alg nsl
5496
5497              Changes the PRNG to use digest algorithm alg (default sha1), and
5498              set nsl (default 16) to the size in bytes of  the  nonce  secret
5499              length (between 16 and 64).
5500
5501              Set  alg  to  none  to  disable  the  PRNG  and  use the OpenSSL
5502              RAND_bytes function instead for all of  OpenVPN's  pseudo-random
5503              number needs.
5504
5505       --rcvbuf size
5506              Set  the TCP/UDP socket receive buffer size. Defaults to operat‐
5507              ing system default.
5508
5509       --shaper n
5510              Limit bandwidth of outgoing tunnel data to n bytes per second on
5511              the  TCP/UDP  port. Note that this will only work if mode is set
5512              to p2p.  If you want to limit the bandwidth in both  directions,
5513              use this option on both peers.
5514
5515              OpenVPN  uses the following algorithm to implement traffic shap‐
5516              ing: Given a shaper rate of n bytes per second, after a datagram
5517              write  of  b bytes is queued on the TCP/UDP port, wait a minimum
5518              of (b / n) seconds before queuing the next write.
5519
5520              It should be noted that OpenVPN supports  multiple  tunnels  be‐
5521              tween  the  same two peers, allowing you to construct full-speed
5522              and reduced bandwidth tunnels at the same time, routing low-pri‐
5523              ority  data  such as off-site backups over the reduced bandwidth
5524              tunnel, and other data over the full-speed tunnel.
5525
5526              Also note that for low bandwidth tunnels (under 1000  bytes  per
5527              second),  you  should probably use lower MTU values as well (see
5528              above), otherwise the packet latency will grow so  large  as  to
5529              trigger  timeouts  in  the TLS layer and TCP connections running
5530              over the tunnel.
5531
5532              OpenVPN allows n to be between 100 bytes/sec and 100 Mbytes/sec.
5533
5534       --sndbuf size
5535              Set the TCP/UDP socket send buffer size. Defaults  to  operating
5536              system default.
5537
5538       --tcp-queue-limit n
5539              Maximum number of output packets queued before TCP (default 64).
5540
5541              When OpenVPN is tunneling data from a TUN/TAP device to a remote
5542              client over a TCP connection, it is possible  that  the  TUN/TAP
5543              device  might produce data at a faster rate than the TCP connec‐
5544              tion can support. When the number of output packets  queued  be‐
5545              fore  sending  to  the TCP socket reaches this limit for a given
5546              client connection, OpenVPN will start to drop  outgoing  packets
5547              directed at this client.
5548
5549       --txqueuelen n
5550              (Linux  only)  Set the TX queue length on the TUN/TAP interface.
5551              Currently defaults to operating system default.
5552

UNSUPPORTED OPTIONS

5554       Options listed in this section have been removed from OpenVPN  and  are
5555       no longer supported
5556
5557       --client-cert-not-required
5558              Removed  in  OpenVPN  2.5.   This should be replaxed with --ver‐
5559              ify-client-cert none.
5560
5561       --ifconfig-pool-linear
5562              Removed in OpenVPN 2.5.  This should be replaced with --topology
5563              p2p.
5564
5565       --key-method
5566              Removed  in OpenVPN 2.5.  This option should not be used, as us‐
5567              ing the old key-method weakens the VPN tunnel security.  The old
5568              key-method  was  also only needed when the remote side was older
5569              than OpenVPN 2.0.
5570
5571       --no-iv
5572              Removed in OpenVPN 2.5.  This option should not be  used  as  it
5573              weakens  the  VPN  tunnel security.  This has been a NOOP option
5574              since OpenVPN 2.4.
5575
5576       --no-replay
5577              Removed in OpenVPN 2.5.  This option should not be  used  as  it
5578              weakens the VPN tunnel security.
5579
5580       --ns-cert-type
5581              Removed  in OpenVPN 2.5.  The nsCertType field is no longer sup‐
5582              ported in recent SSL/TLS libraries.  If your  certificates  does
5583              not  include  key usage and extended key usage fields, they must
5584              be upgraded and the --remote-cert-tls option should be used  in‐
5585              stead.
5586

CONNECTION PROFILES

5588       Client configuration files may contain multiple remote servers which it
5589       will attempt to connect against.  But there are some configuration  op‐
5590       tions  which  are  related to specific --remote options.  For these use
5591       cases, connection profiles are the solution.
5592
5593       By enacpulating the --remote option and related options within <connec‐
5594       tion> and </connection>, these options are handled as a group.
5595
5596       An  OpenVPN  client will try each connection profile sequentially until
5597       it achieves a successful connection.
5598
5599       --remote-random can be used  to  initially  "scramble"  the  connection
5600       list.
5601
5602       Here is an example of connection profile usage:
5603
5604          client
5605          dev tun
5606
5607          <connection>
5608          remote 198.19.34.56 1194 udp
5609          </connection>
5610
5611          <connection>
5612          remote 198.19.34.56 443 tcp
5613          </connection>
5614
5615          <connection>
5616          remote 198.19.34.56 443 tcp
5617          http-proxy 192.168.0.8 8080
5618          </connection>
5619
5620          <connection>
5621          remote 198.19.36.99 443 tcp
5622          http-proxy 192.168.0.8 8080
5623          </connection>
5624
5625          persist-key
5626          persist-tun
5627          pkcs12 client.p12
5628          remote-cert-tls server
5629          verb 3
5630
5631       First  we try to connect to a server at 198.19.34.56:1194 using UDP. If
5632       that fails, we then try to connect to 198.19.34.56:443  using  TCP.  If
5633       that  also  fails,  then  try  connecting  through  an  HTTP  proxy  at
5634       192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to connect
5635       through the same proxy to a server at 198.19.36.99:443 using TCP.
5636
5637       The  following  OpenVPN  options  may  be used inside of a <connection>
5638       block:
5639
5640       bind,   connect-retry,    connect-retry-max,    connect-timeout,    ex‐
5641       plicit-exit-notify,  float,  fragment,  http-proxy,  http-proxy-option,
5642       key-direction, link-mtu, local, lport, mssfix, mtu-disc, nobind,  port,
5643       proto,  remote,  rport,  socks-proxy, tls-auth, tls-crypt, tun-mtu and,
5644       tun-mtu-extra.
5645
5646       A defaulting mechanism exists for specifying options to  apply  to  all
5647       <connection>  profiles. If any of the above options (with the exception
5648       of remote ) appear outside of a <connection> block, but in a configura‐
5649       tion file which has one or more <connection> blocks, the option setting
5650       will be used as a default for <connection> blocks which  follow  it  in
5651       the configuration file.
5652
5653       For  example,  suppose the nobind option were placed in the sample con‐
5654       figuration file above, near the top of the file, before the first <con‐
5655       nection>  block.  The effect would be as if nobind were declared in all
5656       <connection> blocks below it.
5657

INLINE FILE SUPPORT

5659       OpenVPN allows including files in the main configuration for the  --ca,
5660       --cert,  --dh,  --extra-certs, --key, --pkcs12, --secret, --crl-verify,
5661       --http-proxy-user-pass,      --tls-auth,       --auth-gen-token-secret,
5662       --tls-crypt and --tls-crypt-v2 options.
5663
5664       Each  inline  file  started  by the line <option> and ended by the line
5665       </option>
5666
5667       Here is an example of an inline file usage
5668
5669          <cert>
5670          -----BEGIN CERTIFICATE-----
5671          [...]
5672          -----END CERTIFICATE-----
5673          </cert>
5674
5675       When using the inline file feature with --pkcs12 the inline file has to
5676       be  base64 encoded. Encoding of a .p12 file into base64 can be done for
5677       example with OpenSSL by running openssl base64 -in input.p12
5678

SIGNALS

5680       SIGHUP Cause OpenVPN to close  all  TUN/TAP  and  network  connections,
5681              restart,  re-read  the  configuration  file (if any), and reopen
5682              TUN/TAP and network connections.
5683
5684       SIGUSR1
5685              Like SIGHUP`, except don't re-read configuration file, and  pos‐
5686              sibly  don't close and reopen TUN/TAP device, re-read key files,
5687              preserve local IP address/port, or preserve  most  recently  au‐
5688              thenticated  remote  IP  address/port  based  on  --persist-tun,
5689              --persist-key, --persist-local-ip  and  --persist-remote-ip  op‐
5690              tions respectively (see above).
5691
5692              This signal may also be internally generated by a timeout condi‐
5693              tion, governed by the --ping-restart option.
5694
5695              This signal, when combined with --persist-remote-ip, may be sent
5696              when  the  underlying parameters of the host's network interface
5697              change such as when the host is a DHCP client and is assigned  a
5698              new IP address.  See --ipchange for more information.
5699
5700       SIGUSR2
5701              Causes  OpenVPN to display its current statistics (to the syslog
5702              file if --daemon is used, or stdout otherwise).
5703
5704       SIGINT, SIGTERM
5705              Causes OpenVPN to exit gracefully.
5706

FAQ

5708       https://community.openvpn.net/openvpn/wiki/FAQ
5709

HOWTO

5711       For a more comprehensive guide to setting up OpenVPN  in  a  production
5712       setting,         see         the         OpenVPN        HOWTO        at
5713       https://openvpn.net/community-resources/how-to/
5714

PROTOCOL

5716       For   a   description   of   OpenVPN's   underlying    protocol,    see
5717       https://openvpn.net/community-resources/openvpn-protocol/
5718

WEB

5720       OpenVPN's web site is at https://openvpn.net/
5721
5722       Go  here  to  download  the latest version of OpenVPN, subscribe to the
5723       mailing lists, read the mailing list archives, or browse the SVN repos‐
5724       itory.
5725

BUGS

5727       Report all bugs to the OpenVPN team info@openvpn.net
5728

SEE ALSO

5730       openvpn-examples(5),   dhcpcd(8),  ifconfig(8),  openssl(1),  route(8),
5731       scp(1) ssh(1)
5732

NOTES

5734       This product includes software developed  by  the  OpenSSL  Project  (‐
5735       https://www.openssl.org/)
5736
5737       For     more     information     on     the     TLS    protocol,    see
5738       http://www.ietf.org/rfc/rfc2246.txt
5739
5740       For more information on  the  LZO  real-time  compression  library  see
5741       https://www.oberhumer.com/opensource/lzo/
5742
5744       Copyright  (C) 2002-2020 OpenVPN Inc This program is free software; you
5745       can redistribute it and/or modify it under the terms of the GNU General
5746       Public License version 2 as published by the Free Software Foundation.
5747

AUTHORS

5749       James Yonan james@openvpn.net
5750
5751
5752
5753
5754                                                                    OPENVPN(8)
Impressum