Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
OPENVPN(8)		    System Manager's Manual		    OPENVPN(8)

       openvpn - Secure	IP tunnel daemon

       openvpn [ options ... ]
       openvpn	--help

       OpenVPN	is  an	open source VPN	daemon by James	Yonan. Because OpenVPN
       tries to	be a universal VPN tool	offering a great deal of  flexibility,
       there  are a lot	of options on this manual page.	If you're new to Open-
       VPN, you	might want to skip ahead to the	 examples  section  where  you
       will  see how to	construct simple VPNs on the command line without even
       needing a configuration file.

       Also note that there's more documentation and examples on  the  OpenVPN
       web site:

       And  if you would like to see a shorter version of this manual, see the
       openvpn usage message which can be obtained by running openvpn  without
       any parameters.

       OpenVPN	is  a  robust and highly flexible VPN daemon. OpenVPN supports
       SSL/TLS security,  ethernet  bridging,  TCP  or	UDP  tunnel  transport
       through	proxies	 or  NAT,  support  for	dynamic	IP addresses and DHCP,
       scalability to hundreds or thousands of users, and portability to  most
       major OS	platforms.

       OpenVPN	is  tightly  bound to the OpenSSL library, and derives much of
       its crypto capabilities from it.

       OpenVPN supports	conventional encryption	using a	pre-shared secret  key
       (Static	Key mode) or public key	security (SSL/TLS mode)	using client &
       server certificates. OpenVPN also supports non-encrypted	 TCP/UDP  tun-

       OpenVPN	is designed to work with the TUN/TAP virtual networking	inter-
       face that exists	on most	platforms.

       Overall,	OpenVPN	aims to	offer many of the key features	of  IPSec  but
       with a relatively lightweight footprint.

       OpenVPN allows any option to be placed either on	the command line or in
       a configuration file. Though all	command	line options are preceded by a
       double-leading-dash  ("--"),  this prefix can be	removed	when an	option
       is placed in a configuration file.

   Generic Options
       This section covers generic options which are accessible	regardless  of
       which mode OpenVPN is configured	as.

       --help Show options.

	      Don't  cache --askpass or	--auth-user-pass username/passwords in
	      virtual memory.

	      If specified, this directive will	cause OpenVPN  to  immediately
	      forget  username/password	 inputs	 after they are	used. As a re-
	      sult, when OpenVPN needs a username/password, it will prompt for
	      input  from  stdin, which	may be multiple	times during the dura-
	      tion of an OpenVPN session.

	      When using --auth-nocache	in combination	with  a	 user/password
	      file  and	 --chroot  or  --daemon,  make sure to use an absolute

	      This directive does not affect the  --http-proxy	username/pass-
	      word.  It	is always cached.

       --cd dir
	      Change  directory	to dir prior to	reading	any files such as con-
	      figuration files,	key files, scripts, etc. dir should be an  ab-
	      solute  path,  with a leading "/", and without any references to
	      the current directory such as . or ...

	      This option is useful when you are running OpenVPN  in  --daemon
	      mode,  and  you  want to consolidate all of your OpenVPN control
	      files in one location.

       --chroot	dir
	      Chroot to	dir after initialization. --chroot  essentially	 rede-
	      fines  dir  as  being  the top level directory tree (/). OpenVPN
	      will therefore be	unable to access any files outside this	 tree.
	      This can be desirable from a security standpoint.

	      Since  the  chroot  operation is delayed until after initializa-
	      tion, most OpenVPN options that reference	files will operate  in
	      a	pre-chroot context.

	      In  many	cases,	the dir	parameter can point to an empty	direc-
	      tory, however complications can result when scripts or  restarts
	      are executed after the chroot operation.

	      Note:  The  SSL  library	will  probably need /dev/urandom to be
	      available	inside the chroot directory dir. This is  because  SSL
	      libraries	 occasionally  need to collect fresh randomness. Newer
	      linux kernels and	some BSDs implement a  getrandom()  or	geten-
	      tropy()  syscall	that  removes  the need	for /dev/urandom to be

       --compat-mode version
	      This option provides a way to alter the default of OpenVPN to be
	      more  compatible	with the version version specified. All	of the
	      changes this option does can also	be achieved  using  individual
	      configuration options.

	      Note:  Using  this  option  reverts defaults to no longer	recom-
	      mended values and	should be avoided if possible.

	      The following table details what defaults	are changed  depending
	      on the version specified.

	      o	2.5.x  or  lower:  --allow-compression	asym  is automatically
		added to the configuration if no other compression options are

	      o	2.4.x  or  lower:  The	cipher	in  --cipher  is  appended  to

	      o	2.3.x or lower:	--data-cipher-fallback is automatically	 added
		with the same cipher as	--cipher

	      o	2.3.6 or lower:	--tls-version-min 1.0 is added to the configu-
		ration when --tls-version-min is not explicitly	set.

       --config	file
	      Load additional config options from file where each line	corre-
	      sponds  to  one command line option, but with the	leading	-- re-

	      If --config file is the only option to the openvpn command,  the
	      --config can be removed, and the command can be given as openvpn

	      Note that	configuration files can	 be  nested  to	 a  reasonable

	      Double  quotation	or single quotation characters ("", '')	can be
	      used to enclose single parameters	containing whitespace, and "#"
	      or ";" characters	in the first column can	be used	to denote com-

	      Note that	OpenVPN	2.0 and	higher performs	backslash-based	 shell
	      escaping for characters not in single quotations,	so the follow-
	      ing mappings should be observed:

		 \\	  Maps to a single backslash character (\).
		 \"	  Pass a literal doublequote character ("), don't
			  interpret it as enclosing a parameter.
		 \[SPACE] Pass a literal space or tab character, don't
			  interpret it as a parameter delimiter.

	      For example on Windows,  use  double  backslashes	 to  represent

		 secret	"c:\\OpenVPN\\secret.key"

	      For      examples	     of	     configuration	files,	   see

	      Here is an example configuration file:

		 # Sample OpenVPN configuration	file for
		 # using a pre-shared static key.
		 # '#' or ';' may be used to delimit comments.

		 # Use a dynamic tun device.
		 dev tun

		 # Our remote peer
		 remote	mypeer.mydomain

		 # is our local VPN endpoint
		 # is our remote VPN endpoint

		 # Our pre-shared static key
		 secret	static.key

       --daemon	progname
	      Become a daemon after  all  initialization  functions  are  com-

	      Valid syntaxes:

		 daemon	progname

	      This  option  will cause all message and error output to be sent
	      to the syslog file (such as /var/log/messages), except  for  the
	      output  of  scripts  and	ifconfig  commands,  which  will go to
	      /dev/null	unless otherwise redirected.  The  syslog  redirection
	      occurs  immediately  at the point	that --daemon is parsed	on the
	      command line even	though the daemonization point	occurs	later.
	      If one of	the --log options is present, it will supersede	syslog

	      The optional progname parameter will cause OpenVPN to report its
	      program  name to the system logger as progname. This can be use-
	      ful in linking OpenVPN messages in the syslog file with specific
	      tunnels. When unspecified, progname defaults to openvpn.

	      When OpenVPN is run with the --daemon option, it will try	to de-
	      lay daemonization	until the majority of initialization functions
	      which  are capable of generating fatal errors are	complete. This
	      means that initialization	scripts	can test the return status  of
	      the  openvpn command for a fairly	reliable indication of whether
	      the command has correctly	initialized  and  entered  the	packet
	      forwarding event loop.

	      In  OpenVPN,  the	vast majority of errors	which occur after ini-
	      tialization are non-fatal.

	      Note: as soon as OpenVPN has daemonized,	it  can	 not  ask  for
	      usernames, passwords, or key pass	phrases	anymore. This has cer-
	      tain consequences, namely	that using a  password-protected  pri-
	      vate  key	 will fail unless the --askpass	option is used to tell
	      OpenVPN to ask for the pass phrase (this requirement is  new  in
	      v2.3.7, and is a consequence of calling daemon() before initial-
	      izing the	crypto layer).

	      Further, using --daemon together with --auth-user-pass  (entered
	      on  console) and --auth-nocache will fail	as soon	as key renego-
	      tiation (and reauthentication) occurs.

	      Disable "data channel offload" (DCO).

	      On Linux don't use the ovpn-dco device driver, but  rather  rely
	      on the legacy tun	module.

	      You  may	want  to use this option if your server	needs to allow
	      clients older than version 2.4 to	connect.

	      DEPRECATED Disable "options consistency check" (OCC) in configu-
	      rations that do not use TLS.

	      Don't output a warning message if	option inconsistencies are de-
	      tected between peers. An	example	 of  an	 option	 inconsistency
	      would be where one peer uses --dev tun while the other peer uses
	      --dev tap.

	      Use of this option is discouraged, but is	provided as  a	tempo-
	      rary  fix	 in  situations	where a	recent version of OpenVPN must
	      connect to an old	version.

       --engine	engine-name
	      Enable OpenSSL hardware-based crypto engine functionality.

	      Valid syntaxes:

		 engine	engine-name

	      If engine-name is	specified, use a specific crypto  engine.  Use
	      the  --show-engines standalone option to list the	crypto engines
	      which are	supported by OpenSSL.

	      (Experimental) Optimize TUN/TAP/UDP I/O  writes  by  avoiding  a
	      call to poll/epoll/select	prior to the write operation. The pur-
	      pose of such a call would	normally be to block until the	device
	      or  socket is ready to accept the	write. Such blocking is	unnec-
	      essary on	some platforms which don't support write  blocking  on
	      UDP  sockets or TUN/TAP devices. In such cases, one can optimize
	      the event	loop by	avoiding the poll/epoll/select call, improving
	      CPU efficiency by	5% to 10%.

	      This  option  can	 only  be  used	 on  non-Windows systems, when
	      --proto udp is specified,	and when --shaper is NOT specified.

       --group group
	      Similar to the --user option, this option	changes	the  group  ID
	      of the OpenVPN process to	group after initialization.

       --ignore-unknown-option args
	      Valid syntax:

		 ignore-unknown-options	opt1 opt2 opt3 ... optN

	      When one of options opt1 ... optN	is encountered in the configu-
	      ration file the configuration file parsing does not fail if this
	      OpenVPN  version	does  not  support  the	option.	Multiple --ig-
	      nore-unknown-option options can be given	to  support  a	larger
	      number of	options	to ignore.

	      This option should be used with caution, as there	are good secu-
	      rity reasons for having OpenVPN fail if it detects problems in a
	      config  file.   Having  said  that,  there are valid reasons for
	      wanting new software features to gracefully degrade when encoun-
	      tered by older software versions.

	      --ignore-unknown-option is available since OpenVPN 2.3.3.

       --iproute cmd
	      Set  alternate  command  to  execute instead of default iproute2
	      command.	May be used in order to	execute	 OpenVPN  in  unprivi-
	      leged environment.

       --keying-material-exporter args
	      Save  Exported  Keying  Material [RFC5705] of len	bytes (must be
	      between 16 and 4095  bytes)  using  label	 in  environment  (ex-
	      ported_keying_material)	 for   use   by	  plugins   in	 OPEN-
	      VPN_PLUGIN_TLS_FINAL callback.

	      Valid syntax:

		 keying-material-exporter label	len

	      Note that	exporter labels	have the potential to collide with ex-
	      isting  PRF  labels. In order to prevent this, labels MUST begin
	      with EXPORTER.

	      Disable paging by	calling	the POSIX mlockall function.  Requires
	      that OpenVPN be initially	run as root (though OpenVPN can	subse-
	      quently downgrade	its UID	using the --user option).

	      Using this option	ensures	that key material and tunnel data  are
	      never  written  to  disk due to virtual memory paging operations
	      which occur under	most modern operating systems. It ensures that
	      even  if	an attacker was	able to	crack the box running OpenVPN,
	      he would not be able to scan the system  swap  file  to  recover
	      previously  used	ephemeral keys,	which are used for a period of
	      time governed by the --reneg options (see	below),	then are  dis-

	      The  downside of using --mlock is	that it	will reduce the	amount
	      of physical memory available to other applications.

	      The limit	on how much memory can be locked and how that limit is
	      enforced	are  OS-dependent.  On Linux the default limit that an
	      unprivileged process may lock (RLIMIT_MEMLOCK) is	 low,  and  if
	      privileges  are  dropped	later,	future memory allocations will
	      very likely fail.	The limit can be  increased  using  ulimit  or
	      systemd directives depending on how OpenVPN is started.

	      If  the  platform	has the	getrlimit(2) system call, OpenVPN will
	      check for	the amount of mlock-able memory	before calling	mlock-
	      all(2),  and  tries to increase the limit	to 100 MB if less than
	      this is configured.  100 Mb is somewhat arbitrary	- it is	enough
	      for  a moderately-sized OpenVPN deployment, but the memory usage
	      might go beyond that if the  number  of  concurrent  clients  is

       --nice n
	      Change  process  priority	after initialization (n	greater	than 0
	      is lower priority, n less	than zero is higher priority).

	      Don't re-read key	files across SIGUSR1 or	--ping-restart.

	      This option can be combined with --user to allow restarts	 trig-
	      gered  by	 the  SIGUSR1 signal. Normally if you drop root	privi-
	      leges in OpenVPN,	the daemon cannot be restarted since  it  will
	      now be unable to re-read protected key files.

	      This option solves the problem by	persisting keys	across SIGUSR1
	      resets, so they don't need to be re-read.

       --providers providers
	      Load the list of (OpenSSL) providers. This is mainly useful  for
	      using  an	external provider for key management like tpm2-openssl
	      or to load the legacy provider with

		 --providers legacy default

	      Behaviour	of changing this option	between	SIGHUP	might  not  be
	      well  behaving.	If  you	need to	change/add/remove this option,
	      fully restart OpenVPN.

       --remap-usr1 signal
	      Control whether internally or externally generated SIGUSR1  sig-
	      nals  are	 remapped to SIGHUP (restart without persisting	state)
	      or SIGTERM (exit).

	      signal can be set	to SIGHUP or SIGTERM. By default, no remapping

       --script-security level
	      This  directive offers policy-level control over OpenVPN's usage
	      of external programs and scripts.	Lower level  values  are  more
	      restrictive,  higher  values  are	 more permissive. Settings for

	      0	     Strictly no calling of external programs.

	      1	     (Default) Only call built-in executables such  as	ifcon-
		     fig, ip, route, or	netsh.

	      2	     Allow  calling  of	 built-in executables and user-defined

	      3	     Allow passwords to	be passed to scripts via environmental
		     variables (potentially unsafe).

	      OpenVPN  releases	before v2.3 also supported a method flag which
	      indicated	how OpenVPN should call	external commands and scripts.
	      This  could  be either execve or system. As of OpenVPN 2.3, this
	      flag is no longer	accepted. In most *nix	environments  the  ex-
	      ecve() approach has been used without any	issues.

	      Some  directives	such as	--up allow options to be passed	to the
	      external script. In these	cases make sure	the script  name  does
	      not  contain  any	 spaces	or the configuration parser will choke
	      because it can't determine where the script name ends and	script
	      options start.

	      To run scripts in	Windows	in earlier OpenVPN versions you	needed
	      to either	add a full path	to the script  interpreter  which  can
	      parse the	script or use the system flag to run these scripts. As
	      of OpenVPN 2.3 it	is now a strict	requirement to have full  path
	      to  the  script  interpreter when	running	non-executables	files.
	      This is not needed for executable	files,	such  as  .exe,	 .com,
	      .bat  or	.cmd  files.  For  example, if you have	a Visual Basic
	      script, you must use this	syntax now:

		 --up 'C:\\Windows\\System32\\wscript.exe C:\\Program\ Files\\OpenVPN\\config\\my-up-script.vbs'

	      Please note the single quote marks and the escaping of the back-
	      slashes (\) and the space	character.

	      The reason the support for the system flag was removed is	due to
	      the security implications	with shell expansions  when  executing
	      scripts via the system() call.

       --setcon	context
	      Apply  SELinux  context  after  initialization. This essentially
	      provides the ability to restrict OpenVPN's rights	to  only  net-
	      work  I/O	 operations, thanks to SELinux.	This goes further than
	      --user and --chroot in that those	two, while being  great	 secu-
	      rity  features,  unfortunately  do not protect against privilege
	      escalation by exploitation of a vulnerable system	call. You  can
	      of  course  combine all three, but please	note that since	setcon
	      requires access to /proc you will	have to	provide	it inside  the
	      chroot directory (e.g. with mount	--bind).

	      Since  the  setcon  operation is delayed until after initializa-
	      tion, OpenVPN can	be restricted to just  network-related	system
	      calls,  whereas  by applying the context before startup (such as
	      the OpenVPN one provided in the SELinux Reference	Policies)  you
	      will  have to allow many things required only during initializa-

	      Like with	chroot,	 complications	can  result  when  scripts  or
	      restarts	are  executed after the	setcon operation, which	is why
	      you should really	consider using the  --persist-key  and	--per-
	      sist-tun options.

       --status	args
	      Write  operational status	to file	every n	seconds. n defaults to
	      60 if not	specified.

	      Valid syntaxes:

		 status	file
		 status	file n

	      Status can also be written to the	syslog by  sending  a  SIGUSR2

	      With  multi-client  capability  enabled  on a server, the	status
	      file includes a list of clients and a routing table. The	output
	      format  can be controlled	by the --status-version	option in that

	      For clients or instances running in point-to-point mode, it will
	      contain the traffic statistics.

       --status-version	n
	      Set the status file format version number	to n.

	      This  only  affects the status file on servers with multi-client
	      capability enabled.  Valid status	version	values:

	      1	     Traditional format	(default). The	client	list  contains
		     the  following  fields comma-separated: Common Name, Real
		     Address, Bytes Received, Bytes Sent, Connected Since.

	      2	     A more reliable format for	external processing.  Compared
		     to	 version  1,  the client list contains some additional
		     fields: Virtual Address, Virtual IPv6 Address,  Username,
		     Client  ID, Peer ID, Data Channel Cipher. Future versions
		     may extend	the number of fields.

	      3	     Identical to 2, but fields	are tab-separated.

	      Do a self-test of	OpenVPN's crypto options by encrypting and de-
	      crypting	test packets using the data channel encryption options
	      specified	above.	This option does not require a peer  to	 func-
	      tion, and	therefore can be specified without --dev or --remote.

	      The typical usage	of --test-crypto would be something like this:

		 openvpn --test-crypto --secret	key


		 openvpn --test-crypto --secret	key --verb 9

	      This  option  is	very  useful to	test OpenVPN after it has been
	      ported to	a new platform,	or to isolate  problems	 in  the  com-
	      piler,  OpenSSL  crypto library, or OpenVPN's crypto code. Since
	      it is a self-test	mode, problems with encryption and authentica-
	      tion can be debugged independently of network and	tunnel issues.

       --tmp-dir dir
	      Specify a	directory dir for temporary files. This	directory will
	      be used by openvpn processes and script to communicate temporary
	      data  with openvpn main process. Note that the directory must be
	      writable by the OpenVPN process after it has dropped  it's  root

	      This directory will be used by in	the following cases:

	      o	--client-connect   scripts  and	 OPENVPN_PLUGIN_CLIENT_CONNECT
		plug-in	hook to	dynamically generate client-specific  configu-
		ration	client_connect_config_file  and	return success/failure
		via client_connect_deferred_file when  using  deferred	client
		connect	method

	      o	OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY   plug-in	hooks  returns
		success/failure	via auth_control_file when using deferred auth
		method and pending authentification via	pending_auth_file.

	      Enable prediction	resistance on mbed TLS's RNG.

	      Enabling	prediction resistance causes the RNG to	reseed in each
	      call for random. Reseeding this often can	 quickly  deplete  the
	      kernel entropy pool.

	      If  you  need this option, please	consider running a daemon that
	      adds entropy to the kernel pool.

       --user user
	      Change the user ID of the	OpenVPN	process	to user	after initial-
	      ization, dropping	privileges in the process. This	option is use-
	      ful to protect the system	in the event that some	hostile	 party
	      was able to gain control of an OpenVPN session. Though OpenVPN's
	      security features	make this unlikely, it is provided as a	second
	      line of defense.

	      By  setting  user	to an unprivileged user	dedicated to run open-
	      vpn, the hostile party would be  limited	in  what  damage  they
	      could cause. Of course once you take away	privileges, you	cannot
	      return them to an	OpenVPN	session. This means, for example, that
	      if  you  want  to	 reset an OpenVPN daemon with a	SIGUSR1	signal
	      (for example in response to a DHCP reset), you should  make  use
	      of  one  or more of the --persist	options	to ensure that OpenVPN
	      doesn't need to execute any privileged operations	 in  order  to
	      restart (such as re-reading key files or running ifconfig	on the
	      TUN device).

	      NOTE: Previous versions of openvpn used nobody  as  the  example
	      unpriviledged  user.  It is not recommended to actually use that
	      user since it is usually used by other system services  already.
	      Always create a dedicated	user for openvpn.

       --writepid file
	      Write OpenVPN's main process ID to file.

   Log options
       --echo parms
	      Echo parms to log	output.

	      Designed	to  be used to send messages to	a controlling applica-
	      tion which is receiving the OpenVPN log output.

	      Output errors to stderr instead of stdout	unless log  output  is
	      redirected by one	of the --log options.

       --log file
	      Output  logging  messages	 to  file,  including  output  to std-
	      out/stderr which is generated by called scripts. If file already
	      exists  it  will	be truncated. This option takes	effect immedi-
	      ately when it is parsed in the command line and  will  supersede
	      syslog output if --daemon	is also	specified. This	option is per-
	      sistent over the entire course of	an OpenVPN  instantiation  and
	      will not be reset	by SIGHUP, SIGUSR1, or --ping-restart.

	      Note that	on Windows, when OpenVPN is started as a service, log-
	      ging occurs by default without the need to specify this option.

       --log-append file
	      Append logging messages to file.	If file	 does  not  exist,  it
	      will  be	created. This option behaves exactly like --log	except
	      that it appends to rather	than truncating	the log	file.

	      Always write timestamps and message flags	to log messages,  even
	      when  they  otherwise would not be prefixed. In particular, this
	      applies to log messages sent to stdout.

       --mute n
	      Log at most n consecutive	messages in the	same category. This is
	      useful to	limit repetitive logging of similar message types.

	      Silence  the output of replay warnings, which are	a common false
	      alarm on WiFi networks. This option preserves  the  security  of
	      the replay protection code without the verbosity associated with
	      warnings about duplicate packets.

	      Avoid writing timestamps to log messages,	even when they	other-
	      wise would be prepended. In particular, this applies to log mes-
	      sages sent to stdout.

       --syslog	progname
	      Direct log output	to system logger, but do not become a  daemon.
	      See --daemon directive above for description of progname parame-

       --verb n
	      Set output verbosity to n	(default 1). Each level	shows all info
	      from  the	 previous levels. Level	3 is recommended if you	want a
	      good summary of what's happening without being swamped  by  out-

	      0	     No	output except fatal errors.

	      1	to 4 Normal usage range.

	      5	     Outputs R and W characters	to the console for each	packet
		     read and write, uppercase is used for TCP/UDP packets and
		     lowercase is used for TUN/TAP packets.

	      6	to 11
		     Debug  info  range	(see errlevel.h	in the source code for
		     additional	information on debug levels).

   Protocol options
       Options in this section affect features available in the	 OpenVPN  wire
       protocol.   Many	of these options also define the encryption options of
       the data	channel	in the OpenVPN wire protocol.  These options  must  be
       configured in a compatible way between both the local and remote	side.

       --allow-compression mode
	      As  described  in	the --compress option, compression is a	poten-
	      tially dangerous option.	This option allows controlling the be-
	      haviour of OpenVPN when compression is used and allowed.

	      Valid syntaxes:

		 allow-compression mode

	      The mode argument	can be one of the following values:

	      asym   OpenVPN  will  only  decompress  downlink packets but not
		     compress uplink packets.  This also allows	 migrating  to
		     disable  compression when changing	both server and	client
		     configurations to remove compression at the same time  is
		     not a feasible option.

	      no (default)
		     OpenVPN will refuse any non-stub compression.

	      yes    OpenVPN will send and receive compressed packets.

       --auth alg
	      Authenticate data	channel	packets	and (if	enabled) tls-auth con-
	      trol channel packets with	HMAC using  message  digest  algorithm
	      alg. (The	default	is SHA1	). HMAC	is a commonly used message au-
	      thentication algorithm (MAC) that	uses a data string,  a	secure
	      hash algorithm and a key to produce a digital signature.

	      The  OpenVPN  data  channel protocol uses	encrypt-then-mac (i.e.
	      first encrypt a packet  then  HMAC  the  resulting  ciphertext),
	      which prevents padding oracle attacks.

	      If  an  AEAD cipher mode (e.g. GCM) is chosen then the specified
	      --auth algorithm is ignored for the data channel and the authen-
	      tication	method	of  the	AEAD cipher is used instead. Note that
	      alg still	specifies the digest used for tls-auth.

	      In static-key encryption mode, the HMAC key is included  in  the
	      key file generated by --genkey. In TLS mode, the HMAC key	is dy-
	      namically	generated and shared between peers via the TLS control
	      channel.	If  OpenVPN  receives a	packet with a bad HMAC it will
	      drop the packet. HMAC usually adds 16 or 20  bytes  per  packet.
	      Set alg=none to disable authentication.

	      For	 more	     information       on	HMAC	   see

       --cipher	alg
	      This option should not be	used any longer	in TLS mode and	 still
	      exists for two reasons:

	      o	compatibility	with  old  configurations  still  carrying  it

	      o	allow users connecting to OpenVPN peers	older  than  2.6.0  to
		have  --cipher	configured the same way	as the remote counter-
		part. This can avoid MTU/frame size warnings.

	      Before 2.4.0, this option	was used to select the	cipher	to  be
	      configured  on the data channel, however,	later versions usually
	      ignored this directive in	favour of a negotiated cipher.	Start-
	      ing  with	 2.6.0,	this option is always ignored in TLS mode when
	      it comes to configuring the cipher and will only control the ci-
	      pher for --secret	pre-shared-key mode (note: this	mode is	depre-
	      cated and	strictly not recommended).

	      If you wish to specify the cipher	to use on  the	data  channel,
	      please   see   --data-ciphers   (for  regular  negotiation)  and
	      --data-ciphers-fallback (for a fallback option when the negotia-
	      tion  cannot take	place because the other	peer is	old or has ne-
	      gotiation	disabled).

	      To  see  ciphers	that  are  available  with  OpenVPN,  use  the
	      --show-ciphers option.

	      Set alg to none to disable encryption.

       --compress algorithm
	      DEPRECATED Enable	a compression algorithm. Compression is	gener-
	      ally not recommended. VPN	tunnels	which use compression are sus-
	      ceptible	to the VORALCE attack vector. See also the migrate pa-
	      rameter below.

	      The algorithm parameter may be lzo, lz4, lz4-v2, stub,  stub-v2,
	      migrate  or  empty.  LZO and LZ4 are different compression algo-
	      rithms, with LZ4 generally offering the  best  performance  with
	      least CPU	usage.

	      The  lz4-v2 and stub-v2 variants implement a better framing that
	      does not add overhead when packets  cannot  be  compressed.  All
	      other  variants always add one extra framing byte	compared to no
	      compression framing.

	      Especially stub-v2 is essentially	identical  to  no  compression
	      and  no compression framing as its header	indicates IP version 5
	      in a tun setup and can (ab)used to complete disable  compression
	      to clients. (See the migrate option below)

	      If  the  algorithm parameter is stub, stub-v2 or empty, compres-
	      sion will	be turned off, but the packet framing for  compression
	      will still be enabled, allowing a	different setting to be	pushed
	      later.  Additionally, stub and stub-v2  wil  disable  announcing
	      lzo and lz4 compression support via IV_ variables	to the server.

	      Note:  the  stub	(or  empty)  option is NOT compatible with the
	      older option --comp-lzo no.

	      Using migrate as compression algorithm enables a special	migra-
	      tion   mode.    It   allows   migration  away  from  the	--com-
	      press/--comp-lzo options to no compression.   This  option  sets
	      the server to no compression mode	and the	server behaves identi-
	      cal to a server without a	compression  option  for  all  clients
	      without  a  compression in their config. However,	if a client is
	      detected that indicates that compression is used (via OCC),  the
	      server  will  automatically  add	--push compress	stub-v2	to the
	      client specific configuration if supported  by  the  client  and
	      otherwise	 switch	 to comp-lzo no	and add	--push comp-lzo	to the
	      client specific configuration.

	      *Security	Considerations*

	      Compression and encryption is a tricky combination.  If  an  at-
	      tacker  knows or is able to control (parts of) the plain-text of
	      packets that contain secrets, the	attacker might be able to  ex-
	      tract  the  secret if compression	is enabled. See	e.g. the CRIME
	      and BREACH attacks on TLS	and VORACLE on VPNs which also	lever-
	      age  to  break encryption. If you	are not	entirely sure that the
	      above does not apply to your traffic, you	are advised to not en-
	      able compression.

       --comp-lzo mode
	      DEPRECATED  Enable  LZO  compression  algorithm.	Compression is
	      generally	not recommended.  VPN tunnels which  uses  compression
	      are suspectible to the VORALCE attack vector.

	      Use  LZO	compression -- may add up to 1 byte per	packet for in-
	      compressible data. mode may be yes, no, or adaptive (default).

	      In a server mode setup, it is possible to	selectively turn  com-
	      pression on or off for individual	clients.

	      First,  make  sure the client-side config	file enables selective
	      compression by having at least one --comp-lzo directive, such as
	      --comp-lzo  no.  This  will turn off compression by default, but
	      allow a future directive push from  the  server  to  dynamically
	      change the on/off/adaptive setting.

	      Next in a	--client-config-dir file, specify the compression set-
	      ting for the client, for example:

		 comp-lzo yes
		 push "comp-lzo	yes"

	      The first	line sets the comp-lzo setting for the server side  of
	      the link,	the second sets	the client side.

	      DEPRECATED When used in conjunction with --comp-lzo, this	option
	      will disable OpenVPN's adaptive compression algorithm. Normally,
	      adaptive compression is enabled with --comp-lzo.

	      Adaptive	compression  tries to optimize the case	where you have
	      compression enabled, but you are	sending	 predominantly	incom-
	      pressible	 (or  pre-compressed) packets over the tunnel, such as
	      an FTP or	rsync transfer of a large, compressed file. With adap-
	      tive  compression, OpenVPN will periodically sample the compres-
	      sion process to measure its efficiency. If the data  being  sent
	      over  the	 tunnel	 is  already compressed, the compression effi-
	      ciency will be very low, triggering openvpn to disable  compres-
	      sion for a period	of time	until the next re-sample test.

	      Alternative  way	of specifying the optional direction parameter
	      for the --tls-auth and --secret options. Useful when  using  in-
	      line files (See section on inline	files).

       --data-ciphers cipher-list
	      Restrict	the allowed ciphers to be negotiated to	the ciphers in
	      cipher-list. cipher-list is a colon-separated list  of  ciphers,
	      and  defaults  to	AES-256-GCM:AES-128-GCM:CHACHA20-POLY1305 when
	      Chacha20-Poly1305	     is	     available	    and	     otherwise

	      For servers, the first cipher from cipher-list that is also sup-
	      ported by	the client will	be pushed to clients that support  ci-
	      pher negotiation.

	      For more details see the chapter on Data channel cipher negotia-
	      tion.  Especially	if you need to support	clients	 with  OpenVPN
	      versions older than 2.4!

	      Starting	with  OpenVPN 2.6 a cipher can be prefixed with	a ? to
	      mark it as optional. This	allows including ciphers in  the  list
	      that   may   not	 be   available	  on   all   platforms.	  E.g.
	      AES-256-GCM:AES-128-GCM:?CHACHA20-POLY1305  would	 only	enable
	      Chacha20-Poly1305	if the underlying SSL library (and its config-
	      uration) supports	it.

	      Cipher negotiation is enabled in client-server mode  only.  I.e.
	      if  --mode  is  set  to  server (server-side, implied by setting
	      --server ), or if	--pull is specified (client-side,  implied  by
	      setting --client).

	      If no common cipher is found during cipher negotiation, the con-
	      nection is terminated. To	support	old clients/old	 servers  that
	      do  not  provide	any  cipher negotiation	support	see --data-ci-

	      If --compat-mode is set to a version older than 2.5.0 the	cipher
	      specified	 by --cipher will be appended to --data-ciphers	if not
	      already present.

	      This list	is restricted to be 127	chars long after conversion to
	      OpenVPN ciphers.

	      This option was called --ncp-ciphers in OpenVPN 2.4 but has been
	      renamed to --data-ciphers	in OpenVPN 2.5 to more accurately  re-
	      flect its	meaning.

       --data-ciphers-fallback alg
	      Configure	 a cipher that is used to fall back to if we could not
	      determine	which cipher the peer is willing to use.

	      This option should only be needed	to connect to peers  that  are
	      running  OpenVPN 2.3 or older versions, and have been configured
	      with --enable-small (typically used on routers or	other embedded

       --secret	args
	      DEPRECATED  Enable  Static  Key  encryption  mode	(non-TLS). Use
	      pre-shared secret	file which was generated with --genkey.

	      Valid syntaxes:

		 secret	file
		 secret	file direction

	      The optional direction parameter enables the use of  4  distinct
	      keys  (HMAC-send,	cipher-encrypt,	HMAC-receive, cipher-decrypt),
	      so that each data	flow direction has a different set of HMAC and
	      cipher  keys. This has a number of desirable security properties
	      including	eliminating certain kinds of DoS  and  message	replay

	      When  the	 direction parameter is	omitted, 2 keys	are used bidi-
	      rectionally, one for HMAC	and the	other  for  encryption/decryp-

	      The direction parameter should always be complementary on	either
	      side of the connection, i.e. one side should use 0 and the other
	      should use 1, or both sides should omit it altogether.

	      The  direction  parameter	requires that file contains a 2048 bit
	      key. While pre-1.5 versions of OpenVPN  generate	1024  bit  key
	      files,  any  version of OpenVPN which supports the direction pa-
	      rameter, will also support 2048 bit key  file  generation	 using
	      the --genkey option.

	      Static  key  encryption mode has certain advantages, the primary
	      being ease of configuration.

	      There are	no certificates	or certificate authorities or  compli-
	      cated negotiation	handshakes and protocols. The only requirement
	      is that you have a pre-existing secure channel  with  your  peer
	      (such as ssh) to initially copy the key. This requirement, along
	      with the fact that your key never	changes	 unless	 you  manually
	      generate	a new one, makes it somewhat less secure than TLS mode
	      (see below). If an attacker manages to steal  your  key,	every-
	      thing  that  was ever encrypted with it is compromised. Contrast
	      that to the perfect forward secrecy features of TLS mode	(using
	      Diffie Hellman key exchange), where even if an attacker was able
	      to steal your private key, he would gain no information to  help
	      him decrypt past sessions.

	      Another  advantageous  aspect  of	 Static	Key encryption mode is
	      that it is a handshake-free protocol without any	distinguishing
	      signature	or feature (such as a header or	protocol handshake se-
	      quence) that would mark the ciphertext packets as	 being	gener-
	      ated  by	OpenVPN.  Anyone  eavesdropping	 on the	wire would see
	      nothing but random-looking data.

       --tran-window n
	      Transition window	-- our old key can live	this many seconds  af-
	      ter  a  new  a  key renegotiation	begins (default	3600 seconds).
	      This feature allows for a	graceful transition from  old  to  new
	      key,  and	removes	the key	renegotiation sequence from the	criti-
	      cal path of tunnel data forwarding.

   Client Options
       The client options are used when	connecting to an OpenVPN  server  con-
       figured	to use --server, --server-bridge, or --mode server in its con-

	      Allow client to pull DNS names from server  (rather  than	 being
	      limited	to   IP	  address)   for   --ifconfig,	 --route,  and

	      When this	option is set, OpenVPN	will  not  drop	 incoming  tun
	      packets with same	destination as host.

       --auth-token token
	      This  is	not an option to be used directly in any configuration
	      files, but rather	 push  this  option  from  a  --client-connect
	      script	or   a	 --plugin   which   hooks   into   the	 OPEN-
	      calls. This option provides a possibility	to replace the clients
	      password with an authentication token during the lifetime	of the
	      OpenVPN client.

	      Whenever	  the	 connection    is    renegotiated    and   the
	      --auth-user-pass-verify script or	--plugin  making  use  of  the
	      OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY  hook is triggered, it will
	      pass over	this token as the password instead of the password the
	      user  provided.  The authentication token	can only be reset by a
	      full reconnect where the server can  push	 new  options  to  the
	      client. The password the user entered is never preserved once an
	      authentication token has been set. If the	 OpenVPN  server  side
	      rejects the authentication token then the	client will receive an
	      AUTH_FAILED and disconnect.

	      The purpose of this is to	enable two factor authentication meth-
	      ods,  such  as  HOTP  or TOTP, to	be used	without	needing	to re-
	      trieve a new OTP code each time the connection is	 renegotiated.
	      Another  use  case is to cache authentication data on the	client
	      without needing to have the users	password cached	in memory dur-
	      ing the life time	of the session.

	      To  make	use  of	 this  feature,	the --client-connect script or
	      --plugin needs to	put

		 push "auth-token UNIQUE_TOKEN_VALUE"

	      into the file/buffer for dynamic configuration data.  This  will
	      then  make  the OpenVPN server to	push this value	to the client,
	      which replaces the local password	with the UNIQUE_TOKEN_VALUE.

	      Newer clients (2.4.7+) will fall back to the  original  password
	      method  after  a	failed auth. Older clients will	keep using the
	      token value and react according to --auth-retry

       --auth-token-user base64username
	      Companion	option to --auth-token.	This options allows  to	 over-
	      ride  the	username used by the client when reauthenticating with
	      the auth-token.  It also allows to use  --auth-token  in	setups
	      that normally do not use username	and password.

	      The username has to be base64 encoded.

	      Authenticate with	server using username/password.

	      Valid syntaxes:

		 auth-user-pass	up

	      If up is present,	it must	be a file containing username/password
	      on 2 lines. If the password line is missing, OpenVPN will	prompt
	      for one.

	      If  up  is  omitted, username/password will be prompted from the

	      The server configuration must specify an --auth-user-pass-verify
	      script to	verify the username/password provided by the client.

       --auth-retry type
	      Controls	how OpenVPN responds to	username/password verification
	      errors such as the client-side response to an  AUTH_FAILED  mes-
	      sage  from the server or verification failure of the private key

	      Normally used to prevent auth errors from	 being	fatal  on  the
	      client  side,  and to permit username/password requeries in case
	      of error.

	      An AUTH_FAILED message is	generated by the server	if the	client
	      fails  --auth-user-pass  authentication,	or  if the server-side
	      --client-connect script returns an error status when the	client
	      tries to connect.

	      type can be one of:

	      none   Client  will  exit	 with  a  fatal	error (this is the de-

		     Client will retry the connection without  requerying  for
		     an	 --auth-user-pass  username/password.  Use this	option
		     for unattended clients.

		     Client  will  requery  for	 an   --auth-user-pass	 user-
		     name/password and/or private key password before attempt-
		     ing a reconnection.

	      Note that	while this option cannot be pushed,  it	 can  be  con-
	      trolled from the management interface.

	      A	 helper	 directive  designed  to simplify the configuration of
	      OpenVPN's	client mode. This directive is equivalent to:


       --client-nat args
	      This pushable client option sets up a stateless  one-to-one  NAT
	      rule  on	packet	addresses  (not	ports),	and is useful in cases
	      where routes or ifconfig settings	pushed	to  the	 client	 would
	      create an	IP numbering conflict.


		 client-nat snat
		 client-nat dnat

	      network/netmask  (for  example defines
	      the local	view of	a resource from	the client perspective,	 while
	      alias/netmask  (for  example defines the
	      remote view from the server perspective.

	      Use snat (source NAT) for	resources owned	by the client and dnat
	      (destination NAT)	for remote resources.

	      Set  --verb  6  for debugging info showing the transformation of
	      src/dest addresses in packets.

       --connect-retry args
	      Wait n seconds between connection	 attempts  (default  1).   Re-
	      peated reconnection attempts are slowed down after 5 retries per
	      remote by	doubling the wait time	after  each  unsuccessful  at-

	      Valid syntaxes:

		 connect retry n
		 connect retry n max

	      If the optional argument max is specified, the maximum wait time
	      in seconds gets capped at	that value (default 300).

       --connect-retry-max n
	      n	specifies the number of	times each  --remote  or  <connection>
	      entry  is	 tried.	Specifying n as	1 would	try each entry exactly
	      once. A successful connection resets the counter.	 (default  un-

       --connect-timeout n
	      See --server-poll-timeout.

       --dns args
	      Client DNS configuration to be used with the connection.

	      Valid syntaxes:

		 dns search-domains domain [domain ...]
		 dns server n address addr[:port] [addr[:port]]
		 dns server n resolve-domains|exclude-domains domain [domain ...]
		 dns server n dnssec yes|optional|no
		 dns server n transport	DoH|DoT|plain
		 dns server n sni server-name

	      The  --dns  search-domains  directive  takes  one	or more	domain
	      names to be added	as DNS domain suffixes.	If it is repeated mul-
	      tiple  times  within  a  configuration the domains are appended,
	      thus e.g.	domain names pushed by a server	will amend locally de-
	      fined ones.

	      The  --dns  server  directive is used to configure DNS server n.
	      The server id n must be a	value between -128 and 127. For	pushed
	      DNS  server  options it must be between 0	and 127. The server id
	      is used to group options and also	for ordering the list of  con-
	      figured DNS servers; lower numbers come first. DNS servers being
	      pushed to	a client replace already configured DNS	 servers  with
	      the same server id.

	      The  address option configures the IPv4 and / or IPv6 address of
	      the DNS server. Optionally a port	can be appended	after a	colon.
	      IPv6  addresses need to be enclosed in brackets if a port	is ap-

	      The resolve-domains and exclude-domains options take one or more
	      DNS  domains which are explicitly	resolved or explicitly not re-
	      solved by	a server. Only one of the options  can	be  configured
	      for  a  server.	resolve-domains	 is used to define a split-dns
	      setup, where only	given domains are resolved by  a  server.  ex-
	      clude-domains  is	used to	define domains which will never	be re-
	      solved by	a server (e.g. domains which can only be resolved  lo-
	      cally).  Systems	which  do  not support fine grained DNS	domain
	      configuration, will ignore these settings.

	      The dnssec option	is used	 to  configure	validation  of	DNSSEC
	      records.	 While the exact semantics may differ for resolvers on
	      different	systems, yes likely  makes  validation	mandatory,  no
	      disables it, and optional	uses it	opportunistically.

	      The   transport	option	 enables   DNS-over-HTTPS   (DoH)   or
	      DNS-over-TLS (DoT) for a DNS server. The sni option can be  used
	      with them	to specify the server-name for TLS server name indica-

	      Each server has to have at least one address  configured	for  a
	      configuration to be valid. All the other options can be omitted.

	      Note  that not all options may be	supported on all platforms. As
	      soon support for different systems is  implemented,  information
	      will be added here how unsupported options are treated.

	      The  --dns option	will eventually	obsolete the --dhcp-option di-
	      rective.	Until then it will replace configuration at the	places
	      --dhcp-option  puts  it,	so that	--dns overrides	--dhcp-option.
	      Thus, --dns can be used today to migrate from --dhcp-option.

       --explicit-exit-notify n
	      In UDP client mode or point-to-point mode, send  server/peer  an
	      exit  notification  if tunnel is restarted or OpenVPN process is
	      exited. In client	mode, on exit/restart, this option  will  tell
	      the  server  to  immediately  close  its	client instance	object
	      rather than waiting for a	timeout.

	      If both server and client	support	sending	this message using the
	      control  channel,	 the  message  will be sent as control-channel
	      message. Otherwise the message is	sent as	data-channel  message,
	      which will be ignored by data-channel offloaded peers.

	      The  n parameter (default	1 if not present) controls the maximum
	      number of	attempts that the client will try to resend  the  exit
	      notification message if messages are sent	in data-channel	mode.

	      In UDP server mode, send RESTART control channel command to con-
	      nected clients. The n parameter (default 1 if not	present)  con-
	      trols  client behavior. With n = 1 client	will attempt to	recon-
	      nect to the same server, with n =	2 client will advance  to  the
	      next server.

	      OpenVPN  will not	send any exit notifications unless this	option
	      is enabled.

       --inactive args
	      Causes OpenVPN to	exit after n  seconds  of  inactivity  on  the
	      TUN/TAP  device. The time	length of inactivity is	measured since
	      the last incoming	or outgoing tunnel packet. The	default	 value
	      is 0 seconds, which disables this	feature.

	      Valid syntaxes:

		 inactive n
		 inactive n bytes

	      If  the  optional	bytes parameter	is included, exit if less than
	      bytes of combined	in/out traffic are produced on the tun/tap de-
	      vice in n	seconds.

	      In  any  case,  OpenVPN's	 internal ping packets (which are just
	      keepalives) and TLS control packets are not  considered  "activ-
	      ity",  nor  are they counted as traffic, as they are used	inter-
	      nally by OpenVPN and are not an indication of actual user	activ-

       --proto-force p
	      When  iterating  through connection profiles, only consider pro-
	      files using protocol p (tcp | udp).

	      Note that	this specifically only filters by the transport	 layer
	      protocol,	 i.e. UDP or TCP. This does not	affect whether IPv4 or
	      IPv6 is used as IP protocol.

	      For implementation reasons the option accepts the	4 and  6  suf-
	      fixes  when  specifying  the protocol (i.e. udp4 / udp6 /	tcp4 /
	      tcp6).  However, these behave the	same as	without	the suffix and
	      should be	avoided	to prevent confusion.

       --pull This  option  must  be used on a client which is connecting to a
	      multi-client server. It indicates	to OpenVPN that	it should  ac-
	      cept options pushed by the server, provided they are part	of the
	      legal set	of pushable options (note that the  --pull  option  is
	      implied by --client ).

	      In  particular,  --pull  allows the server to push routes	to the
	      client, so you should not	use --pull or --client	in  situations
	      where  you  don't	 trust	the  server  to	 have control over the
	      client's routing table.

       --pull-filter args
	      Filter options on	the client pushed by the server	to the client.

	      Valid syntaxes:

		 pull-filter accept text
		 pull-filter ignore text
		 pull-filter reject text

	      Filter options received from the server  if  the	option	starts
	      with text.  The action flag accept allows	the option, ignore re-
	      moves it and reject  flags  an  error  and  triggers  a  SIGUSR1
	      restart.	The  filters may be specified multiple times, and each
	      filter is	applied	in the order it	is specified. The filtering of
	      each option stops	as soon	as a match is found. Unmatched options
	      are accepted by default.

	      Prefix comparison	is used	to match text against the received op-
	      tion so that

		 pull-filter ignore "route"

	      would  remove all	pushed options starting	with route which would
	      include, for example, route-gateway. Enclose text	in  quotes  to
	      embed spaces.

		 pull-filter accept "route 192.168.1."
		 pull-filter ignore "route "

	      would remove all routes that do not start	with 192.168.1.

	      Note  that  reject may result in a repeated cycle	of failure and
	      reconnect, unless	multiple remotes are specified and  connection
	      to the next remote succeeds. To silently ignore an option	pushed
	      by the server, use ignore.

	      Push additional information about	the client to server. The fol-
	      lowing data is always pushed to the server:

		     The client	OpenVPN	version

		     The client	OS platform

		     If	client was built with LZO stub capability

		     If	the client supports LZ4	compressions.

		     Details about protocol extensions that the	peer supports.
		     The variable is a bitfield	and the	bits  are  defined  as
		     follows (starting a bit 0 for the first (unused) bit:

		     o bit 1: The peer supports	peer-id	floating mechanism

		     o bit  2:	The client expects a push-reply	and the	server
		       may send	this reply without waiting for a  push-request

		     o bit  3:	The  client is capable of doing	key derivation
		       using RFC5705 key material exporter.

		     o bit 4: The client is capable  of	 accepting  additional
		       arguments to the	AUTH_PENDING message.

		     Negotiable	 ciphers,  client  supports --cipher pushed by
		     the server, a value of 2 or greater indicates client sup-
		     ports AES-GCM-128 and AES-GCM-256.

		     The  client  announces the	list of	supported ciphers con-
		     figured with the --data-ciphers option to the server.

		     The client	announces the support of pushable MTU and  the
		     maximum MTU it is willing to accept.

	      IV_GUI_VER=<gui_id> <version>
		     The  UI  version  of  a UI	if one is running, for example
		     de.blinkt.openvpn 0.5.47 for the Android app.

		     Additional	 authentication	 methods  supported   by   the
		     client.   This  may  be  set  by  the client UI/GUI using

	      When --push-peer-info is enabled the additional information con-
	      sists of the following data:

		     This  is intended to be a unique and persistent ID	of the
		     client.  The string  value	 can  be  any  readable	 ASCII
		     string up to 64 bytes.  OpenVPN 2.x and some other	imple-
		     mentations	use the	MAC address of the client's  interface
		     used to reach the default gateway.	If this	string is gen-
		     erated by the client, it should be	 consistent  and  pre-
		     served  across  independent session and preferably	re-in-
		     stallations and upgrades.

	      IV_SSL=<version string>
		     The ssl version used by the client, e.g.  OpenSSL	1.0.2f
		     28	Jan 2016.

		     The version of the	operating system, e.g. 6.1 for Windows

		     Client environment	variables whose	names start with UV_

       --remote	args
	      Remote host name or IP address, port and protocol.

	      Valid syntaxes:

		 remote	host
		 remote	host port
		 remote	host port proto

	      The port and proto arguments are optional.  The  OpenVPN	client
	      will  try	 to connect to a server	at host:port.  The proto argu-
	      ment indicates the protocol to use when connecting with the  re-
	      mote,  and  may  be tcp or udp.  To enforce IPv4 or IPv6 connec-
	      tions add	a 4 or 6 suffix; like udp4 / udp6 / tcp4 / tcp6.

	      On the client, multiple --remote options may  be	specified  for
	      redundancy, each referring to a different	OpenVPN	server,	in the
	      order specified by the list of --remote options. Specifying mul-
	      tiple --remote options for this purpose is a special case	of the
	      more general connection-profile feature.	See  the  <connection>
	      documentation below.

	      The  client  will	 move  on to the next host in the list,	in the
	      event of connection failure. Note	that at	any  given  time,  the
	      OpenVPN client will at most be connected to one server.


		 remote 1194
		 remote 1194 tcp

	      Note:  Since  UDP	 is  connectionless, connection	failure	is de-
		     fined by the --ping and --ping-restart options.

		     Also, if you use multiple --remote	options, AND  you  are
		     dropping root privileges on the client with --user	and/or
		     --group AND the client is running a  non-Windows  OS,  if
		     the  client  needs	 to  switch to a different server, and
		     that server pushes	back different TUN/TAP or  route  set-
		     tings,  the  client  may lack the necessary privileges to
		     close and reopen the TUN/TAP interface. This could	 cause
		     the client	to exit	with a fatal error.

	      If --remote is unspecified, OpenVPN will listen for packets from
	      any IP address, but will not act on those	 packets  unless  they
	      pass  all	authentication tests. This requirement for authentica-
	      tion is binding on all potential peers, even  those  from	 known
	      and  supposedly trusted IP addresses (it is very easy to forge a
	      source IP	address	on a UDP packet).

	      When used	in TCP mode, --remote will act as a filter,  rejecting
	      connections from any host	which does not match host.

	      If  host	is a DNS name which resolves to	multiple IP addresses,
	      OpenVPN will try them in the order that the system getaddrinfo()
	      presents	them, so priorization and DNS randomization is done by
	      the system library. Unless an IP version is forced by the	proto-
	      col  specification  (4/6 suffix),	OpenVPN	will try both IPv4 and
	      IPv6 addresses, in the order getaddrinfo() returns them.

	      When multiple --remote address/ports are specified, or  if  con-
	      nection  profiles	 are being used, initially randomize the order
	      of the list as a kind of basic load-balancing measure.

	      Prepend a	random string (6 bytes,	12 hex characters) to hostname
	      to prevent DNS caching. For example, "" would be mod-
	      ified to "<random-chars>".

       --resolv-retry n
	      If hostname resolve fails	for --remote, retry resolve for	n sec-
	      onds before failing.

	      Set n to infinite	to retry indefinitely.

	      By  default, --resolv-retry infinite is enabled. You can disable
	      by setting n=0.

	      After initially connecting to a remote peer,  disallow  any  new
	      connections.  Using  this	option means that a remote peer	cannot
	      connect, disconnect, and then reconnect.

	      If the daemon is reset by	a signal or  --ping-restart,  it  will
	      allow one	new connection.

	      --single-session	can  be	used with --ping-exit or --inactive to
	      create a single dynamic session that will	exit when finished.

       --server-poll-timeout n
	      When connecting to a remote server do not	wait for more  than  n
	      seconds  for  a  response	before trying the next server. The de-
	      fault value is 120. This timeout includes	proxy and TCP  connect

       --static-challenge args
	      Enable static challenge/response protocol

	      Valid syntax:

		 static-challenge text echo

	      The text challenge text is presented to the user which describes
	      what information is requested.  The echo flag indicates  if  the
	      user's  input should be echoed on	the screen.  Valid echo	values
	      are 0 or 1.

	      See management-notes.txt in the OpenVPN distribution for	a  de-
	      scription	of the OpenVPN challenge/response protocol.

	      Show  sensed  HTTP or SOCKS proxy	settings. Currently, only Win-
	      dows clients support this	option.

       --http-proxy args
	      Connect to remote	host through an	HTTP proxy.  This requires  at
	      least  an	 address  server and port argument.  If	HTTP Proxy-Au-
	      thenticate is required, a	file name to an	authfile file contain-
	      ing a username and password on 2 lines can be given, or stdin to
	      prompt from console. Its content can also	be  specified  in  the
	      config file with the --http-proxy-user-pass option. (See section
	      on inline	files)

	      The last optional	argument is an auth-method which should	be one
	      of none, basic, or ntlm.

	      HTTP  Digest  authentication  is supported as well, but only via
	      the auto or auto-nct flags (below).  This	must replace the auth-
	      file argument.

	      The  auto	 flag  causes  OpenVPN	to automatically determine the
	      auth-method and query stdin  or  the  management	interface  for
	      username/password	 credentials, if required. This	flag exists on
	      OpenVPN 2.1 or higher.

	      The auto-nct flag	(no clear-text auth) instructs OpenVPN to  au-
	      tomatically  determine  the authentication method, but to	reject
	      weak authentication protocols such as HTTP Basic Authentication.


		 http-proxy 3128
		 http-proxy 3128 authfile.txt
		 http-proxy 3128 stdin
		 http-proxy 3128 auto	basic
		 http-proxy 3128 auto-nct ntlm

       --http-proxy-option args
	      Set extended HTTP	proxy options. Requires	an option type as  ar-
	      gument  and  an  optional	 parameter to the type.	 Repeat	to set
	      multiple options.

	      VERSION version
		     Set HTTP version number to	version	(default 1.0).

	      AGENT user-agent
		     Set HTTP "User-Agent" string to user-agent.

	      CUSTOM-HEADER name content
		     Adds the custom Header with name as name and  content  as
		     the content of the	custom HTTP header.


		 http-proxy-option VERSION 1.1
		 http-proxy-option AGENT OpenVPN/2.4
		 http-proxy-option X-Proxy-Flag	some-flags

       --socks-proxy args
	      Connect  to  remote  host	 through  a  Socks5 proxy.  A required
	      server argument is needed.  Optionally a port (default 1080) and
	      authfile	can  be	 given.	  The  authfile	is a file containing a
	      username and password on 2 lines,	or stdin can be	used to	prompt
	      from console.

   Server Options
       Starting	 with  OpenVPN 2.0, a multi-client TCP/UDP server mode is sup-
       ported, and can be enabled with the --mode  server  option.  In	server
       mode,  OpenVPN will listen on a single port for incoming	client connec-
       tions. All client connections will be routed through a  single  tun  or
       tap interface. This mode	is designed for	scalability and	should be able
       to support hundreds or even thousands of	clients	on  sufficiently  fast
       hardware. SSL/TLS authentication	must be	used in	this mode.

       --auth-gen-token	args
	      Returns  an  authentication  token to successfully authenticated

	      Valid syntax:

		 auth-gen-token	[lifetime] [renewal-time] [external-auth]

	      After  successful	 user/password	authentication,	 the   OpenVPN
	      server will with this option generate a temporary	authentication
	      token and	push that to the client. On the	 following  renegotia-
	      tions,  the  OpenVPN  client will	pass this token	instead	of the
	      users password. On the server side the server will do the	 token
	      authentication  internally and it	will NOT do any	additional au-
	      thentications against configured external	user/password  authen-
	      tication mechanisms.

	      The  tokens  implemented	by  this  mechanism include an initial
	      timestamp	and a renew timestamp and are secured by HMAC.

	      The lifetime argument defines how	long the  generated  token  is
	      valid.   The  lifetime is	defined	in seconds. If lifetime	is not
	      set or it	is set to 0, the token will never expire.

	      If renewal-time is not set it defaults to	reneg-sec.

	      The token	will expire either after the  configured  lifetime  of
	      the  token is reached or after not being renewed for more	than 2
	      *	renewal-time seconds. Clients will be sent renewed  tokens  on
	      every TLS	renegotiation. If renewal-time is lower	than reneg-sec
	      the server will push an  updated temporary authentication	 token
	      every  reneweal-time seconds. This is done to invalidate a token
	      if a client is disconnected for a	sufficiently long time,	 while
	      at  the same time	permitting much	longer token lifetimes for ac-
	      tive clients.

	      This feature is useful for environments which are	configured  to
	      use  One	Time  Passwords	(OTP) as part of the user/password au-
	      thentications and	that authentication mechanism does not	imple-
	      ment any auth-token support.

	      When the external-auth keyword is	present	the normal authentica-
	      tion method will always be called	even if	 auth-token  succeeds.
	      Normally	other authentications method are skipped if auth-token
	      verification succeeds or fails.

	      This option postpones this decision to the external  authentica-
	      tion methods and checks the validity of the account and do other

	      In this mode the environment will	 have  a  session_id  variable
	      that  holds the session id from auth-gen-token. Also an environ-
	      ment variable session_state is present. This variable  indicates
	      whether  the  auth-token	has  succeeded or not. It can have the
	      following	values:

		     No	token from client.

		     Token is valid and	not expired.

		     Token is valid but	has expired.

		     Token is invalid (failed HMAC or wrong length)

	      AuthenticatedEmptyUser / ExpiredEmptyUser
		     The token is not valid with the username  sent  from  the
		     client  but  would	 be valid (or expired) if we assume an
		     empty username was	used instead.  These two cases	are  a
		     workaround	 for  behaviour	 in  OpenVPN 3.	 If this work-
		     around is not needed these	two cases should be handled in
		     the same way as Invalid.

	      Warning:	Use  this feature only if you want your	authentication
	      method called on every verification. Since the external  authen-
	      tication	is called it needs to also indicate a success or fail-
	      ure of the authentication. It is strongly	recommended to	return
	      an  authentication  failure  in  the case	of the Invalid/Expired
	      auth-token with the external-auth	option unless the client could
	      authenticate  in	another	 acceptable  way (e.g. client certifi-
	      cate), otherwise returning success will lead  to	authentication
	      bypass  (as  does	 returning  success on a wrong password	from a

       --auth-gen-token-secret file
	      Specifies	a file that holds  a  secret  for  the	HMAC  used  in
	      --auth-gen-token	If file	is not present OpenVPN will generate a
	      random secret on startup.	This file should be used if auth-token
	      should validate after restarting a server	or if client should be
	      able  to	roam  between  multiple	 OpenVPN  servers  with	 their

	      Allow  connections  by  clients  that  do	 not  specify  a user-
	      name/password.  Normally,	when --auth-user-pass-verify or	--man-
	      agement-client-auth  are	specified (or an authentication	plugin
	      module), the  OpenVPN  server  daemon  will  require  connecting
	      clients  to  specify  a username and password. This option makes
	      the submission of	a username/password by clients optional, pass-
	      ing  the	responsibility to the user-defined authentication mod-
	      ule/script to accept or deny the client based on	other  factors
	      (such as the setting of X509 certificate fields).	 When this op-
	      tion is used, and	a connecting client does not  submit  a	 user-
	      name/password,  the  user-defined	 authentication	 module/script
	      will see the username and	password as being set to empty strings
	      (""). The	authentication module/script MUST have logic to	detect
	      this condition and respond accordingly.

	      Require, as a condition of  authentication,  that	 a  connecting
	      client has a --client-config-dir file.

       --client-config-dir dir
	      Specify  a directory dir for custom client config	files. After a
	      connecting client	has been authenticated,	OpenVPN	will  look  in
	      this  directory  for a file having the same name as the client's
	      X509 common name.	If a matching file exists, it will  be	opened
	      and  parsed  for	client-specific	 configuration	options. If no
	      matching file is found, OpenVPN will instead  try	 to  open  and
	      parse a default file called "DEFAULT", which may be provided but
	      is not required. Note that the configuration files must be read-
	      able by the OpenVPN process after	it has dropped it's root priv-

	      This file	can specify a fixed IP address for a given client  us-
	      ing  --ifconfig-push,  as	 well  as  fixed  subnets owned	by the
	      client using --iroute.

	      One of the useful	properties of this option is  that  it	allows
	      client  configuration  files to be conveniently created, edited,
	      or removed while the server is live, without needing to  restart
	      the server.

	      The  following  options  are legal in a client-specific context:
	      --push, --push-reset, --push-remove, --iroute,  --ifconfig-push,
	      --vlan-pvid and --config.

	      Because the OpenVPN server mode handles multiple clients through
	      a	single tun or tap interface, it	is effectively a  router.  The
	      --client-to-client   flag	 tells	OpenVPN	 to  internally	 route
	      client-to-client traffic rather than pushing  all	 client-origi-
	      nating traffic to	the TUN/TAP interface.

	      When  this  option  is  used,  each  client will "see" the other
	      clients which are	currently connected.  Otherwise,  each	client
	      will  only  see the server. Don't	use this option	if you want to
	      firewall tunnel traffic using custom, per-client rules.

	      Please note that when using data channel offload this option has
	      no  effect.  Packets are always sent to the tunnel interface and
	      then routed based	on the system routing table.

	      Disable a	particular client (based on the	common name) from con-
	      necting.	 Don't	use this option	to disable a client due	to key
	      or password compromise. Use a CRL	(certificate revocation	 list)
	      instead (see the --crl-verify option).

	      This  option must	be associated with a specific client instance,
	      which means that it must be specified either  in	a  client  in-
	      stance config file using --client-config-dir or dynamically gen-
	      erated using a --client-connect script.

       --connect-freq args
	      Allow a maximum of  n  new  connections  per  sec	 seconds  from

	      Valid syntax:

		 connect-freq n	sec

	      This  is	designed to contain DoS	attacks	which flood the	server
	      with connection requests using  certificates  which  will	 ulti-
	      mately fail to authenticate.

	      This limit applies after --connect-freq-initial and only applies
	      to client	that have completed the	three-way handshake or	client
	      that  use	--tls-crypt-v2 without cookie support (allow-noncookie
	      argument to --tls-crypt-v2).

	      This is an imperfect solution however, because  in  a  real  DoS
	      scenario,	legitimate connections might also be refused.

	      For  the best protection against DoS attacks in server mode, use
	      --proto udp and either --tls-auth	or --tls-crypt.

       --connect-freq-initial args
	      (UDP only) Allow a maximum of n initial  connection  packet  re-
	      sponses per sec seconds from the OpenVPN server to clients.

	      Valid syntax:

		 connect-freq-initial n	sec

	      OpenVPN  starting	at 2.6 is very efficient in responding to ini-
	      tial connection packets. When not	limiting the initial responses
	      an OpenVPN daemon	can be abused in reflection attacks.  This op-
	      tion is designed to limit	the rate OpenVPN will respond to  ini-
	      tial attacks.

	      Connection  attempts  that  complete the initial three-way hand-
	      shake will not be	counted	against	the limit. The default	is  to
	      allow 100	initial	connection per 10s.

	      Allow multiple clients with the same common name to concurrently
	      connect. In the absence of this option, OpenVPN will  disconnect
	      a	 client	 instance  upon	 connection of a new client having the
	      same common name.

       --ifconfig-pool args
	      Set aside	a pool of subnets to be	dynamically allocated to  con-
	      necting clients, similar to a DHCP server.

	      Valid syntax:

		 ifconfig-pool start-IP	end-IP [netmask]

	      For  tun-style  tunnels,	each client will be given a /30	subnet
	      (for interoperability with Windows clients).  For	tap-style tun-
	      nels,  individual	 addresses will	be allocated, and the optional
	      netmask parameter	will also be pushed to clients.

       --ifconfig-ipv6-pool args
	      Specify an IPv6 address pool for dynamic assignment to clients.

	      Valid args:

		 ifconfig-ipv6-pool ipv6addr/bits

	      The pool starts at ipv6addr and matches  the  offset  determined
	      from  the	start of the IPv4 pool.	 If the	host part of the given
	      IPv6 address is 0, the pool starts at ipv6addr +1.

       --ifconfig-pool-persist args
	      Persist/unpersist	ifconfig-pool data to file, at seconds	inter-
	      vals (default 600), as well as on	program	startup	and shutdown.

	      Valid syntax:

		 ifconfig-pool-persist file [seconds]

	      The  goal	 of  this option is to provide a long-term association
	      between clients (denoted by their	common name) and  the  virtual
	      IP  address assigned to them from	the ifconfig-pool. Maintaining
	      a	long-term association is good for clients  because  it	allows
	      them to effectively use the --persist-tun	option.

	      file  is	a  comma-delimited  ASCII  file,  formatted  as	 <Com-

	      If seconds = 0, file will	be treated as read-only. This is  use-
	      ful if you would like to treat file as a configuration file.

	      Note  that  the  entries	in this	file are treated by OpenVPN as
	      suggestions only,	based on past associations  between  a	common
	      name  and	IP address.  They do not guarantee that	the given com-
	      mon name will always receive the given IP	address. If  you  want
	      guaranteed assignment, use --ifconfig-push

       --ifconfig-push args
	      Push  virtual  IP	 endpoints  for	 client	tunnel,	overriding the
	      --ifconfig-pool dynamic allocation.

	      Valid syntax:

		 ifconfig-push local remote-netmask [alias]

	      The parameters local and remote-netmask are set according	to the
	      --ifconfig directive which you want to execute on	the client ma-
	      chine to configure the remote end	of the tunnel. Note  that  the
	      parameters  local	and remote-netmask are from the	perspective of
	      the client, not the server. They may be DNS names	rather than IP
	      addresses,  in which case	they will be resolved on the server at
	      the time of client connection.

	      The optional alias parameter may be  used	 in  cases  where  NAT
	      causes  the client view of its local endpoint to differ from the
	      server view. In this case	local/remote-netmask will refer	to the
	      server  view while alias/remote-netmask will refer to the	client

	      This option must be associated with a specific client  instance,
	      which  means  that  it  must be specified	either in a client in-
	      stance config file using --client-config-dir or dynamically gen-
	      erated using a --client-connect script.

	      Remember also to include a --route directive in the main OpenVPN
	      config file which	encloses local,	so that	the kernel  will  know
	      to route it to the server's TUN/TAP interface.

	      OpenVPN's	 internal  client IP address selection algorithm works
	      as follows:

	      1. Use --client-connect script  generated	 file  for  static  IP
		 (first	choice).

	      2. Use --client-config-dir file for static IP (next choice).

	      3. Use --ifconfig-pool allocation	for dynamic IP (last choice).

       --ifconfig-ipv6-push args
	      for --client-config-dir per-client static	IPv6 interface config-
	      uration, see --client-config-dir and  --ifconfig-push  for  more

	      Valid syntax:

		 ifconfig-ipv6-push ipv6addr/bits ipv6remote

	      Configure	a multi-homed UDP server. This option needs to be used
	      when a server has	more than one IP address (e.g. multiple	inter-
	      faces,  or  secondary IP addresses), and is not using --local to
	      force binding to one specific address only. This option will add
	      some extra lookups to the	packet path to ensure that the UDP re-
	      ply packets are always sent from the address that	the client  is
	      talking  to. This	is not supported on all	platforms, and it adds
	      more processing, so it's not enabled by default.


		     o This option is only relevant for	UDP servers.

		     o If you do an IPv6+IPv4 dual-stack bind on a  Linux  ma-
		       chine  with  multiple IPv4 address, connections to IPv4
		       addresses will not work right on	kernels	 before	 3.15,
		       due  to missing kernel support for the IPv4-mapped case
		       (some distributions have	ported this to earlier	kernel
		       versions, though).

       --iroute	args
	      Generate an internal route to a specific client. The netmask pa-
	      rameter, if omitted, defaults to

	      Valid syntax:

		 iroute	network	[netmask]

	      This directive can be used to route  a  fixed  subnet  from  the
	      server to	a particular client, regardless	of where the client is
	      connecting from.	Remember that you must also add	the  route  to
	      the  system  routing table as well (such as by using the --route
	      directive). The reason why two routes are	 needed	 is  that  the
	      --route  directive routes	the packet from	the kernel to OpenVPN.
	      Once in OpenVPN, the --iroute directive routes to	 the  specific

	      However,	when  using  DCO,  the	--iroute  directive is usually
	      enough for DCO to	fully configure	the routing table.  The	 extra
	      --route  directive is required only if the expected behaviour is
	      to route the traffic for a specific network to the VPN interface
	      also  when the responsible client	is not connected (traffic will
	      then be dropped).

	      This option must be specified either in a	client instance	config
	      file  using --client-config-dir or dynamically generated using a
	      --client-connect script.

	      The --iroute directive also has an  important  interaction  with
	      --push  "route ...". --iroute essentially	defines	a subnet which
	      is owned by a particular client (we will call this client	A). If
	      you would	like other clients to be able to reach A's subnet, you
	      can use --push "route ..." together with	--client-to-client  to
	      effect this. In order for	all clients to see A's subnet, OpenVPN
	      must push	this route to all clients EXCEPT for A,	since the sub-
	      net  is already owned by A. OpenVPN accomplishes this by not not
	      pushing a	route to a client if it	matches	one  of	 the  client's

       --iroute-ipv6 args
	      for  --client-config-dir per-client static IPv6 route configura-
	      tion, see	--iroute for more details how to setup and  use	 this,
	      and how --iroute and --route interact.

	      Valid syntax:

		 iroute-ipv6 ipv6addr/bits

       --max-clients n
	      Limit server to a	maximum	of n concurrent	clients.

       --max-routes-per-client n
	      Allow  a	maximum	of n internal routes per client	(default 256).
	      This is designed to help contain DoS attacks where an  authenti-
	      cated  client  floods  the server	with packets appearing to come
	      from many	unique MAC addresses, forcing the  server  to  deplete
	      virtual  memory  as its internal routing table expands. This di-
	      rective can be used in a --client-config-dir file	or auto-gener-
	      ated  by	a --client-connect script to override the global value
	      for a particular client.

	      Note that	this directive affects OpenVPN's internal routing  ta-
	      ble, not the kernel routing table.

	      DEPRECATED Clients that connect with options that	are incompati-
	      ble with those of	the server will	be disconnected.

	      Options  that  will  be  compared	 for   compatibility   include
	      dev-type,	 link-mtu,  tun-mtu,  proto, ifconfig, comp-lzo, frag-
	      ment,  keydir,  cipher,  auth,   keysize,	  secret,   no-replay,
	      tls-auth,	key-method, tls-server and tls-client.

	      This option requires that	--disable-occ NOT be used.

       --port-share args
	      Share OpenVPN TCP	with another service

	      Valid syntax:

		 port-share host port [dir]

	      When run in TCP server mode, share the OpenVPN port with another
	      application, such	as an HTTPS server. If OpenVPN senses  a  con-
	      nection  to  its	port which is using a non-OpenVPN protocol, it
	      will proxy the connection	to the server at host:port.  Currently
	      only  designed to	work with HTTP/HTTPS, though it	would be theo-
	      retically	possible to extend to other protocols such as ssh.

	      dir specifies an optional	directory where	a temporary file  with
	      name  N  containing  content C will be dynamically generated for
	      each proxy connection, where N is	 the  source  IP:port  of  the
	      client  connection and C is the source IP:port of	the connection
	      to the proxy receiver. This directory can	be used	as  a  dictio-
	      nary  by	the proxy receiver to determine	the origin of the con-
	      nection. Each generated file will	be automatically deleted  when
	      the proxied connection is	torn down.

	      Not implemented on Windows.

       --push option
	      Push  a  config file option back to the client for remote	execu-
	      tion. Note that option must be enclosed in double	 quotes	 ("").
	      The  client  must	 specify --pull	in its config file. The	set of
	      options which can	be pushed is limited by	both  feasibility  and
	      security.	Some options such as those which would execute scripts
	      are banned, since	they would  effectively	 allow	a  compromised
	      server  to  execute  arbitrary code on the client. Other options
	      such as TLS or MTU  parameters  cannot  be  pushed  because  the
	      client  needs  to	 know them before the connection to the	server
	      can be initiated.

	      This is a	partial	list of	options	which can currently be pushed:
	      --route,	 --route-gateway,  --route-delay,  --redirect-gateway,
	      --ip-win32,   --dhcp-option,    --dns,	--inactive,    --ping,
	      --ping-exit,   --ping-restart,  --setenv,	 --auth-token,	--per-
	      sist-key,	 --persist-tun,	 --echo,  --comp-lzo,  --socket-flags,
	      --sndbuf,	--rcvbuf, --session-timeout

       --push-remove opt
	      Selectively  remove  all	--push options matching	"opt" from the
	      option list for a	client.	opt is matched as a substring  against
	      the   whole   option  string  to-be-pushed  to  the  client,  so
	      --push-remove route would	remove all --push route	... and	--push
	      route-ipv6  ...	statements,  while  --push-remove  "route-ipv6
	      2001:" would only	remove IPv6 routes for 2001:...	networks.

	      --push-remove can	only be	used  in  a  client-specific  context,
	      like  in	a --client-config-dir file, or --client-connect	script
	      or plugin	-- similar to --push-reset, just more selective.

	      NOTE: to change an option, --push-remove can be  used  to	 first
	      remove  the old value, and then add a new	--push option with the
	      new value.

	      NOTE 2: due to implementation details,  'ifconfig'  and  'ifcon-
	      fig-ipv6'	 can only be removed with an exact match on the	option
	      (	push-remove ifconfig), no substring matching and  no  matching
	      on the IPv4/IPv6 address argument	is possible.

	      Don't  inherit  the  global  push	list for a specific client in-
	      stance.  Specify this option in a	client-specific	 context  such
	      as  with	a  --client-config-dir configuration file. This	option
	      will ignore --push options at the	global config file level.

	      NOTE: --push-reset is very thorough: it will remove  almost  all
	      options  from  the list of to-be-pushed options.	In many	cases,
	      some of these options will need to be re-configured afterwards -
	      specifically,  --topology	 subnet	 and  --route-gateway will get
	      lost and this will break client configs in  many	cases.	 Thus,
	      for most purposes, --push-remove is better suited	to selectively
	      remove push options for individual clients.

       --server	args
	      A	helper directive designed to  simplify	the  configuration  of
	      OpenVPN's	 server	 mode.	This  directive	will set up an OpenVPN
	      server which will	allocate addresses to clients out of the given
	      network/netmask.	The  server itself will	take the .1 address of
	      the given	network	for use	as the server-side endpoint of the lo-
	      cal  TUN/TAP interface. If the optional nopool flag is given, no
	      dynamic IP address pool will prepared for	VPN clients.

	      Valid syntax:

		 server	network	netmask	[nopool]

	      For example, --server expands as follows:

		 mode server
		 push "topology	[topology]"

		 if dev	tun AND	(topology == net30 OR topology == p2p):
		   if !nopool:
		   if client-to-client:
		     push "route"
		   else	if topology == net30:
		     push "route"

		 if dev	tap OR (dev tun	AND topology ==	subnet):
		   if !nopool:
		   push	"route-gateway"
		   if route-gateway unset:

	      Don't  use  --server  if	you   are   ethernet   bridging.   Use
	      --server-bridge instead.

       --server-bridge args
	      A	helper directive similar to --server which is designed to sim-
	      plify the	configuration of OpenVPN's  server  mode  in  ethernet
	      bridging configurations.

	      Valid syntaxes:

		 server-bridge gateway netmask pool-start-IP pool-end-IP
		 server-bridge [nogw]

	      If  --server-bridge  is used without any parameters, it will en-
	      able a DHCP-proxy	mode, where connecting	OpenVPN	 clients  will
	      receive an IP address for	their TAP adapter from the DHCP	server
	      running on the OpenVPN server-side LAN. Note that	 only  clients
	      that  support  the binding of a DHCP client with the TAP adapter
	      (such as Windows)	can support this mode. The optional nogw  flag
	      (advanced)  indicates  that  gateway  information	 should	not be
	      pushed to	the client.

	      To configure ethernet bridging, you must	first  use  your  OS's
	      bridging	capability to bridge the TAP interface with the	ether-
	      net NIC interface.  For example, on Linux	this is	done with  the
	      brctl  tool,  and	with Windows XP	it is done in the Network Con-
	      nections Panel by	selecting the ethernet and  TAP	 adapters  and
	      right-clicking on	"Bridge	Connections".

	      Next  you	you must manually set the IP/netmask on	the bridge in-
	      terface.	The gateway and	netmask	parameters to  --server-bridge
	      can  be set to either the	IP/netmask of the bridge interface, or
	      the IP/netmask of	the default gateway/router on the bridged sub-

	      Finally,	set aside a IP range in	the bridged subnet, denoted by
	      pool-start-IP and	pool-end-IP, for OpenVPN to allocate  to  con-
	      necting clients.

	      For  example,  server-bridge expands as follows:

		 mode server

		 push "route-gateway"

	      In another example, --server-bridge (without parameters) expands
	      as follows:

		 mode server

		 push "route-gateway dhcp"

	      Or --server-bridge nogw expands as follows:

		 mode server

       --server-ipv6 args
	      Convenience-function  to enable a	number of IPv6 related options
	      at once, namely --ifconfig-ipv6, --ifconfig-ipv6-pool and	--push

	      Valid syntax:

		 server-ipv6 ipv6addr/bits

	      Pushing  of  the	--tun-ipv6 directive is	done for older clients
	      which require an explicit	--tun-ipv6 in their configuration.

       --stale-routes-check args
	      Remove routes which haven't had activity for n seconds (i.e. the
	      ageing time).  This check	is run every t seconds (i.e. check in-

	      Valid syntax:

		 stale-routes-check n [t]

	      If t is not present it defaults to n.

	      This option helps	to keep	the dynamic routing table  small.  See
	      also --max-routes-per-client

	      Use  the	authenticated username as the common-name, rather than
	      the common-name from the client certificate. Requires that  some
	      form  of	--auth-user-pass verification is in effect. As the re-
	      placement	happens	after --auth-user-pass verification, the veri-
	      fication	script	or  plugin  will still receive the common-name
	      from the certificate.

	      The common_name environment variable passed to scripts and plug-
	      ins  invoked  after  authentication (e.g,	client-connect script)
	      and file names parsed in client-config directory will match  the

       --verify-client-cert mode
	      Specify  whether	the  client is required	to supply a valid cer-

	      Possible mode options are:

	      none   A client certificate is not required. the client needs to
		     authenticate  using username/password only. Be aware that
		     using this	directive is less secure than  requiring  cer-
		     tificates from all	clients.

		     If	 you  use this directive, the entire responsibility of
		     authentication will rest on your  --auth-user-pass-verify
		     script,  so  keep	in mind	that bugs in your script could
		     potentially compromise the	security of your VPN.

		     --verify-client-cert none is functionally	equivalent  to

		     A client may present a certificate	but it is not required
		     to	do so.	When using this	directive, you should also use
		     a	--auth-user-pass-verify	 script	to ensure that clients
		     are authenticated using a	certificate,  a	 username  and
		     password, or possibly even	both.

		     Again,  the  entire responsibility	of authentication will
		     rest on your --auth-user-pass-verify script, so  keep  in
		     mind  that	 bugs in your script could potentially compro-
		     mise the security of your VPN.

		     This is the default  option.  A  client  is  required  to
		     present a certificate, otherwise VPN access is refused.

	      If you don't use this directive (or use --verify-client-cert re-
	      quire) but you also specify an  --auth-user-pass-verify  script,
	      then OpenVPN will	perform	double authentication. The client cer-
	      tificate verification  AND  the  --auth-user-pass-verify	script
	      will  need  to succeed in	order for a client to be authenticated
	      and accepted onto	the VPN.

	      Server-only option. Turns	the OpenVPN  server  instance  into  a
	      switch that understands VLAN-tagging, based on IEEE 802.1Q.

	      The server TAP device and	each of	the connecting clients is seen
	      as a port	of the switch. All client ports	are in	untagged  mode
	      and  the	server	TAP device is VLAN-tagged, untagged or accepts
	      both, depending on the --vlan-accept setting.

	      Ethernet frames with a prepended 802.1Q tag are called "tagged".
	      If  the  VLAN  Identifier	(VID) field in such a tag is non-zero,
	      the frame	is called "VLAN-tagged". If the	VID is zero,  but  the
	      Priority	Control	 Point	(PCP)  field is	non-zero, the frame is
	      called "prio-tagged". If there is	no 802.1Q tag,	the  frame  is

	      Using   the   --vlan-pvid	  v   option   once  per  client  (see
	      --client-config-dir), each port can be associated	with a certain
	      VID.   Packets  can  only	 be forwarded between ports having the
	      same VID.	 Therefore, clients with differing VIDs	are completely
	      separated	 from one-another, even	if --client-to-client is acti-

	      The packet filtering takes place in the OpenVPN server.  Clients
	      should not have any VLAN tagging configuration applied.

	      The  --vlan-tagging  option is off by default. While turned off,
	      OpenVPN accepts any Ethernet frame and does not perform any spe-
	      cial processing for VLAN-tagged packets.

	      This option can only be activated	in --dev tap mode.

       --vlan-accept args
	      Configure	the VLAN tagging policy	for the	server TAP device.

	      Valid syntax:

		 vlan-accept  all|tagged|untagged

	      The following modes are available:

	      tagged Admit  only  VLAN-tagged frames. Only VLAN-tagged packets
		     are accepted, while untagged or  priority-tagged  packets
		     are dropped when entering the server TAP device.

		     Admit  only untagged and prio-tagged frames.  VLAN-tagged
		     packets  are  not	accepted,  while  untagged  or	prior-
		     ity-tagged	 packets  entering  the	 server	TAP device are
		     tagged  with  the	value  configured   for	  the	global
		     --vlan-pvid setting.

	      all (default)
		     Admit  all	 frames.   All	packets	 are admitted and then
		     treated like untagged or tagged mode respectively.

	      Note:  Some vendors refer	to switch ports	running	in tagged mode
		     as	 "trunk	 ports"	 and  switch ports running in untagged
		     mode as "access ports".

	      Packets forwarded	from clients to	 the  server  are  VLAN-tagged
	      with  the	 originating client's PVID, unless the VID matches the
	      global --vlan-pvid, in which case	the tag	is removed.

	      If no PVID is configured for a given  client  (see  --vlan-pvid)
	      packets are tagged with 1	by default.

       --vlan-pvid v
	      Specifies	 which	VLAN  identifier  a "port" is associated with.
	      Only valid when --vlan-tagging is	speficied.

	      In the client context, the setting specifies  which  VLAN	 ID  a
	      client is	associated with. In the	global context,	the VLAN ID of
	      the server TAP device is set. The	latter only  makes  sense  for
	      --vlan-accept untagged and --vlan-accept all modes.

	      Valid  values  for v go from 1 through to	4094. The global value
	      defaults to 1. If	no --vlan-pvid is specified in the client con-
	      text, the	global value is	inherited.

	      In  some switch implementations, the PVID	is also	referred to as
	      "Native VLAN".

   SSL Library information
	      (Standalone) Show	all cipher algorithms to use with the --cipher

	      (Standalone)  Show all message digest algorithms to use with the
	      --auth option.

	      (Standalone) Show	all TLS	ciphers	supported by  the  crypto  li-
	      brary.   OpenVPN	uses  TLS  to secure the control channel, over
	      which the	keys that are used to protect the actual  VPN  traffic
	      are exchanged. The TLS ciphers will be sorted from highest pref-
	      erence (most secure) to lowest.

	      Be aware that whether a cipher suite in this list	 can  actually
	      work  depends  on	 the  specific	setup of both peers (e.g. both
	      peers must support the cipher, and an ECDSA  cipher  suite  will
	      not work if you are using	an RSA certificate, etc.).

	      (Standalone)  Show currently available hardware-based crypto ac-
	      celeration engines supported by the OpenSSL library.

	      (Standalone) Show	all available elliptic	curves/groups  to  use
	      with the --ecdh-curve and	tls-groups options.

   Generating key material
       --genkey	args
	      (Standalone)  Generate  a	key to be used of the type keytype. if
	      keyfile is left out or empty the key will	be output  on  stdout.
	      See the following	sections for the different keytypes.

	      Valid syntax:

		 --genkey keytype keyfile

	      Valid keytype arguments are:

	      secret		    Standard OpenVPN shared secret keys

	      tls-crypt		    Alias for secret

	      tls-auth		    Alias for secret

	      auth-token	    Key	used for --auth-gen-token-key

	      tls-crypt-v2-server   TLS	Crypt v2 server	key

	      tls-crypt-v2-client   TLS	Crypt v2 client	key


		 $ openvpn --genkey secret shared.key
		 $ openvpn --genkey tls-crypt shared.key
		 $ openvpn --genkey tls-auth shared.key
		 $ openvpn --genkey tls-crypt-v2-server	v2crypt-server.key
		 $ openvpn --tls-crypt-v2 v2crypt-server.key --genkey tls-crypt-v2-client v2crypt-client-1.key

	      o	Generating  Shared  Secret  Keys Generate a shared secret, for
		use with the --secret, --tls-auth or --tls-crypt options.


		   $ openvpn --genkey secret|tls-crypt|tls-auth	keyfile

		The key	is saved in keyfile.  All  three  variants  (--secret,
		tls-crypt  and	tls-auth)  generate  the same type of key. The
		aliases	are added for convenience.

		If using this for --secret, this file must be shared with  the
		peer over a pre-existing secure	channel	such as	scp(1).

	      o	Generating  TLS	 Crypt v2 Server key Generate a	--tls-crypt-v2
		key to be used by an OpenVPN server.  The  key	is  stored  in


		   --genkey tls-crypt-v2-server	keyfile

	      o	Generating  TLS	 Crypt v2 Client key Generate a	--tls-crypt-v2
		key to be used by OpenVPN clients.  The	key is stored in  key-


		   --genkey tls-crypt-v2-client	keyfile	[metadata]

		If  supplied,  include	the  supplied  metadata	in the wrapped
		client key. This metadata must be supplied  in	base64-encoded
		form. The metadata must	be at most 733 bytes long (980 charac-
		ters in	base64,	though note that 980 base64 characters can en-
		code more than 733 bytes).

		If  no	metadata  is  supplied,	OpenVPN	will use a 64-bit unix
		timestamp representing the current time	 in  UTC,  encoded  in
		network	order, as metadata for the generated key.

		A  tls-crypt-v2	 client	 key is	wrapped	using a	server key. To
		generate a client key, the  user  must	therefore  supply  the
		server key using the --tls-crypt-v2 option.

		Servers	 can  use  --tls-crypt-v2-verify to specify a metadata
		verification command.

	      o	Generate Authentication	Token key Generate a new  secret  that
		can be used with --auth-gen-token-secret


		   --genkey auth-token [keyfile]

		Note:  This file should	be kept	secret to the server as	anyone
		       that has	access to this file will be able  to  generate
		       auth  tokens  that  the	OpenVPN	 server	will accept as

   Data	Channel	Renegotiation
       When running OpenVPN in client/server mode, the data channel will use a
       separate	 ephemeral  encryption	key which is rotated at	regular	inter-

       --reneg-bytes n
	      Renegotiate data channel key after  n  bytes  sent  or  received
	      (disabled	 by default with an exception, see below). OpenVPN al-
	      lows the lifetime	of a key to be expressed as a number of	 bytes
	      encrypted/decrypted,  a  number  of packets, or a	number of sec-
	      onds. A key renegotiation	will be	forced if any of  these	 three
	      criteria are met by either peer.

	      If  using	 ciphers  with	cipher block sizes less	than 128-bits,
	      --reneg-bytes is set to 64MB by default, unless it is explicitly
	      disabled	by setting the value to	0, but this is HIGHLY DISCOUR-
	      AGED as this is designed to  add	some  protection  against  the
	      SWEET32 attack vector. For more information see the --cipher op-

       --reneg-pkts n
	      Renegotiate data channel key after n packets sent	 and  received
	      (disabled	by default).

       --reneg-sec args
	      Renegotiate  data	channel	key after at most max seconds (default
	      3600) and	at least min  seconds  (default	 is  90%  of  max  for
	      servers, and equal to max	for clients).

		 reneg-sec max [min]

	      The  effective --reneg-sec value used is per session pseudo-uni-
	      form-randomized between min and max.

	      With the default value of	3600 this results in an	effective  per
	      session  value in	the range of 3240 .. 3600 seconds for servers,
	      or just 3600 for clients.

	      When using dual-factor authentication, note  that	 this  default
	      value  may  cause	 the  end user to be challenged	to reauthorize
	      once per hour.

	      Also, keep in mind that this option can  be  used	 on  both  the
	      client  and  server,  and	whichever uses the lower value will be
	      the one to trigger the renegotiation. A common mistake is	to set
	      --reneg-sec  to  a  higher value on either the client or server,
	      while the	other side of the connection is	still  using  the  de-
	      fault value of 3600 seconds, meaning that	the renegotiation will
	      still occur once per 3600	seconds. The solution is  to  increase
	      --reneg-sec on both the client and server, or set	it to 0	on one
	      side of the connection (to disable), and to your chosen value on
	      the other	side.

   TLS Mode Options
       TLS  mode  is the most powerful crypto mode of OpenVPN in both security
       and flexibility.	TLS mode works by establishing control and data	 chan-
       nels  which  are	multiplexed over a single TCP/UDP port.	OpenVPN	initi-
       ates a TLS session over the control channel and uses it to exchange ci-
       pher  and HMAC keys to protect the data channel.	TLS mode uses a	robust
       reliability layer over the UDP connection for all control channel  com-
       munication,  while  the	data channel, over which encrypted tunnel data
       passes, is forwarded without any	mediation. The result is the  best  of
       both  worlds:  a	fast data channel that forwards	over UDP with only the
       overhead	of encrypt, decrypt, and HMAC functions, and a control channel
       that  provides  all of the security features of TLS, including certifi-
       cate-based authentication and Diffie Hellman forward secrecy.

       To use TLS mode,	each peer that runs OpenVPN should have	its own	 local
       certificate/key pair (--cert and	--key),	signed by the root certificate
       which is	specified in --ca.

       When two	OpenVPN	peers connect, each presents its local certificate  to
       the  other. Each	peer will then check that its partner peer presented a
       certificate which was signed by the master root certificate  as	speci-
       fied in --ca.

       If  that	 check	on  both peers succeeds, then the TLS negotiation will
       succeed,	both OpenVPN peers will	exchange temporary session  keys,  and
       the tunnel will begin passing data.

       The OpenVPN project provides a set of scripts for managing RSA certifi-
       cates and keys:

       --askpass file
	      Get certificate password from console or file before  we	daemo-

	      Valid syntaxes:

		 askpass file

	      For  the extremely security conscious, it	is possible to protect
	      your private key with a password.	Of course this means that  ev-
	      ery time the OpenVPN daemon is started you must be there to type
	      the password. The	--askpass option allows	you to	start  OpenVPN
	      from  the	command	line.  It will query you for a password	before
	      it daemonizes. To	protect	a private  key	with  a	 password  you
	      should  omit  the	-nodes option when you use the openssl command
	      line tool	to manage certificates and private keys.

	      If file is specified, read the password from the first  line  of
	      file.  Keep  in  mind  that storing your password	in a file to a
	      certain extent invalidates the extra security provided by	 using
	      an encrypted key.

       --ca file
	      Certificate authority (CA) file in .pem format, also referred to
	      as the root certificate. This file can  have  multiple  certifi-
	      cates  in	 .pem format, concatenated together. You can construct
	      your own certificate authority certificate and  private  key  by
	      using a command such as:

		 openssl req -nodes -new -x509 -keyout ca.key -out ca.crt

	      Then  edit  your openssl.cnf file	and edit the certificate vari-
	      able to point to your new	root certificate ca.crt.

	      For testing purposes only, the OpenVPN distribution  includes  a
	      sample  CA  certificate (ca.crt).	Of course you should never use
	      the test certificates and	test keys distributed with OpenVPN  in
	      a	 production environment, since by virtue of the	fact that they
	      are distributed with OpenVPN, they are totally insecure.

       --capath	dir
	      Directory	containing trusted certificates	(CAs  and  CRLs).  Not
	      available	with mbed TLS.

	      CAs in the capath	directory are expected to be named <hash>.<n>.
	      CRLs are expected	to be named <hash>.r<n>. See the  -CApath  op-
	      tion  of	openssl	 verify, and the -hash option of openssl x509,
	      openssl crl and X509_LOOKUP_hash_dir()(3)	for more information.

	      Similar to the --crl-verify option, CRLs	are  not  mandatory  -
	      OpenVPN  will  log the usual warning in the logs if the relevant
	      CRL is missing, but the connection will be allowed.

       --cert file
	      Local peer's signed certificate in .pem format --	must be	signed
	      by  a  certificate  authority whose certificate is in --ca file.
	      Each peer	in an OpenVPN link running in TLS mode should have its
	      own certificate and private key file. In addition, each certifi-
	      cate should have been signed by the key of a certificate author-
	      ity  whose  public key resides in	the --ca certificate authority
	      file. You	can easily make	your own  certificate  authority  (see
	      above)  or  pay  money  to  use  a  commercial  service  such as (in which case	you will be  helping  to  finance  the
	      world's  second space tourist :).	To generate a certificate, you
	      can use a	command	such as:

		 openssl req -nodes -new -keyout mycert.key -out mycert.csr

	      If your certificate authority private key	lives on  another  ma-
	      chine, copy the certificate signing request (mycert.csr) to this
	      other machine (this can be done over an insecure channel such as
	      email). Now sign the certificate with a command such as:

		 openssl ca -out mycert.crt -in	mycert.csr

	      Now  copy	 the  certificate  (mycert.crt)	back to	the peer which
	      initially	generated the .csr file	(this can  be  over  a	public
	      medium).	Note that the openssl ca command reads the location of
	      the certificate authority	key from its configuration  file  such
	      as  /usr/share/ssl/openssl.cnf --	note also that for certificate
	      authority	functions, you must set	up the files index.txt (may be
	      empty) and serial	(initialize to 01).

       --crl-verify args
	      Check peer certificate against a Certificate Revocation List.

	      Valid syntax:

		 crl-verify file/directory flag


		 crl-verify crl-file.pem
		 crl-verify /etc/openvpn/crls dir

	      A	 CRL  (certificate  revocation list) is	used when a particular
	      key is compromised but when the overall PKI is still intact.

	      Suppose you had a	PKI consisting of a CA,	root certificate,  and
	      a	 number	of client certificates.	Suppose	a laptop computer con-
	      taining a	client key and certificate was stolen. By  adding  the
	      stolen certificate to the	CRL file, you could reject any connec-
	      tion which attempts to use it, while preserving the overall  in-
	      tegrity of the PKI.

	      The  only	 time when it would be necessary to rebuild the	entire
	      PKI from scratch would be	if the root certificate	key itself was

	      The  option  is  not mandatory - if the relevant CRL is missing,
	      OpenVPN will log a warning in the	logs - e.g.

		 VERIFY	WARNING: depth=0, unable to get	certificate CRL

	      but the connection will be allowed.  If the optional dir flag is
	      specified,  enable  a  different	mode  where  the crl-verify is
	      pointed at a directory containing	files named as revoked	serial
	      numbers  (the  files may be empty, the contents are never	read).
	      If a client requests a connection, where the client  certificate
	      serial  number (decimal string) is the name of a file present in
	      the directory, it	will be	rejected.

	      Note:  As	the crl	file (or directory) is read every time a  peer
		     connects,	if  you	 are  dropping	root  privileges  with
		     --user, make sure that this user  has  sufficient	privi-
		     leges to read the file.

       --dh file
	      File  containing	Diffie	Hellman	parameters in .pem format (re-
	      quired for --tls-server only).

	      Set file to none to disable Diffie Hellman key exchange (and use
	      ECDH only). Note that this requires peers	to be using an SSL li-
	      brary that supports ECDH TLS cipher suites (e.g. OpenSSL 1.0.1+,
	      or mbed TLS 2.0+).

	      Use openssl dhparam -out dh2048.pem 2048 to generate 2048-bit DH
	      parameters. Diffie Hellman parameters may	be considered public.

       --ecdh-curve name
	      Specify the curve	to use	for  elliptic  curve  Diffie  Hellman.
	      Available	curves can be listed with --show-curves. The specified
	      curve will only be used for ECDH TLS-ciphers.

	      This option is not supported in mbed TLS builds of OpenVPN.

       --extra-certs file
	      Specify a	file containing	one or more  PEM  certs	 (concatenated
	      together)	that complete the local	certificate chain.

	      This  option  is useful for "split" CAs, where the CA for	server
	      certs is different than the CA for client	certs.	Putting	 certs
	      in  this	file allows them to be used to complete	the local cer-
	      tificate chain without trusting them to verify the  peer-submit-
	      ted  certificate,	 as would be the case if the certs were	placed
	      in the ca	file.

       --hand-window n
	      Handshake	Window -- the TLS-based	 key  exchange	must  finalize
	      within n seconds of handshake initiation by any peer (default 60
	      seconds).	If the handshake fails we will attempt	to  reset  our
	      connection  with	our  peer  and try again. Even in the event of
	      handshake	failure	we will	still use our expiring key for	up  to
	      --tran-window  seconds to	maintain continuity of transmission of
	      tunnel data.

	      The --hand-window	parameter also controls	 the  amount  of  time
	      that  the	OpenVPN	client repeats the pull	request	until it times

       --key file
	      Local peer's private key in .pem format.	Use  the  private  key
	      which  was generated when	you built your peer's certificate (see
	      --cert file above).

       --pkcs12	file
	      Specify a	PKCS #12 file containing local private key, local cer-
	      tificate,	 and  root CA certificate. This	option can be used in-
	      stead of --ca, --cert, and --key.	 Not available with mbed TLS.

       --remote-cert-eku oid
	      Require that peer	certificate was	signed with  an	 explicit  ex-
	      tended key usage.

	      This is a	useful security	option for clients, to ensure that the
	      host they	connect	to is a	designated server.

	      The extended key usage should be encoded	in  oid	 notation,  or
	      OpenSSL symbolic representation.

       --remote-cert-ku	key-usage
	      Require  that  peer  certificate	was  signed  with  an explicit

	      If present in the	certificate, the keyUsage value	 is  validated
	      by the TLS library during	the TLS	handshake. Specifying this op-
	      tion without arguments requires this extension to	be present (so
	      the TLS library will verify it).

	      If  key-usage  is	 a list	of usage bits, the keyUsage field must
	      have at least the	same bits set as the bits in one of the	values
	      supplied in the key-usage	list.

	      The key-usage values in the list must be encoded in hex, e.g.

		 remote-cert-ku	a0

       --remote-cert-tls type
	      Require  that  peer  certificate was signed with an explicit key
	      usage and	extended key usage based on RFC3280 TLS	rules.

	      Valid syntaxes:

		 remote-cert-tls server
		 remote-cert-tls client

	      This is a	useful security	option for clients, to ensure that the
	      host  they  connect  to is a designated server. Or the other way
	      around; for a server to verify that only	hosts  with  a	client
	      certificate can connect.

	      The --remote-cert-tls client option is equivalent	to

		 remote-cert-eku "TLS Web Client Authentication"

	      The --remote-cert-tls server option is equivalent	to

		 remote-cert-eku "TLS Web Server Authentication"

	      This  is	an  important security precaution to protect against a
	      man-in-the-middle	attack where an	authorized client attempts  to
	      connect  to  another client by impersonating the server. The at-
	      tack is easily prevented by having  clients  verify  the	server
	      certificate   using   any	  one	of  --remote-cert-tls,	--ver-
	      ify-x509-name, --peer-fingerprint	or --tls-verify.

       --tls-auth args
	      Add an additional	layer of HMAC authentication on	top of the TLS
	      control  channel	to mitigate DoS	attacks	and attacks on the TLS

	      Valid syntaxes:

		 tls-auth file
		 tls-auth file 0
		 tls-auth file 1

	      In a nutshell, --tls-auth	enables	a kind of "HMAC	 firewall"  on
	      OpenVPN's	 TCP/UDP port, where TLS control channel packets bear-
	      ing an incorrect HMAC signature can be dropped immediately with-
	      out response.

	      file (required) is a file	in OpenVPN static key format which can
	      be generated by --genkey.

	      Older  versions  (up  to	OpenVPN	 2.3)  supported  a   freeform
	      passphrase  file.	 This is no longer supported in	newer versions

	      See the --secret option for more information on the optional di-
	      rection parameter.

	      --tls-auth is recommended	when you are running OpenVPN in	a mode
	      where it is listening for	packets	from any IP address,  such  as
	      when  --remote  is  not specified, or --remote is	specified with

	      The rationale for	this feature is	as  follows.  TLS  requires  a
	      multi-packet  exchange before it is able to authenticate a peer.
	      During this time before authentication,  OpenVPN	is  allocating
	      resources	(memory	and CPU) to this potential peer. The potential
	      peer is also exposing many parts of OpenVPN and the OpenSSL  li-
	      brary  to	the packets it is sending. Most	successful network at-
	      tacks today seek to either exploit bugs  in  programs  (such  as
	      buffer  overflow	attacks) or force a program to consume so many
	      resources	that it	becomes	unusable. Of course the	first line  of
	      defense  is  always to produce clean, well-audited code. OpenVPN
	      has been written with buffer overflow attack prevention as a top
	      priority.	But as history has shown, many of the most widely used
	      network applications have, from time to time, fallen  to	buffer
	      overflow attacks.

	      So  as  a	 second	 line  of defense, OpenVPN offers this special
	      layer of authentication on top of	the  TLS  control  channel  so
	      that  every packet on the	control	channel	is authenticated by an
	      HMAC signature and a unique ID for replay	protection. This  sig-
	      nature  will  also  help protect against DoS (Denial of Service)
	      attacks. An important rule of thumb in reducing vulnerability to
	      DoS  attacks is to minimize the amount of	resources a potential,
	      but as yet unauthenticated, client is able to consume.

	      --tls-auth does this by signing every TLS	control	channel	packet
	      with  an HMAC signature, including packets which are sent	before
	      the TLS level has	had a chance to	authenticate the peer. The re-
	      sult  is	that  packets  without	the  correct  signature	can be
	      dropped immediately upon reception, before they have a chance to
	      consume  additional system resources such	as by initiating a TLS
	      handshake. --tls-auth can	be strengthened	by  adding  the	 --re-
	      play-persist  option which will keep OpenVPN's replay protection
	      state in a file so that it is not	lost across restarts.

	      It should	be emphasized that this	feature	is optional  and  that
	      the key file used	with --tls-auth	gives a	peer nothing more than
	      the power	to initiate a TLS handshake. It	is not used to encrypt
	      or authenticate any tunnel data.

	      Use  --tls-crypt	instead	if you want to use the key file	to not
	      only authenticate, but also encrypt the TLS control channel.

       --tls-groups list
	      A	list of	allowable groups/curves	in order of preference.

	      Set the allowed elliptic	curves/groups  for  the	 TLS  session.
	      These  groups  are  allowed to be	used in	signatures and key ex-

	      mbedTLS currently	allows all known curves	per default.

	      OpenSSL 1.1+ restricts the list per default to


	      If you use certificates that use non-standard curves, you	 might
	      need to add them here. If	you do not force the ecdh curve	by us-
	      ing --ecdh-curve,	the groups for ecdh will also be  picked  from
	      this list.

	      OpenVPN  maps  the  curve	 name secp256r1	to prime256v1 to allow
	      specifying the same tls-groups option for	mbedTLS	and OpenSSL.

	      Warning: this option not only affects  elliptic  curve  certifi-
	      cates but	also the key exchange in TLS 1.3 and using this	option
	      improperly will disable TLS 1.3.

       --tls-cert-profile profile
	      Set the allowed cryptographic algorithms	for  certificates  ac-
	      cording to profile.

	      The following profiles are supported:

		     Identical for mbed	TLS to legacy

	      legacy (default)
		     SHA1 and newer, RSA 2048-bit+, any	elliptic curve.

		     SHA2 and newer, RSA 2048-bit+, any	elliptic curve.

	      suiteb SHA256/SHA384, ECDSA with P-256 or	P-384.

	      This option is only fully	supported for mbed TLS builds. OpenSSL
	      builds use the following approximation:

		     sets "security level 0"

	      legacy (default)
		     sets "security level 1"

		     sets "security level 2"

	      suiteb sets "security level 3" and --tls-cipher "SUITEB128".

	      OpenVPN will migrate to 'preferred' as default  in  the  future.
	      Please ensure that your keys already comply.

       WARNING:	--tls-ciphers, --tls-ciphersuites and tls-groups
	      These  options  are expert features, which - if used correctly -
	      can improve the security of your VPN connection. But it is  also
	      easy  to unwittingly use them to carefully align a gun with your
	      foot, or just break your connection. Use with care!

       --tls-cipher l
	      A	list l of allowable TLS	ciphers	delimited by a colon (":").

	      These setting can	be used	to ensure that certain	cipher	suites
	      are  used	(or not	used) for the TLS connection. OpenVPN uses TLS
	      to secure	the control channel, over which	the keys that are used
	      to protect the actual VPN	traffic	are exchanged.

	      The  supplied  list  of ciphers is (after	potential OpenSSL/IANA
	      name translation)	simply supplied	to the crypto library.	Please
	      see the OpenSSL and/or mbed TLS documentation for	details	on the
	      cipher list interpretation.

	      For OpenSSL, the --tls-cipher is used for	TLS 1.2	and below.

	      Use --show-tls to	see a list of TLS ciphers  supported  by  your
	      crypto library.

	      The default for --tls-cipher is to use mbed TLS's	default	cipher
	      list	when	  using	     mbed	TLS	  or	   DE-
	      FAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA	  when
	      using OpenSSL.

       --tls-ciphersuites l
	      Same as --tls-cipher but for TLS 1.3 and up. mbed	TLS has	no TLS
	      1.3 support yet and only the --tls-cipher	setting	is used.

	      The  default  for	 --tls-ciphersuites  is	 to use	the crypto li-
	      brary's default.

	      Enable TLS and assume client role	during TLS handshake.

       --tls-crypt keyfile
	      Encrypt and authenticate all control channel  packets  with  the
	      key from keyfile.	(See --tls-auth	for more background.)

	      Encrypting (and authenticating) control channel packets:

	      o	provides  more	privacy	by hiding the certificate used for the
		TLS connection,

	      o	makes it harder	to identify OpenVPN traffic as such,

	      o	provides "poor-man's" post-quantum security, against attackers
		who  will  never  know the pre-shared key (i.e.	no forward se-

	      In contrast to --tls-auth, --tls-crypt does not require the user
	      to set --key-direction.

	      Security Considerations

	      All  peers  use the same --tls-crypt pre-shared group key	to au-
	      thenticate and encrypt control channel messages. To ensure  that
	      IV  collisions  remain  unlikely,	this key should	not be used to
	      encrypt more than	2^48 client-to-server or 2^48 server-to-client
	      control channel messages.	A typical initial negotiation is about
	      10 packets in each direction. Assuming both initial  negotiation
	      and  renegotiations are at most 2^16 (65536) packets (to be con-
	      servative), and (re)negotiations happen  each  minute  for  each
	      user  (24/7),  this  limits  the	tls-crypt key lifetime to 8171
	      years divided by the number of users. So a setup with 1000 users
	      should  rotate  the  key	at least once each eight years.	(And a
	      setup with 8000 users each year.)

	      If IV collisions were to occur, this could result	in  the	 secu-
	      rity  of	--tls-crypt  degrading	to  the	same security as using
	      --tls-auth.  That	is, the	control	channel	 still	benefits  from
	      the  extra  protection  against active man-in-the-middle-attacks
	      and DoS attacks, but may	no  longer  offer  extra  privacy  and
	      post-quantum security on top of what TLS itself offers.

	      For  large  setups or setups where clients are not trusted, con-
	      sider using --tls-crypt-v2 instead. That uses per-client	unique
	      keys, and	thereby	improves the bounds to 'rotate a client	key at
	      least once per 8000 years'.

       --tls-crypt-v2 keyfile
	      Valid syntax:

		 tls-crypt-v2 keyfile
		 tls-crypt-v2 keyfile force-cookie
		 tls-crypt-v2 keyfile allow-noncookie

	      Use client-specific tls-crypt keys.

	      For clients, keyfile is a	client-specific	tls-crypt key. Such  a
	      key  can be generated using the --genkey tls-crypt-v2-client op-

	      For servers, keyfile is used to unwrap client-specific keys sup-
	      plied  by	 the  client during connection setup. This key must be
	      the same as the key used to  generate  the  client-specific  key
	      (see --genkey tls-crypt-v2-client).

	      On servers, this option can be used together with	the --tls-auth
	      or --tls-crypt option. In	that  case,  the  server  will	detect
	      whether  the client is using client-specific keys, and automati-
	      cally select the right mode.

	      The optional parameters force-cookie  allows  only  tls-crypt-v2
	      clients  that  support  a	cookie based stateless three way hand-
	      shake that avoids	replay attacks and  state  exhaustion  on  the
	      server  side (OpenVPN 2.6	and later). The	option allow-noncookie
	      explicitly allows	older tls-crypt-v2  clients.  The  default  is
	      (currently) allow-noncookie.

       --tls-crypt-v2-verify cmd
	      Run  command  cmd	 to verify the metadata	of the client-specific
	      tls-crypt-v2 key of a connecting client. This allows server  ad-
	      ministrators  to	reject client connections, before exposing the
	      TLS stack	(including the notoriously dangerous X.509  and	 ASN.1
	      stacks) to the connecting	client.

	      OpenVPN supplies the following environment variables to the com-

	      o	script_type is set to tls-crypt-v2-verify

	      o	metadata_type is set to	0 if the metadata was  user  supplied,
		or 1 if	it's a 64-bit unix timestamp representing the key cre-
		ation time.

	      o	metadata_file contains the filename of a temporary  file  that
		contains the client metadata.

	      The command can reject the connection by exiting with a non-zero
	      exit code.

	      Exit on TLS negotiation failure.

       --tls-export-cert directory
	      Store the	certificates the clients use upon connection  to  this
	      directory.  This will be done before --tls-verify	is called. The
	      certificates will	use a temporary	name and will be deleted  when
	      the  tls-verify  script returns. The file	name used for the cer-
	      tificate is available via	the peer_cert environment variable.

	      Enable TLS and assume server role	 during	 TLS  handshake.  Note
	      that OpenVPN is designed as a peer-to-peer application. The des-
	      ignation of client or server is only for the purpose of  negoti-
	      ating the	TLS control channel.

       --tls-timeout n
	      Packet  retransmit timeout on TLS	control	channel	if no acknowl-
	      edgment from remote within n seconds (default 2).	 When  OpenVPN
	      sends a control packet to	its peer, it will expect to receive an
	      acknowledgement within n	seconds	 or  it	 will  retransmit  the
	      packet,  subject	to  a  TCP-like	exponential backoff algorithm.
	      This parameter only applies to  control  channel	packets.  Data
	      channel  packets	(which	carry encrypted	tunnel data) are never
	      acknowledged, sequenced, or retransmitted	by OpenVPN because the
	      higher level network protocols running on	top of the tunnel such
	      as TCP expect this role to be left to them.

       --tls-version-min args
	      Sets the minimum TLS version we will accept from the  peer  (de-
	      fault in 2.6.0 and later is "1.2").

	      Valid syntax:

		 tls-version-min version ['or-highest']

	      Examples	for version include 1.0, 1.1, or 1.2. If or-highest is
	      specified	and version is not recognized, we will only accept the
	      highest TLS version supported by the local SSL implementation.

       --tls-version-max version
	      Set  the maximum TLS version we will use (default	is the highest
	      version supported). Examples for version include	1.0,  1.1,  or

       --verify-hash args
	      DEPRECATED Specify SHA1 or SHA256	fingerprint for	level-1	cert.

	      Valid syntax:

		 verify-hash hash [algo]

	      The level-1 cert is the CA (or intermediate cert)	that signs the
	      leaf certificate,	and is one removed from	the  leaf  certificate
	      in the direction of the root. When accepting a connection	from a
	      peer, the	level-1	cert fingerprint must match hash  or  certifi-
	      cate  verification will fail. Hash is specified as XX:XX:... For


	      The algo flag can	be either SHA1 or SHA256. If not provided,  it
	      defaults to SHA1.

	      This option can also be inlined


       If the option is	inlined, algo is always	SHA256.

       --peer-fingerprint args
		 Specify  a  SHA256 fingerprint	or list	of SHA256 fingerprints
		 to verify the peer certificate	against. The peer  certificate
		 must match one	of the fingerprint or certificate verification
		 will fail. The	option can also	be inlined

	      Valid syntax:

		 peer-fingerprint AD:B0:95:D8:09:...

	      or inline:


	      When the --peer-fingerprint option is used, specifying a CA with
	      --ca  or --capath	is optional. This allows the he	--peer-finger-
	      print to be used as alternative to a PKI with  self-signed  cer-
	      tificates	 for small setups. See the examples section for	such a

       --verify-x509-name args
	      Accept connections only if a host's X.509	name is	equal to name.
	      The remote host must also	pass all other tests of	verification.

	      Valid syntax:

		 verify-x509 name type

	      Which  X.509  name is compared to	name depends on	the setting of
	      type.  type can be subject to match the complete subject DN (de-
	      fault),  name  to	 match a subject RDN or	name-prefix to match a
	      subject RDN prefix. Which	RDN is verified	as name	depends	on the
	      --x509-username-field option. But	it defaults to the common name
	      (CN), e.g. a certificate with a subject DN

		 C=KG, ST=NA, L=Bishkek, CN=Server-1

	      would be matched by:

		 verify-x509-name 'C=KG, ST=NA,	L=Bishkek, CN=Server-1'
		 verify-x509-name Server-1 name
		 verify-x509-name Server- name-prefix

	      The last example is useful if you	want a client to  only	accept
	      connections to Server-1, Server-2, etc.

	      --verify-x509-name  is a useful replacement for the --tls-verify
	      option to	verify the  remote  host,  because  --verify-x509-name
	      works in a --chroot environment without any dependencies.

	      Using  a	name  prefix is	a useful alternative to	managing a CRL
	      (Certificate Revocation List) on the client, since it allows the
	      client  to  refuse  all certificates except for those associated
	      with designated servers.

	      NOTE:  Test against a name prefix	only when you are using	 Open-
		     VPN  with a custom	CA certificate that is under your con-
		     trol. Never use this option with  type  name-prefix  when
		     your  client  certificates	 are  signed by	a third	party,
		     such as a commercial web CA.

       --x509-track attribute
	      Save peer	X509 attribute value in	environment for	use by plugins
	      and  management interface. Prepend a + to	attribute to save val-
	      ues  from	 full  cert  chain.  Values   will   be	  encoded   as
	      X509_<depth>_<attribute>=<value>.	 Multiple --x509-track options
	      can be defined to	track multiple attributes.

       --x509-username-field args
	      Fields in	the X.509 certificate subject to be used as the	 user-
	      name (default CN). If multiple fields are	specified their	values
	      will be concatenated into	the one	username using _ symbol	 as  a

	      Valid syntax:

		 x509-username-field [ext:]fieldname [[ext:]fieldname...]

	      Typically,  this option is specified with	fieldname arguments as
	      either of	the following:

		 x509-username-field emailAddress
		 x509-username-field ext:subjectAltName
		 x509-username-field CN	serialNumber

	      The first	example	uses the value of the  emailAddress  attribute
	      in  the  certificate's Subject field as the username. The	second
	      example uses the ext: prefix to signify that the X.509 extension
	      fieldname	 subjectAltName	 be searched for an rfc822Name (email)
	      field to be used as the username.	In cases where there are  mul-
	      tiple  email  addresses in ext:fieldname,	the last occurrence is
	      chosen. The last example uses the	value of the CN	 attribute  in
	      the  Subject  field, combined with the _ separator and the hexa-
	      decimal representation of	the certificate's serialNumber.

	      When this	option is used,	 the  --verify-x509-name  option  will
	      match against the	chosen fieldname instead of the	Common Name.

	      Only  the	 subjectAltName	and issuerAltName X.509	extensions and
	      serialNumber X.509 attribute are supported.

	      Please note: This	option has a feature  which  will  convert  an
	      all-lowercase fieldname to uppercase characters, e.g., ou	-> OU.
	      A	mixed-case fieldname or	one having the	ext:  prefix  will  be
	      left  as-is.  This  automatic upcasing feature is	deprecated and
	      will be removed in a future release.

	      Non-compliant symbols are	being replaced with the	_ symbol, same
	      as  the  field  separator, so concatenating multiple fields with
	      such or _	symbols	can potentially	lead to	username collisions.

   PKCS#11 / SmartCard options
       --pkcs11-cert-private args
	      Set if access to certificate object should  be  performed	 after
	      login.  Every provider has its own setting.

	      Valid syntaxes:

		 pkcs11-cert-private 0
		 pkcs11-cert-private 1

       --pkcs11-id name
	      Specify  the serialized certificate id to	be used. The id	can be
	      gotten by	the standalone --show-pkcs11-ids option.

	      Acquire PKCS#11 id from management interface.  In	 this  case  a
	      NEED-STR	'pkcs11-id-request'  real-time	message	 will be trig-
	      gered, application may use pkcs11-id-count command  to  retrieve
	      available	 number	 of certificates, and pkcs11-id-get command to
	      retrieve certificate id and certificate body.

       --pkcs11-pin-cache seconds
	      Specify how many seconds the PIN can be cached, the  default  is
	      until the	token is removed.

       --pkcs11-private-mode mode
	      Specify  which method to use in order to perform private key op-
	      erations.	 A different mode can be specified for each  provider.
	      Mode is encoded as hex number, and can be	a mask one of the fol-

	      0	(default)   Try	to determine automatically.

	      1		    Use	sign.

	      2		    Use	sign recover.

	      4		    Use	decrypt.

	      8		    Use	unwrap.

       --pkcs11-protected-authentication args
	      Use PKCS#11 protected authentication path, useful	for  biometric
	      and external keypad devices. Every provider has its own setting.

	      Valid syntaxes:

		 pkcs11-protected-authentication 0
		 pkcs11-protected-authentication 1

       --pkcs11-providers provider
	      Specify an RSA Security Inc. PKCS	#11 Cryptographic Token	Inter-
	      face (Cryptoki) providers	to load. This option can be  used  in-
	      stead of --cert, --key and --pkcs12.

	      If p11-kit is present on the system, its	module
	      will  be	loaded	by  default  if	 either	 the  --pkcs11-id   or
	      --pkcs11-id-management	options	   are	  specified    without
	      --pkcs11-provider	being given.

       --show-pkcs11-ids args
	      (Standalone) Show	PKCS#11	token object list.

	      Valid syntax:

		 show-pkcs11 [provider]	[cert_private]

	      Specify cert_private as 1	if certificates	are stored as  private

	      If  p11-kit  is  present on the system, the provider argument is
	      optional;	if omitted the default	module will be

	      --verb  option  can be used BEFORE this option to	produce	debug-
	      ging information.

       OpenVPN 2.4 and higher have the capability to negotiate the data	cipher
       that is used to encrypt data packets. This section describes the	mecha-
       nism in more detail and the different backwards compatibility mechanism
       with older server and clients.

   OpenVPN 2.5 and later behaviour
       When  both client and server are	at least running OpenVPN 2.5, that the
       order of	the ciphers of the server's --data-ciphers is used to pick the
       the data	cipher.	 That means that the first cipher in that list that is
       also in the client's --data-ciphers list	is chosen. If no common	cipher
       is  found the client is rejected	with a AUTH_FAILED message (as seen in
       client log):
	  AUTH:	Received control message: AUTH_FAILED,Data channel cipher  ne-
	  gotiation failed (no shared cipher)

       OpenVPN	2.5  and  later	 will  only  allow  the	 ciphers  specified in
       --data-ciphers.	 If  --data-ciphers  is	 not  set   the	  default   is
       AES-256-GCM:AES-128-GCM.	  In  2.6  and later the default is changed to
       AES-256-GCM:AES-128-GCM:CHACHA20-POLY1305  when	Chacha20-Poly1305   is

       For  backwards  compatibility  OpenVPN 2.6 and later with --compat-mode
       2.4.x (or lower)	and OpenVPN 2.5	will automatically add a cipher	speci-
       fied using the --cipher option to this list.

   OpenVPN 2.4 clients
       The  negotiation	 support in OpenVPN 2.4	was the	first iteration	of the
       implementation and still	had some quirks. Its main goal was "upgrade to
       AES-256-GCM  when  possible".   An  OpenVPN  2.4	 client	 that is built
       against a crypto	library	that supports AES in GCM  mode	and  does  not
       have  --ncp-disable  will  always  announce support for AES-256-GCM and
       AES-128-GCM to a	server by sending IV_NCP=2.

       This only causes	a problem if --ncp-ciphers  option  has	 been  changed
       from  the  default  of AES-256-GCM:AES-128-GCM to a value that does not
       include these  two  ciphers.  When  an  OpenVPN	server	tries  to  use
       AES-256-GCM  or AES-128-GCM the connection will then fail. It is	there-
       fore recommended	to always have the AES-256-GCM and AES-128-GCM ciphers
       to the --ncp-ciphers options to avoid this behaviour.

   OpenVPN 3 clients
       Clients	   based     on	    the	    OpenVPN	3.x	library	    (-  do  not  have   a	  configurable
       --ncp-ciphers  or --data-ciphers	option.	Instead	these clients will an-
       nounce support for  all	their  supported  AEAD	ciphers	 (AES-256-GCM,
       AES-128-GCM and in newer	versions also Chacha20-Poly1305).

       To  support  OpenVPN  3.x  based	 clients at least one of these ciphers
       needs to	be included in the server's --data-ciphers option.

   OpenVPN 2.3 and older clients (and clients with --ncp-disable)
       When a client without cipher negotiation	support	connects to  a	server
       the  cipher specified with the --cipher option in the client configura-
       tion must be included in	the --data-ciphers option of the server	to al-
       low  the	 client	 to  connect.  Otherwise  the  client will be sent the
       AUTH_FAILED message that	indicates no shared cipher.

       If the client is	2.3 or older and has been configured  with  the	 --en-
       able-small  ./configure argument, using data-ciphers-fallback cipher in
       the server config file with the explicit	cipher used by the  client  is

   OpenVPN 2.4 server
       When  a	client indicates support for AES-128-GCM and AES-256-GCM (with
       IV_NCP=2) an OpenVPN 2.4	server will  send  the	first  cipher  of  the
       --ncp-ciphers  to  the OpenVPN client regardless	of what	the cipher is.
       To emulate the behaviour	of an OpenVPN 2.4 client as close as  possible
       and  have  compatibility	 to a setup that depends on this quirk,	adding
       AES-128-GCM and AES-256-GCM to the client's  --data-ciphers  option  is
       required.  OpenVPN  2.5+	 will only announce the	IV_NCP=2 flag if those
       ciphers are present.

   OpenVPN 2.3 and older servers (and servers with --ncp-disable)
       The cipher used by the server must be included in --data-ciphers	to al-
       low  the	 client	connecting to a	server without cipher negotiation sup-
       port.  (For compatibility OpenVPN 2.5 will also accept the  cipher  set
       with --cipher)

       If  the	server is 2.3 or older and  has	been configured	with the --en-
       able-small ./configure argument,	adding --data-ciphers-fallback	cipher
       to  the	client	config	with the explicit cipher used by the server is

   Blowfish in CBC mode	(BF-CBC) deprecation
       The --cipher option defaulted to	BF-CBC in OpenVPN 2.4 and  older  ver-
       sion.  The default was never changed to ensure backwards	compatibility.
       In OpenVPN 2.5 this behaviour has now been changed so that if the --ci-
       pher is not explicitly set it does not allow the	weak BF-CBC cipher any
       more and	needs to explicitly added as  --cipher	BFC-CBC	 or  added  to

       We  strongly  recommend	to switching away from BF-CBC to a more	secure
       cipher as soon as possible instead.

       OpenVPN consists	of two sides of	network	configuration.	 One  side  is
       the  link between the local and remote side, the	other side is the vir-
       tual network adapter (tun/tap device).

   Link	Options
       This link options section covers	options	related	to the connection  be-
       tween the local and the remote host.

       --bind keywords
	      Bind  to	local address and port.	This is	the default unless any
	      of --proto tcp-client , --http-proxy or --socks-proxy are	used.

	      If the optional ipv6only keyword is present  OpenVPN  will  bind
	      only to IPv6 (as opposed to IPv6 and IPv4) when a	IPv6 socket is

	      Allow remote peer	to change its IP address and/or	 port  number,
	      such  as	due  to	 DHCP  (this is	the default if --remote	is not
	      used).  --float when specified with --remote allows  an  OpenVPN
	      session  to initially connect to a peer at a known address, how-
	      ever if packets arrive from a new	address	and pass all authenti-
	      cation  tests, the new address will take control of the session.
	      This is useful when you are connecting to	a peer which  holds  a
	      dynamic address such as a	dial-in	user or	DHCP client.

	      Essentially, --float tells OpenVPN to accept authenticated pack-
	      ets from any address, not	only the address which	was  specified
	      in the --remote option.

       --fragment args
	      Valid syntax:

		 fragment max
		 fragment max mtu

	      Enable  internal datagram	fragmentation so that no UDP datagrams
	      are sent which are larger	than max bytes.

	      If the mtu parameter is present the max parameter	is interpreted
	      to  include IP and UDP encapsulation overhead. The mtu parameter
	      is introduced in OpenVPN version 2.6.0.

	      If the mtu parameter is absent, the max parameter	is interpreted
	      in  the  same  way  as  the  --link-mtu parameter, i.e.  the UDP
	      packet size after	encapsulation overhead has been	added in,  but
	      not including the	UDP header itself.

	      The  --fragment  option  only makes sense	when you are using the
	      UDP protocol (--proto udp).

	      --fragment adds 4	bytes of overhead per datagram.

	      See the --mssfix option below for	an important related option to

	      It should	also be	noted that this	option is not meant to replace
	      UDP fragmentation	at the IP stack	level. It is only meant	 as  a
	      last resort when path MTU	discovery is broken. Using this	option
	      is less efficient	than fixing path MTU  discovery	 for  your  IP
	      link and using native IP fragmentation instead.

	      Having  said that, there are circumstances where using OpenVPN's
	      internal fragmentation capability	may be your only option,  such
	      as  tunneling  a	UDP multicast stream which requires fragmenta-

       --keepalive args
	      A	helper directive designed to simplify the expression of	--ping
	      and --ping-restart.

	      Valid syntax:

		 keepalive interval timeout

	      Send  ping  once	every interval seconds,	restart	if ping	is not
	      received for timeout seconds.

	      This option can be used on both client and server	side,  but  it
	      is  enough to add	this on	the server side	as it will push	appro-
	      priate --ping and	--ping-restart options to the client. If  used
	      on  both	server	and client, the	values pushed from server will
	      override the client local	values.

	      The timeout argument will	be twice as long on the	 server	 side.
	      This  ensures  that  a timeout is	detected on client side	before
	      the server side drops the	connection.

	      For example, --keepalive 10 60 expands as	follows:

		 if mode server:
		     ping 10			# Argument: interval
		     ping-restart 120		# Argument: timeout*2
		     push "ping	10"		# Argument: interval
		     push "ping-restart	60"	# Argument: timeout
		     ping 10			# Argument: interval
		     ping-restart 60		# Argument: timeout

       --link-mtu n
	      DEPRECATED Sets an upper bound on	the size of UDP	packets	 which
	      are sent between OpenVPN peers. It's best	not to set this	param-
	      eter unless you know what	you're doing.

	      Due to variable header size of IP	header (20 bytes for IPv4  and
	      40  bytes	 for IPv6) and dynamically negotiated data channel ci-
	      pher, this option	is not reliable.  It  is  recommended  to  set
	      tun-mtu with enough headroom instead.

       --local host
	      Local  host  name	 or IP address for bind. If specified, OpenVPN
	      will bind	to this	address	only.  If  unspecified,	 OpenVPN  will
	      bind to all interfaces.

       --lport port
	      Set  local  TCP/UDP port number or name. Cannot be used together
	      with --nobind option.

       --mark value
	      Mark encrypted packets being sent	with value. The	mark value can
	      be matched in policy routing and packetfilter rules. This	option
	      is only supported	in Linux and does nothing on  other  operating

       --mode m
	      Set   OpenVPN   major   mode.   By   default,  OpenVPN  runs  in
	      point-to-point mode (p2p). OpenVPN 2.0  introduces  a  new  mode
	      (server) which implements	a multi-client server capability.

       --mssfix	args
	      Valid syntax:

		 mssfix	max [mtu]

		 mssfix	max [fixed]


	      Announce	to  TCP	 sessions  running  over  the tunnel that they
	      should limit their send packet sizes such	that after OpenVPN has
	      encapsulated  them,  the	resulting UDP packet size that OpenVPN
	      sends to its peer	will not exceed	max bytes. The	default	 value
	      is 1492 mtu. Use 0 as max	to disable mssfix.

	      If  the  mtu parameter is	specified the max value	is interpreted
	      as the resulting packet size of VPN packets including the	IP and
	      UDP  header.  Support for	the mtu	parameter was added with Open-
	      VPN version 2.6.0.

	      If the mtu parameter is not specified, the max parameter is  in-
	      terpreted	in the same way	as the --link-mtu parameter, i.e.  the
	      UDP packet size after encapsulation overhead has been added  in,
	      but  not including the UDP header	itself.	Resulting packet would
	      be at most 28 bytes larger for IPv4 and 48 bytes for IPv6	(20/40
	      bytes  for  IP header and	8 bytes	for UDP	header). Default value
	      of 1450 allows OpenVPN packets to	be transmitted over IPv4 on  a
	      link with	MTU 1478 or higher without IP level fragmentation (and
	      1498 for IPv6).

	      If the fixed parameter is	specified, OpenVPN will	 make  no  at-
	      tempt  to	 calculate  the	VPN encapsulation overhead but instead
	      will set the MSS to limit	the size of the	payload	IP packets  to
	      the  specified number. IPv4 packets will have the	MSS value low-
	      ered to mssfix - 40 and IPv6 packets to mssfix - 60.

	      if --mssfix is specified is specified without any	 parameter  it
	      inherits	the  parameters	of --fragment if specified or uses the
	      default for --mssfix otherwise.

	      The --mssfix option only makes sense when	you are	using the  UDP
	      protocol	for  OpenVPN  peer-to-peer communication, i.e. --proto

	      --mssfix and --fragment can  be  ideally	used  together,	 where
	      --mssfix	will try to keep TCP from needing packet fragmentation
	      in the first place, and if big packets come through anyhow (from
	      protocols	 other	than TCP), --fragment will internally fragment

	      --max-packet-size, --fragment, and --mssfix are designed to work
	      around  cases  where Path	MTU discovery is broken	on the network
	      path between OpenVPN peers.

	      The usual	symptom	of such	a breakdown is an  OpenVPN  connection
	      which successfully starts, but then stalls during	active usage.

	      If --fragment and	--mssfix are used together, --mssfix will take
	      its default max parameter	from the --fragment max	option.

	      Therefore, one could lower the maximum UDP packet	size  to  1300
	      (a  good	first try for solving MTU-related connection problems)
	      with the following options:

		 --tun-mtu 1500	--fragment 1300	--mssfix

	      If the max-packet-size size option is used in the	 configuration
	      it will also act as if mssfix size mtu was specified in the con-

       --mtu-disc type
	      Should we	do Path	MTU discovery on TCP/UDP  channel?  Only  sup-
	      ported  on OSes such as Linux that supports the necessary	system
	      call to set.

	      Valid types:

	      no      Never send DF (Don't Fragment) frames

	      maybe   Use per-route hints

	      yes     Always DF	(Don't Fragment)

	      To empirically  measure  MTU  on	connection  startup,  add  the
	      --mtu-test  option to your configuration.	OpenVPN	will send ping
	      packets of various sizes to the  remote  peer  and  measure  the
	      largest packets which were successfully received.	The --mtu-test
	      process normally takes about 3 minutes to	complete.

	      Do not bind to local address and port. The IP stack  will	 allo-
	      cate  a  dynamic	port for returning packets. Since the value of
	      the dynamic port could not be known in advance by	a  peer,  this
	      option  is only suitable for peers which will be initiating con-
	      nections by using	the --remote option.

	      Set the TOS field	of the tunnel packet to	what the payload's TOS

       --ping n
	      Ping  remote over	the TCP/UDP control channel if no packets have
	      been sent	for at least n seconds (specify	--ping on  both	 peers
	      to  cause	ping packets to	be sent	in both	directions since Open-
	      VPN ping packets are not echoed like IP ping packets). When used
	      in  one  of OpenVPN's secure modes (where	--secret, --tls-server
	      or --tls-client is specified), the ping packet will  be  crypto-
	      graphically secure.

	      This option has two intended uses:

	      1. Compatibility with stateful firewalls.	The periodic ping will
		 ensure	that a stateful	firewall rule which allows OpenVPN UDP
		 packets to pass will not time out.

	      2. To  provide  a	 basis for the remote to test the existence of
		 its peer using	the --ping-exit	option.

	      When using OpenVPN in server mode	see also --keepalive.

       --ping-exit n
	      Causes OpenVPN to	exit after n seconds pass without reception of
	      a	 ping or other packet from remote. This	option can be combined
	      with --inactive, --ping and --ping-exit to create	 a  two-tiered
	      inactivity disconnect.

	      For example,

		 openvpn [options...] --inactive 3600 --ping 10	--ping-exit 60

	      when  used  on  both  peers will cause OpenVPN to	exit within 60
	      seconds if its peer disconnects, but will	exit after one hour if
	      no actual	tunnel data is exchanged.

       --ping-restart n
	      Similar  to  --ping-exit,	 but trigger a SIGUSR1 restart after n
	      seconds pass without reception of	a ping or  other  packet  from

	      This  option  is useful in cases where the remote	peer has a dy-
	      namic IP address and a low-TTL DNS name is used to track the  IP
	      address  using  a	service	such as + a
	      dynamic DNS client such as ddclient.

	      If the peer cannot be reached,  a	 restart  will	be  triggered,
	      causing  the  hostname  used with	--remote to be re-resolved (if
	      --resolv-retry is	also specified).

	      In server	mode, --ping-restart, --inactive or any	other type  of
	      internally generated signal will always be applied to individual
	      client instance objects, never to	whole server itself. Note also
	      in  server mode that any internally generated signal which would
	      normally cause a restart,	will cause the deletion	of the	client
	      instance object instead.

	      In  client mode, the --ping-restart parameter is set to 120 sec-
	      onds by default. This default will hold until the	client pulls a
	      replacement value	from the server, based on the --keepalive set-
	      ting in the server configuration.	To disable the 120 second  de-
	      fault, set --ping-restart	0 on the client.

	      See the signals section below for	more information on SIGUSR1.

	      Note  that the behavior of SIGUSR1 can be	modified by the	--per-
	      sist-tun,	--persist-key,	--persist-local-ip  and	 --persist-re-
	      mote-ip options.

	      Also  note  that --ping-exit and --ping-restart are mutually ex-
	      clusive and cannot be used together.

	      Run the --ping-exit / --ping-restart timer only if we have a re-
	      mote  address. Use this option if	you are	starting the daemon in
	      listen mode (i.e.	without	an explicit --remote  peer),  and  you
	      don't  want  to start clocking timeouts until a remote peer con-

       --proto p
	      Use protocol p for communicating with remote host. p can be udp,
	      tcp-client,  or  tcp-server.  You	 can also limit	OpenVPN	to use
	      only IPv4	or only	IPv6 by	specifying  p  as  udp4,  tcp4-client,
	      tcp4-server or udp6, tcp6-client,	tcp6-server, respectively.

	      The default protocol is udp when --proto is not specified.

	      For  UDP	operation,  --proto  udp  should  be specified on both

	      For TCP operation, one peer must use --proto tcp-server and  the
	      other   must   use  --proto  tcp-client.	A  peer	 started  with
	      tcp-server will wait indefinitely	for an incoming	connection.  A
	      peer  started  with  tcp-client  will attempt to connect,	and if
	      that fails, will sleep for 5 seconds (adjustable via the	--con-
	      nect-retry  option)  and	try  again infinite or up to N retries
	      (adjustable via the --connect-retry-max option). Both TCP	client
	      and server will simulate a SIGUSR1 restart signal	if either side
	      resets the connection.

	      OpenVPN is designed to operate optimally over UDP, but TCP capa-
	      bility  is  provided for situations where	UDP cannot be used. In
	      comparison with UDP, TCP will usually be somewhat	less efficient
	      and less robust when used	over unreliable	or congested networks.

	      This  article  outlines  some of problems	with tunneling IP over

	      There are	certain	cases, however,	where using TCP	may be	advan-
	      tageous from a security and robustness perspective, such as tun-
	      neling non-IP or application-level UDP protocols,	 or  tunneling
	      protocols	which don't possess a built-in reliability layer.

       --port port
	      TCP/UDP port number or port name for both	local and remote (sets
	      both --lport and --rport options to given	port). The current de-
	      fault  of	 1194 represents the official IANA port	number assign-
	      ment for OpenVPN and has been  used  since  version  2.0-beta17.
	      Previous versions	used port 5000 as the default.

       --rport port
	      Set TCP/UDP port number or name used by the --remote option. The
	      port can also be set directly using the --remote option.

       --replay-window args
	      Modify the replay	protection sliding-window size and  time  win-

	      Valid syntaxes:

		 replay-window n
		 replay-window n t

	      Use a replay protection sliding-window of	size n and a time win-
	      dow of t seconds.

	      By default n is 64 (the IPSec default) and t is 15 seconds.

	      This option is only relevant  in	UDP  mode,  i.e.  when	either
	      --proto udp is specified,	or no --proto option is	specified.

	      When OpenVPN tunnels IP packets over UDP,	there is the possibil-
	      ity that packets might be	dropped	or delivered out of order. Be-
	      cause  OpenVPN,  like  IPSec,  is	emulating the physical network
	      layer, it	will accept an out-of-order packet sequence, and  will
	      deliver such packets in the same order they were received	to the
	      TCP/IP  protocol	stack,	provided  they	satisfy	 several  con-

	      a. The  packet  cannot be	a replay (unless --no-replay is	speci-
		 fied, which disables replay protection	altogether).

	      b. If a packet arrives out of order, it will only	be accepted if
		 the  difference  between  its sequence	number and the highest
		 sequence number received so far is less than n.

	      c. If a packet arrives out of order, it will only	be accepted if
		 it  arrives no	later than t seconds after any packet contain-
		 ing a higher sequence number.

	      If you are using a network link with a large  pipeline  (meaning
	      that the product of bandwidth and	latency	is high), you may want
	      to use a larger value for	n. Satellite links in particular often
	      require this.

	      If  you  run  OpenVPN  at	 --verb	 4,  you  will see the message
	      "PID_ERR replay-window backtrack occurred	[x]"  every  time  the
	      maximum  sequence	number backtrack seen thus far increases. This
	      can be used to calibrate n.

	      There is some controversy	on the appropriate method of  handling
	      packet reordering	at the security	layer.

	      Namely, to what extent should the	security layer protect the en-
	      capsulated protocol from attacks which masquerade	as  the	 kinds
	      of  normal  packet  loss	and reordering that occur over IP net-

	      The IPSec	and OpenVPN approach is	 to  allow  packet  reordering
	      within a certain fixed sequence number window.

	      OpenVPN  adds  to	the IPSec model	by limiting the	window size in
	      time as well as sequence space.

	      OpenVPN also adds	TCP transport as an  option  (not  offered  by
	      IPSec)  in  which	 case OpenVPN can adopt	a very strict attitude
	      towards message deletion and reordering: Don't allow  it.	 Since
	      TCP  guarantees reliability, any packet loss or reordering event
	      can be assumed to	be an attack.

	      In this sense, it	could be argued	that TCP tunnel	 transport  is
	      preferred	 when  tunneling  non-IP  or UDP application protocols
	      which might be vulnerable	to a message  deletion	or  reordering
	      attack  which  falls within the normal operational parameters of
	      IP networks.

	      So I would make the statement that one  should  never  tunnel  a
	      non-IP  protocol	or  UDP	 application protocol over UDP,	if the
	      protocol might be	vulnerable to a	message	deletion or reordering
	      attack that falls	within the normal operating parameters of what
	      is to be expected	from the physical IP  layer.  The  problem  is
	      easily fixed by simply using TCP as the VPN transport layer.

       --replay-persist	file
	      Persist  replay-protection  state	 across	sessions using file to
	      save and reload the state.

	      This option will keep a disk copy	of the current replay  protec-
	      tion  state  (i.e. the most recent packet	timestamp and sequence
	      number received from the remote peer), so	 that  if  an  OpenVPN
	      session  is stopped and restarted, it will reject	any replays of
	      packets which were already received by the prior session.

	      This option only makes sense when	replay protection  is  enabled
	      (the  default)  and you are using	either --secret	(shared-secret
	      key mode)	or TLS mode with --tls-auth.

       --session-timeout n
	      Raises SIGTERM for the client instance after n seconds since the
	      beginning	 of  the  session,  forcing OpenVPN to disconnect.  In
	      client mode, OpenVPN will	disconnect and exit, while  in	server
	      mode all client sessions are terminated.

	      This  option  can	 also be specified in a	client instance	config
	      file using --client-config-dir or	dynamically generated using  a
	      --client-connect script. In these	cases, only the	related	client
	      session is terminated.

       --socket-flags flags
	      Apply the	given flags to	the  OpenVPN  transport	 socket.  Cur-
	      rently, only TCP_NODELAY is supported.

	      The  TCP_NODELAY	socket	flag is	useful in TCP mode, and	causes
	      the kernel to send tunnel	packets	immediately over the TCP  con-
	      nection  without	trying to group	several	smaller	packets	into a
	      larger packet.  This can result in a considerably	improvement in

	      This  option  is	pushable  from server to client, and should be
	      used on both client and server for maximum effect.

	      This macro sets the TCP_NODELAY socket flag  on  the  server  as
	      well  as	pushes	it to connecting clients. The TCP_NODELAY flag
	      disables the Nagle algorithm on TCP sockets causing  packets  to
	      be transmitted immediately with low latency, rather than waiting
	      a	short period of	time in	order  to  aggregate  several  packets
	      into  a larger containing	packet.	 In VPN	applications over TCP,
	      TCP_NODELAY is generally a good latency optimization.

	      The macro	expands	as follows:

		 if mode server:
		     socket-flags TCP_NODELAY
		     push "socket-flags	TCP_NODELAY"

       --max-packet-size size
	      This option will instruct	OpenVPN	to try to  limit  the  maximum
	      on-write	packet	size by	restricting the	control	channel	packet
	      size and setting --mssfix.

	      OpenVPN will try to keep its control channel messages below this
	      size but due to some constraints in the protocol this is not al-
	      ways possible. If	the option is not set, the control packet max-
	      imum  size  defaults  to	1250.  The control channel packet size
	      will be restricted to values between 154 and 2048.  The  maximum
	      packet size includes encapsulation overhead like UDP and IP.

	      In terms of --mssfix it will expand to:

		 mssfix	size mtu

	      If you need to set --mssfix for data channel and control channel
	      maximum packet size independently, use --max-packet-size	first,
	      followed by a --mssfix in	the configuration.

	      In  general  the default size of 1250 should work	almost univer-
	      sally apart from specific	corner cases,  especially  since  IPv6
	      requires a MTU of	1280 or	larger.

   Virtual Network Adapter (VPN	interface)
       Options in this section relates to configuration	of the virtual tun/tap
       network interface, including setting the	VPN  IP	 address  and  network

       --bind-dev device
	      (Linux  only)  Set device	to bind	the server socket to a Virtual
	      Routing and Forwarding device

	      On the client, instead of	sending	IPv6 packets over the VPN tun-
	      nel,  all	IPv6 packets are answered with an ICMPv6 no route host
	      message. On the server, all IPv6 packets from  clients  are  an-
	      swered  with an ICMPv6 no	route to host message. This options is
	      intended for cases when IPv6 should be blocked and other options
	      are  not	available.  --block-ipv6  will	use the	remote IPv6 as
	      source address of	the ICMPv6 packets if set, otherwise will  use
	      fe80::7 as source	address.

	      For this option to make sense you	actually have to route traffic
	      to the tun interface. The	following example config  block	 would
	      send all IPv6 traffic to OpenVPN and answer all requests with no
	      route to host, effectively blocking IPv6 (to avoid IPv6  connec-
	      tions  from  dual-stacked	 clients  leaking around IPv4-only VPN

	      Client config

			--ifconfig-ipv6	fd15:53b6:dead::2/64 fd15:53b6:dead::1
			--redirect-gateway ipv6

	      Server config
		     Push a "valid" ipv6 config	to the client and block	on the

			--push "ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1"
			--push "redirect-gateway ipv6"

	      Note:  this  option  does	 not  influence	 traffic sent from the
	      server towards the client	(neither on  the  server  nor  on  the
	      client  side).   This  is	not seen as necessary, as such traffic
	      can be most easily avoided by not	configuring IPv6 on the	server
	      tun, or setting up a server-side firewall	rule.

       --dev device
	      TUN/TAP  virtual network device which can	be tunX, tapX, null or
	      an arbitrary name	string (X can be omitted  for  a  dynamic  de-

	      See  examples  section  below for	an example on setting up a TUN

	      You must use either tun devices on both ends of  the  connection
	      or tap devices on	both ends. You cannot mix them,	as they	repre-
	      sent different underlying	network	layers:

	      tun    devices encapsulate IPv4 or IPv6 (OSI Layer 3)

	      tap    devices encapsulate Ethernet 802.3	(OSI Layer 2).

	      Valid syntaxes:

		 dev tun2
		 dev tap4
		 dev ovpn

	      What happens if the device name is not tun or  tap  is  platform

	      On  most platforms, tunN (e.g. tun2, tun30) and tapN (e.g. tap3)
	      will create a numbered tun/tap interface with the	number	speci-
	      fied  - this is useful if	multiple OpenVPN instances are active,
	      and the instance-to-device mapping  needs	 to  be	 known.	  Some
	      platforms	 do  not  support "numbered tap", so trying --dev tap3
	      will fail.

	      Arbitrary	device names (e.g. --dev tun-home) will	only  work  on
	      FreeBSD  (with  the DCO kernel driver for	tun devices) and Linux
	      (for both	tun and	tap devices, DCO and tun/tap driver).

	      If such a	device name starts with	tun or	tap  (e.g.  tun-home),
	      OpenVPN will choose the right device type	automatically.	Other-
	      wise  the	 desired  device  type	needs  to  be  specified  with
	      --dev-type tun or	--dev-type tap.

	      On Windows, only the names tun and tap are supported.  Selection
	      among multiple installed drivers or  driver  instances  is  done
	      with --dev-node and --windows-driver.

       --dev-node node
	      This  is	a  highly system dependent option to influence tun/tap
	      driver selection.

	      On Linux,	tun/tap	devices	are created by accessing /dev/net/tun,
	      and this device name can be changed using	--dev-node ....

	      Under  Mac  OS  X	this option can	be used	to specify the default
	      tun implementation. Using	--dev-node utun	forces	usage  of  the
	      native Darwin tun	kernel support.	Use --dev-node utunN to	select
	      a	 specific  utun	 instance.  To	force	using	the   tun.kext
	      (/dev/tunX) use --dev-node tun. When not specifying a --dev-node
	      option openvpn will first	try to open utun,  and	fall  back  to

	      On  Windows systems, select the TAP-Win32	adapter	which is named
	      node in the Network Connections Control Panel or the raw GUID of
	      the adapter enclosed by braces. The --show-adapters option under
	      Windows can also be used to enumerate  all  available  TAP-Win32
	      adapters	and  will  show	 both  the network connections control
	      panel name and the GUID for each TAP-Win32 adapter.

	      On other platforms, --dev-node node will influence the naming of
	      the  created  tun/tap device, if supported on that platform.  If
	      OpenVPN cannot figure out	whether	node is	a TUN  or  TAP	device
	      based  on	 the  name,  you should	also specify --dev-type	tun or
	      --dev-type tap.

       --dev-type device-type
	      Which device type	are we using? device-type should be  tun  (OSI
	      Layer  3)	 or  tap  (OSI	Layer  2). Use this option only	if the
	      TUN/TAP device used with --dev does not begin with tun or	tap.

       --dhcp-option args
	      Set additional network parameters	on supported platforms.	May be
	      specified	 on  the  client or pushed from	the server. On Windows
	      these options are	handled	by the tap-windows6 driver by  default
	      or  directly by OpenVPN if dhcp is disabled or the wintun	driver
	      is in use. The OpenVPN for Android client	also handles them  in-

	      On  all  other  platforms	 these	options	 are only saved	in the
	      client's environment under the  name  foreign_option_{n}	before
	      the  --up	 script	 is called. A plugin or	an --up	script must be
	      used to pick up and interpret these as required. Many Linux dis-
	      tributions include such scripts and some third-party user	inter-
	      faces such as tunnelblick	also come with	scripts	 that  process
	      these options.

	      Valid syntax:

		 dhcp-options type [parm]

	      DOMAIN name
		     Set Connection-specific DNS Suffix	to name.

		     Alias  to	DOMAIN.	 This  is  a  compatibility option, it
		     should not	be used	in new deployments.

	      DOMAIN-SEARCH name
		     Add name to the domain search list.  Repeat  this	option
		     to	add more entries. Up to	10 domains are supported.

	      DNS address
		     Set primary domain	name server IPv4 or IPv6 address.  Re-
		     peat this option to set secondary DNS server addresses.

		     Note: DNS IPv6 servers are	currently set using netsh (the
		     existing DHCP code	can only do IPv4 DHCP, and that	proto-
		     col only permits IPv4  addresses  anywhere).  The	option
		     will be put into the environment, so an --up script could
		     act upon it if needed.

	      WINS address
		     Set primary WINS server address (NetBIOS over TCP/IP Name
		     Server).  Repeat this option to set secondary WINS	server

	      NBDD address
		     Set primary NBDD  server  address	(NetBIOS  over	TCP/IP
		     Datagram  Distribution Server). Repeat this option	to set
		     secondary NBDD server addresses.

	      NTP address
		     Set primary NTP server address (Network  Time  Protocol).
		     Repeat this option	to set secondary NTP server addresses.

	      NBT type
		     Set NetBIOS over TCP/IP Node type.	Possible options:

		     1	    b-node (broadcasts)

		     2	    p-node  (point-to-point  name  queries  to	a WINS

		     4	    m-node (broadcast then query name server)

		     8	    h-node (query name server, then broadcast).

	      NBS scope-id
		     Set NetBIOS over TCP/IP Scope. A NetBIOS  Scope  ID  pro-
		     vides  an	extended  naming  service for the NetBIOS over
		     TCP/IP (Known as NBT) module. The primary	purpose	 of  a
		     NetBIOS  scope ID is to isolate NetBIOS traffic on	a sin-
		     gle network to only those nodes  with  the	 same  NetBIOS
		     scope ID. The NetBIOS scope ID is a character string that
		     is	appended to the	NetBIOS	name. The NetBIOS scope	ID  on
		     two  hosts	 must match, or	the two	hosts will not be able
		     to	communicate.  The NetBIOS Scope	ID also	allows comput-
		     ers to use	the same computer name,	as they	have different
		     scope IDs.	The Scope ID becomes a	part  of  the  NetBIOS
		     name,  making  the	name unique. (This description of Net-
		     BIOS scopes courtesy of

		     Disable Netbios-over-TCP/IP.

	      code   PROXY_HTTP	host port Sets a HTTP  proxy  that  should  be
		     used when connected to the	VPN.

		     This  option  currently only works	on OpenVPN for Android
		     and requires Android 10 or	later.

       --ifconfig args
	      Set TUN/TAP adapter parameters. It requires the  IP  address  of
	      the  local VPN endpoint. For TUN devices in point-to-point mode,
	      the next argument	must be	the VPN	IP address of the  remote  VPN
	      endpoint.	 For  TAP devices, or TUN devices used with --topology
	      subnet, the second argument is the subnet	mask  of  the  virtual
	      network segment which is being created or	connected to.

	      For TUN devices, which facilitate	virtual	point-to-point IP con-
	      nections (when used in --topology	net30 or p2p mode), the	proper
	      usage of --ifconfig is to	use two	private	IP addresses which are
	      not a member of any existing subnet which	is in use. The IP  ad-
	      dresses  may be consecutive and should have their	order reversed
	      on the remote peer.  After the VPN is  established,  by  pinging
	      rn, you will be pinging across the VPN.

	      For  TAP	devices,  which	 provide the ability to	create virtual
	      ethernet segments, or TUN	 devices  in  --topology  subnet  mode
	      (which create virtual "multipoint	networks"), --ifconfig is used
	      to set an	IP address and subnet mask just	as a physical ethernet
	      adapter  would be	similarly configured. If you are attempting to
	      connect to a remote ethernet bridge, the IP address  and	subnet
	      should  be set to	values which would be valid on the the bridged
	      ethernet segment (note also that DHCP can	be used	for  the  same

	      This  option,  while  primarily a	proxy for the ifconfig(8) com-
	      mand, is designed	to simplify TUN/TAP  tunnel  configuration  by
	      providing	 a standard interface to the different ifconfig	imple-
	      mentations on different platforms.

	      --ifconfig parameters which are IP addresses can also be	speci-
	      fied as a	DNS or /etc/hosts file resolvable name.

	      For TAP devices, --ifconfig should not be	used if	the TAP	inter-
	      face will	be getting an IP address lease from a DHCP server.


		 # tun device in net30/p2p mode

		 # tun/tap device in subnet mode

       --ifconfig-ipv6 args
	      Configure	an IPv6	address	on the tun device.

	      Valid syntax:

		 ifconfig-ipv6 ipv6addr/bits [ipv6remote]

	      The ipv6addr/bits	argument is the	IPv6 address to	use. The  sec-
	      ond  parameter  is  used	as route target	for --route-ipv6 if no
	      gateway is specified.

	      The --topology option has	no influence with --ifconfig-ipv6

	      Don't actually execute  ifconfig/netsh  commands,	 instead  pass
	      --ifconfig parameters to scripts using environmental variables.

	      Don't  output  an	options	consistency check warning if the --if-
	      config option on this side of the	connection doesn't  match  the
	      remote side.  This is useful when	you want to retain the overall
	      benefits of the  options	consistency  check  (also  see	--dis-
	      able-occ	option)	while only disabling the ifconfig component of
	      the check.

	      For example, if you have a configuration where  the  local  host
	      uses  --ifconfig	but  the  remote  host	does not, use --ifcon-
	      fig-nowarn on the	local host.

	      This option will also silence warnings about  potential  address
	      conflicts	 which	occasionally  annoy  more experienced users by
	      triggering "false	positive" warnings.

       --lladdr	address
	      Specify the link layer address, more commonly known as  the  MAC
	      address.	Only applied to	TAP devices.

	      Don't  close  and	 reopen	 TUN/TAP device	or run up/down scripts
	      across SIGUSR1 or	--ping-restart restarts.

	      SIGUSR1 is a restart signal similar to SIGHUP, but which	offers
	      finer-grained control over reset options.

       --redirect-gateway flags
	      Automatically  execute routing commands to cause all outgoing IP
	      traffic to be redirected over the	VPN. This is a client-side op-

	      This option performs three steps:

	      1. Create	a static route for the --remote	address	which forwards
		 to the	pre-existing default gateway. This is done so that (3)
		 will not create a routing loop.

	      2. Delete	the default gateway route.

	      3. Set  the  new	default	gateway	to be the VPN endpoint address
		 (derived either from --route-gateway or the second  parameter
		 to --ifconfig when --dev tun is specified).

	      When  the	 tunnel	 is  torn down,	all of the above steps are re-
	      versed so	that the original default route	is restored.

	      Option flags:

	      local  Add the local flag	if both	 OpenVPN  peers	 are  directly
		     connected via a common subnet, such as with wireless. The
		     local flag	will cause step	(1) above to be	omitted.

		     Try to automatically determine whether  to	 enable	 local
		     flag above.

	      def1   Use  this	flag  to override the default gateway by using and rather than This has
		     the benefit of overriding but not wiping out the original
		     default gateway.

		     Add a direct route	to the DHCP server (if it  is  non-lo-
		     cal)  which  bypasses  the	 tunnel	 (Available on Windows
		     clients, may not be available on non-Windows clients).

		     Add a direct route	to the	DNS  server(s)	(if  they  are
		     non-local)	 which	bypasses the tunnel (Available on Win-
		     dows  clients,  may  not  be  available  on   non-Windows

		     Block  access to local LAN	when the tunnel	is active, ex-
		     cept for the LAN gateway itself. This is accomplished  by
		     routing  the  local  LAN  (except for the LAN gateway ad-
		     dress) into the tunnel.

	      ipv6   Redirect IPv6 routing into	the tunnel. This works similar
		     to	 the def1 flag,	that is, more specific IPv6 routes are
		     added (2000::/4, 3000::/4), covering the whole IPv6  uni-
		     cast space.

	      !ipv4  Do	not redirect IPv4 traffic - typically used in the flag
		     pair ipv6 !ipv4 to	redirect IPv6-only.

       --redirect-private flags
	      Like --redirect-gateway, but omit	actually changing the  default
	      gateway.	Useful when pushing private subnets.

       --route args
	      Add route	to routing table after connection is established. Mul-
	      tiple routes can be specified. Routes will be automatically torn
	      down in reverse order prior to TUN/TAP device close.

	      Valid syntaxes:

		 route network/IP
		 route network/IP netmask
		 route network/IP netmask gateway
		 route network/IP netmask gateway metric

	      This  option is intended as a convenience	proxy for the route(8)
	      shell command, while at the same time providing portable	seman-
	      tics across OpenVPN's platform space.

		     defaults to when not given

		     default  taken from --route-gateway or the	second parame-
		     ter to --ifconfig when --dev tun is specified.

	      metric default taken from	--route-metric if set, otherwise 0.

	      The default can be specified by leaving an option	blank or  set-
	      ting it to default.

	      The  network  and	 gateway parameters can	also be	specified as a
	      DNS or /etc/hosts	file resolvable	name, or as one	of three  spe-
	      cial keywords:

		     The  remote  VPN  endpoint	 address  (derived either from
		     --route-gateway or	the  second  parameter	to  --ifconfig
		     when --dev	tun is specified).

		     The  pre-existing IP default gateway, read	from the rout-
		     ing table (not supported on all OSes).

		     The --remote address if OpenVPN is	being  run  in	client
		     mode, and is undefined in server mode.

       --route-delay args
	      Valid syntaxes:

		 route-delay n
		 route-delay n m

	      Delay  n seconds (default	0) after connection establishment, be-
	      fore adding routes. If n is 0, routes will be added  immediately
	      upon  connection	establishment.	If  --route-delay  is omitted,
	      routes will be added immediately after TUN/TAP device  open  and
	      --up  script  execution,	before any --user or --group privilege
	      downgrade	(or --chroot execution.)

	      This option is designed to be useful in scenarios	where DHCP  is
	      used  to set tap adapter addresses. The delay will give the DHCP
	      handshake	time to	complete before	routes are added.

	      On Windows, --route-delay	tries to be more intelligent by	 wait-
	      ing  w seconds (default 30 by default) for the TAP-Win32 adapter
	      to come up before	adding routes.

       --route-ipv6 args
	      Setup IPv6 routing in the	system to send the specified IPv6 net-
	      work into	OpenVPN's tun.

	      Valid syntax:

		 route-ipv6 ipv6addr/bits [gateway] [metric]

	      The  gateway  parameter  is only used for	IPv6 routes across tap
	      devices, and if missing,	the  ipv6remote	 field	from  --ifcon-
	      fig-ipv6 or --route-ipv6-gateway is used.

       --route-gateway arg
	      Specify a	default	gateway	for use	with --route.

	      If  dhcp is specified as the parameter, the gateway address will
	      be  extracted  from  a  DHCP  negotiation	  with	 the   OpenVPN
	      server-side LAN.

	      Valid syntaxes:

		 route-gateway gateway
		 route-gateway dhcp

       --route-ipv6-gateway gw
	      Specify a	default	gateway	gw for use with	--route-ipv6.

       --route-metric m
	      Specify a	default	metric m for use with --route.

	      Don't add	or remove routes automatically.	Instead	pass routes to
	      --route-up script	using environmental variables.

	      When used	with --client or  --pull,  accept  options  pushed  by
	      server  EXCEPT  for  routes,  block-outside-dns and dhcp options
	      like DNS servers.

	      When used	on the client, this option effectively bars the	server
	      from  adding  routes to the client's routing table, however note
	      that this	option still allows the	server to set the TCP/IP prop-
	      erties of	the client's TUN/TAP interface.

       --topology mode
	      Configure	 virtual addressing topology when running in --dev tun
	      mode. This directive has no meaning in --dev tap mode, which al-
	      ways uses	a subnet topology.

	      If  you  set  this  directive  on	 the  server, the --server and
	      --server-bridge directives will automatically push  your	chosen
	      topology	setting	to clients as well. This directive can also be
	      manually pushed to clients. Like the --dev directive,  this  di-
	      rective must always be compatible	between	client and server.

	      mode can be one of:

	      net30  Use a point-to-point topology, by allocating one /30 sub-
		     net per client. This is designed to allow	point-to-point
		     semantics	when  some  or	all  of	the connecting clients
		     might be Windows systems. This is the default on  OpenVPN

	      p2p    Use  a  point-to-point topology where the remote endpoint
		     of	the client's tun interface always points to the	 local
		     endpoint  of  the server's	tun interface. This mode allo-
		     cates a single IP address per connecting client. Only use
		     when none of the connecting clients are Windows systems.

	      subnet Use  a  subnet  rather  than a point-to-point topology by
		     configuring the tun interface with	a local	IP address and
		     subnet  mask,  similar  to	the topology used in --dev tap
		     and ethernet bridging mode. This mode allocates a	single
		     IP	 address per connecting	client and works on Windows as
		     well. Only	available when server and clients are  OpenVPN
		     2.1  or  higher, or OpenVPN 2.0.x which has been manually
		     patched with the --topology directive code. When used  on
		     Windows,  requires	version	8.2 or higher of the TAP-Win32
		     driver. When used on *nix,	requires that the  tun	driver
		     supports  an  ifconfig(8) command which sets a subnet in-
		     stead of a	remote endpoint	IP address.

	      Note: Using --topology subnet changes the	interpretation of  the
	      arguments	 of  --ifconfig	 to  mean "address netmask", no	longer
	      "local remote".

       --tun-mtu args
	      Valid syntaxes:

		 tun-mtu tun-mtu
		 tun-mtu tun-mtu occ-mtu

	      Take the TUN device MTU to be tun-mtu and	derive	the  link  MTU
	      from  it.	  In  most cases, you will probably want to leave this
	      parameter	set to its default value.

	      The default for tun-mtu is 1500.

	      The OCC MTU can be used to avoid warnings	about  mismatched  MTU
	      from clients. If occ-mtu is not specified, it will to default to
	      the tun-mtu.

	      The MTU (Maximum Transmission Units)  is	the  maximum  datagram
	      size  in	bytes  that can	be sent	unfragmented over a particular
	      network path.  OpenVPN requires that packets on the control  and
	      data channels be sent unfragmented.

	      MTU problems often manifest themselves as	connections which hang
	      during periods of	active usage.

	      It's best	to use the --fragment and/or --mssfix options to  deal
	      with MTU sizing issues.

	      Note:  Depending on the platform,	the operating system allows to
	      receive packets larger than tun-mtu (e.g.	Linux and FreeBSD) but
	      other  platforms (like macOS) limit received packets to the same
	      size as the MTU.

       --tun-max-mtu maxmtu
	      This configures the maximum MTU size that	a server can  push  to
	      maxmtu,  by  configuring	the internal buffers to	allow at least
	      this packet size.	 The default for maxmtu	 is  1600.  Currently,
	      only  increasing	beyond 1600 is possible, and attempting	to re-
	      duce max-mtu below 1600 will be ignored.

       --tun-mtu-extra n
	      Assume that the TUN/TAP device might return as many as  n	 bytes
	      more than	the --tun-mtu size on read. This parameter defaults to
	      0, which is sufficient for most TUN devices. TAP devices may in-
	      troduce  additional  overhead  in	 excess	of the MTU size, and a
	      setting of 32 is the default when	TAP devices are	used. This pa-
	      rameter  only  controls internal OpenVPN buffer sizing, so there
	      is no transmission  overhead  associated	with  using  a	larger

   TUN/TAP standalone operations
       These  two  standalone  operations  will	 require  --dev	and optionally
       --user and/or --group.

	      (Standalone) Create a persistent tunnel on platforms which  sup-
	      port them	such as	Linux. Normally	TUN/TAP	tunnels	exist only for
	      the period of time that an application has them open.  This  op-
	      tion  takes  advantage  of the TUN/TAP driver's ability to build
	      persistent tunnels that live through multiple instantiations  of
	      OpenVPN and die only when	they are deleted or the	machine	is re-

	      One of the advantages of persistent tunnels is that they	elimi-
	      nate  the	 need  for separate --up and --down scripts to run the
	      appropriate ifconfig(8) and route(8)  commands.  These  commands
	      can  be placed in	the the	same shell script which	starts or ter-
	      minates an OpenVPN session.

	      Another  advantage  is  that  open   connections	 through   the
	      TUN/TAP-based  tunnel  will  not	be  reset  if the OpenVPN peer
	      restarts.	This can be useful to provide uninterrupted connectiv-
	      ity  through  the	 tunnel	 in  the  event	of a DHCP reset	of the
	      peer's public IP address (see the	--ipchange option above).

	      One disadvantage of persistent tunnels is	that it	is  harder  to
	      automatically  configure	their  MTU  value  (see	--link-mtu and
	      --tun-mtu	above).

	      On some platforms	such as	Windows, TAP-Win32 tunnels are persis-
	      tent by default.

	      (Standalone) Remove a persistent tunnel.

   Virtual Routing and Forwarding
       Options in this section relates to configuration	of virtual routing and
       forwarding in combination with the underlying operating system.

       As of today this	is only	supported on Linux, a kernel >=	4.9 is	recom-

       This  could  come in handy when for example the external	network	should
       be only used as a means to connect to some VPN endpoints	and all	 regu-
       lar traffic should only be routed through any tunnel(s).	 This could be
       achieved	by setting up a	VRF and	configuring the	interface connected to
       the  external  network  to  be part of the VRF. The examples below will
       cover this setup.

       Another option would be to put the tun/tap interface into a  VRF.  This
       could  be done by an up-script which uses the ip	link set command shown

   VRF setup with iproute2
       Create VRF vrf_external and map it to routing table 1023

	  ip link add vrf_external type	vrf table 1023

       Move eth0 into vrf_external

	  ip link set master vrf_external dev eth0

       Any prefixes configured on eth0 will  be	 moved	from  the  :code`main`
       routing table into routing table	1023

   VRF setup with ifupdown
       For Debian based	Distributions ifupdown2	provides an almost drop-in re-
       placement for ifupdown including	VRFs and other features.  A configura-
       tion  for  an  interface	eth0 being part	of VRF code:vrf_external could
       look like this:

	  auto eth0
	  iface	eth0
	      address 2001:db8:08:15::42/64
	      gateway 2001:db8:08:15::1
	      vrf vrf_external

	  auto vrf_external
	  iface	vrf_external
	      vrf-table	1023

   OpenVPN configuration
       The OpenVPN configuration needs to contain this line:

	  bind-dev vrf_external

   Further reading
       Wikipedia	has	   nice		page	     one	 VRFs:

       This  talk  from	the Network Track of FrOSCon 2018 provides an overview
       about advanced layer 2 and layer	3 features of Linux

	  o Slides:

	  o Video						     (german):

       OpenVPN can execute external scripts in various phases of the  lifetime
       of the OpenVPN process.

   Script Order	of Execution
       1.  --up

	   Executed after TCP/UDP socket bind and TUN/TAP open.

       2.  --tls-verify

	   Executed when we have a still untrusted remote peer.

       3.  --ipchange

	   Executed  after  connection	authentication,	 or  remote IP address

       4.  --client-connect

	   Executed in --mode server mode immediately after client authentica-

       5.  --route-up

	   Executed after connection authentication, either immediately	after,
	   or some number of seconds after as defined by the --route-delay op-

       6.  --route-pre-down

	   Executed right before the routes are	removed.

       7.  --client-disconnect

	   Executed in --mode server mode on client instance shutdown.

       8.  --down

	   Executed after TCP/UDP and TUN/TAP close.

       9.  --learn-address

	   Executed  in	 --mode	 server	mode whenever an IPv4 address/route or
	   MAC address is added	to OpenVPN's internal routing table.

       10. --auth-user-pass-verify

	   Executed in --mode server mode on new client	connections, when  the
	   client is still untrusted.

       11. --client-crresponse
	      Execute  in  --mode server whenever a client sends a CR_RESPONSE

       --auth-user-pass-verify args
	      Require the client to provide a username/password	 (possibly  in
	      addition to a client certificate)	for authentication.

	      Valid syntax:

		 auth-user-pass-verify cmd method

	      OpenVPN  will  run command cmd to	validate the username/password
	      provided by the client.

	      cmd consists of a	path to	a script (or executable	program),  op-
	      tionally	followed  by  arguments. The path and arguments	may be
	      single- or double-quoted and/or escaped using a  backslash,  and
	      should be	separated by one or more spaces.

	      If  method is set	to via-env, OpenVPN will call cmd with the en-
	      vironmental variables username and password  set	to  the	 user-
	      name/password  strings  provided by the client. Beware that this
	      method is	insecure on some platforms which make the  environment
	      of a process publicly visible to other unprivileged processes.

	      If  method  is  set to via-file, OpenVPN will write the username
	      and password to the first	two lines of  a	 temporary  file.  The
	      filename will be passed as an argument to	cmd, and the file will
	      be automatically deleted by OpenVPN after	 the  script  returns.
	      The  location  of	 the  temporary	 file  is  controlled  by  the
	      --tmp-dir	option,	and will default to the	current	 directory  if
	      unspecified.  For	 security,  consider  setting  --tmp-dir  to a
	      volatile storage medium such as /dev/shm (if available) to  pre-
	      vent the username/password file from touching the	hard drive.

	      The script should	examine	the username and password, returning a
	      success exit code	(0) if the client's authentication request  is
	      to  be  accepted,	 a failure code	(1) to reject the client, or a
	      that the authentication is deferred (2). If  the	authentication
	      is  deferred, the	script must fork/start a background or another
	      non-blocking operation to	continue  the  authentication  in  the
	      background.  When	 finshing the authentication, a	1 or 0 must be
	      written to the file specified by the auth_control_file.

	      If the file specified by auth_failed_reason_file exists and  has
	      non-empty	 content,  the	content	 of  this file will be used as
	      AUTH_FAILED message. To avoid race conditions, this file	should
	      be written before	auth_control_file.

	      This  auth  fail	reason	can be something simple	like "User has
	      been permanently disabled" but there are also some special  auth
	      failed messages.

	      The  TEMP	 message indicates that	the authentication temporarily
	      failed and that the client should	continue to retry to  connect.
	      The  server can optionally give a	user readable message and hint
	      the client a behavior  how  to  proceed.	The  keywords  of  the
	      AUTH_FAILED,TEMP	message	 are  comma  separated keys/values and
	      provide a	hint to	the client how to proceed.  Currently  defined
	      keywords are:

	      backoff s
		     instructs	the  client  to	wait at	least s	seconds	before
		     the next connection attempt. If the client	already	uses a
		     higher delay for reconnection attempt, the	delay will not
		     be	shortened.

	      advance addr
		     Instructs the client to reconnect to the  next  (IP)  ad-
		     dress of the current server.

	      advance remote
		     Instructs	the  client to skip the	remaining IP addresses
		     of	the current server and instead	connect	 to  the  next
		     server specified in the configuration file.

	      advance no
		     Instructs	the  client  to	 retry	connecting to the same
		     server again.

	      For example, the message TEMP[backoff 42,advance no]: No free IP
	      addresses	 indicates  that  the VPN connection can currently not
	      succeed and instructs the	client to retry	in 42 seconds again.

	      When deferred authentication is in use, the script can also  re-
	      quest pending authentication by writing to the file specified by
	      the auth_pending_file. The first line must  be  the  timeout  in
	      seconds,	the  required  method on the second line (e.g. crtext)
	      and  third  line	must  be  the  EXTRA  as  documented  in   the
	      client-pending-auth section of doc/management.txt.

	      This  directive  is  designed to enable a	plugin-style interface
	      for extending OpenVPN's authentication capabilities.

	      To protect against a client passing a maliciously	 formed	 user-
	      name  or	password string, the username string must consist only
	      of these characters: alphanumeric, underbar ('_'),  dash	('-'),
	      dot  ('.'),  or at ('@').	The password string can	consist	of any
	      printable	characters except for CR or LF.	Any illegal characters
	      in  either  the username or password string will be converted to
	      underbar ('_').

	      Care must	be taken by any	user-defined scripts to	avoid creating
	      a	 security vulnerability	in the way that	these strings are han-
	      dled. Never use these strings in such a way that they  might  be
	      escaped or evaluated by a	shell interpreter.

	      For  a  sample script that performs PAM authentication, see sam-
	      ple-scripts/ in the OpenVPN source distribution.

		 Executed when the client sends	a  text	 based	challenge  re-

		 Valid syntax:

		     client-crresponse cmd

	      OpenVPN  will  write the response	of the client into a temporary
	      file.  The filename will be passed as an argument	 to  cmd,  and
	      the  file	 will  be  automatically  deleted by OpenVPN after the
	      script returns.

	      The response is passed as	is from	the client. The	 script	 needs
	      to  check	 itself	 if  the  input	is valid, e.g. if the input is
	      valid base64 encoding.

	      The script can either directly write the result of the verifica-
	      tion   to	  auth_control_file   or   further   defer   it.   See
	      `--auth-user-pass-verify`` for details.

	      For a  sample  script  that  implement  TOTP  (RFC  6238)	 based
	      two-factor authentication, see sample-scripts/

       --client-connect	cmd
	      Run command cmd on client	connection.

	      cmd  consists of a path to a script (or executable program), op-
	      tionally followed	by arguments. The path and  arguments  may  be
	      single-  or  double-quoted and/or	escaped	using a	backslash, and
	      should be	separated by one or more spaces.

	      The command is passed the	common name  and  IP  address  of  the
	      just-authenticated  client as environmental variables (see envi-
	      ronmental	variable section below). The command  is  also	passed
	      the pathname of a	freshly	created	temporary file as the last ar-
	      gument (after any	arguments specified in cmd ), to  be  used  by
	      the command to pass dynamically generated	config file directives
	      back to OpenVPN.

	      If the script wants to generate a	dynamic	config file to be  ap-
	      plied on the server when the client connects, it should write it
	      to the file named	by the last argument.

	      See the --client-config-dir option below for options  which  can
	      be legally used in a dynamically generated config	file.

	      Note  that  the return value of script is	significant. If	script
	      returns a	non-zero error status, it will cause the client	to  be

	      If  a --client-connect wants to defer the	generating of the con-
	      figuration then the script needs to use  the  client_connect_de-
	      ferred_file  and	client_connect_config_file  environment	 vari-
	      ables, and write status accordingly into these files.   See  the
	      Environmental Variables section for more details.

       --client-disconnect cmd
	      Like  --client-connect  but  called on client instance shutdown.
	      Will not be called unless	the --client-connect script and	 plug-
	      ins  (if	defined)  were previously called on this instance with
	      successful (0) status returns.

	      The exception to this rule is if the --client-disconnect command
	      or  plugins  are cascaded, and at	least one client-connect func-
	      tion succeeded, then ALL of the client-disconnect	functions  for
	      scripts  and  plugins  will  be called on	client instance	object
	      deletion,	even in	cases where some of the	related	client-connect
	      functions	returned an error status.

	      The  --client-disconnect	command	 is not	passed any extra argu-
	      ments (only those	arguments specified in cmd, if any).

       --down cmd
	      Run command cmd after TUN/TAP  device  close  (post  --user  UID
	      change  and/or  --chroot ). cmd consists of a path to script (or
	      executable program), optionally followed by arguments. The  path
	      and arguments may	be single- or double-quoted and/or escaped us-
	      ing a backslash, and should be separated by one or more spaces.

	      Called with the same parameters and environmental	 variables  as
	      the --up option above.

	      Note  that  if  you  reduce  privileges  by  using --user	and/or
	      --group, your --down script will also run	at reduced privilege.

	      Call --down cmd/script before, rather than after,	TUN/TAP	close.

       --ipchange cmd
	      Run command cmd when our remote ip-address is initially  authen-
	      ticated or changes.

	      cmd  consists of a path to a script (or executable program), op-
	      tionally followed	by arguments. The path and  arguments  may  be
	      single-  or  double-quoted and/or	escaped	using a	backslash, and
	      should be	separated by one or more spaces.

	      When cmd is executed two arguments are appended after any	 argu-
	      ments specified in cmd , as follows:

		 cmd ip	address	port number

	      Don't  use --ipchange in --mode server mode. Use a --client-con-
	      nect script instead.

	      See the Environmental Variables section below for	additional pa-
	      rameters passed as environmental variables.

	      If you are running in a dynamic IP address environment where the
	      IP addresses of either peer could	change without notice, you can
	      use  this	 script, for example, to edit the /etc/hosts file with
	      the current address of the peer. The script will	be  run	 every
	      time the remote peer changes its IP address.

	      Similarly	 if our	IP address changes due to DHCP,	we should con-
	      figure our IP address change script (see man page	for dhcpcd(8))
	      to  deliver  a SIGHUP or SIGUSR1 signal to OpenVPN. OpenVPN will
	      then re-establish	a connection with its most recently  authenti-
	      cated peer on its	new IP address.

       --learn-address cmd
	      Run command cmd to validate client virtual addresses or routes.

	      cmd  consists of a path to a script (or executable program), op-
	      tionally followed	by arguments. The path and  arguments  may  be
	      single-  or  double-quoted and/or	escaped	using a	backslash, and
	      should be	separated by one or more spaces.

	      Three arguments will be appended to any arguments	in cmd as fol-

	      $1 - [operation]
		     "add",  "update", or "delete" based on whether or not the
		     address is	being added  to,  modified,  or	 deleted  from
		     OpenVPN's internal	routing	table.

	      $2 - [address]
		     The  address  being  learned or unlearned.	This can be an
		     IPv4 address such as "", an IPv4 subnet such
		     as	 "",  or	 an ethernet MAC address (when
		     --dev tap is being	used) such as "00:FF:01:02:03:04".

	      $3 - [common name]
		     The common	name on	the certificate	 associated  with  the
		     client  linked to this address. Only present for "add" or
		     "update" operations, not "delete".

	      On "add" or "update" methods, if the script  returns  a  failure
	      code  (non-zero),	 OpenVPN  will reject the address and will not
	      modify its internal routing table.

	      Normally,	the cmd	script will use	the information	provided above
	      to  set  appropriate  firewall entries on	the VPN	TUN/TAP	inter-
	      face. Since OpenVPN provides the association between virtual  IP
	      or  MAC  address	and the	client's authenticated common name, it
	      allows a user-defined script to configure	firewall access	 poli-
	      cies  with regard	to the client's	high-level common name,	rather
	      than the low level client	virtual	addresses.

       --route-up cmd
	      Run command cmd after routes are added, subject  to  --route-de-

	      cmd  consists of a path to a script (or executable program), op-
	      tionally followed	by arguments. The path and  arguments  may  be
	      single-  or  double-quoted and/or	escaped	using a	backslash, and
	      should be	separated by one or more spaces.

	      See the Environmental Variables section below for	additional pa-
	      rameters passed as environmental variables.

       --route-pre-down	cmd
	      Run command cmd before routes are	removed	upon disconnection.

	      cmd  consists of a path to a script (or executable program), op-
	      tionally followed	by arguments. The path and  arguments  may  be
	      single-  or  double-quoted and/or	escaped	using a	backslash, and
	      should be	separated by one or more spaces.

	      See the Environmental Variables section below for	additional pa-
	      rameters passed as environmental variables.

       --setenv	args
	      Set  a  custom  environmental  variable  name=value  to  pass to

	      Valid syntaxes:

		 setenv	name value
		 setenv	opt config_option

	      By setting FORWARD_COMPATIBLE  to	 1,  the  config  file	syntax
	      checking	is  relaxed  so	that unknown directives	will trigger a
	      warning but not a	fatal error, on	the assumption	that  a	 given
	      unknown directive	might be valid in future OpenVPN versions.

	      This option should be used with caution, as there	are good secu-
	      rity reasons for having OpenVPN fail if it detects problems in a
	      config  file.   Having  said  that,  there are valid reasons for
	      wanting new software features to gracefully degrade when encoun-
	      tered by older software versions.

	      It is also possible to tag a single directive so as not to trig-
	      ger a fatal error	if the directive isn't recognized. To do this,
	      prepend the following before the directive: setenv opt

	      Versions	prior  to OpenVPN 2.3.3	will always ignore options set
	      with the setenv opt directive.

	      See also --ignore-unknown-option

       --setenv-safe args
	      Set a custom environmental variable  OPENVPN_name	 to  value  to
	      pass to scripts.

	      Valid syntaxes:

		 setenv-safe name value

	      This  directive  is  designed  to	 be  pushed  by	 the server to
	      clients, and the prepending of  OPENVPN_	to  the	 environmental
	      variable	is  a  safety precaution to prevent a LD_PRELOAD style
	      attack from a malicious or compromised server.

       --tls-verify cmd
	      Run command cmd to verify	the X509 name of a pending TLS connec-
	      tion  that has otherwise passed all other	tests of certification
	      (except for revocation via --crl-verify directive;  the  revoca-
	      tion test	occurs after the --tls-verify test).

	      cmd  should return 0 to allow the	TLS handshake to proceed, or 1
	      to fail.

	      cmd consists of a	path to	a script (or executable	program),  op-
	      tionally	followed  by  arguments. The path and arguments	may be
	      single- or double-quoted and/or escaped using a  backslash,  and
	      should be	separated by one or more spaces.

	      When  cmd	is executed two	arguments are appended after any argu-
	      ments specified in cmd, as follows:

		 cmd certificate_depth subject

	      These arguments are, respectively, the current certificate depth
	      and the X509 subject distinguished name (dn) of the peer.

	      This  feature is useful if the peer you want to trust has	a cer-
	      tificate which was signed	by a certificate  authority  who  also
	      signed many other	certificates, where you	don't necessarily want
	      to trust all of them, but	rather be selective about  which  peer
	      certificate  you will accept. This feature allows	you to write a
	      script which will	test the X509 name on a	certificate and	decide
	      whether  or  not it should be accepted. For a simple perl	script
	      which will test the common name field on	the  certificate,  see
	      the file verify-cn in the	OpenVPN	distribution.

	      See the Environmental Variables section below for	additional pa-
	      rameters passed as environmental variables.

       --up cmd
	      Run command cmd after successful TUN/TAP device open (pre	--user
	      UID change).

	      cmd  consists of a path to a script (or executable program), op-
	      tionally followed	by arguments. The path and  arguments  may  be
	      single-  or  double-quoted and/or	escaped	using a	backslash, and
	      should be	separated by one or more spaces.

	      The up command is	useful for  specifying	route  commands	 which
	      route IP traffic destined	for private subnets which exist	at the
	      other end	of the VPN connection into the tunnel.

	      For --dev	tun execute as:

		 cmd tun_dev tun_mtu 0 ifconfig_local_ip ifconfig_remote_ip [init | restart]

	      For --dev	tap execute as:

		 cmd tap_dev tap_mtu 0 ifconfig_local_ip ifconfig_netmask [init	| restart]

	      See the Environmental Variables section below for	additional pa-
	      rameters passed as environmental variables.  The 0 argument used
	      to be link_mtu which is no longer	passed to scripts  -  to  keep
	      the argument order, it was replaced with 0.

	      Note that	if cmd includes	arguments, all OpenVPN-generated argu-
	      ments will be appended to	them to	build an  argument  list  with
	      which the	executable will	be called.

	      Typically, cmd will run a	script to add routes to	the tunnel.

	      Normally	the  up	 script	 is called after the TUN/TAP device is
	      opened. In this context, the last	command	line parameter	passed
	      to  the  script will be init. If the --up-restart	option is also
	      used, the	up script will be  called  for	restarts  as  well.  A
	      restart  is considered to	be a partial reinitialization of Open-
	      VPN where	the TUN/TAP instance is	preserved  (the	 --persist-tun
	      option  will enable such preservation).  A restart can be	gener-
	      ated by a	SIGUSR1	signal,	a --ping-restart timeout, or a connec-
	      tion reset when the TCP protocol is enabled with the --proto op-
	      tion. If a restart occurs, and --up-restart has been  specified,
	      the up script will be called with	restart	as the last parameter.

	      NOTE:  On	 restart,  OpenVPN will	not pass the full set of envi-
		     ronment variables to the script. Namely,  everything  re-
		     lated  to	routing	 and  gateways	will not be passed, as
		     nothing needs to be done anyway - all the	routing	 setup
		     is	 already in place. Additionally, the up-restart	script
		     will run with the downgraded UID/GID settings (if config-

	      The  following  standalone example shows how the --up script can
	      be called	in both	an initialization and restart context.	(NOTE:
	      for security reasons, don't run the following example unless UDP
	      port 9999	is blocked by your firewall. Also,  the	 example  will
	      run indefinitely,	so you should abort with control-c).

		 openvpn --dev tun --port 9999 --verb 4	--ping-restart 10 \
			 --up 'echo up'	--down 'echo down' --persist-tun  \

	      Note  that  OpenVPN also provides	the --ifconfig option to auto-
	      matically	ifconfig the TUN device, eliminating the need  to  de-
	      fine an --up script, unless you also want	to configure routes in
	      the --up script.

	      If --ifconfig is also specified, OpenVPN will pass the  ifconfig
	      local  and  remote  endpoints  on	 the  command line to the --up
	      script so	that they can be used to configure routes such as:

		 route add -net netmask gw $5

	      Delay TUN/TAP open and possible --up script execution until  af-
	      ter TCP/UDP connection establishment with	peer.

	      In  --proto  udp	mode, this option normally requires the	use of
	      --ping to	allow connection initiation to be sensed  in  the  ab-
	      sence of tunnel data, since UDP is a "connectionless" protocol.

	      On  Windows,  this  option  will delay the TAP-Win32 media state
	      transitioning to	"connected"  until  connection	establishment,
	      i.e.  the	 receipt  of  the  first authenticated packet from the

	      Enable the --up and --down scripts to be called for restarts  as
	      well  as	initial	 program  start. This option is	described more
	      fully above in the --up option documentation.

   String Types	and Remapping
       In certain cases, OpenVPN  will	perform	 remapping  of	characters  in
       strings.	Essentially, any characters outside the	set of permitted char-
       acters for each string type will	be converted to	underbar ('_').

       Q: Why is string	remapping necessary?
	      It's an important	security feature to prevent the	malicious cod-
	      ing of strings from untrusted sources to be passed as parameters
	      to scripts, saved	in the environment, used  as  a	 common	 name,
	      translated to a filename,	etc.

       Q: Can string remapping be disabled?
	      Yes,  by	using  the  --no-name-remapping	 option,  however this
	      should be	considered an advanced option.

       Here is a brief rundown of OpenVPN's current string types and the  per-
       mitted character	class for each string:

       X509 Names
	      Alphanumeric,  underbar  ('_'), dash ('-'), dot ('.'), at	('@'),
	      colon (':'), slash ('/'),	and equal ('='). Alphanumeric  is  de-
	      fined  as	 a  character which will cause the C library isalnum()
	      function to return true.

       Common Names
	      Alphanumeric, underbar ('_'), dash  ('-'),  dot  ('.'),  and  at

       --auth-user-pass	username
	      Same  as	Common Name, with one exception: starting with OpenVPN
	      2.0.1,	the    username	   is	 passed	   to	 the	 OPEN-
	      VPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin in its raw form, without
	      string remapping.

       --auth-user-pass	password
	      Any "printable" character	except CR or LF. Printable is  defined
	      to be a character	which will cause the C library isprint() func-
	      tion to return true.

       --client-config-dir filename as derived from common name	or`username
	      Alphanumeric, underbar ('_'), dash ('-'),	and dot	 ('.')	except
	      for "."  or ".." as standalone strings. As of v2.0.1-rc6,	the at
	      ('@') character has been added as	well  for  compatibility  with
	      the common name character	class.

       Environmental variable names
	      Alphanumeric or underbar ('_').

       Environmental variable values
	      Any printable character.

       For  all	cases, characters in a string which are	not members of the le-
       gal character class for that string type	will be	remapped  to  underbar

   Environmental Variables
       Once  set,  a variable is persisted indefinitely	until it is reset by a
       new value or a restart,

       As of OpenVPN 2.0-beta12, in server mode, environmental	variables  set
       by  OpenVPN are scoped according	to the client objects they are associ-
       ated with, so there should not be any issues with scripts having	access
       to  stale, previously set variables which refer to different client in-

	      Total number of bytes received from client during	 VPN  session.
	      Set prior	to execution of	the --client-disconnect	script.

	      Total  number  of	 bytes	sent to	client during VPN session. Set
	      prior to execution of the	--client-disconnect script.

	      The path to the configuration file that should be	written	to  by
	      the --client-connect script (optional, if	per-session configura-
	      tion is desired).	 This is the same file name as passed via com-
	      mand line	argument on the	call to	the --client-connect script.

	      This  file  can be optionally written to in order	to to communi-
	      cate a status code of  the  --client-connect  script  or	plgin.
	      Only  the	 first	character in the file is relevant.  It must be
	      either 1 to indicate normal script execution, 0 indicates	an er-
	      ror  (in	the same way that a non	zero exit status does) or 2 to
	      indicate that the	script deferred	returning the config file.

	      For deferred (background)	handling, the script  or  plugin  MUST
	      write  2	to  the	 file to indicate the deferral and then	return
	      with exit	code 0 to signal deferred handler started OK.

	      A	background process or similar must then	take care  of  writing
	      the  configuration  to  the  file	 indicated  by the client_con-
	      nect_config_file environment variable and	when  finished,	 write
	      the a 1 to this file (or 0 in case of an error).

	      The  absence  of	any character in the file when the script fin-
	      ishes executing is  interpreted  the  same  as  1.  This	allows
	      scripts  that  are not written to	support	the defer mechanism to
	      be used unmodified.

	      The X509 common name of an authenticated client.	Set  prior  to
	      execution	   of	 --client-connect,   --client-disconnect   and
	      --auth-user-pass-verify scripts.

       config Name of first --config file. Set on program initiation and reset
	      on SIGHUP.

       daemon Set to "1" if the	--daemon directive is specified, or "0"	other-
	      wise.  Set on program initiation and reset on SIGHUP.

	      Set to "1" if the	--log or --log-append  directives  are	speci-
	      fied,  or	 "0" otherwise.	Set on program initiation and reset on

       dev    The actual name of the TUN/TAP device, including a  unit	number
	      if it exists. Set	prior to --up or --down	script execution.

	      On  Windows, the device index of the TUN/TAP adapter (to be used
	      in netsh.exe calls which sometimes just do not work  right  with
	      interface	names).	Set prior to --up or --down script execution.

       dns_*  The --dns	configuration options will be made available to	script
	      execution	through	this set of environment	 variables.  Variables
	      appear  only  if	the corresponding option has a value assigned.
	      For the semantics	of each	individual variable, please  refer  to
	      the documentation	for --dns.


	      An  option pushed	via --push to a	client which does not natively
	      support it, such as --dhcp-option	on a non-Windows system,  will
	      be  recorded  to	this  environmental variable sequence prior to
	      --up script execution.

	      The broadcast address for	the virtual ethernet segment which  is
	      derived  from  the --ifconfig option when	--dev tap is used. Set
	      prior to OpenVPN calling the ifconfig or netsh (windows  version
	      of ifconfig) commands which normally occurs prior	to --up	script

	      The local	VPN endpoint IPv6 address specified  in	 the  --ifcon-
	      fig-ipv6	option (first parameter). Set prior to OpenVPN calling
	      the ifconfig or code:netsh (windows version  of  ifconfig)  com-
	      mands which normally occurs prior	to --up	script execution.

	      The  prefix length of the	IPv6 network on	the VPN	interface. De-
	      rived from the /nnn parameter of the IPv6	address	in  the	 --if-
	      config-ipv6 option (first	parameter). Set	prior to OpenVPN call-
	      ing the ifconfig or netsh	(windows version of ifconfig) commands
	      which normally occurs prior to --up script execution.

	      The  remote  VPN endpoint	IPv6 address specified in the --ifcon-
	      fig-ipv6 option (second parameter). Set prior to OpenVPN calling
	      the  ifconfig  or	 netsh	(windows version of ifconfig) commands
	      which normally occurs prior to --up script execution.

	      The local	VPN endpoint IP	address	specified  in  the  --ifconfig
	      option  (first  parameter). Set prior to OpenVPN calling the if-
	      config or	netsh (windows version	of  ifconfig)  commands	 which
	      normally occurs prior to --up script execution.

	      The  remote  VPN endpoint	IP address specified in	the --ifconfig
	      option (second parameter)	when --dev tun is used.	Set  prior  to
	      OpenVPN calling the ifconfig or netsh (windows version of	ifcon-
	      fig) commands which normally occurs prior	to --up	script	execu-

	      The  subnet  mask	of the virtual ethernet	segment	that is	speci-
	      fied as the second parameter to --ifconfig when --dev tap	is be-
	      ing  used.  Set  prior  to OpenVPN calling the ifconfig or netsh
	      (windows version of ifconfig)  commands  which  normally	occurs
	      prior to --up script execution.

	      The  local  virtual IP address for the TUN/TAP tunnel taken from
	      an --ifconfig-push directive if specified, or otherwise from the
	      ifconfig pool (controlled	by the --ifconfig-pool config file di-
	      rective).	Only set for --dev tun tunnels.	This option is set  on
	      the  server  prior  to  execution	 of  the  --client-connect and
	      --client-disconnect scripts.

	      The virtual IP netmask for the  TUN/TAP  tunnel  taken  from  an
	      --ifconfig-push  directive  if  specified, or otherwise from the
	      ifconfig pool (controlled	by the --ifconfig-pool config file di-
	      rective).	 Only set for --dev tap	tunnels. This option is	set on
	      the server  prior	 to  execution	of  the	 --client-connect  and
	      --client-disconnect scripts.

	      The  remote virtual IP address for the TUN/TAP tunnel taken from
	      an --ifconfig-push directive if specified, or otherwise from the
	      ifconfig pool (controlled	by the --ifconfig-pool config file di-
	      rective).	This option is set on the server prior to execution of
	      the --client-connect and --client-disconnect scripts.

	      No longer	passed to scripts since	OpenVPN	2.6.0.	Used to	be the
	      maximum packet size (not including the IP	header)	of tunnel data
	      in UDP tunnel transport mode.

       local  The  --local  parameter.	Set on program initiation and reset on

	      The local	port number or name, specified by --port  or  --lport.
	      Set on program initiation	and reset on SIGHUP.

	      The  password  provided  by  a  connecting  client. Set prior to
	      --auth-user-pass-verify script execution only when  the  via-env
	      modifier	is  specified,	and deleted from the environment after
	      the script returns.

       proto  The --proto parameter. Set on program initiation	and  reset  on

	      The  --remote  parameter.	Set on program initiation and reset on

	      The remote port number, specified	by --port or --rport.  Set  on
	      program initiation and reset on SIGHUP.

	      The pre-existing default IP gateway in the system	routing	table.
	      Set prior	to --up	script execution.

	      The default gateway used by --route options, as specified	in ei-
	      ther the --route-gateway option or the second parameter to --if-
	      config when --dev	tun is specified. Set prior to --up script ex-

	      A	 set of	variables which	define each route to be	added, and are
	      set prior	to --up	script execution.

	      parm will	be one of network, netmask", gateway, or metric.

	      n	is the OpenVPN route number, starting from 1.

	      If the network or	gateway	are resolvable DNS names, their	IP ad-
	      dress  translations  will	be recorded rather than	their names as
	      denoted on the command line or configuration file.

	      A	set of variables which define each IPv6	route to be added, and
	      are set prior to --up script execution.

	      parm  will be one	of network, gateway or metric. route_ipv6_net-
	      work_{n} contains	netmask	as  /nnn,  unlike  IPv4	 where	it  is
	      passed in	a separate environment variable.

	      n	is the OpenVPN route number, starting from 1.

	      If the network or	gateway	are resolvable DNS names, their	IP ad-
	      dress translations will be recorded rather than their  names  as
	      denoted on the command line or configuration file.

	      Temporary	 file name containing the client certificate upon con-
	      nection.	Useful in conjunction with --tls-verify.

	      Set to "init" or "restart" prior to  up/down  script  execution.
	      For more information, see	documentation for --up.

	      Prior  to	 execution  of any script, this	variable is set	to the
	      type of script being run.	It can be one of  the  following:  up,
	      down,  ipchange,	route-up,  tls-verify,	auth-user-pass-verify,
	      client-connect, client-disconnect	or learn-address. Set prior to
	      execution	of any script.

       signal The  reason  for exit or restart.	Can be one of sigusr1, sighup,
	      sigterm, sigint, inactive	 (controlled  by  --inactive  option),
	      ping-exit	(controlled by --ping-exit option), ping-restart (con-
	      trolled by --ping-restart	option),  connection-reset  (triggered
	      on  TCP  connection  reset),  error or unknown (unknown signal).
	      This variable is set just	prior to down script execution.

	      Client connection	timestamp, formatted as	a human-readable  time
	      string.  Set prior to execution of the --client-connect script.

	      The  duration  (in  seconds)  of the client session which	is now
	      disconnecting. Set prior to execution of the --client-disconnect

	      Client   connection  timestamp,  formatted  as  a	 unix  integer
	      date/time	value. Set prior to execution of the  --client-connect

       tls_digest_{n} /	tls_digest_sha256_{n}
	      Contains	the  certificate SHA1 /	SHA256 fingerprint, where n is
	      the verification level. Only set for TLS connections. Set	 prior
	      to execution of --tls-verify script.

	      A	 series	of certificate fields from the remote peer, where n is
	      the verification level. Only set for TLS connections. Set	 prior
	      to execution of --tls-verify script.

	      The serial number	of the certificate from	the remote peer, where
	      n	is the verification level. Only	set for	TLS  connections.  Set
	      prior  to	 execution of --tls-verify script. This	is in the form
	      of a decimal string like "933971680", which is suitable for  do-
	      ing serial-based OCSP queries (with OpenSSL, do not prepend "0x"
	      to the string) If	something goes wrong while reading  the	 value
	      from  the	 certificate  it will be an empty string, so your code
	      should  check  that.  See	 the  contrib/OCSP_check/
	      script for an example.

	      Like tls_serial_{n}, but in hex form (e.g.  12:34:56:78:9A).

	      The  MTU	of  the	 TUN/TAP  device.  Set prior to	--up or	--down
	      script execution.

       trusted_ip / trusted_ip6)
	      Actual IP	address	of connecting client or	peer  which  has  been
	      authenticated.   Set   prior   to	  execution   of   --ipchange,
	      --client-connect and --client-disconnect scripts.	If using  ipv6
	      endpoints	(udp6, tcp6), trusted_ip6 will be set instead.

	      Actual  port  number of connecting client	or peer	which has been
	      authenticated.   Set   prior   to	  execution   of   --ipchange,
	      --client-connect and --client-disconnect scripts.

       untrusted_ip / untrusted_ip6
	      Actual  IP  address  of  connecting client or peer which has not
	      been authenticated yet. Sometimes	used to	 nmap  the  connecting
	      host  in	a --tls-verify script to ensure	it is firewalled prop-
	      erly.   Set   prior   to	 execution   of	   --tls-verify	   and
	      --auth-user-pass-verify  scripts.	If using ipv6 endpoints	(udp6,
	      tcp6), untrusted_ip6 will	be set instead.

	      Actual port number of connecting client or peer  which  has  not
	      been  authenticated  yet.	Set prior to execution of --tls-verify
	      and --auth-user-pass-verify scripts.

	      The username provided by	a  connecting  client.	Set  prior  to
	      --auth-user-pass-verify  script  execution only when the via-env
	      modifier is specified.

	      An X509 subject field from the remote peer certificate, where  n
	      is  the  verification  level.  Only set for TLS connections. Set
	      prior to execution of --tls-verify script. This variable is sim-
	      ilar  to tls_id_{n} except the component X509 subject fields are
	      broken out, and no string	remapping occurs on these field	values
	      (except  for  remapping of control characters to "_"). For exam-
	      ple, the following variables would be set	on the OpenVPN	server
	      using the	sample client certificate in sample-keys (client.crt).
	      Note that	the verification level is 0 for	the client certificate
	      and 1 for	the CA certificate.


   Management Interface	Options
       OpenVPN	provides  a feature rich socket	based management interface for
       both server and client mode operations.

       --management args
	      Enable a management server on a socket-name Unix socket on those
	      platforms	supporting it, or on a designated TCP port.

	      Valid syntaxes:

		 management socket-name	unix	      #
		 management socket-name	unix pw-file  #	(recommended)
		 management IP port		      #	(INSECURE)
		 management IP port pw-file	      #

	      pw-file,	if  specified,	is  a password file where the password
	      must be on first line. Instead of	a filename it can use the key-
	      word stdin which will prompt the user for	a password to use when
	      OpenVPN is starting.

	      For unix sockets,	the default behaviour is to create a unix  do-
	      main  socket  that  may  be connected to by any process. Use the
	      --management-client-user	and  --management-client-group	direc-
	      tives to restrict	access.

	      The  management  interface provides a special mode where the TCP
	      management link can operate over the tunnel  itself.  To	enable
	      this  mode, set IP to tunnel. Tunnel mode	will cause the manage-
	      ment interface to	listen for a TCP connection on the  local  VPN
	      address of the TUN/TAP interface.

	      *BEWARE* of enabling the management interface over TCP. In these
	      cases you	should ALWAYS make use of pw-file to password  protect
	      the  management  interface. Any user who can connect to this TCP
	      IP:port will be able to manage and control (and interfere	 with)
	      the  OpenVPN  process. It	is also	strongly recommended to	set IP
	      to (localhost) to restrict accessibility of  the  man-
	      agement server to	local clients.

	      While  the  management port is designed for programmatic control
	      of OpenVPN by other applications,	it is possible	to  telnet  to
	      the  port,  using	a telnet client	in "raw" mode. Once connected,
	      type help	for a list of commands.

	      For detailed documentation on the	management interface, see  the
	      management-notes.txt  file in the	management folder of the Open-
	      VPN source distribution.

	      Management interface will	connect	as a TCP/unix domain client to
	      IP:port  specified  by  --management rather than listen as a TCP
	      server or	on a unix domain socket.

	      If the client connection fails to	connect	or is disconnected,  a
	      SIGTERM signal will be generated causing OpenVPN to quit.

	      Gives  management	interface client the responsibility to authen-
	      ticate clients after their client	certificate has	been verified.
	      See  management-notes.txt	 in  OpenVPN distribution for detailed

       --management-client-group g
	      When the management interface is	listening  on  a  unix	domain
	      socket, only allow connections from group	g.

       --management-client-user	u
	      When  the	 management  interface	is  listening on a unix	domain
	      socket, only allow connections from user u.

       --management-external-cert certificate-hint
	      Allows usage for external	certificate instead of	--cert	option
	      (client-only).  certificate-hint is an arbitrary string which is
	      passed to	a  management  interface  client  as  an  argument  of
	      NEED-CERTIFICATE	 notification.	 Requires  --management-exter-

       --management-external-key args
	      Allows usage for external	private	key file instead of --key  op-
	      tion (client-only).

	      Valid syntaxes:

		 management-external-key nopadding
		 management-external-key pkcs1
		 management-external-key pss

	      or any combination like:

		 management-external-key nopadding pkcs1
		 management-external-key pkcs1 pss

	      The  optional  parameters	nopadding pkcs1	and pss	signal support
	      for different padding  algorithms.  See  doc/mangement-notes.txt
	      for a complete description of this feature.

	      Make  OpenVPN  forget  passwords when management session discon-

	      This directive does not affect the  --http-proxy	username/pass-
	      word.  It	is always cached.

	      Start OpenVPN in a hibernating state, until a client of the man-
	      agement interface	explicitly starts it  with  the	 hold  release

       --management-log-cache n
	      Cache  the  most recent n	lines of log file history for usage by
	      the management channel.

	      Query  management	 channel  for	private	  key	password   and
	      --auth-user-pass	username/password.  Only  query	the management
	      channel for inputs which ordinarily would	have been queried from
	      the console.

	      Query management channel for proxy server	information for	a spe-
	      cific --remote (client-only).

	      Allow  management	 interface  to	override  --remote  directives

	      Send  SIGUSR1  signal  to	 OpenVPN if management session discon-
	      nects. This is useful when you wish  to  disconnect  an  OpenVPN
	      session  on user logoff.	For --management-client	this option is
	      not needed since a disconnect will always	generate a SIGTERM.

	      Report tunnel up/down events to management interface.

   Plug-in Interface Options
       OpenVPN can be extended by loading external plug-in modules at runtime.
       These plug-ins must be prebuilt and adhere to the OpenVPN Plug-In API.

       --plugin	args
	      Loads an OpenVPN plug-in module.

	      Valid syntax:

		 plugin	module-name
		 plugin	module-name "arguments"

	      The  module-name	needs to be the	first argument,	indicating the
	      plug-in to load.	The second argument is an optional init	string
	      which  will be passed directly to	the plug-in.  If the init con-
	      sists of multiple	arguments it must be enclosed in double-quotes
	      (").   Multiple  plugin  modules	may be loaded into one OpenVPN

	      The module-name argument can be just a filename  or  a  filename
	      with a relative or absolute path.	The format of the filename and
	      path defines if the  plug-in  will  be  loaded  from  a  default
	      plug-in directory	or outside this	directory.

		 --plugin path	       Effective directory used
		 ===================== =============================	       DEFAULT_DIR/
		  subdir/     DEFAULT_DIR/subdir/
		  ./subdir/   CWD/subdir/
		  /usr/lib/my/  /usr/lib/my/

	      DEFAULT_DIR  is replaced by the default plug-in directory, which
	      is configured at the build time of OpenVPN. CWD is  the  current
	      directory	 where	OpenVPN	 was  started or the directory OpenVPN
	      have switched into via the --cd option before the	 --plugin  op-

	      For  more	 information  and  examples  on	 how  to build OpenVPN
	      plug-in modules, see the README file in the plugin folder	of the
	      OpenVPN source distribution.

	      If you are using an RPM install of OpenVPN, see /usr/share/open-
	      vpn/plugin. The documentation is in doc and  the	actual	plugin
	      modules are in lib.

	      Multiple plugin modules can be cascaded, and modules can be used
	      in tandem	with scripts. The modules will be called by OpenVPN in
	      the  order  that they are	declared in the	config file. If	both a
	      plugin and script	are configured	for  the  same	callback,  the
	      script  will  be	called	last.  If  the return code of the mod-
	      ule/script controls an authentication function (such as tls-ver-
	      ify,  auth-user-pass-verify, or client-connect), then every mod-
	      ule and script must return success (0) in	order for the  connec-
	      tion to be authenticated.

		     Plug-ins  may  do deferred	execution, meaning the plug-in
		     will return the control back to the main OpenVPN  process
		     and  provide  the plug-in result later on via a different
		     thread or process.	 OpenVPN does NOT support multiple au-
		     thentication plug-ins where more than one plugin tries to
		     do	deferred authentication.  If  this  behaviour  is  de-
		     tected, OpenVPN will shut down upon first authentication.

   Windows-Specific Options
       --allow-nonadmin	TAP-adapter
	      (Standalone)  Set	 TAP-adapter to	allow access from non-adminis-
	      trative accounts.	If TAP-adapter is omitted, all TAP adapters on
	      the  system  will	 be  configured	to allow non-admin access. The
	      non-admin	access setting will only persist  for  the  length  of
	      time  that the TAP-Win32 device object and driver	remain loaded,
	      and will need to be re-enabled after a reboot, or	if the	driver
	      is  unloaded and reloaded. This directive	can only be used by an

	      Block DNS	servers	on  other  network  adapters  to  prevent  DNS
	      leaks.  This  option prevents any	application from accessing TCP
	      or UDP port 53 except one	inside the  tunnel.  It	 uses  Windows
	      Filtering	Platform (WFP) and works on Windows Vista or later.

	      This  option  is considered unknown on non-Windows platforms and
	      unsupported on Windows XP, resulting in  fatal  error.  You  may
	      want  to	use --setenv opt or --ignore-unknown-option (not suit-
	      able for Windows XP) to ignore said error. Note that pushing un-
	      known options from server	does not trigger fatal errors.

       --cryptoapicert select-string
	      (Windows/OpenSSL Only) Load the certificate and private key from
	      the Windows Certificate System Store.

	      Use this option instead of --cert	and --key.

	      This makes it possible to	use any	smart card, supported by  Win-
	      dows,  but  also	any  kind of certificate, residing in the Cert
	      Store, where you have access to the private key. This option has
	      been  tested  with  a  couple of different smart cards (GemSAFE,
	      Cryptoflex, and Swedish Post Office eID) on the client side, and
	      also an imported PKCS12 software certificate on the server side.

	      To select	a certificate, based on	a substring search in the cer-
	      tificate's subject:

		 cryptoapicert "SUBJ:Peter Runestig"

	      To select	a certificate, based on	certificate's thumbprint:

		 cryptoapicert "THUMB:f6 49 24 41 01 b4	..."

	      The thumbprint hex string	can easily be copy-and-pasted from the
	      Windows Certificate Store	GUI.

	      Ask  Windows  to release the TAP adapter lease on	shutdown. This
	      option has no effect now,	as it is enabled by  default  starting
	      with OpenVPN 2.4.1.

	      Ask  Windows to renew the	TAP adapter lease on startup. This op-
	      tion is normally unnecessary, as Windows automatically  triggers
	      a	 DHCP  renegotiation on	the TAP	adapter	when it	comes up, how-
	      ever if you set the TAP-Win32 adapter Media Status  property  to
	      "Always Connected", you may need this flag.

       --ip-win32 method
	      When  using  --ifconfig on Windows, set the TAP-Win32 adapter IP
	      address and netmask using	method.	Don't use this	option	unless
	      you are also using --ifconfig.

	      manual Don't  set	 the  IP address or netmask automatically. In-
		     stead output a message to the console telling the user to
		     configure the adapter manually and	indicating the IP/net-
		     mask which	OpenVPN	expects	the adapter to be set to.

	      dynamic [offset] [lease-time]
		     Automatically set the IP address and netmask by  replying
		     to	 DHCP  query  messages	generated by the kernel.  This
		     mode is probably the "cleanest" solution for setting  the
		     TCP/IP  properties	since it uses the well-known DHCP pro-
		     tocol. There are, however,	two  prerequisites  for	 using
		     this mode:

		     1.	The  TCP/IP  properties	for the	TAP-Win32 adapter must
			be set to "Obtain an IP	address	automatically",	and

		     2.	OpenVPN	needs to claim an IP address in	the subnet for
			use as the virtual DHCP	server address.

		     By	 default in --dev tap mode, OpenVPN will take the nor-
		     mally unused first	address	in the subnet. For example, if
		     your  subnet  is netmask, then
		     OpenVPN will take the IP address  to  use  as
		     the  virtual  DHCP	 server	 address.   In --dev tun mode,
		     OpenVPN will cause	the DHCP server	to masquerade as if it
		     were coming from the remote endpoint.

		     The  optional  offset  parameter is an integer which is >
		     -256 and <	256 and	which defaults to 0. If	offset is pos-
		     itive,  the DHCP server will masquerade as	the IP address
		     at	network	address	+ offset. If offset is	negative,  the
		     DHCP  server  will	masquerade as the IP address at	broad-
		     cast address + offset.

		     The Windows ipconfig /all command can  be	used  to  show
		     what  Windows  thinks the DHCP server address is. OpenVPN
		     will "claim" this address,	so make	sure to	use a free ad-
		     dress.  Having  said  that,  different OpenVPN instantia-
		     tions, including different	ends of	the  same  connection,
		     can share the same	virtual	DHCP server address.

		     The  lease-time  parameter	controls the lease time	of the
		     DHCP assignment given to the TAP-Win32  adapter,  and  is
		     denoted  in  seconds.  Normally a very long lease time is
		     preferred	because	 it  prevents  routes  involving   the
		     TAP-Win32 adapter from being lost when the	system goes to
		     sleep. The	default	lease time is one year.

	      netsh  Automatically set the IP address and  netmask  using  the
		     Windows command-line "netsh" command. This	method appears
		     to	work correctly on Windows XP but not Windows 2000.

	      ipapi  Automatically set the IP address and  netmask  using  the
		     Windows  IP Helper	API. This approach does	not have ideal
		     semantics,	though testing has  indicated  that  it	 works
		     okay  in  practice. If you	use this option, it is best to
		     leave the TCP/IP properties for the TAP-Win32 adapter  in
		     their default state, i.e. "Obtain an IP address automati-

	      adaptive (Default)
		     Try dynamic method	initially and fail over	 to  netsh  if
		     the  DHCP negotiation with	the TAP-Win32 adapter does not
		     succeed in	20 seconds. Such failures have been  known  to
		     occur  when  certain  third-party	firewall  packages in-
		     stalled on	the client machine block the DHCP  negotiation
		     used  by  the  TAP-Win32  adapter.	Note that if the netsh
		     failover occurs, the TAP-Win32 adapter TCP/IP  properties
		     will  be  reset  from DHCP	to static, and this will cause
		     future OpenVPN startups using the adaptive	 mode  to  use
		     netsh immediately,	rather than trying dynamic first.

		     To	 "unstick"  the	 adaptive  mode	 from using netsh, run
		     OpenVPN at	least once using the dynamic mode  to  restore
		     the TAP-Win32 adapter TCP/IP properties to	a DHCP config-

	      Put up a "press any key to  continue"  message  on  the  console
	      prior to OpenVPN program exit. This option is automatically used
	      by the Windows explorer when OpenVPN is run on  a	 configuration
	      file using the right-click explorer menu.

	      Run  ipconfig  /flushdns and ipconfig /registerdns on connection
	      initiation. This is  known  to  kick  Windows  into  recognizing
	      pushed DNS servers.

       --route-method m
	      Which method m to	use for	adding routes on Windows?

	      adaptive (default)
		     Try  IP helper API	first. If that fails, fall back	to the
		     route.exe shell command.

	      ipapi  Use IP helper API.

	      exe    Call the route.exe	shell command.

       --service args
	      Should be	used when OpenVPN is being automatically  executed  by
	      another  program	in such	a context that no interaction with the
	      user via display or keyboard is possible.

	      Valid syntax:

		 service exit-event [0|1]

	      In general, end-users should never need to explicitly  use  this
	      option,  as  it  is  automatically  added	by the OpenVPN service
	      wrapper when a given OpenVPN configuration is  being  run	 as  a

	      exit-event  is  the  name	 of a Windows global event object, and
	      OpenVPN will continuously	monitor	the state of this event	object
	      and exit when it becomes signaled.

	      The  second  parameter indicates the initial state of exit-event
	      and normally defaults to 0.

	      Multiple OpenVPN processes can be	simultaneously	executed  with
	      the  same	 exit-event  parameter.	 In  any case, the controlling
	      process can signal exit-event, causing  all  such	 OpenVPN  pro-
	      cesses to	exit.

	      When executing an	OpenVPN	process	using the --service directive,
	      OpenVPN will probably not	have a console window to  output  sta-
	      tus/error	 messages,  therefore  it  is  useful  to use --log or
	      --log-append to write these messages to a	file.

	      (Standalone) Show	available TAP-Win32 adapters which can be  se-
	      lected  using the	--dev-node option. On non-Windows systems, the
	      ifconfig(8) command provides similar functionality.

	      (Standalone) Show	OpenVPN's view of the system routing table and
	      network adapter list.

	      Output  OpenVPN's	 view  of the system routing table and network
	      adapter list to the syslog or log	file after the TUN/TAP adapter
	      has been brought up and any routes have been added.

	      (Standalone)  Show  valid	subnets	for --dev tun emulation. Since
	      the TAP-Win32 driver exports an ethernet interface  to  Windows,
	      and since	TUN devices are	point-to-point in nature, it is	neces-
	      sary for the TAP-Win32 driver to impose certain  constraints  on
	      TUN endpoint address selection.

	      Namely,  the  point-to-point endpoints used in TUN device	emula-
	      tion must	be the middle two addresses of a /30  subnet  (netmask

       --tap-sleep n
	      Cause  OpenVPN  to  sleep	 for  n	 seconds immediately after the
	      TAP-Win32	adapter	state is set to	"connected".

	      This option is intended to be used to troubleshoot problems with
	      the  --ifconfig  and --ip-win32 options, and is used to give the
	      TAP-Win32	adapter	time to	come up	before Windows IP  Helper  API
	      operations are applied to	it.

       --win-sys path
	      Set  the	Windows	 system	directory pathname to use when looking
	      for system executables such as route.exe and netsh.exe.  By  de-
	      fault,  if this directive	is not specified, OpenVPN will use the
	      SystemRoot environment variable.

	      This option has changed behaviour	since OpenVPN 2.3. Earlier you
	      had  to  define  --win-sys env to	use the	SystemRoot environment
	      variable,	otherwise it  defaulted	 to  C:\\WINDOWS.  It  is  not
	      needed  to use the env keyword any more, and it will just	be ig-
	      nored. A warning is logged when this is found in the  configura-
	      tion file.

       --windows-driver	drv
	      Specifies	 which	tun  driver  to	 use. Values are ovpn-dco (de-
	      fault), tap-windows6 and wintun.	ovpn-dco  and  wintun  require
	      --dev tun. wintun	also requires OpenVPN process to run elevated,
	      or be invoked using the Interactive Service.

   Standalone Debug Options
       --show-gateway args
	      (Standalone) Show	current	IPv4 and IPv6 default gateway and  in-
	      terface  towards the gateway (if the protocol in question	is en-

	      Valid syntax:

		 --show-gateway	IPv6-target

	      For IPv6 this queries the	route towards ::/128, or the specified
	      IPv6  target  address if passed as argument.  For	IPv4 on	Linux,
	      Windows, MacOS and BSD it	looks for a route.  If there
	      are more specific	routes,	the result will	not always be matching
	      the route	of the IPv4 packets to the VPN gateway.

   Advanced Expert Options
       These are options only required when special tweaking is	needed,	 often
       used when debugging or testing out special usage	scenarios.

       --hash-size args
	      Set the size of the real address hash table to r and the virtual
	      address table to v.

	      Valid syntax:

		 hash-size r v

	      By default, both tables are sized	at 256 buckets.

       --bcast-buffers n
	      Allocate n buffers for broadcast datagrams (default 256).

	      Preserve initially resolved local	IP  address  and  port	number
	      across SIGUSR1 or	--ping-restart restarts.

	      Preserve	most recently authenticated remote IP address and port
	      number across SIGUSR1 or --ping-restart restarts.

       --rcvbuf	size
	      Set the TCP/UDP socket receive buffer size. Defaults to  operat-
	      ing system default.

       --shaper	n
	      Limit bandwidth of outgoing tunnel data to n bytes per second on
	      the TCP/UDP port.	Note that this will only work if mode  is  set
	      to  p2p.	If you want to limit the bandwidth in both directions,
	      use this option on both peers.

	      OpenVPN uses the following algorithm to implement	traffic	 shap-
	      ing: Given a shaper rate of n bytes per second, after a datagram
	      write of b bytes is queued on the	TCP/UDP	port, wait  a  minimum
	      of (b / n) seconds before	queuing	the next write.

	      It  should  be  noted that OpenVPN supports multiple tunnels be-
	      tween the	same two peers,	allowing you to	 construct  full-speed
	      and reduced bandwidth tunnels at the same	time, routing low-pri-
	      ority data such as off-site backups over the  reduced  bandwidth
	      tunnel, and other	data over the full-speed tunnel.

	      Also  note  that for low bandwidth tunnels (under	1000 bytes per
	      second), you should probably use lower MTU values	as  well  (see
	      above),  otherwise  the  packet latency will grow	so large as to
	      trigger timeouts in the TLS layer	and  TCP  connections  running
	      over the tunnel.

	      OpenVPN allows n to be between 100 bytes/sec and 100 Mbytes/sec.

       --sndbuf	size
	      Set  the	TCP/UDP	socket send buffer size. Defaults to operating
	      system default.

       --tcp-queue-limit n
	      Maximum number of	output packets queued before TCP (default 64).

	      When OpenVPN is tunneling	data from a TUN/TAP device to a	remote
	      client  over  a  TCP connection, it is possible that the TUN/TAP
	      device might produce data	at a faster rate than the TCP  connec-
	      tion  can	 support. When the number of output packets queued be-
	      fore sending to the TCP socket reaches this limit	 for  a	 given
	      client  connection,  OpenVPN will	start to drop outgoing packets
	      directed at this client.

       --txqueuelen n
	      (Linux only) Set the TX queue length on the  TUN/TAP  interface.
	      Currently	defaults to operating system default.

	      Disables	the  opportunistic  use	 of data channel offloading if
	      available.  Without this option, OpenVPN will  opportunistically
	      use  DCO	mode if	the config options and the running kernel sup-
	      ports using DCO.

	      Data channel offload currently  requires	data-ciphers  to  only
	      contain  AEAD  ciphers (AES-GCM and Chacha20-Poly1305) and Linux
	      with the ovpn-dco	module.

	      Note that	some options have no effect or cannot be used when DCO
	      mode is enabled.

	      On platforms that	do not support DCO disable-dco has no effect.

       Options	listed	in this	section	have been removed from OpenVPN and are
       no longer supported

	      Removed in OpenVPN 2.5.  This should  be	replaxed  with	--ver-
	      ify-client-cert none.

	      Removed in OpenVPN 2.5.  This should be replaced with --topology

	      Removed in OpenVPN 2.5.  This option should not be used, as  us-
	      ing the old key-method weakens the VPN tunnel security.  The old
	      key-method was also only needed when the remote side  was	 older
	      than OpenVPN 2.0.

	      Removed  in  OpenVPN  2.6.   The	built-in packet	filtering (pf)
	      functionality has	been removed.

	      Removed in OpenVPN 2.6.  This option mainly served a role	as de-
	      bug  option  when	NCP was	first introduced.  It should no	longer
	      be necessary.

	      Removed in OpenVPN 2.5.  This option should not be  used	as  it
	      weakens  the  VPN	 tunnel	security.  This	has been a NOOP	option
	      since OpenVPN 2.4.

	      Removed in OpenVPN 2.5.  This option should not be  used	as  it
	      weakens the VPN tunnel security.

	      Removed  in OpenVPN 2.5.	The nsCertType field is	no longer sup-
	      ported in	recent SSL/TLS libraries.  If your  certificates  does
	      not  include  key	usage and extended key usage fields, they must
	      be upgraded and the --remote-cert-tls option should be used  in-

       --prng Removed  in  OpenVPN 2.6.	 We now	always use the PRNG of the SSL

       Client configuration files may contain multiple remote servers which it
       will  attempt to	connect	against.  But there are	some configuration op-
       tions which are related to specific --remote options.   For  these  use
       cases, connection profiles are the solution.

       By enacpulating the --remote option and related options within <connec-
       tion> and </connection>,	these options are handled as a group.

       An OpenVPN client will try each connection profile  sequentially	 until
       it achieves a successful	connection.

       --remote-random	can  be	 used  to  initially "scramble"	the connection

       Here is an example of connection	profile	usage:

	  dev tun

	  remote 1194 udp

	  remote 443 tcp

	  remote 443 tcp
	  http-proxy 8080

	  remote 443 tcp
	  http-proxy 8080

	  pkcs12 client.p12
	  remote-cert-tls server
	  verb 3

       First we	try to connect to a server at	using UDP.  If
       that  fails,  we	 then try to connect to using TCP. If
       that  also  fails,  then	 try  connecting  through  an  HTTP  proxy  at	to using TCP. Finally,	try to connect
       through the same	proxy to a server at using TCP.

       The following OpenVPN options may be  used  inside  of  a  <connection>

       bind,	connect-retry,	  connect-retry-max,	connect-timeout,   ex-
       plicit-exit-notify,  float,  fragment,  http-proxy,  http-proxy-option,
       key-direction,  link-mtu, local,	lport, mssfix, mtu-disc, nobind, port,
       proto, remote, rport, socks-proxy, tls-auth,  tls-crypt,	 tun-mtu  and,

       A  defaulting  mechanism	 exists	for specifying options to apply	to all
       <connection> profiles. If any of	the above options (with	the  exception
       of remote ) appear outside of a <connection> block, but in a configura-
       tion file which has one or more <connection> blocks, the	option setting
       will  be	 used  as a default for	<connection> blocks which follow it in
       the configuration file.

       For example, suppose the	nobind option were placed in the  sample  con-
       figuration file above, near the top of the file,	before the first <con-
       nection>	block. The effect would	be as if nobind	were declared  in  all
       <connection> blocks below it.

       OpenVPN	allows including files in the main configuration for the --ca,
       --cert, --dh, --extra-certs, --key, --pkcs12,  --secret,	 --crl-verify,
       --http-proxy-user-pass,	     --tls-auth,      --auth-gen-token-secret,
       --peer-fingerprint, --tls-crypt,	--tls-crypt-v2 and  --verify-hash  op-

       Each  inline  file  started  by the line	<option> and ended by the line

       Here is an example of an	inline file usage

	  -----END CERTIFICATE-----

       When using the inline file feature with --pkcs12	the inline file	has to
       be  base64 encoded. Encoding of a .p12 file into	base64 can be done for
       example with OpenSSL by running openssl base64 -in input.p12

       SIGHUP Cause OpenVPN to close  all  TUN/TAP  and	 network  connections,
	      restart,	re-read	 the  configuration  file (if any), and	reopen
	      TUN/TAP and network connections.

	      Like SIGHUP`, except don't re-read configuration file, and  pos-
	      sibly  don't close and reopen TUN/TAP device, re-read key	files,
	      preserve local IP	address/port, or preserve  most	 recently  au-
	      thenticated  remote  IP  address/port  based  on	--persist-tun,
	      --persist-key, --persist-local-ip	 and  --persist-remote-ip  op-
	      tions respectively (see above).

	      This signal may also be internally generated by a	timeout	condi-
	      tion, governed by	the --ping-restart option.

	      This signal, when	combined with --persist-remote-ip, may be sent
	      when  the	 underlying parameters of the host's network interface
	      change such as when the host is a	DHCP client and	is assigned  a
	      new IP address.  See --ipchange for more information.

	      Causes  OpenVPN to display its current statistics	(to the	syslog
	      file if --daemon is used,	or stdout otherwise).

	      Causes OpenVPN to	exit gracefully.


       For a more comprehensive	guide to setting up OpenVPN  in	 a  production
       setting,		see	    the		OpenVPN	       HOWTO	    at

       For   a	 description   of   OpenVPN's	underlying    protocol,	   see

       OpenVPN's web site is at

       Go  here	 to  download  the latest version of OpenVPN, subscribe	to the
       mailing lists, read the mailing list archives, or browse	the SVN	repos-

       Report all bugs to the OpenVPN team

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

       This product includes software developed	 by  the  OpenSSL  Project  (-

       For     more	information	on     the     TLS    protocol,	   see

       For more	information on	the  LZO  real-time  compression  library  see

       Copyright  (C) 2002-2020	OpenVPN	Inc This program is free software; you
       can redistribute	it and/or modify it under the terms of the GNU General
       Public License version 2	as published by	the Free Software Foundation.

       James Yonan



Want to link to this manual page? Use this URL:

home | help