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

ENCRYPTION OPTIONS

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

DATA CHANNEL CIPHER NEGOTIATION

2996       OpenVPN 2.4 and higher have the capability to negotiate the data cipher
2997       that is used to encrypt data packets. This section describes the mecha‐
2998       nism in more detail and the different backwards compatibility mechanism
2999       with older server and clients.
3000
3001   OpenVPN 2.5 and higher behaviour
3002       When both client and server are at least running OpenVPN 2.5, that  the
3003       order of the ciphers of the server's --data-ciphers is used to pick the
3004       the data cipher.  That means that the first cipher in that list that is
3005       also in the client's --data-ciphers list is chosen. If no common cipher
3006       is found the client is rejected with a AUTH_FAILED message (as seen  in
3007       client log):
3008          AUTH:  Received control message: AUTH_FAILED,Data channel cipher ne‐
3009          gotiation failed (no shared cipher)
3010
3011       OpenVPN 2.5 will only allow the ciphers specified in --data-ciphers. To
3012       ensure  backwards compatibility also if a cipher is specified using the
3013       --cipher option it is automatically added to this list. If both options
3014       are unset the default is AES-256-GCM:AES-128-GCM.
3015
3016   OpenVPN 2.4 clients
3017       The  negotiation  support in OpenVPN 2.4 was the first iteration of the
3018       implementation and still had some quirks. Its main goal was "upgrade to
3019       AES-256-GCM  when  possible".   An  OpenVPN  2.4  client  that is built
3020       against a crypto library that supports AES in GCM  mode  and  does  not
3021       have  --ncp-disable  will  always  announce support for AES-256-GCM and
3022       AES-128-GCM to a server by sending IV_NCP=2.
3023
3024       This only causes a problem if --ncp-ciphers  option  has  been  changed
3025       from  the  default  of AES-256-GCM:AES-128-GCM to a value that does not
3026       include  these  two  ciphers.  When  a  OpenVPN  servers  try  to   use
3027       AES-256-GCM  or AES-128-GCM the connection will then fail. It is there‐
3028       fore recommended to always have the AES-256-GCM and AES-128-GCM ciphers
3029       to the --ncp-ciphers options to avoid this behaviour.
3030
3031   OpenVPN 3 clients
3032       Clients     based     on     the     OpenVPN     3.x     library     (‐
3033       https://github.com/openvpn/openvpn3/)  do  not  have   a   configurable
3034       --ncp-ciphers  or --data-ciphers option. Instead these clients will an‐
3035       nounce support for  all  their  supported  AEAD  ciphers  (AES-256-GCM,
3036       AES-128-GCM and in newer versions also Chacha20-Poly1305).
3037
3038       To  support  OpenVPN  3.x  based  clients at least one of these ciphers
3039       needs to be included in the server's --data-ciphers option.
3040
3041   OpenVPN 2.3 and older clients (and clients with --ncp-disable)
3042       When a client without cipher negotiation support connects to  a  server
3043       the  cipher specified with the --cipher option in the client configura‐
3044       tion must be included in the --data-ciphers option of the server to al‐
3045       low  the  client  to  connect.  Otherwise  the  client will be sent the
3046       AUTH_FAILED message that indicates no shared cipher.
3047
3048       If the client is 2.3 or older and has been configured  with  the  --en‐
3049       able-small  ./configure argument, using data-ciphers-fallback cipher in
3050       the server config file with the explicit cipher used by the  client  is
3051       necessary.
3052
3053   OpenVPN 2.4 server
3054       When  a  client indicates support for AES-128-GCM and AES-256-GCM (with
3055       IV_NCP=2) an OpenVPN 2.4 server will  send  the  first  cipher  of  the
3056       --ncp-ciphers  to  the OpenVPN client regardless of what the cipher is.
3057       To emulate the behaviour of an OpenVPN 2.4 client as close as  possible
3058       and  have  compatibility  to a setup that depends on this quirk, adding
3059       AES-128-GCM and AES-256-GCM to the client's  --data-ciphers  option  is
3060       required.  OpenVPN  2.5+  will only announce the IV_NCP=2 flag if those
3061       ciphers are present.
3062
3063   OpenVPN 2.3 and older servers (and servers with --ncp-disable)
3064       The cipher used by the server must be included in --data-ciphers to al‐
3065       low  the  client connecting to a server without cipher negotiation sup‐
3066       port.  (For compatibility OpenVPN 2.5 will also accept the  cipher  set
3067       with --cipher)
3068
3069       If  the  server is 2.3 or older and  has been configured with the --en‐
3070       able-small ./configure argument, adding data-ciphers-fallback cipher to
3071       the client config with the explicit cipher used by the server is neces‐
3072       sary.
3073
3074   Blowfish in CBC mode (BF-CBC) deprecation
3075       The --cipher option defaulted to BF-CBC in OpenVPN 2.4 and  older  ver‐
3076       sion.  The default was never changed to ensure backwards compatibility.
3077       In OpenVPN 2.5 this behaviour has now been changed so that if the --ci‐
3078       pher is not explicitly set it does not allow the weak BF-CBC cipher any
3079       more and needs to explicitly added as  --cipher  BFC-CBC  or  added  to
3080       --data-ciphers.
3081
3082       We  strongly  recommend  to switching away from BF-CBC to a more secure
3083       cipher as soon as possible instead.
3084

NETWORK CONFIGURATION

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

SCRIPTING INTEGRATION

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

UNSUPPORTED OPTIONS

5491       Options  listed  in this section have been removed from OpenVPN and are
5492       no longer supported
5493
5494       --client-cert-not-required
5495              Removed in OpenVPN 2.5.  This should  be  replaxed  with  --ver‐
5496              ify-client-cert none.
5497
5498       --ifconfig-pool-linear
5499              Removed in OpenVPN 2.5.  This should be replaced with --topology
5500              p2p.
5501
5502       --key-method
5503              Removed in OpenVPN 2.5.  This option should not be used, as  us‐
5504              ing the old key-method weakens the VPN tunnel security.  The old
5505              key-method was also only needed when the remote side  was  older
5506              than OpenVPN 2.0.
5507
5508       --no-iv
5509              Removed  in  OpenVPN  2.5.  This option should not be used as it
5510              weakens the VPN tunnel security.  This has been  a  NOOP  option
5511              since OpenVPN 2.4.
5512
5513       --no-replay
5514              Removed  in  OpenVPN  2.5.  This option should not be used as it
5515              weakens the VPN tunnel security.
5516
5517       --ns-cert-type
5518              Removed in OpenVPN 2.5.  The nsCertType field is no longer  sup‐
5519              ported  in  recent SSL/TLS libraries.  If your certificates does
5520              not include key usage and extended key usage fields,  they  must
5521              be  upgraded and the --remote-cert-tls option should be used in‐
5522              stead.
5523

CONNECTION PROFILES

5525       Client configuration files may contain multiple remote servers which it
5526       will  attempt to connect against.  But there are some configuration op‐
5527       tions which are related to specific --remote options.   For  these  use
5528       cases, connection profiles are the solution.
5529
5530       By enacpulating the --remote option and related options within <connec‐
5531       tion> and </connection>, these options are handled as a group.
5532
5533       An OpenVPN client will try each connection profile  sequentially  until
5534       it achieves a successful connection.
5535
5536       --remote-random  can  be  used  to  initially "scramble" the connection
5537       list.
5538
5539       Here is an example of connection profile usage:
5540
5541          client
5542          dev tun
5543
5544          <connection>
5545          remote 198.19.34.56 1194 udp
5546          </connection>
5547
5548          <connection>
5549          remote 198.19.34.56 443 tcp
5550          </connection>
5551
5552          <connection>
5553          remote 198.19.34.56 443 tcp
5554          http-proxy 192.168.0.8 8080
5555          </connection>
5556
5557          <connection>
5558          remote 198.19.36.99 443 tcp
5559          http-proxy 192.168.0.8 8080
5560          </connection>
5561
5562          persist-key
5563          persist-tun
5564          pkcs12 client.p12
5565          remote-cert-tls server
5566          verb 3
5567
5568       First we try to connect to a server at 198.19.34.56:1194 using UDP.  If
5569       that  fails,  we  then try to connect to 198.19.34.56:443 using TCP. If
5570       that  also  fails,  then  try  connecting  through  an  HTTP  proxy  at
5571       192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to connect
5572       through the same proxy to a server at 198.19.36.99:443 using TCP.
5573
5574       The following OpenVPN options may be  used  inside  of  a  <connection>
5575       block:
5576
5577       bind,    connect-retry,    connect-retry-max,    connect-timeout,   ex‐
5578       plicit-exit-notify,  float,  fragment,  http-proxy,  http-proxy-option,
5579       key-direction,  link-mtu, local, lport, mssfix, mtu-disc, nobind, port,
5580       proto, remote, rport, socks-proxy, tls-auth,  tls-crypt,  tun-mtu  and,
5581       tun-mtu-extra.
5582
5583       A  defaulting  mechanism  exists for specifying options to apply to all
5584       <connection> profiles. If any of the above options (with the  exception
5585       of remote ) appear outside of a <connection> block, but in a configura‐
5586       tion file which has one or more <connection> blocks, the option setting
5587       will  be  used  as a default for <connection> blocks which follow it in
5588       the configuration file.
5589
5590       For example, suppose the nobind option were placed in the  sample  con‐
5591       figuration file above, near the top of the file, before the first <con‐
5592       nection> block. The effect would be as if nobind were declared  in  all
5593       <connection> blocks below it.
5594

INLINE FILE SUPPORT

5596       OpenVPN  allows including files in the main configuration for the --ca,
5597       --cert, --dh, --extra-certs, --key, --pkcs12,  --secret,  --crl-verify,
5598       --http-proxy-user-pass,       --tls-auth,      --auth-gen-token-secret,
5599       --tls-crypt and --tls-crypt-v2 options.
5600
5601       Each inline file started by the line <option> and  ended  by  the  line
5602       </option>
5603
5604       Here is an example of an inline file usage
5605
5606          <cert>
5607          -----BEGIN CERTIFICATE-----
5608          [...]
5609          -----END CERTIFICATE-----
5610          </cert>
5611
5612       When using the inline file feature with --pkcs12 the inline file has to
5613       be base64 encoded. Encoding of a .p12 file into base64 can be done  for
5614       example with OpenSSL by running openssl base64 -in input.p12
5615

SIGNALS

5617       SIGHUP Cause  OpenVPN  to  close  all  TUN/TAP and network connections,
5618              restart, re-read the configuration file  (if  any),  and  reopen
5619              TUN/TAP and network connections.
5620
5621       SIGUSR1
5622              Like  SIGHUP`, except don't re-read configuration file, and pos‐
5623              sibly don't close and reopen TUN/TAP device, re-read key  files,
5624              preserve  local  IP  address/port, or preserve most recently au‐
5625              thenticated  remote  IP  address/port  based  on  --persist-tun,
5626              --persist-key,  --persist-local-ip  and  --persist-remote-ip op‐
5627              tions respectively (see above).
5628
5629              This signal may also be internally generated by a timeout condi‐
5630              tion, governed by the --ping-restart option.
5631
5632              This signal, when combined with --persist-remote-ip, may be sent
5633              when the underlying parameters of the host's  network  interface
5634              change  such as when the host is a DHCP client and is assigned a
5635              new IP address.  See --ipchange for more information.
5636
5637       SIGUSR2
5638              Causes OpenVPN to display its current statistics (to the  syslog
5639              file if --daemon is used, or stdout otherwise).
5640
5641       SIGINT, SIGTERM
5642              Causes OpenVPN to exit gracefully.
5643

EXAMPLES

5645       Prior  to  running these examples, you should have OpenVPN installed on
5646       two machines with network connectivity between them. If  you  have  not
5647       yet installed OpenVPN, consult the INSTALL file included in the OpenVPN
5648       distribution.
5649
5650   Firewall Setup:
5651       If firewalls exist between the two machines, they should be set to for‐
5652       ward  the  port  OpenVPN is configured to use, in both directions.  The
5653       default for OpenVPN is 1194/udp.  If you do not have control  over  the
5654       firewalls  between the two machines, you may still be able to use Open‐
5655       VPN by adding --ping 15 to each of the openvpn commands used  below  in
5656       the  examples  (this will cause each peer to send out a UDP ping to its
5657       remote peer once every 15 seconds which will cause many stateful  fire‐
5658       walls  to  forward packets in both directions without an explicit fire‐
5659       wall rule).
5660
5661       Please see your operating system guides for how to configure the  fire‐
5662       wall on your systems.
5663
5664   VPN Address Setup:
5665       For  purposes of our example, our two machines will be called bob.exam‐
5666       ple.com and alice.example.com. If you are constructing a VPN  over  the
5667       internet,  then  replace bob.example.com and alice.example.com with the
5668       internet hostname or IP address that each machine will use  to  contact
5669       the other over the internet.
5670
5671       Now  we  will choose the tunnel endpoints. Tunnel endpoints are private
5672       IP addresses that only have meaning in the context of the VPN. Each ma‐
5673       chine  will  use  the tunnel endpoint of the other machine to access it
5674       over the VPN. In our example, the tunnel endpoint  for  bob.example.com
5675       will be 10.4.0.1 and for alice.example.com, 10.4.0.2.
5676
5677       Once  the VPN is established, you have essentially created a secure al‐
5678       ternate path between the two hosts which is addressed by using the tun‐
5679       nel endpoints. You can control which network traffic passes between the
5680       hosts (a) over the VPN or (b) independently of  the  VPN,  by  choosing
5681       whether  to use (a) the VPN endpoint address or (b) the public internet
5682       address, to access the remote host. For example if you are on bob.exam‐
5683       ple.com  and  you  wish to connect to alice.example.com via ssh without
5684       using the VPN (since ssh has its own built-in security) you  would  use
5685       the  command  ssh  alice.example.com. However in the same scenario, you
5686       could also use the command telnet 10.4.0.2 to create a  telnet  session
5687       with  alice.example.com  over the VPN, that would use the VPN to secure
5688       the session rather than ssh.
5689
5690       You can use any address you wish for the tunnel endpoints but make sure
5691       that  they  are  private addresses (such as those that begin with 10 or
5692       192.168) and that they are not part of any existing subnet on the  net‐
5693       works  of  either  peer, unless you are bridging. If you use an address
5694       that is part of your local subnet for either of the  tunnel  endpoints,
5695       you will get a weird feedback loop.
5696
5697   Example 1: A simple tunnel without security
5698       On bob:
5699
5700          openvpn --remote alice.example.com --dev tun1 \
5701                   --ifconfig 10.4.0.1 10.4.0.2 --verb 9
5702
5703       On alice:
5704
5705          openvpn --remote bob.example.com --dev tun1 \
5706                   --ifconfig 10.4.0.2 10.4.0.1 --verb 9
5707
5708       Now verify the tunnel is working by pinging across the tunnel.
5709
5710       On bob:
5711
5712          ping 10.4.0.2
5713
5714       On alice:
5715
5716          ping 10.4.0.1
5717
5718       The  --verb  9  option will produce verbose output, similar to the tcp‐
5719       dump(8) program. Omit the --verb 9 option to have OpenVPN run quietly.
5720
5721   Example 2: A tunnel with static-key security (i.e. using a  pre-shared  se‐
5722       cret)
5723       First build a static key on bob.
5724
5725          openvpn --genkey --secret key
5726
5727       This  command  will  build a key file called key (in ascii format). Now
5728       copy key to alice.example.com over a secure medium such as by using the
5729       scp(1) program.
5730
5731       On bob:
5732
5733          openvpn --remote alice.example.com --dev tun1  \
5734                   --ifconfig 10.4.0.1 10.4.0.2 --verb 5 \
5735                   --secret key
5736
5737       On alice:
5738
5739          openvpn --remote bob.example.com --dev tun1   \
5740                  --ifconfig 10.4.0.2 10.4.0.1 --verb 5 \
5741                  --secret key
5742
5743       Now verify the tunnel is working by pinging across the tunnel.
5744
5745       On bob:
5746
5747          ping 10.4.0.2
5748
5749       On alice:
5750
5751          ping 10.4.0.1
5752
5753   Example 3: A tunnel with full TLS-based security
5754       For this test, we will designate bob as the TLS client and alice as the
5755       TLS server.
5756
5757       Note:  The client or server designation only has meaning  for  the  TLS
5758              subsystem.   It   has  no  bearing  on  OpenVPN's  peer-to-peer,
5759              UDP-based communication model.*
5760
5761       First, build a separate certificate/key pair for  both  bob  and  alice
5762       (see  above  where  --cert  is discussed for more info). Then construct
5763       Diffie Hellman parameters (see above where --dh is discussed  for  more
5764       info). You can also use the included test files client.crt, client.key,
5765       server.crt, server.key and ca.crt. The .crt files are certificates/pub‐
5766       lic-keys,  the  .key files are private keys, and ca.crt is a certifica‐
5767       tion authority who has signed  both  client.crt  and  server.crt.   For
5768       Diffie Hellman parameters you can use the included file dh2048.pem.
5769
5770       WARNING:
5771              All  client,  server, and certificate authority certificates and
5772              keys included in the OpenVPN distribution are  totally  insecure
5773              and should be used for testing only.
5774
5775       On bob:
5776
5777          openvpn --remote alice.example.com --dev tun1    \
5778                  --ifconfig 10.4.0.1 10.4.0.2             \
5779                  --tls-client --ca ca.crt                 \
5780                  --cert client.crt --key client.key       \
5781                  --reneg-sec 60 --verb 5
5782
5783       On alice:
5784
5785          openvpn --remote bob.example.com --dev tun1      \
5786                  --ifconfig 10.4.0.2 10.4.0.1             \
5787                  --tls-server --dh dh1024.pem --ca ca.crt \
5788                  --cert server.crt --key server.key       \
5789                  --reneg-sec 60 --verb 5
5790
5791       Now verify the tunnel is working by pinging across the tunnel.
5792
5793       On bob:
5794
5795          ping 10.4.0.2
5796
5797       On alice:
5798
5799          ping 10.4.0.1
5800
5801       Notice  the  --reneg-sec 60 option we used above. That tells OpenVPN to
5802       renegotiate the data channel keys every minute. Since we used --verb  5
5803       above, you will see status information on each new key negotiation.
5804
5805       For  production  operations, a key renegotiation interval of 60 seconds
5806       is probably too frequent. Omit the --reneg-sec 60 option to  use  Open‐
5807       VPN's default key renegotiation interval of one hour.
5808
5809   Routing:
5810       Assuming  you  can  ping across the tunnel, the next step is to route a
5811       real subnet over the secure tunnel. Suppose that bob and alice have two
5812       network  interfaces  each, one connected to the internet, and the other
5813       to a private network. Our goal is to securely connect both private net‐
5814       works.  We will assume that bob's private subnet is 10.0.0.0/24 and al‐
5815       ice's is 10.0.1.0/24.
5816
5817       First, ensure that IP forwarding is enabled on both  peers.  On  Linux,
5818       enable routing:
5819
5820          echo 1 > /proc/sys/net/ipv4/ip_forward
5821
5822       This setting is not persistent.  Please see your operating systems doc‐
5823       umentation how to properly configure IP forwarding, which is also  per‐
5824       sistent through system boots.
5825
5826       If  your system is configured with a firewall.  Please see your operat‐
5827       ing systems guide on how to configure the firewall.  You typically want
5828       to  allow  traffic coming from and going to the tun/tap adapter OpenVPN
5829       is configured to use.
5830
5831       On bob:
5832
5833          route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
5834
5835       On alice:
5836
5837          route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
5838
5839       Now any machine on the 10.0.0.0/24 subnet can access any machine on the
5840       10.0.1.0/24 subnet over the secure tunnel (or vice versa).
5841
5842       In  a  production  environment, you could put the route command(s) in a
5843       script and execute with the --up option.
5844

FAQ

5846       https://community.openvpn.net/openvpn/wiki/FAQ
5847

HOWTO

5849       For a more comprehensive guide to setting up OpenVPN  in  a  production
5850       setting,         see         the         OpenVPN        HOWTO        at
5851       https://openvpn.net/community-resources/how-to/
5852

PROTOCOL

5854       For   a   description   of   OpenVPN's   underlying    protocol,    see
5855       https://openvpn.net/community-resources/openvpn-protocol/
5856

WEB

5858       OpenVPN's web site is at https://openvpn.net/
5859
5860       Go  here  to  download  the latest version of OpenVPN, subscribe to the
5861       mailing lists, read the mailing list archives, or browse the SVN repos‐
5862       itory.
5863

BUGS

5865       Report all bugs to the OpenVPN team info@openvpn.net
5866

SEE ALSO

5868       dhcpcd(8), ifconfig(8), openssl(1), route(8), scp(1) ssh(1)
5869

NOTES

5871       This  product  includes  software  developed  by the OpenSSL Project (‐
5872       https://www.openssl.org/)
5873
5874       For    more    information     on     the     TLS     protocol,     see
5875       http://www.ietf.org/rfc/rfc2246.txt
5876
5877       For  more  information  on  the  LZO  real-time compression library see
5878       https://www.oberhumer.com/opensource/lzo/
5879
5881       Copyright (C) 2002-2020 OpenVPN Inc This program is free software;  you
5882       can redistribute it and/or modify it under the terms of the GNU General
5883       Public License version 2 as published by the Free Software Foundation.
5884

AUTHORS

5886       James Yonan james@openvpn.net
5887
5888
5889
5890
5891                                                                    OPENVPN(8)
Impressum