New upstream version 2.5~beta3upstream/2.5_beta3

1 files changed, 6954 insertions, 0 deletions

diff --git a/doc/openvpn.8 b/doc/openvpn.8
new file mode 100644
index 0000000..b914f32
--- /dev/null
+++ b/doc/openvpn.8
@@ -0,0 +1,6954 @@
+.\" Man page generated from reStructuredText.
+.
+.TH OPENVPN 8 "" "" "System Manager's Manual"
+.SH NAME
+openvpn \- Secure IP tunnel daemon
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH SYNOPSIS
+.nf
+\fBopenvpn\fP [ options ... ]
+\fBopenvpn\fP  \fB\-\-help\fP
+.fi
+.sp
+.SH INTRODUCTION
+.sp
+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\(aqre new to
+OpenVPN, 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.
+.sp
+Also note that there\(aqs more documentation and examples on the OpenVPN
+web site: \fI\%https://openvpn.net/\fP
+.sp
+And if you would like to see a shorter version of this manual, see the
+openvpn usage message which can be obtained by running \fBopenvpn\fP
+without any parameters.
+.SH DESCRIPTION
+.sp
+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.
+.sp
+OpenVPN is tightly bound to the OpenSSL library, and derives much of its
+crypto capabilities from it.
+.sp
+OpenVPN supports conventional encryption using a pre\-shared secret key
+\fB(Static Key mode)\fP or public key security \fB(SSL/TLS mode)\fP using
+client & server certificates. OpenVPN also supports non\-encrypted
+TCP/UDP tunnels.
+.sp
+OpenVPN is designed to work with the \fBTUN/TAP\fP virtual networking
+interface that exists on most platforms.
+.sp
+Overall, OpenVPN aims to offer many of the key features of IPSec but
+with a relatively lightweight footprint.
+.SH OPTIONS
+.sp
+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.
+.SS Generic Options
+.sp
+This section covers generic options which are accessible regardless of
+which mode OpenVPN is configured as.
+.INDENT 0.0
+.TP
+.B \-\-help
+Show options.
+.TP
+.B \-\-auth\-nocache
+Don\(aqt cache \fB\-\-askpass\fP or \fB\-\-auth\-user\-pass\fP username/passwords in
+virtual memory.
+.sp
+If specified, this directive will cause OpenVPN to immediately forget
+username/password inputs after they are used. As a result, when OpenVPN
+needs a username/password, it will prompt for input from stdin, which
+may be multiple times during the duration of an OpenVPN session.
+.sp
+When using \fB\-\-auth\-nocache\fP in combination with a user/password file
+and \fB\-\-chroot\fP or \fB\-\-daemon\fP, make sure to use an absolute path.
+.sp
+This directive does not affect the \fB\-\-http\-proxy\fP username/password.
+It is always cached.
+.TP
+.BI \-\-cd \ dir
+Change directory to \fBdir\fP prior to reading any files such as
+configuration files, key files, scripts, etc. \fBdir\fP should be an
+absolute path, with a leading "/", and without any references to the
+current directory such as \fB\&.\fP or \fB\&..\fP\&.
+.sp
+This option is useful when you are running OpenVPN in \fB\-\-daemon\fP mode,
+and you want to consolidate all of your OpenVPN control files in one
+location.
+.TP
+.BI \-\-chroot \ dir
+Chroot to \fBdir\fP after initialization. \fB\-\-chroot\fP essentially
+redefines \fBdir\fP 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.
+.sp
+Since the chroot operation is delayed until after initialization, most
+OpenVPN options that reference files will operate in a pre\-chroot
+context.
+.sp
+In many cases, the \fBdir\fP parameter can point to an empty directory,
+however complications can result when scripts or restarts are executed
+after the chroot operation.
+.sp
+Note: The SSL library will probably need /dev/urandom to be available
+inside the chroot directory \fBdir\fP\&. This is because SSL libraries
+occasionally need to collect fresh random. Newer linux kernels and some
+BSDs implement a getrandom() or getentropy() syscall that removes the
+need for /dev/urandom to be available.
+.TP
+.BI \-\-config \ file
+Load additional config options from \fBfile\fP where each line corresponds
+to one command line option, but with the leading \(aq\-\-\(aq removed.
+.sp
+If \fB\-\-config file\fP is the only option to the openvpn command, the
+\fB\-\-config\fP can be removed, and the command can be given as \fBopenvpn
+file\fP
+.sp
+Note that configuration files can be nested to a reasonable depth.
+.sp
+Double quotation or single quotation characters ("", \(aq\(aq) can be used to
+enclose single parameters containing whitespace, and "#" or ";"
+characters in the first column can be used to denote comments.
+.sp
+Note that OpenVPN 2.0 and higher performs backslash\-based shell escaping
+for characters not in single quotations, so the following mappings
+should be observed:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\e\e       Maps to a single backslash character (\e).
+\e"       Pass a literal doublequote character ("), don\(aqt
+         interpret it as enclosing a parameter.
+\e[SPACE] Pass a literal space or tab character, don\(aqt
+         interpret it as a parameter delimiter.
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For example on Windows, use double backslashes to represent pathnames:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+secret "c:\e\eOpenVPN\e\esecret.key"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For examples of configuration files, see
+\fI\%https://openvpn.net/community\-resources/how\-to/\fP
+.sp
+Here is an example configuration file:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+#
+# Sample OpenVPN configuration file for
+# using a pre\-shared static key.
+#
+# \(aq#\(aq or \(aq;\(aq may be used to delimit comments.
+
+# Use a dynamic tun device.
+dev tun
+
+# Our remote peer
+remote mypeer.mydomain
+
+# 10.1.0.1 is our local VPN endpoint
+# 10.1.0.2 is our remote VPN endpoint
+ifconfig 10.1.0.1 10.1.0.2
+
+# Our pre\-shared static key
+secret static.key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-daemon \ progname
+Become a daemon after all initialization functions are completed. This
+option will cause all message and error output to be sent to the syslog
+file (such as \fB/var/log/messages\fP), except for the output of
+scripts and ifconfig commands, which will go to \fB/dev/null\fP unless
+otherwise redirected. The syslog redirection occurs immediately at the
+point that \fB\-\-daemon\fP is parsed on the command line even though the
+daemonization point occurs later. If one of the \fB\-\-log\fP options is
+present, it will supersede syslog redirection.
+.sp
+The optional \fBprogname\fP parameter will cause OpenVPN to report its
+program name to the system logger as \fBprogname\fP\&. This can be useful in
+linking OpenVPN messages in the syslog file with specific tunnels. When
+unspecified, \fBprogname\fP defaults to "openvpn".
+.sp
+When OpenVPN is run with the \fB\-\-daemon\fP option, it will try to delay
+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.
+.sp
+In OpenVPN, the vast majority of errors which occur after initialization
+are non\-fatal.
+.sp
+Note: as soon as OpenVPN has daemonized, it can not ask for usernames,
+passwords, or key pass phrases anymore. This has certain consequences,
+namely that using a password\-protected private key will fail unless the
+\fB\-\-askpass\fP 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 initializing the crypto layer).
+.sp
+Further, using \fB\-\-daemon\fP together with \fB\-\-auth\-user\-pass\fP (entered
+on console) and \fB\-\-auth\-nocache\fP will fail as soon as key
+renegotiation (and reauthentication) occurs.
+.TP
+.B \-\-disable\-occ
+Don\(aqt output a warning message if option inconsistencies are detected
+between peers. An example of an option inconsistency would be where one
+peer uses \fB\-\-dev tun\fP while the other peer uses \fB\-\-dev tap\fP\&.
+.sp
+Use of this option is discouraged, but is provided as a temporary fix in
+situations where a recent version of OpenVPN must connect to an old
+version.
+.TP
+.BI \-\-engine \ engine\-name
+Enable OpenSSL hardware\-based crypto engine functionality.
+.sp
+If \fBengine\-name\fP is specified, use a specific crypto engine. Use the
+\fB\-\-show\-engines\fP standalone option to list the crypto engines which
+are supported by OpenSSL.
+.TP
+.B \-\-fast\-io
+(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
+poll/epoll/select prior to the write operation. The purpose of such a
+call would normally be to block until the device or socket is ready to
+accept the write. Such blocking is unnecessary on some platforms which
+don\(aqt 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%.
+.sp
+This option can only be used on non\-Windows systems, when \fB\-\-proto
+udp\fP is specified, and when \fB\-\-shaper\fP is NOT specified.
+.TP
+.BI \-\-group \ group
+Similar to the \fB\-\-user\fP option, this option changes the group ID of
+the OpenVPN process to \fBgroup\fP after initialization.
+.TP
+.BI \-\-ignore\-unknown\-option \ args
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ignore\-unknown\-options opt1 opt2 opt3 ... optN
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When one of options \fBopt1 ... optN\fP is encountered in the configuration
+file the configuration file parsing does not fail if this OpenVPN version
+does not support the option. Multiple \fB\-\-ignore\-unknown\-option\fP options
+can be given to support a larger number of options to ignore.
+.sp
+This option should be used with caution, as there are good security
+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 encountered by older software
+versions.
+.sp
+\fB\-\-ignore\-unknown\-option\fP is available since OpenVPN 2.3.3.
+.TP
+.BI \-\-iproute \ cmd
+Set alternate command to execute instead of default \fBiproute2\fP command.
+May be used in order to execute OpenVPN in unprivileged environment.
+.TP
+.BI \-\-keying\-material\-exporter \ args
+Save Exported Keying Material [RFC5705] of len bytes (must be between 16
+and 4095 bytes) using \fBlabel\fP in environment
+(\fBexported_keying_material\fP) for use by plugins in
+\fBOPENVPN_PLUGIN_TLS_FINAL\fP callback.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+keying\-material\-exporter label len
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Note that exporter \fBlabels\fP have the potential to collide with existing
+PRF labels. In order to prevent this, labels \fIMUST\fP begin with
+\fBEXPORTER\fP\&.
+.TP
+.B \-\-mlock
+Disable paging by calling the POSIX mlockall function. Requires that
+OpenVPN be initially run as root (though OpenVPN can subsequently
+downgrade its UID using the \fB\-\-user\fP option).
+.sp
+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 \fB\-\-reneg\fP options (see
+below), then are discarded.
+.sp
+The downside of using \fB\-\-mlock\fP is that it will reduce the amount of
+physical memory available to other applications.
+.TP
+.BI \-\-nice \ n
+Change process priority after initialization (\fBn\fP greater than 0 is
+lower priority, \fBn\fP less than zero is higher priority).
+.TP
+.B \-\-persist\-key
+Don\(aqt re\-read key files across \fBSIGUSR1\fP or \fB\-\-ping\-restart\fP\&.
+.sp
+This option can be combined with \fB\-\-user nobody\fP to allow restarts
+triggered by the \fBSIGUSR1\fP signal. Normally if you drop root
+privileges in OpenVPN, the daemon cannot be restarted since it will now
+be unable to re\-read protected key files.
+.sp
+This option solves the problem by persisting keys across \fBSIGUSR1\fP
+resets, so they don\(aqt need to be re\-read.
+.TP
+.BI \-\-remap\-usr1 \ signal
+Control whether internally or externally generated \fBSIGUSR1\fP signals
+are remapped to \fBSIGHUP\fP (restart without persisting state) or
+SIGTERM (exit).
+.sp
+\fBsignal\fP can be set to \fBSIGHUP\fP or \fBSIGTERM\fP\&. By default,
+no remapping occurs.
+.TP
+.BI \-\-script\-security \ level
+This directive offers policy\-level control over OpenVPN\(aqs usage of
+external programs and scripts. Lower \fBlevel\fP values are more
+restrictive, higher values are more permissive. Settings for \fBlevel\fP:
+.INDENT 7.0
+.TP
+.B \fB0\fP
+Strictly no calling of external programs.
+.TP
+.B \fB1\fP
+(Default) Only call built\-in executables such as ifconfig,
+ip, route, or netsh.
+.TP
+.B \fB2\fP
+Allow calling of built\-in executables and user\-defined
+scripts.
+.TP
+.B \fB3\fP
+Allow passwords to be passed to scripts via environmental
+variables (potentially unsafe).
+.UNINDENT
+.sp
+OpenVPN releases before v2.3 also supported a \fBmethod\fP flag which
+indicated how OpenVPN should call external commands and scripts. This
+could be either \fBexecve\fP or \fBsystem\fP\&. As of OpenVPN 2.3, this
+flag is no longer accepted. In most *nix environments the execve()
+approach has been used without any issues.
+.sp
+Some directives such as \fB\-\-up\fP 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\(aqt determine where the script name ends and script options start.
+.sp
+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 \fBsystem\fP 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:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-up \(aqC:\e\eWindows\e\eSystem32\e\ewscript.exe C:\e\eProgram\e Files\e\eOpenVPN\e\econfig\e\emy\-up\-script.vbs\(aq
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Please note the single quote marks and the escaping of the backslashes
+(\e) and the space character.
+.sp
+The reason the support for the \fBsystem\fP flag was removed is due to
+the security implications with shell expansions when executing scripts
+via the \fBsystem()\fP call.
+.TP
+.BI \-\-setcon \ context
+Apply SELinux \fBcontext\fP after initialization. This essentially
+provides the ability to restrict OpenVPN\(aqs rights to only network I/O
+operations, thanks to SELinux. This goes further than \fB\-\-user\fP and
+\fB\-\-chroot\fP in that those two, while being great security 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).
+.sp
+Since the setcon operation is delayed until after initialization,
+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 initialization.
+.sp
+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 \fB\-\-persist\-key\fP and \fB\-\-persist\-tun\fP options.
+.TP
+.BI \-\-status \ args
+Write operational status to \fBfile\fP every \fBn\fP seconds.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+status file
+status file n
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Status can also be written to the syslog by sending a \fBSIGUSR2\fP
+signal.
+.sp
+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 \fB\-\-status\-version\fP option in that case.
+.sp
+For clients or instances running in point\-to\-point mode, it will contain
+the traffic statistics.
+.TP
+.BI \-\-status\-version \ n
+Set the status file format version number to \fBn\fP\&.
+.sp
+This only affects the status file on servers with multi\-client
+capability enabled.  Valid status version values:
+.INDENT 7.0
+.TP
+.B \fB1\fP
+Traditional format (default). The client list contains the
+following fields comma\-separated: Common Name, Real Address, Bytes
+Received, Bytes Sent, Connected Since.
+.TP
+.B \fB2\fP
+A more reliable format for external processing. Compared to
+version \fB1\fP, 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.
+.TP
+.B \fB3\fP
+Identical to \fB2\fP, but fields are tab\-separated.
+.UNINDENT
+.TP
+.B \-\-test\-crypto
+Do a self\-test of OpenVPN\(aqs crypto options by encrypting and decrypting
+test packets using the data channel encryption options specified above.
+This option does not require a peer to function, and therefore can be
+specified without \fB\-\-dev\fP or \fB\-\-remote\fP\&.
+.sp
+The typical usage of \fB\-\-test\-crypto\fP would be something like this:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-test\-crypto \-\-secret key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+or
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-test\-crypto \-\-secret key \-\-verb 9
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This option is very useful to test OpenVPN after it has been ported to a
+new platform, or to isolate problems in the compiler, OpenSSL crypto
+library, or OpenVPN\(aqs crypto code. Since it is a self\-test mode,
+problems with encryption and authentication can be debugged
+independently of network and tunnel issues.
+.TP
+.BI \-\-tmp\-dir \ dir
+Specify a directory \fBdir\fP 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\(aqs root privileges.
+.sp
+This directory will be used by in the following cases:
+.INDENT 7.0
+.IP \(bu 2
+\fB\-\-client\-connect\fP scripts and \fBOPENVPN_PLUGIN_CLIENT_CONNECT\fP
+plug\-in hook to dynamically generate client\-specific configuration
+\fBclient_connect_config_file\fP and return success/failure via
+\fBclient_connect_deferred_file\fP when using deferred client connect
+method
+.IP \(bu 2
+\fBOPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY\fP plug\-in hooks returns
+success/failure via \fBauth_control_file\fP when using deferred auth
+method
+.IP \(bu 2
+\fBOPENVPN_PLUGIN_ENABLE_PF\fP plugin hook to pass filtering rules
+via \fBpf_file\fP
+.UNINDENT
+.TP
+.B \-\-use\-prediction\-resistance
+Enable prediction resistance on mbed TLS\(aqs RNG.
+.sp
+Enabling prediction resistance causes the RNG to reseed in each call for
+random. Reseeding this often can quickly deplete the kernel entropy
+pool.
+.sp
+If you need this option, please consider running a daemon that adds
+entropy to the kernel pool.
+.TP
+.BI \-\-user \ user
+Change the user ID of the OpenVPN process to \fBuser\fP after
+initialization, dropping privileges in the process. This option is
+useful to protect the system in the event that some hostile party was
+able to gain control of an OpenVPN session. Though OpenVPN\(aqs security
+features make this unlikely, it is provided as a second line of defense.
+.sp
+By setting \fBuser\fP to \fBnobody\fP or somebody similarly unprivileged,
+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 \fBSIGUSR1\fP signal (for example in response to
+a DHCP reset), you should make use of one or more of the \fB\-\-persist\fP
+options to ensure that OpenVPN doesn\(aqt need to execute any privileged
+operations in order to restart (such as re\-reading key files or running
+\fBifconfig\fP on the TUN device).
+.TP
+.BI \-\-writepid \ file
+Write OpenVPN\(aqs main process ID to \fBfile\fP\&.
+.UNINDENT
+.SS Log options
+.INDENT 0.0
+.TP
+.BI \-\-echo \ parms
+Echo \fBparms\fP to log output.
+.sp
+Designed to be used to send messages to a controlling application which
+is receiving the OpenVPN log output.
+.TP
+.B \-\-errors\-to\-stderr
+Output errors to stderr instead of stdout unless log output is
+redirected by one of the \fB\-\-log\fP options.
+.TP
+.BI \-\-log \ file
+Output logging messages to \fBfile\fP, including output to stdout/stderr
+which is generated by called scripts. If \fBfile\fP already exists it will
+be truncated. This option takes effect immediately when it is parsed in
+the command line and will supersede syslog output if \fB\-\-daemon\fP or
+\fB\-\-inetd\fP is also specified. This option is persistent over the entire
+course of an OpenVPN instantiation and will not be reset by
+\fBSIGHUP\fP, \fBSIGUSR1\fP, or \fB\-\-ping\-restart\fP\&.
+.sp
+Note that on Windows, when OpenVPN is started as a service, logging
+occurs by default without the need to specify this option.
+.TP
+.BI \-\-log\-append \ file
+Append logging messages to \fBfile\fP\&.  If \fBfile\fP does not exist, it will
+be created. This option behaves exactly like \fB\-\-log\fP except that it
+appends to rather than truncating the log file.
+.TP
+.B \-\-machine\-readable\-output
+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.
+.TP
+.BI \-\-mute \ n
+Log at most \fBn\fP consecutive messages in the same category. This is
+useful to limit repetitive logging of similar message types.
+.TP
+.B \-\-mute\-replay\-warnings
+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.
+.TP
+.B \-\-suppress\-timestamps
+Avoid writing timestamps to log messages, even when they otherwise would
+be prepended. In particular, this applies to log messages sent to
+stdout.
+.TP
+.BI \-\-syslog \ progname
+Direct log output to system logger, but do not become a daemon. See
+\fB\-\-daemon\fP directive above for description of \fBprogname\fP parameter.
+.TP
+.BI \-\-verb \ n
+Set output verbosity to \fBn\fP (default \fB1\fP). Each level shows all
+info from the previous levels. Level \fB3\fP is recommended if you want
+a good summary of what\(aqs happening without being swamped by output.
+.INDENT 7.0
+.TP
+.B \fB0\fP
+No output except fatal errors.
+.TP
+.B \fB1\fP to \fB4\fP
+Normal usage range.
+.TP
+.B \fB5\fP
+Outputs \fBR\fP and \fBW\fP 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.
+.TP
+.B \fB6\fP to \fB11\fP
+Debug info range (see \fBerrlevel.h\fP in the source code for
+additional information on debug levels).
+.UNINDENT
+.UNINDENT
+.SS Protocol options
+.sp
+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.
+.INDENT 0.0
+.TP
+.BI \-\-allow\-compression \ mode
+As described in the \fB\-\-compress\fP option, compression is a potentially
+dangerous option.  This option allows controlling the behaviour of
+OpenVPN when compression is used and allowed.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+allow\-compression
+allow\-compression mode
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBmode\fP argument can be one of the following values:
+.INDENT 7.0
+.TP
+.B \fBasym\fP  (default)
+OpenVPN will only \fIdecompress downlink packets\fP but \fInot compress
+uplink packets\fP\&.  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.
+.TP
+.B \fBno\fP
+OpenVPN will refuse any non\-stub compression.
+.TP
+.B \fByes\fP
+OpenVPN will send and receive compressed packets.
+.UNINDENT
+.TP
+.BI \-\-auth \ alg
+Authenticate data channel packets and (if enabled) \fBtls\-auth\fP control
+channel packets with HMAC using message digest algorithm \fBalg\fP\&. (The
+default is \fBSHA1\fP ). HMAC is a commonly used message authentication
+algorithm (MAC) that uses a data string, a secure hash algorithm and a
+key to produce a digital signature.
+.sp
+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.
+.sp
+If an AEAD cipher mode (e.g. GCM) is chosen then the specified \fB\-\-auth\fP
+algorithm is ignored for the data channel and the authentication method
+of the AEAD cipher is used instead. Note that \fBalg\fP still specifies
+the digest used for \fBtls\-auth\fP\&.
+.sp
+In static\-key encryption mode, the HMAC key is included in the key file
+generated by \fB\-\-genkey\fP\&. In TLS mode, the HMAC key is dynamically
+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 \fBalg=none\fP to disable
+authentication.
+.sp
+For more information on HMAC see
+\fI\%http://www.cs.ucsd.edu/users/mihir/papers/hmac.html\fP
+.TP
+.BI \-\-cipher \ alg
+This option is deprecated for server\-client mode. \fB\-\-data\-ciphers\fP
+or possibly \fI\-\-data\-ciphers\-fallback\(ga\fP should be used instead.
+.sp
+Encrypt data channel packets with cipher algorithm \fBalg\fP\&.
+.sp
+The default is \fBBF\-CBC\fP, an abbreviation for Blowfish in Cipher
+Block Chaining mode. When cipher negotiation (NCP) is allowed,
+OpenVPN 2.4 and newer on both client and server side will automatically
+upgrade to \fBAES\-256\-GCM\fP\&.  See \fB\-\-data\-ciphers\fP and
+\fB\-\-ncp\-disable\fP for more details on NCP.
+.sp
+Using \fBBF\-CBC\fP is no longer recommended, because of its 64\-bit
+block size. This small block size allows attacks based on collisions, as
+demonstrated by SWEET32. See
+\fI\%https://community.openvpn.net/openvpn/wiki/SWEET32\fP
+for details. Due to this, support for \fBBF\-CBC\fP, \fBDES\fP,
+\fBCAST5\fP, \fBIDEA\fP and \fBRC2\fP ciphers will be removed in
+OpenVPN 2.6.
+.sp
+To see other ciphers that are available with OpenVPN, use the
+\fB\-\-show\-ciphers\fP option.
+.sp
+Set \fBalg\fP to \fBnone\fP to disable encryption.
+.TP
+.BI \-\-compress \ algorithm
+\fBDEPRECATED\fP Enable a compression algorithm.  Compression is generally
+not recommended.  VPN tunnels which use compression are susceptible to
+the VORALCE attack vector.
+.sp
+The \fBalgorithm\fP parameter may be \fBlzo\fP, \fBlz4\fP,
+\fBlz4\-v2\fP, \fBstub\fP, \fBstub\-v2\fP or empty.
+LZO and LZ4 are different compression algorithms, with LZ4 generally
+offering the best performance with least CPU usage.
+.sp
+The \fBlz4\-v2\fP and \fBstub\-v2\fP 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.
+.sp
+If the \fBalgorithm\fP parameter is \fBstub\fP, \fBstub\-v2\fP or empty,
+compression will be turned off, but the packet framing for compression
+will still be enabled, allowing a different setting to be pushed later.
+Additionally, \fBstub\fP and \fBstub\-v2\fP wil disable announcing
+\fBlzo\fP and \fBlz4\fP compression support via \fIIV_\fP variables to the
+server.
+.sp
+Note: the \fBstub\fP (or empty) option is NOT compatible with the older
+option \fB\-\-comp\-lzo no\fP\&.
+.sp
+\fB*Security Considerations*\fP
+.sp
+Compression and encryption is a tricky combination. If an attacker knows
+or is able to control (parts of) the plain\-text of packets that contain
+secrets, the attacker might be able to extract the secret if compression
+is enabled. See e.g. the \fICRIME\fP and \fIBREACH\fP attacks on TLS and
+\fIVORACLE\fP on VPNs which also leverage to break encryption. If you are not
+entirely sure that the above does not apply to your traffic, you are
+advised to \fInot\fP enable compression.
+.TP
+.BI \-\-comp\-lzo \ mode
+\fBDEPRECATED\fP Enable LZO compression algorithm.  Compression is
+generally not recommended.  VPN tunnels which uses compression are
+suspectible to the VORALCE attack vector.
+.sp
+Use LZO compression \-\- may add up to 1 byte per packet for incompressible
+data. \fBmode\fP may be \fByes\fP, \fBno\fP, or \fBadaptive\fP
+(default).
+.sp
+In a server mode setup, it is possible to selectively turn compression
+on or off for individual clients.
+.sp
+First, make sure the client\-side config file enables selective
+compression by having at least one \fB\-\-comp\-lzo\fP directive, such as
+\fB\-\-comp\-lzo no\fP\&. This will turn off compression by default, but allow
+a future directive push from the server to dynamically change the
+\fBon\fP/\fBoff\fP/\fBadaptive\fP setting.
+.sp
+Next in a \fB\-\-client\-config\-dir\fP file, specify the compression setting
+for the client, for example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+comp\-lzo yes
+push "comp\-lzo yes"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The first line sets the \fBcomp\-lzo\fP setting for the server side of the
+link, the second sets the client side.
+.TP
+.B \-\-comp\-noadapt
+\fBDEPRECATED\fP When used in conjunction with \fB\-\-comp\-lzo\fP, this option
+will disable OpenVPN\(aqs adaptive compression algorithm. Normally, adaptive
+compression is enabled with \fB\-\-comp\-lzo\fP\&.
+.sp
+Adaptive compression tries to optimize the case where you have
+compression enabled, but you are sending predominantly incompressible
+(or pre\-compressed) packets over the tunnel, such as an FTP or rsync
+transfer of a large, compressed file. With adaptive compression, OpenVPN
+will periodically sample the compression process to measure its
+efficiency. If the data being sent over the tunnel is already
+compressed, the compression efficiency will be very low, triggering
+openvpn to disable compression for a period of time until the next
+re\-sample test.
+.TP
+.B \-\-key\-direction
+Alternative way of specifying the optional direction parameter for the
+\fB\-\-tls\-auth\fP and \fB\-\-secret\fP options. Useful when using inline files
+(See section on inline files).
+.TP
+.BI \-\-keysize \ n
+\fBDEPRECATED\fP This option will be removed in OpenVPN 2.6.
+.sp
+Size of cipher key in bits (optional). If unspecified, defaults to
+cipher\-specific default. The \fB\-\-show\-ciphers\fP option (see below) shows
+all available OpenSSL ciphers, their default key sizes, and whether the
+key size can be changed. Use care in changing a cipher\(aqs default key
+size. Many ciphers have not been extensively cryptanalyzed with
+non\-standard key lengths, and a larger key may offer no real guarantee
+of greater security, or may even reduce security.
+.TP
+.BI \-\-data\-ciphers \ cipher\-list
+Restrict the allowed ciphers to be negotiated to the ciphers in
+\fBcipher\-list\fP\&. \fBcipher\-list\fP is a colon\-separated list of ciphers,
+and defaults to \fBAES\-256\-GCM:AES\-128\-GCM\fP\&.
+.sp
+For servers, the first cipher from \fBcipher\-list\fP that is also
+supported by the client will be pushed to clients that support cipher
+negotiation.
+.sp
+Cipher negotiation is enabled in client\-server mode only. I.e. if
+\fB\-\-mode\fP is set to \(aqserver\(aq (server\-side, implied by setting
+\fB\-\-server\fP ), or if \fB\-\-pull\fP is specified (client\-side, implied by
+setting \-\-client).
+.sp
+If no common cipher is found during cipher negotiation, the connection
+is terminated. To support old clients/old servers that do not provide any
+cipher negotiation support see \fB\-\-data\-ciphers\-fallback\fP\&.
+.sp
+Additionally, to allow for more smooth transition, if NCP is enabled,
+OpenVPN will inherit the cipher of the peer if that cipher is different
+from the local \fB\-\-cipher\fP setting, but the peer cipher is one of the
+ciphers specified in \fB\-\-data\-ciphers\fP\&. E.g. a non\-NCP client (<=v2.3,
+or with \-\-ncp\-disabled set) connecting to a NCP server (v2.4+) with
+\fB\-\-cipher BF\-CBC\fP and \fB\-\-data\-ciphers AES\-256\-GCM:AES\-256\-CBC\fP set can
+either specify \fB\-\-cipher BF\-CBC\fP or \fB\-\-cipher AES\-256\-CBC\fP and both
+will work.
+.sp
+Note for using NCP with an OpenVPN 2.4 peer: This list must include the
+\fBAES\-256\-GCM\fP and \fBAES\-128\-GCM\fP ciphers.
+.sp
+This list is restricted to be 127 chars long after conversion to OpenVPN
+ciphers.
+.sp
+This option was called \fB\-\-ncp\-ciphers\fP in OpenVPN 2.4 but has been renamed
+to \fB\-\-data\-ciphers\fP in OpenVPN 2.5 to more accurately reflect its meaning.
+.TP
+.BI \-\-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.
+.sp
+This option should only be needed to
+connect to peers that are running OpenVPN 2.3 and older version, and
+have been configured with \fI\-\-enable\-small\fP
+(typically used on routers or other embedded devices).
+.TP
+.B \-\-ncp\-disable
+\fBDEPRECATED\fP Disable "Negotiable Crypto Parameters". This completely
+disables cipher negotiation.
+.TP
+.BI \-\-secret \ args
+Enable Static Key encryption mode (non\-TLS). Use pre\-shared secret
+\fBfile\fP which was generated with \fB\-\-genkey\fP\&.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+secret file
+secret file direction
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The optional \fBdirection\fP 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 attacks.
+.sp
+When the \fBdirection\fP parameter is omitted, 2 keys are used
+bidirectionally, one for HMAC and the other for encryption/decryption.
+.sp
+The \fBdirection\fP parameter should always be complementary on either
+side of the connection, i.e. one side should use \fB0\fP and the other
+should use \fB1\fP, or both sides should omit it altogether.
+.sp
+The \fBdirection\fP parameter requires that \fBfile\fP contains a 2048 bit
+key. While pre\-1.5 versions of OpenVPN generate 1024 bit key files, any
+version of OpenVPN which supports the \fBdirection\fP parameter, will also
+support 2048 bit key file generation using the \fB\-\-genkey\fP option.
+.sp
+Static key encryption mode has certain advantages, the primary being
+ease of configuration.
+.sp
+There are no certificates or certificate authorities or complicated
+negotiation handshakes and protocols. The only requirement is that you
+have a pre\-existing secure channel with your peer (such as \fBssh\fP) 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, everything 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.
+.sp
+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 sequence) that would
+mark the ciphertext packets as being generated by OpenVPN. Anyone
+eavesdropping on the wire would see nothing but random\-looking data.
+.TP
+.BI \-\-tran\-window \ n
+Transition window \-\- our old key can live this many seconds after a new
+a key renegotiation begins (default \fB3600\fP seconds). This feature
+allows for a graceful transition from old to new key, and removes the key
+renegotiation sequence from the critical path of tunnel data forwarding.
+.UNINDENT
+.SS Client Options
+.sp
+The client options are used when connecting to an OpenVPN server configured
+to use \fB\-\-server\fP, \fB\-\-server\-bridge\fP, or \fB\-\-mode server\fP in its
+configuration.
+.INDENT 0.0
+.TP
+.B \-\-allow\-pull\-fqdn
+Allow client to pull DNS names from server (rather than being limited to
+IP address) for \fB\-\-ifconfig\fP, \fB\-\-route\fP, and \fB\-\-route\-gateway\fP\&.
+.TP
+.B \-\-allow\-recursive\-routing
+When this option is set, OpenVPN will not drop incoming tun packets with
+same destination as host.
+.TP
+.BI \-\-auth\-token \ token
+This is not an option to be used directly in any configuration files,
+but rather push this option from a \fB\-\-client\-connect\fP script or a
+\fB\-\-plugin\fP which hooks into the \fBOPENVPN_PLUGIN_CLIENT_CONNECT\fP
+or \fBOPENVPN_PLUGIN_CLIENT_CONNECT_V2\fP calls. This option provides a
+possibility to replace the clients password with an authentication token
+during the lifetime of the OpenVPN client.
+.sp
+Whenever the connection is renegotiated and the
+\fB\-\-auth\-user\-pass\-verify\fP script or \fB\-\-plugin\fP making use of the
+\fBOPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY\fP 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 \fBAUTH_FAILED\fP and disconnect.
+.sp
+The purpose of this is to enable two factor authentication methods, such
+as HOTP or TOTP, to be used without needing to retrieve 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 during the life time of the session.
+.sp
+To make use of this feature, the \fB\-\-client\-connect\fP script or
+\fB\-\-plugin\fP needs to put
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+push "auth\-token UNIQUE_TOKEN_VALUE"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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 \fBUNIQUE_TOKEN_VALUE\fP\&.
+.sp
+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 \fB\-\-auth\-retry\fP
+.TP
+.B \-\-auth\-user\-pass
+Authenticate with server using username/password.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+auth\-user\-pass
+auth\-user\-pass up
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If \fBup\fP is present, it must be a file containing username/password on 2
+lines. If the password line is missing, OpenVPN will prompt for one.
+.sp
+If \fBup\fP is omitted, username/password will be prompted from the
+console.
+.sp
+The server configuration must specify an \fB\-\-auth\-user\-pass\-verify\fP
+script to verify the username/password provided by the client.
+.TP
+.BI \-\-auth\-retry \ type
+Controls how OpenVPN responds to username/password verification errors
+such as the client\-side response to an \fBAUTH_FAILED\fP message from
+the server or verification failure of the private key password.
+.sp
+Normally used to prevent auth errors from being fatal on the client
+side, and to permit username/password requeries in case of error.
+.sp
+An \fBAUTH_FAILED\fP message is generated by the server if the client
+fails \fB\-\-auth\-user\-pass\fP authentication, or if the server\-side
+\fB\-\-client\-connect\fP script returns an error status when the client
+tries to connect.
+.sp
+\fBtype\fP can be one of:
+.INDENT 7.0
+.TP
+.B \fBnone\fP
+Client will exit with a fatal error (this is the default).
+.TP
+.B \fBnointeract\fP
+Client will retry the connection without requerying
+for an \fB\-\-auth\-user\-pass\fP username/password. Use this option for
+unattended clients.
+.TP
+.B \fBinteract\fP
+Client will requery for an \fB\-\-auth\-user\-pass\fP
+username/password and/or private key password before attempting a
+reconnection.
+.UNINDENT
+.sp
+Note that while this option cannot be pushed, it can be controlled from
+the management interface.
+.TP
+.B \-\-client
+A helper directive designed to simplify the configuration of OpenVPN\(aqs
+client mode. This directive is equivalent to:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pull
+tls\-client
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-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.
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+client\-nat snat 192.168.0.0/255.255.0.0
+client\-nat dnat 10.64.0.0/255.255.0.0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBnetwork/netmask\fP (for example \fB192.168.0.0/255.255.0.0\fP) defines
+the local view of a resource from the client perspective, while
+\fBalias/netmask\fP (for example \fB10.64.0.0/255.255.0.0\fP) defines the
+remote view from the server perspective.
+.sp
+Use \fBsnat\fP (source NAT) for resources owned by the client and
+\fBdnat\fP (destination NAT) for remote resources.
+.sp
+Set \fB\-\-verb 6\fP for debugging info showing the transformation of
+src/dest addresses in packets.
+.TP
+.BI \-\-connect\-retry \ n
+Wait \fBn\fP seconds between connection attempts (default \fB5\fP).
+Repeated reconnection attempts are slowed down after 5 retries per
+remote by doubling the wait time after each unsuccessful attempt. An
+optional argument \fBmax\fP specifies the maximum value of wait time in
+seconds at which it gets capped (default \fB300\fP).
+.TP
+.BI \-\-connect\-retry\-max \ n
+\fBn\fP specifies the number of times each \fB\-\-remote\fP or
+\fB<connection>\fP entry is tried. Specifying \fBn\fP as \fB1\fP would try
+each entry exactly once. A successful connection resets the counter.
+(default \fIunlimited\fP).
+.TP
+.BI \-\-connect\-timeout \ n
+See \fB\-\-server\-poll\-timeout\fP\&.
+.TP
+.BI \-\-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.
+.sp
+The \fBn\fP parameter (default \fB1\fP if not present) controls the
+maximum number of attempts that the client will try to resend the exit
+notification message.
+.sp
+In UDP server mode, send \fBRESTART\fP control channel command to
+connected clients. The \fBn\fP parameter (default \fB1\fP if not present)
+controls client behavior. With \fBn\fP = \fB1\fP client will attempt to
+reconnect to the same server, with \fBn\fP = \fB2\fP client will advance
+to the next server.
+.sp
+OpenVPN will not send any exit notifications unless this option is
+enabled.
+.TP
+.BI \-\-inactive \ args
+Causes OpenVPN to exit after \fBn\fP 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.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+inactive n
+inactive n bytes
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If the optional \fBbytes\fP parameter is included, exit if less than
+\fBbytes\fP of combined in/out traffic are produced on the tun/tap device
+in \fBn\fP seconds.
+.sp
+In any case, OpenVPN\(aqs internal ping packets (which are just keepalives)
+and TLS control packets are not considered "activity", nor are they
+counted as traffic, as they are used internally by OpenVPN and are not
+an indication of actual user activity.
+.TP
+.BI \-\-proto\-force \ p
+When iterating through connection profiles, only consider profiles using
+protocol \fBp\fP (\fBtcp\fP | \fBudp\fP).
+.TP
+.B \-\-pull
+This option must be used on a client which is connecting to a
+multi\-client server. It indicates to OpenVPN that it should accept
+options pushed by the server, provided they are part of the legal set of
+pushable options (note that the \fB\-\-pull\fP option is implied by
+\fB\-\-client\fP ).
+.sp
+In particular, \fB\-\-pull\fP allows the server to push routes to the
+client, so you should not use \fB\-\-pull\fP or \fB\-\-client\fP in situations
+where you don\(aqt trust the server to have control over the client\(aqs
+routing table.
+.TP
+.BI \-\-pull\-filter \ args
+Filter options on the client pushed by the server to the client.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pull\-filter accept text
+pull\-filter ignore text
+pull\-filter reject text
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Filter options received from the server if the option starts with
+\fBtext\fP\&.  The action flag \fBaccept\fP allows the option,
+\fBignore\fP removes it and \fBreject\fP flags an error and triggers
+a \fBSIGUSR1\fP 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.
+.sp
+Prefix comparison is used to match \fBtext\fP against the received option so
+that
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pull\-filter ignore "route"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+would remove all pushed options starting with \fBroute\fP which would
+include, for example, \fBroute\-gateway\fP\&. Enclose \fItext\fP in quotes to
+embed spaces.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pull\-filter accept "route 192.168.1."
+pull\-filter ignore "route "
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+would remove all routes that do not start with \fB192.168.1\fP\&.
+.sp
+\fINote\fP that \fBreject\fP 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 \fBignore\fP\&.
+.TP
+.BI \-\-remote \ args
+Remote host name or IP address.  It supports two additional optional
+arguments: \fBport\fP and \fBproto\fP\&.  On the client, multiple \fB\-\-remote\fP
+options may be specified for redundancy, each referring to a different
+OpenVPN server. Specifying multiple \fB\-\-remote\fP options for this
+purpose is a special case of the more general connection\-profile
+feature. See the \fB<connection>\fP documentation below.
+.sp
+The OpenVPN client will try to connect to a server at \fBhost:port\fP in
+the order specified by the list of \fB\-\-remote\fP options.
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+remote server.example.net
+remote server.example.net 1194
+remote server.example.net tcp
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBproto\fP indicates the protocol to use when connecting with the remote,
+and may be \fBtcp\fP or \fBudp\fP\&.
+.sp
+For forcing IPv4 or IPv6 connection suffix tcp or udp with 4/6 like
+udp4/udp6/tcp4/tcp6.
+.sp
+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.
+.sp
+Note that since UDP is connectionless, connection failure is defined by
+the \fB\-\-ping\fP and \fB\-\-ping\-restart\fP options.
+.sp
+Note the following corner case: If you use multiple \fB\-\-remote\fP
+options, AND you are dropping root privileges on the client with
+\fB\-\-user\fP and/or \fB\-\-group\fP 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 settings, 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.
+.sp
+If \fB\-\-remote\fP 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 authentication 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).
+.sp
+When used in TCP mode, \fB\-\-remote\fP will act as a filter, rejecting
+connections from any host which does not match \fBhost\fP\&.
+.sp
+If \fBhost\fP 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 protocol
+specification (4/6 suffix), OpenVPN will try both IPv4 and IPv6
+addresses, in the order getaddrinfo() returns them.
+.TP
+.B \-\-remote\-random
+When multiple \fB\-\-remote\fP address/ports are specified, or if connection
+profiles are being used, initially randomize the order of the list as a
+kind of basic load\-balancing measure.
+.TP
+.B \-\-remote\-random\-hostname
+Prepend a random string (6 bytes, 12 hex characters) to hostname to
+prevent DNS caching. For example, "foo.bar.gov" would be modified to
+"<random\-chars>.foo.bar.gov".
+.TP
+.BI \-\-resolv\-retry \ n
+If hostname resolve fails for \fB\-\-remote\fP, retry resolve for \fBn\fP
+seconds before failing.
+.sp
+Set \fBn\fP to "infinite" to retry indefinitely.
+.sp
+By default, \fB\-\-resolv\-retry infinite\fP is enabled. You can disable by
+setting n=0.
+.TP
+.B \-\-single\-session
+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.
+.sp
+If the daemon is reset by a signal or \fB\-\-ping\-restart\fP, it will allow
+one new connection.
+.sp
+\fB\-\-single\-session\fP can be used with \fB\-\-ping\-exit\fP or \fB\-\-inactive\fP
+to create a single dynamic session that will exit when finished.
+.TP
+.BI \-\-server\-poll\-timeout \ n
+When connecting to a remote server do not wait for more than \fBn\fP
+seconds for a response before trying the next server. The default value
+is 120s. This timeout includes proxy and TCP connect timeouts.
+.TP
+.BI \-\-static\-challenge \ args
+Enable static challenge/response protocol
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+static\-challenge text echo
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBtext\fP challenge text is presented to the user which describes what
+information is requested.  The \fBecho\fP flag indicates if the user\(aqs
+input should be echoed on the screen.  Valid \fBecho\fP values are
+\fB0\fP or \fB1\fP\&.
+.sp
+See management\-notes.txt in the OpenVPN distribution for a description of
+the OpenVPN challenge/response protocol.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-show\-proxy\-settings
+Show sensed HTTP or SOCKS proxy settings. Currently, only Windows
+clients support this option.
+.TP
+.BI \-\-http\-proxy \ args
+Connect to remote host through an HTTP proxy.  This requires at least an
+address \fBserver\fP and \fBport\fP argument.  If HTTP Proxy\-Authenticate
+is required, a file name to an \fBauthfile\fP file containing a username
+and password on 2 lines can be given, or \fBstdin\fP to prompt from
+console. Its content can also be specified in the config file with the
+\fB\-\-http\-proxy\-user\-pass\fP option. (See section on inline files)
+.sp
+The last optional argument is an \fBauth\-method\fP which should be one
+of \fBnone\fP, \fBbasic\fP, or \fBntlm\fP\&.
+.sp
+HTTP Digest authentication is supported as well, but only via the
+\fBauto\fP or \fBauto\-nct\fP flags (below).  This must replace
+the \fBauthfile\fP argument.
+.sp
+The \fBauto\fP flag causes OpenVPN to automatically determine the
+\fBauth\-method\fP and query stdin or the management interface for
+username/password credentials, if required. This flag exists on OpenVPN
+2.1 or higher.
+.sp
+The \fBauto\-nct\fP flag (no clear\-text auth) instructs OpenVPN to
+automatically determine the authentication method, but to reject weak
+authentication protocols such as HTTP Basic Authentication.
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+http\-proxy proxy.example.net 3128
+http\-proxy proxy.example.net 3128 authfile.txt
+http\-proxy proxy.example.net 3128 stdin
+http\-proxy proxy.example.net 3128 auto basic
+http\-proxy proxy.example.net 3128 auto\-nct ntlm
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-http\-proxy\-option \ args
+Set extended HTTP proxy options. Requires an option \fBtype\fP as argument
+and an optional \fBparameter\fP to the type.  Repeat to set multiple
+options.
+.INDENT 7.0
+.TP
+.B \fBVERSION\fP \fBversion\fP
+Set HTTP version number to \fBversion\fP (default \fB1.0\fP).
+.TP
+.B \fBAGENT\fP \fBuser\-agent\fP
+Set HTTP "User\-Agent" string to \fBuser\-agent\fP\&.
+.TP
+.B \fBCUSTOM\-HEADER\fP \fBname\fP \fBcontent\fP
+Adds the custom Header with \fBname\fP as name and \fBcontent\fP as
+the content of the custom HTTP header.
+.UNINDENT
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+http\-proxy\-option VERSION 1.1
+http\-proxy\-option AGENT OpenVPN/2.4
+http\-proxy\-option X\-Proxy\-Flag some\-flags
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-socks\-proxy \ args
+Connect to remote host through a Socks5 proxy.  A required \fBserver\fP
+argument is needed.  Optionally a \fBport\fP (default \fB1080\fP) and
+\fBauthfile\fP can be given.  The \fBauthfile\fP is a file containing a
+username and password on 2 lines, or \fBstdin\fP can be used to
+prompt from console.
+.UNINDENT
+.SS Server Options
+.sp
+Starting with OpenVPN 2.0, a multi\-client TCP/UDP server mode is
+supported, and can be enabled with the \fB\-\-mode server\fP option. In
+server mode, OpenVPN will listen on a single port for incoming client
+connections. 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.
+.INDENT 0.0
+.TP
+.BI \-\-auth\-gen\-token \ args
+Returns an authentication token to successfully authenticated clients.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+auth\-gen\-token [lifetime] [external\-auth]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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 renegotiations, 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 authentications against configured external user/password
+authentication mechanisms.
+.sp
+The tokens implemented by this mechanism include an initial timestamp and
+a renew timestamp and are secured by HMAC.
+.sp
+The \fBlifetime\fP 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 \fB0\fP, the token will never expire.
+.sp
+The token will expire either after the configured \fBlifetime\fP of the
+token is reached or after not being renewed for more than 2 *
+\fBreneg\-sec\fP seconds. Clients will be sent renewed tokens on every TLS
+renogiation to keep the client\(aqs token updated. This is done to
+invalidate a token if a client is disconnected for a sufficently long
+time, while at the same time permitting much longer token lifetimes for
+active clients.
+.sp
+This feature is useful for environments which are configured to use One
+Time Passwords (OTP) as part of the user/password authentications and
+that authentication mechanism does not implement any auth\-token support.
+.sp
+When the \fBexternal\-auth\fP keyword is present the normal
+authentication method will always be called even if auth\-token succeeds.
+Normally other authentications method are skipped if auth\-token
+verification suceeds or fails.
+.sp
+This option postpones this decision to the external authentication
+methods and checks the validity of the account and do other checks.
+.sp
+In this mode the environment will have a \fBsession_id\fP variable that
+holds the session id from auth\-gen\-token. Also an environment variable
+\fBsession_state\fP is present. This variable indicates whether the
+auth\-token has succeeded or not. It can have the following values:
+.INDENT 7.0
+.TP
+.B \fBInitial\fP
+No token from client.
+.TP
+.B \fBAuthenticated\fP
+Token is valid and not expired.
+.TP
+.B \fBExpired\fP
+Token is valid but has expired.
+.TP
+.B \fBInvalid\fP
+Token is invalid (failed HMAC or wrong length)
+.TP
+.B \fBAuthenticatedEmptyUser\fP / \fBExpiredEmptyUser\fP
+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 workaround is not needed these two cases should
+be handled in the same way as \fBInvalid\fP\&.
+.UNINDENT
+.sp
+\fBWarning:\fP Use this feature only if you want your authentication
+method called on every verification. Since the external authentication
+is called it needs to also indicate a success or failure 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 certificate), otherwise returning success
+will lead to authentication bypass (as does returning success on a wrong
+password from a script).
+.TP
+.BI \-\-auth\-gen\-token\-secret \ file
+Specifies a file that holds a secret for the HMAC used in
+\fB\-\-auth\-gen\-token\fP If \fBfile\fP 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 auth\-token.
+.TP
+.B \-\-auth\-user\-pass\-optional
+Allow connections by clients that do not specify a username/password.
+Normally, when \fB\-\-auth\-user\-pass\-verify\fP or
+\fB\-\-management\-client\-auth\fP 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, passing the responsibility to the
+user\-defined authentication module/script to accept or deny the client
+based on other factors (such as the setting of X509 certificate fields).
+When this option is used, and a connecting client does not submit a
+username/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.
+.TP
+.B \-\-ccd\-exclusive
+Require, as a condition of authentication, that a connecting client has
+a \fB\-\-client\-config\-dir\fP file.
+.TP
+.BI \-\-client\-config\-dir \ dir
+Specify a directory \fBdir\fP 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\(aqs 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 readable by the OpenVPN process after it has
+dropped it\(aqs root privileges.
+.sp
+This file can specify a fixed IP address for a given client using
+\fB\-\-ifconfig\-push\fP, as well as fixed subnets owned by the client using
+\fB\-\-iroute\fP\&.
+.sp
+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.
+.sp
+The following options are legal in a client\-specific context: \fB\-\-push\fP,
+\fB\-\-push\-reset\fP, \fB\-\-push\-remove\fP, \fB\-\-iroute\fP, \fB\-\-ifconfig\-push\fP,
+\fB\-\-vlan\-pvid\fP and \fB\-\-config\fP\&.
+.TP
+.B \-\-client\-to\-client
+Because the OpenVPN server mode handles multiple clients through a
+single tun or tap interface, it is effectively a router. The
+\fB\-\-client\-to\-client\fP flag tells OpenVPN to internally route
+client\-to\-client traffic rather than pushing all client\-originating
+traffic to the TUN/TAP interface.
+.sp
+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\(aqt use this option if you want to firewall tunnel traffic
+using custom, per\-client rules.
+.TP
+.B \-\-disable
+Disable a particular client (based on the common name) from connecting.
+Don\(aqt use this option to disable a client due to key or password
+compromise. Use a CRL (certificate revocation list) instead (see the
+\fB\-\-crl\-verify\fP option).
+.sp
+This option must be associated with a specific client instance, which
+means that it must be specified either in a client instance config file
+using \fB\-\-client\-config\-dir\fP or dynamically generated using a
+\fB\-\-client\-connect\fP script.
+.TP
+.BI \-\-connect\-freq \ args
+Allow a maximum of \fBn\fP new connections per \fBsec\fP seconds from
+clients.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+connect\-freq n sec
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This is designed to contain DoS attacks which flood the server
+with connection requests using certificates which will ultimately fail
+to authenticate.
+.sp
+This is an imperfect solution however, because in a real DoS scenario,
+legitimate connections might also be refused.
+.sp
+For the best protection against DoS attacks in server mode, use
+\fB\-\-proto udp\fP and either \fB\-\-tls\-auth\fP or \fB\-\-tls\-crypt\fP\&.
+.TP
+.B \-\-duplicate\-cn
+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.
+.TP
+.BI \-\-ifconfig\-pool \ args
+Set aside a pool of subnets to be dynamically allocated to connecting
+clients, similar to a DHCP server.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ifconfig\-pool start\-IP end\-IP [netmask]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For tun\-style tunnels, each client
+will be given a /30 subnet (for interoperability with Windows clients).
+For tap\-style tunnels, individual addresses will be allocated, and the
+optional \fBnetmask\fP parameter will also be pushed to clients.
+.TP
+.BI \-\-ifconfig\-ipv6\-pool \ args
+Specify an IPv6 address pool for dynamic assignment to clients.
+.sp
+Valid args:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ifconfig\-ipv6\-pool ipv6addr/bits
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The pool starts at \fBipv6addr\fP and matches the offset determined from
+the start of the IPv4 pool.
+.TP
+.BI \-\-ifconfig\-pool\-persist \ args
+Persist/unpersist ifconfig\-pool data to \fBfile\fP, at \fBseconds\fP
+intervals (default \fB600\fP), as well as on program startup and shutdown.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ifconfig\-pool\-persist file [seconds]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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 \fB\-\-persist\-tun\fP option.
+.sp
+\fBfile\fP is a comma\-delimited ASCII file, formatted as
+\fB<Common\-Name>,<IP\-address>\fP\&.
+.sp
+If \fBseconds\fP = \fB0\fP, \fBfile\fP will be treated as read\-only. This
+is useful if you would like to treat \fBfile\fP as a configuration file.
+.sp
+Note that the entries in this file are treated by OpenVPN as
+\fIsuggestions\fP only, based on past associations between a common name and
+IP address.  They do not guarantee that the given common name will always
+receive the given IP address. If you want guaranteed assignment, use
+\fB\-\-ifconfig\-push\fP
+.TP
+.BI \-\-ifconfig\-push \ args
+Push virtual IP endpoints for client tunnel, overriding the
+\fB\-\-ifconfig\-pool\fP dynamic allocation.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ifconfig\-push local remote\-netmask [alias]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The parameters \fBlocal\fP and \fBremote\-netmask\fP are set according to the
+\fB\-\-ifconfig\fP directive which you want to execute on the client machine
+to configure the remote end of the tunnel. Note that the parameters
+\fBlocal\fP and \fBremote\-netmask\fP 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.
+.sp
+The optional \fBalias\fP 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 \fBlocal/remote\-netmask\fP will refer to the server view while
+\fBalias/remote\-netmask\fP will refer to the client view.
+.sp
+This option must be associated with a specific client instance, which
+means that it must be specified either in a client instance config file
+using \fB\-\-client\-config\-dir\fP or dynamically generated using a
+\fB\-\-client\-connect\fP script.
+.sp
+Remember also to include a \fB\-\-route\fP directive in the main OpenVPN
+config file which encloses \fBlocal\fP, so that the kernel will know to
+route it to the server\(aqs TUN/TAP interface.
+.sp
+OpenVPN\(aqs internal client IP address selection algorithm works as
+follows:
+.INDENT 7.0
+.IP 1. 3
+Use \fB\-\-client\-connect script\fP generated file for static IP
+(first choice).
+.IP 2. 3
+Use \fB\-\-client\-config\-dir\fP file for static IP (next choice).
+.IP 3. 3
+Use \fB\-\-ifconfig\-pool\fP allocation for dynamic IP (last
+choice).
+.UNINDENT
+.TP
+.BI \-\-ifconfig\-ipv6\-push \ args
+for \fB\-\-client\-config\-dir\fP per\-client static IPv6 interface
+configuration, see \fB\-\-client\-config\-dir\fP and \fB\-\-ifconfig\-push\fP for
+more details.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ifconfig\-ipv6\-push ipv6addr/bits ipv6remote
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-inetd \ args
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+inetd
+inetd wait
+inetd nowait
+inetd wait progname
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Use this option when OpenVPN is being run from the inetd or \fBxinetd\fP(8)
+server.
+.sp
+The \fBwait\fP and \fBnowait\fP option must match what is specified
+in the inetd/xinetd config file. The \fBnowait\fP mode can only be used
+with \fB\-\-proto tcp\-server\fP The default is \fBwait\fP\&.  The
+\fBnowait\fP mode can be used to instantiate the OpenVPN daemon as a
+classic TCP server, where client connection requests are serviced on a
+single port number. For additional information on this kind of
+configuration, see the OpenVPN FAQ:
+\fI\%https://community.openvpn.net/openvpn/wiki/325\-openvpn\-as\-a\-\-forking\-tcp\-server\-which\-can\-service\-multiple\-clients\-over\-a\-single\-tcp\-port\fP
+.sp
+This option precludes the use of \fB\-\-daemon\fP, \fB\-\-local\fP or
+\fB\-\-remote\fP\&.  Note that this option causes message and error output to
+be handled in the same way as the \fB\-\-daemon\fP option. The optional
+\fBprogname\fP parameter is also handled exactly as in \fB\-\-daemon\fP\&.
+.sp
+Also note that in \fBwait\fP mode, each OpenVPN tunnel requires a separate
+TCP/UDP port and a separate inetd or xinetd entry. See the OpenVPN 1.x
+HOWTO for an example on using OpenVPN with xinetd:
+\fI\%https://openvpn.net/community\-resources/1xhowto/\fP
+.TP
+.B \-\-multihome
+Configure a multi\-homed UDP server. This option needs to be used when a
+server has more than one IP address (e.g. multiple interfaces, or
+secondary IP addresses), and is not using \fB\-\-local\fP to force binding
+to one specific address only. This option will add some extra lookups to
+the packet path to ensure that the UDP reply 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\(aqs not enabled by
+default.
+.INDENT 7.0
+.TP
+.B \fINotes:\fP
+.INDENT 7.0
+.IP \(bu 2
+This option is only relevant for UDP servers.
+.IP \(bu 2
+If you do an IPv6+IPv4 dual\-stack bind on a Linux machine 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).
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-iroute \ args
+Generate an internal route to a specific client. The \fBnetmask\fP
+parameter, if omitted, defaults to \fB255.255.255.255\fP\&.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+iroute network [netmask]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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 \fB\-\-route\fP directive). The reason why two
+routes are needed is that the \fB\-\-route\fP directive routes the packet
+from the kernel to OpenVPN. Once in OpenVPN, the \fB\-\-iroute\fP directive
+routes to the specific client.
+.sp
+This option must be specified either in a client instance config file
+using \fB\-\-client\-config\-dir\fP or dynamically generated using a
+\fB\-\-client\-connect\fP script.
+.sp
+The \fB\-\-iroute\fP directive also has an important interaction with
+\fB\-\-push "route ..."\fP\&. \fB\-\-iroute\fP essentially defines a subnet which
+is owned by a particular client (we will call this client \fIA\fP). If you
+would like other clients to be able to reach \fIA\fP\(aqs subnet, you can use
+\fB\-\-push "route ..."\fP together with \fB\-\-client\-to\-client\fP to effect
+this. In order for all clients to see \fIA\fP\(aqs subnet, OpenVPN must push
+this route to all clients EXCEPT for \fIA\fP, since the subnet is already
+owned by \fIA\fP\&. OpenVPN accomplishes this by not not pushing a route to
+a client if it matches one of the client\(aqs iroutes.
+.TP
+.BI \-\-iroute\-ipv6 \ args
+for \fB\-\-client\-config\-dir\fP per\-client static IPv6 route configuration,
+see \fB\-\-iroute\fP for more details how to setup and use this, and how
+\fB\-\-iroute\fP and \fB\-\-route\fP interact.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+iroute\-ipv6 ipv6addr/bits
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-max\-clients \ n
+Limit server to a maximum of \fBn\fP concurrent clients.
+.TP
+.BI \-\-max\-routes\-per\-client \ n
+Allow a maximum of \fBn\fP internal routes per client (default
+\fB256\fP). This is designed to help contain DoS attacks where an
+authenticated 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 directive can be used
+in a \fB\-\-client\-config\-dir\fP file or auto\-generated by a
+\fB\-\-client\-connect\fP script to override the global value for a particular
+client.
+.sp
+Note that this directive affects OpenVPN\(aqs internal routing table, not
+the kernel routing table.
+.TP
+.B \-\-opt\-verify
+Clients that connect with options that are incompatible with those of the
+server will be disconnected.
+.sp
+Options that will be compared for compatibility include \fBdev\-type\fP,
+\fBlink\-mtu\fP, \fBtun\-mtu\fP, \fBproto\fP, \fBifconfig\fP,
+\fBcomp\-lzo\fP, \fBfragment\fP, \fBkeydir\fP, \fBcipher\fP,
+\fBauth\fP, \fBkeysize\fP, \fBsecret\fP, \fBno\-replay\fP,
+\fBtls\-auth\fP, \fBkey\-method\fP, \fBtls\-server\fP
+and \fBtls\-client\fP\&.
+.sp
+This option requires that \fB\-\-disable\-occ\fP NOT be used.
+.TP
+.BI \-\-port\-share \ args
+Share OpenVPN TCP with another service
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+port\-share host port [dir]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When run in TCP server mode, share the OpenVPN port with another
+application, such as an HTTPS server. If OpenVPN senses a connection to
+its port which is using a non\-OpenVPN protocol, it will proxy the
+connection to the server at \fBhost\fP:\fBport\fP\&. Currently only designed to
+work with HTTP/HTTPS, though it would be theoretically possible to
+extend to other protocols such as ssh.
+.sp
+\fBdir\fP 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 dictionary by the proxy receiver to determine
+the origin of the connection. Each generated file will be automatically
+deleted when the proxied connection is torn down.
+.sp
+Not implemented on Windows.
+.TP
+.BI \-\-push \ option
+Push a config file option back to the client for remote execution. Note
+that \fBoption\fP must be enclosed in double quotes (\fB""\fP). The
+client must specify \fB\-\-pull\fP 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.
+.sp
+This is a partial list of options which can currently be pushed:
+\fB\-\-route\fP, \fB\-\-route\-gateway\fP, \fB\-\-route\-delay\fP,
+\fB\-\-redirect\-gateway\fP, \fB\-\-ip\-win32\fP, \fB\-\-dhcp\-option\fP,
+\fB\-\-inactive\fP, \fB\-\-ping\fP, \fB\-\-ping\-exit\fP, \fB\-\-ping\-restart\fP,
+\fB\-\-setenv\fP, \fB\-\-auth\-token\fP, \fB\-\-persist\-key\fP, \fB\-\-persist\-tun\fP,
+\fB\-\-echo\fP, \fB\-\-comp\-lzo\fP, \fB\-\-socket\-flags\fP, \fB\-\-sndbuf\fP,
+\fB\-\-rcvbuf\fP
+.TP
+.B \-\-push\-peer\-info
+Push additional information about the client to server. The following
+data is always pushed to the server:
+.INDENT 7.0
+.TP
+.B \fBIV_VER=<version>\fP
+The client OpenVPN version
+.TP
+.B \fBIV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]\fP
+The client OS platform
+.TP
+.B \fBIV_LZO_STUB=1\fP
+If client was built with LZO stub capability
+.TP
+.B \fBIV_LZ4=1\fP
+If the client supports LZ4 compressions.
+.TP
+.B \fBIV_PROTO\fP
+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:
+.INDENT 7.0
+.IP \(bu 2
+bit 1: The peer supports peer\-id floating mechanism
+.IP \(bu 2
+bit 2: The client expects a push\-reply and the server may
+send this reply without waiting for a push\-request first.
+.UNINDENT
+.TP
+.B \fBIV_NCP=2\fP
+Negotiable ciphers, client supports \fB\-\-cipher\fP pushed by
+the server, a value of 2 or greater indicates client supports
+\fIAES\-GCM\-128\fP and \fIAES\-GCM\-256\fP\&.
+.TP
+.B \fBIV_CIPHERS=<ncp\-ciphers>\fP
+The client announces the list of supported ciphers configured with the
+\fB\-\-data\-ciphers\fP option to the server.
+.TP
+.B \fBIV_GUI_VER=<gui_id> <version>\fP
+The UI version of a UI if one is running, for example
+\fBde.blinkt.openvpn 0.5.47\fP for the Android app.
+.UNINDENT
+.sp
+When \fB\-\-push\-peer\-info\fP is enabled the additional information consists
+of the following data:
+.INDENT 7.0
+.TP
+.B \fBIV_HWADDR=<mac address>\fP
+The MAC address of clients default gateway
+.TP
+.B \fBIV_SSL=<version string>\fP
+The ssl version used by the client, e.g.
+\fBOpenSSL 1.0.2f 28 Jan 2016\fP\&.
+.TP
+.B \fBIV_PLAT_VER=x.y\fP
+The version of the operating system, e.g. 6.1 for Windows 7.
+.TP
+.B \fBUV_<name>=<value>\fP
+Client environment variables whose names start with
+\fBUV_\fP
+.UNINDENT
+.TP
+.BI \-\-push\-remove \ opt
+Selectively remove all \fB\-\-push\fP options matching "opt" from the option
+list for a client. \fBopt\fP is matched as a substring against the whole
+option string to\-be\-pushed to the client, so \fB\-\-push\-remove route\fP
+would remove all \fB\-\-push route ...\fP and \fB\-\-push route\-ipv6 ...\fP
+statements, while \fB\-\-push\-remove "route\-ipv6 2001:"\fP would only remove
+IPv6 routes for \fB2001:...\fP networks.
+.sp
+\fB\-\-push\-remove\fP can only be used in a client\-specific context, like in
+a \fB\-\-client\-config\-dir\fP file, or \fB\-\-client\-connect\fP script or plugin
+\-\- similar to \fB\-\-push\-reset\fP, just more selective.
+.sp
+\fINOTE\fP: to \fIchange\fP an option, \fB\-\-push\-remove\fP can be used to first
+remove the old value, and then add a new \fB\-\-push\fP option with the new
+value.
+.sp
+\fINOTE 2\fP: due to implementation details, \(aqifconfig\(aq and \(aqifconfig\-ipv6\(aq
+can only be removed with an exact match on the option (
+\fBpush\-remove ifconfig\fP), no substring matching and no matching on
+the IPv4/IPv6 address argument is possible.
+.TP
+.B \-\-push\-reset
+Don\(aqt inherit the global push list for a specific client instance.
+Specify this option in a client\-specific context such as with a
+\fB\-\-client\-config\-dir\fP configuration file. This option will ignore
+\fB\-\-push\fP options at the global config file level.
+.TP
+.BI \-\-server \ args
+A helper directive designed to simplify the configuration of OpenVPN\(aqs
+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 \fB\&.1\fP address of the given network for
+use as the server\-side endpoint of the local TUN/TAP interface. If the
+optional \fBnopool\fP flag is given, no dynamic IP address pool will
+prepared for VPN clients.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+server network netmask [nopool]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For example, \fB\-\-server 10.8.0.0 255.255.255.0\fP expands as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+mode server
+tls\-server
+push "topology [topology]"
+
+if dev tun AND (topology == net30 OR topology == p2p):
+  ifconfig 10.8.0.1 10.8.0.2
+  if !nopool:
+    ifconfig\-pool 10.8.0.4 10.8.0.251
+  route 10.8.0.0 255.255.255.0
+  if client\-to\-client:
+    push "route 10.8.0.0 255.255.255.0"
+  else if topology == net30:
+    push "route 10.8.0.1"
+
+if dev tap OR (dev tun AND topology == subnet):
+  ifconfig 10.8.0.1 255.255.255.0
+  if !nopool:
+    ifconfig\-pool 10.8.0.2 10.8.0.253 255.255.255.0
+  push "route\-gateway 10.8.0.1"
+  if route\-gateway unset:
+    route\-gateway 10.8.0.2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Don\(aqt use \fB\-\-server\fP if you are ethernet bridging. Use
+\fB\-\-server\-bridge\fP instead.
+.TP
+.BI \-\-server\-bridge \ args
+A helper directive similar to \fB\-\-server\fP which is designed to simplify
+the configuration of OpenVPN\(aqs server mode in ethernet bridging
+configurations.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+server\-bridge gateway netmask pool\-start\-IP pool\-end\-IP
+server\-bridge [nogw]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If \fB\-\-server\-bridge\fP is used without any parameters, it will enable 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 \fBnogw\fP flag (advanced) indicates that gateway
+information should not be pushed to the client.
+.sp
+To configure ethernet bridging, you must first use your OS\(aqs bridging
+capability to bridge the TAP interface with the ethernet NIC interface.
+For example, on Linux this is done with the \fBbrctl\fP tool, and with
+Windows XP it is done in the Network Connections Panel by selecting the
+ethernet and TAP adapters and right\-clicking on "Bridge Connections".
+.sp
+Next you you must manually set the IP/netmask on the bridge interface.
+The \fBgateway\fP and \fBnetmask\fP parameters to \fB\-\-server\-bridge\fP can be
+set to either the IP/netmask of the bridge interface, or the IP/netmask
+of the default gateway/router on the bridged subnet.
+.sp
+Finally, set aside a IP range in the bridged subnet, denoted by
+\fBpool\-start\-IP\fP and \fBpool\-end\-IP\fP, for OpenVPN to allocate to
+connecting clients.
+.sp
+For example, \fBserver\-bridge 10.8.0.4 255.255.255.0 10.8.0.128
+10.8.0.254\fP expands as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+mode server
+tls\-server
+
+ifconfig\-pool 10.8.0.128 10.8.0.254 255.255.255.0
+push "route\-gateway 10.8.0.4"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In another example, \fB\-\-server\-bridge\fP (without parameters) expands as
+follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+mode server
+tls\-server
+
+push "route\-gateway dhcp"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Or \fB\-\-server\-bridge nogw\fP expands as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+mode server
+tls\-server
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-stale\-routes\-check \ args
+Remove routes which haven\(aqt had activity for \fBn\fP seconds (i.e. the ageing
+time).  This check is run every \fBt\fP seconds (i.e. check interval).
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+stale\-routes\-check n [t]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If \fBt\fP is not present it defaults to \fBn\fP\&.
+.sp
+This option helps to keep the dynamic routing table small. See also
+\fB\-\-max\-routes\-per\-client\fP
+.TP
+.B \-\-username\-as\-common\-name
+For \fB\-\-auth\-user\-pass\-verify\fP authentication, use the authenticated
+username as the common name, rather than the common name from the client
+cert.
+.TP
+.BI \-\-verify\-client\-cert \ mode
+Specify whether the client is required to supply a valid certificate.
+.sp
+Possible \fBmode\fP options are:
+.INDENT 7.0
+.TP
+.B \fBnone\fP
+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 certificates from all
+clients.
+.sp
+If you use this directive, the entire responsibility of authentication
+will rest on your \fB\-\-auth\-user\-pass\-verify\fP script, so keep in mind
+that bugs in your script could potentially compromise the security of
+your VPN.
+.sp
+\fB\-\-verify\-client\-cert none\fP is functionally equivalent to
+\fB\-\-client\-cert\-not\-required\fP\&.
+.TP
+.B \fBoptional\fP
+A client may present a certificate but it is not required to do so.
+When using this directive, you should also use a
+\fB\-\-auth\-user\-pass\-verify\fP script to ensure that clients are
+authenticated using a certificate, a username and password, or
+possibly even both.
+.sp
+Again, the entire responsibility of authentication will rest on your
+\fB\-\-auth\-user\-pass\-verify\fP script, so keep in mind that bugs in your
+script could potentially compromise the security of your VPN.
+.TP
+.B \fBrequire\fP
+This is the default option. A client is required to present a
+certificate, otherwise VPN access is refused.
+.UNINDENT
+.sp
+If you don\(aqt use this directive (or use \fB\-\-verify\-client\-cert require\fP)
+but you also specify an \fB\-\-auth\-user\-pass\-verify\fP script, then OpenVPN
+will perform double authentication. The client certificate verification
+AND the \fB\-\-auth\-user\-pass\-verify\fP script will need to succeed in order
+for a client to be authenticated and accepted onto the VPN.
+.TP
+.B \-\-vlan\-tagging
+Server\-only option. Turns the OpenVPN server instance into a switch that
+understands VLAN\-tagging, based on IEEE 802.1Q.
+.sp
+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
+\fB\-\-vlan\-accept\fP setting.
+.sp
+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 "untagged".
+.sp
+Using the \fB\-\-vlan\-pvid v\fP 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 \fB\-\-client\-to\-client\fP is activated.
+.sp
+The packet filtering takes place in the OpenVPN server. Clients should
+not have any VLAN tagging configuration applied.
+.sp
+The \fB\-\-vlan\-tagging\fP option is off by default. While turned off,
+OpenVPN accepts any Ethernet frame and does not perform any special
+processing for VLAN\-tagged packets.
+.sp
+This option can only be activated in \fB\-\-dev tap mode\fP\&.
+.TP
+.BI \-\-vlan\-accept \ args
+Configure the VLAN tagging policy for the server TAP device.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+vlan\-accept  all|tagged|untagged
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The following modes are available:
+.INDENT 7.0
+.TP
+.B \fBtagged\fP
+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.
+.TP
+.B \fBuntagged\fP
+Admit only untagged and prio\-tagged frames.  VLAN\-tagged packets are
+not accepted, while untagged or priority\-tagged packets entering the
+server TAP device are tagged with the value configured for the global
+\fB\-\-vlan\-pvid\fP setting.
+.TP
+.B \fBall\fP (default)
+Admit all frames.  All packets are admitted and then treated like
+untagged or tagged mode respectively.
+.TP
+.B \fINote\fP:
+Some vendors refer to switch ports running in \fBtagged\fP mode
+as "trunk ports" and switch ports running in \fBuntagged\fP mode
+as "access ports".
+.UNINDENT
+.sp
+Packets forwarded from clients to the server are VLAN\-tagged with the
+originating client\(aqs PVID, unless the VID matches the global
+\fB\-\-vlan\-pvid\fP, in which case the tag is removed.
+.sp
+If no \fIPVID\fP is configured for a given client (see \-\-vlan\-pvid) packets
+are tagged with 1 by default.
+.TP
+.BI \-\-vlan\-pvid \ v
+Specifies which VLAN identifier a "port" is associated with. Only valid
+when \fB\-\-vlan\-tagging\fP is speficied.
+.sp
+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 \fB\-\-vlan\-accept
+untagged\fP and \fB\-\-vlan\-accept all\fP modes.
+.sp
+Valid values for \fBv\fP go from \fB1\fP through to \fB4094\fP\&. The
+global value defaults to \fB1\fP\&. If no \fB\-\-vlan\-pvid\fP is specified in
+the client context, the global value is inherited.
+.sp
+In some switch implementations, the \fIPVID\fP is also referred to as "Native
+VLAN".
+.UNINDENT
+.SH ENCRYPTION OPTIONS
+.SS SSL Library information
+.INDENT 0.0
+.TP
+.B \-\-show\-ciphers
+(Standalone) Show all cipher algorithms to use with the \fB\-\-cipher\fP
+option.
+.TP
+.B \-\-show\-digests
+(Standalone) Show all message digest algorithms to use with the
+\fB\-\-auth\fP option.
+.TP
+.B \-\-show\-tls
+(Standalone) Show all TLS ciphers supported by the crypto library.
+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 preference (most secure) to lowest.
+.sp
+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.).
+.TP
+.B \-\-show\-engines
+(Standalone) Show currently available hardware\-based crypto acceleration
+engines supported by the OpenSSL library.
+.TP
+.B \-\-show\-groups
+(Standalone) Show all available elliptic curves/groups to use with the
+\fB\-\-ecdh\-curve\fP and \fBtls\-groups\fP options.
+.UNINDENT
+.SS Generating key material
+.INDENT 0.0
+.TP
+.BI \-\-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.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-genkey keytype keyfile
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Valid keytype arguments are:
+.sp
+\fBsecret\fP                Standard OpenVPN shared secret keys
+.sp
+\fBtls\-crypt\fP             Alias for \fBsecret\fP
+.sp
+\fBtls\-auth\fP              Alias for \fBsecret\fP
+.sp
+\fBauth\-token\fP            Key used for \fB\-\-auth\-gen\-token\-key\fP
+.sp
+\fBtls\-crypt\-v2\-server\fP   TLS Crypt v2 server key
+.sp
+\fBtls\-crypt\-v2\-client\fP   TLS Crypt v2 client key
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ 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
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.IP \(bu 2
+Generating \fIShared Secret Keys\fP
+Generate a shared secret, for use with the \fB\-\-secret\fP, \fB\-\-tls\-auth\fP
+or \fB\-\-tls\-crypt\fP options.
+.sp
+Syntax:
+.INDENT 2.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ openvpn \-\-genkey secret|tls\-crypt|tls\-auth keyfile
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The key is saved in \fBkeyfile\fP\&. All three variants (\fB\-\-secret\fP,
+\fBtls\-crypt\fP and \fBtls\-auth\fP) generate the same type of key. The
+aliases are added for convenience.
+.sp
+If using this for \fB\-\-secret\fP, this file must be shared with the peer
+over a pre\-existing secure channel such as \fBscp\fP(1).
+.IP \(bu 2
+Generating \fITLS Crypt v2 Server key\fP
+Generate a \fB\-\-tls\-crypt\-v2\fP key to be used by an OpenVPN server.
+The key is stored in \fBkeyfile\fP\&.
+.sp
+Syntax:
+.INDENT 2.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-genkey tls\-crypt\-v2\-server keyfile
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP \(bu 2
+Generating \fITLS Crypt v2 Client key\fP
+Generate a \-\-tls\-crypt\-v2 key to be used by OpenVPN clients.  The
+key is stored in \fBkeyfile\fP\&.
+.sp
+Syntax
+.INDENT 2.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-genkey tls\-crypt\-v2\-client keyfile [metadata]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If supplied, include the supplied \fBmetadata\fP in the wrapped client
+key. This metadata must be supplied in base64\-encoded form. The
+metadata must be at most 735 bytes long (980 bytes in base64).
+.sp
+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.
+.sp
+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
+\fB\-\-tls\-crypt\-v2\fP option.
+.sp
+Servers can use \fB\-\-tls\-crypt\-v2\-verify\fP to specify a metadata
+verification command.
+.IP \(bu 2
+Generate \fIAuthentication Token key\fP
+Generate a new secret that can be used with \fB\-\-auth\-gen\-token\-secret\fP
+.sp
+Syntax:
+.INDENT 2.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-genkey auth\-token [keyfile]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 2.0
+.TP
+.B \fINote:\fP
+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 valid.
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS Data Channel Renegotiation
+.sp
+When running OpenVPN in client/server mode, the data channel will use a
+separate ephemeral encryption key which is rotated at regular intervals.
+.INDENT 0.0
+.TP
+.BI \-\-reneg\-bytes \ n
+Renegotiate data channel key after \fBn\fP bytes sent or received
+(disabled by default with an exception, see below). OpenVPN allows the
+lifetime of a key to be expressed as a number of bytes
+encrypted/decrypted, a number of packets, or a number of seconds. A key
+renegotiation will be forced if any of these three criteria are met by
+either peer.
+.sp
+If using ciphers with cipher block sizes less than 128\-bits,
+\fB\-\-reneg\-bytes\fP is set to 64MB by default, unless it is explicitly
+disabled by setting the value to \fB0\fP, but this is
+\fBHIGHLY DISCOURAGED\fP as this is designed to add some protection against
+the SWEET32 attack vector. For more information see the \fB\-\-cipher\fP
+option.
+.TP
+.BI \-\-reneg\-pkts \ n
+Renegotiate data channel key after \fBn\fP packets sent and received
+(disabled by default).
+.TP
+.BI \-\-reneg\-sec \ args
+Renegotiate data channel key after at most \fBmax\fP seconds
+(default \fB3600\fP) and at least \fBmin\fP seconds (default is 90% of
+\fBmax\fP for servers, and equal to \fBmax\fP for clients).
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+reneg\-sec max [min]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The effective \fB\-\-reneg\-sec\fP value used is per session
+pseudo\-uniform\-randomized between \fBmin\fP and \fBmax\fP\&.
+.sp
+With the default value of \fB3600\fP this results in an effective per
+session value in the range of \fB3240\fP\&..:code:\fI3600\fP seconds for
+servers, or just 3600 for clients.
+.sp
+When using dual\-factor authentication, note that this default value may
+cause the end user to be challenged to reauthorize once per hour.
+.sp
+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 \fB\-\-reneg\-sec\fP to a
+higher value on either the client or server, while the other side of the
+connection is still using the default value of \fB3600\fP seconds,
+meaning that the renegotiation will still occur once per \fB3600\fP
+seconds. The solution is to increase \-\-reneg\-sec on both the client and
+server, or set it to \fB0\fP on one side of the connection (to
+disable), and to your chosen value on the other side.
+.UNINDENT
+.SS TLS Mode Options
+.sp
+TLS mode is the most powerful crypto mode of OpenVPN in both security
+and flexibility. TLS mode works by establishing control and data
+channels which are multiplexed over a single TCP/UDP port. OpenVPN
+initiates a TLS session over the control channel and uses it to exchange
+cipher and HMAC keys to protect the data channel. TLS mode uses a robust
+reliability layer over the UDP connection for all control channel
+communication, 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
+certificate\-based authentication and Diffie Hellman forward secrecy.
+.sp
+To use TLS mode, each peer that runs OpenVPN should have its own local
+certificate/key pair (\fB\-\-cert\fP and \fB\-\-key\fP), signed by the root
+certificate which is specified in \fB\-\-ca\fP\&.
+.sp
+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 specified
+in \fB\-\-ca\fP\&.
+.sp
+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.
+.sp
+The OpenVPN project provides a set of scripts for managing RSA
+certificates and keys: \fI\%https://github.com/OpenVPN/easy\-rsa\fP
+.INDENT 0.0
+.TP
+.BI \-\-askpass \ file
+Get certificate password from console or \fBfile\fP before we daemonize.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+askpass
+askpass file
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For the extremely security conscious, it is possible to protect your
+private key with a password. Of course this means that every time the
+OpenVPN daemon is started you must be there to type the password. The
+\fB\-\-askpass\fP 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 \fB\-nodes\fP option when
+you use the \fBopenssl\fP command line tool to manage certificates and
+private keys.
+.sp
+If \fBfile\fP is specified, read the password from the first line of
+\fBfile\fP\&. Keep in mind that storing your password in a file to a certain
+extent invalidates the extra security provided by using an encrypted
+key.
+.TP
+.BI \-\-ca \ file
+Certificate authority (CA) file in .pem format, also referred to as the
+\fIroot\fP certificate. This file can have multiple certificates in .pem
+format, concatenated together. You can construct your own certificate
+authority certificate and private key by using a command such as:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openssl req \-nodes \-new \-x509 \-keyout ca.key \-out ca.crt
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Then edit your openssl.cnf file and edit the \fBcertificate\fP variable to
+point to your new root certificate \fBca.crt\fP\&.
+.sp
+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.
+.TP
+.BI \-\-capath \ dir
+Directory containing trusted certificates (CAs and CRLs). Not available
+with mbed TLS.
+.sp
+CAs in the capath directory are expected to be named <hash>.<n>. CRLs
+are expected to be named <hash>.r<n>. See the \fB\-CApath\fP option of
+\fBopenssl verify\fP, and the \fB\-hash\fP option of \fBopenssl x509\fP,
+\fBopenssl crl\fP and \fBX509_LOOKUP_hash_dir()\fP(3)
+for more information.
+.sp
+Similar to the \fB\-\-crl\-verify\fP 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.
+.TP
+.BI \-\-cert \ file
+Local peer\(aqs signed certificate in .pem format \-\- must be signed by a
+certificate authority whose certificate is in \fB\-\-ca file\fP\&. Each peer
+in an OpenVPN link running in TLS mode should have its own certificate
+and private key file. In addition, each certificate should have been
+signed by the key of a certificate authority whose public key resides in
+the \fB\-\-ca\fP certificate authority file. You can easily make your own
+certificate authority (see above) or pay money to use a commercial
+service such as thawte.com (in which case you will be helping to finance
+the world\(aqs second space tourist :). To generate a certificate, you can
+use a command such as:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openssl req \-nodes \-new \-keyout mycert.key \-out mycert.csr
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If your certificate authority private key lives on another machine, 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:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openssl ca \-out mycert.crt \-in mycert.csr
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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 \fBopenssl ca\fP command reads the location of the certificate
+authority key from its configuration file such as
+\fB/usr/share/ssl/openssl.cnf\fP \-\- note also that for certificate
+authority functions, you must set up the files \fBindex.txt\fP (may be
+empty) and \fBserial\fP (initialize to \fB01\fP).
+.TP
+.BI \-\-crl\-verify \ args
+Check peer certificate against a Certificate Revocation List.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+crl\-verify file/directory flag
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+crl\-verify crl\-file.pem
+crl\-verify /etc/openvpn/crls dir
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+A CRL (certificate revocation list) is used when a particular key is
+compromised but when the overall PKI is still intact.
+.sp
+Suppose you had a PKI consisting of a CA, root certificate, and a number
+of client certificates. Suppose a laptop computer containing a client
+key and certificate was stolen. By adding the stolen certificate to the
+CRL file, you could reject any connection which attempts to use it,
+while preserving the overall integrity of the PKI.
+.sp
+The only time when it would be necessary to rebuild the entire PKI from
+scratch would be if the root certificate key itself was compromised.
+.sp
+The option is not mandatory \- if the relevant CRL is missing, OpenVPN
+will log a warning in the logs \- e.g.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+VERIFY WARNING: depth=0, unable to get certificate CRL
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+but the connection will be allowed.  If the optional \fBdir\fP flag
+is specified, enable a different mode where the \fBcrl\-verify\fP 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.
+.INDENT 7.0
+.TP
+.B \fINote:\fP
+As the crl file (or directory) is read every time a peer
+connects, if you are dropping root privileges with
+\fB\-\-user\fP, make sure that this user has sufficient
+privileges to read the file.
+.UNINDENT
+.TP
+.BI \-\-dh \ file
+File containing Diffie Hellman parameters in .pem format (required for
+\fB\-\-tls\-server\fP only).
+.sp
+Set \fBfile\fP to \fBnone\fP to disable Diffie Hellman key exchange (and
+use ECDH only). Note that this requires peers to be using an SSL library
+that supports ECDH TLS cipher suites (e.g. OpenSSL 1.0.1+, or
+mbed TLS 2.0+).
+.sp
+Use \fBopenssl dhparam \-out dh2048.pem 2048\fP to generate 2048\-bit DH
+parameters. Diffie Hellman parameters may be considered public.
+.TP
+.BI \-\-ecdh\-curve \ name
+Specify the curve to use for elliptic curve Diffie Hellman. Available
+curves can be listed with \fB\-\-show\-curves\fP\&. The specified curve will
+only be used for ECDH TLS\-ciphers.
+.sp
+This option is not supported in mbed TLS builds of OpenVPN.
+.TP
+.BI \-\-extra\-certs \ file
+Specify a \fBfile\fP containing one or more PEM certs (concatenated
+together) that complete the local certificate chain.
+.sp
+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 certificate chain without
+trusting them to verify the peer\-submitted certificate, as would be the
+case if the certs were placed in the \fBca\fP file.
+.TP
+.BI \-\-hand\-window \ n
+Handshake Window \-\- the TLS\-based key exchange must finalize within
+\fBn\fP seconds of handshake initiation by any peer (default \fB60\fP
+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 \fB\-\-tran\-window\fP seconds to
+maintain continuity of transmission of tunnel data.
+.TP
+.BI \-\-key \ file
+Local peer\(aqs private key in .pem format. Use the private key which was
+generated when you built your peer\(aqs certificate (see \fB\-\-cert file\fP
+above).
+.TP
+.BI \-\-pkcs12 \ file
+Specify a PKCS #12 file containing local private key, local certificate,
+and root CA certificate. This option can be used instead of \fB\-\-ca\fP,
+\fB\-\-cert\fP, and \fB\-\-key\fP\&.  Not available with mbed TLS.
+.TP
+.BI \-\-remote\-cert\-eku \ oid
+Require that peer certificate was signed with an explicit \fIextended key
+usage\fP\&.
+.sp
+This is a useful security option for clients, to ensure that the host
+they connect to is a designated server.
+.sp
+The extended key usage should be encoded in \fIoid notation\fP, or \fIOpenSSL
+symbolic representation\fP\&.
+.TP
+.BI \-\-remote\-cert\-ku \ key\-usage
+Require that peer certificate was signed with an explicit
+\fBkey\-usage\fP\&.
+.sp
+If present in the certificate, the \fBkeyUsage\fP value is validated by
+the TLS library during the TLS handshake. Specifying this option without
+arguments requires this extension to be present (so the TLS library will
+verify it).
+.sp
+If \fBkey\-usage\fP is a list of usage bits, the \fBkeyUsage\fP field
+must have \fIat least\fP the same bits set as the bits in \fIone of\fP the values
+supplied in the \fBkey\-usage\fP list.
+.sp
+The \fBkey\-usage\fP values in the list must be encoded in hex, e.g.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+remote\-cert\-ku a0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-remote\-cert\-tls \ type
+Require that peer certificate was signed with an explicit \fIkey usage\fP
+and \fIextended key usage\fP based on RFC3280 TLS rules.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+remote\-cert\-tls server
+remote\-cert\-tls client
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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.
+.sp
+The \fB\-\-remote\-cert\-tls client\fP option is equivalent to
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+remote\-cert\-ku
+remote\-cert\-eku "TLS Web Client Authentication"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fB\-\-remote\-cert\-tls server\fP option is equivalent to
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+remote\-cert\-ku
+remote\-cert\-eku "TLS Web Server Authentication"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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 attack is easily
+prevented by having clients verify the server certificate using any one
+of \fB\-\-remote\-cert\-tls\fP, \fB\-\-verify\-x509\-name\fP, or \fB\-\-tls\-verify\fP\&.
+.TP
+.BI \-\-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 stack.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+tls\-auth file
+tls\-auth file 0
+tls\-auth file 1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In a nutshell, \fB\-\-tls\-auth\fP enables a kind of "HMAC firewall" on
+OpenVPN\(aqs TCP/UDP port, where TLS control channel packets bearing an
+incorrect HMAC signature can be dropped immediately without response.
+.sp
+\fBfile\fP (required) is a file in OpenVPN static key format which can be
+generated by \fB\-\-genkey\fP\&.
+.sp
+Older versions (up to OpenVPN 2.3) supported a freeform passphrase file.
+This is no longer supported in newer versions (v2.4+).
+.sp
+See the \fB\-\-secret\fP option for more information on the optional
+\fBdirection\fP parameter.
+.sp
+\fB\-\-tls\-auth\fP is recommended when you are running OpenVPN in a mode
+where it is listening for packets from any IP address, such as when
+\fB\-\-remote\fP is not specified, or \fB\-\-remote\fP is specified with
+\fB\-\-float\fP\&.
+.sp
+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 library to the packets it is
+sending. Most successful network attacks 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.
+.sp
+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 signature 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.
+.sp
+\fB\-\-tls\-auth\fP 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 result 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. \fB\-\-tls\-auth\fP can be
+strengthened by adding the \fB\-\-replay\-persist\fP option which will keep
+OpenVPN\(aqs replay protection state in a file so that it is not lost
+across restarts.
+.sp
+It should be emphasized that this feature is optional and that the key
+file used with \fB\-\-tls\-auth\fP gives a peer nothing more than the power
+to initiate a TLS handshake. It is not used to encrypt or authenticate
+any tunnel data.
+.sp
+Use \fB\-\-tls\-crypt\fP instead if you want to use the key file to not only
+authenticate, but also encrypt the TLS control channel.
+.TP
+.BI \-\-tls\-groups \ list
+A list of allowable groups/curves in order of preference.
+.sp
+Set the allowed elliptic curves/groups for the TLS session.
+These groups are allowed to be used in signatures and key exchange.
+.sp
+mbedTLS currently allows all known curves per default.
+.sp
+OpenSSL 1.1+ restricts the list per default to
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+"X25519:secp256r1:X448:secp521r1:secp384r1".
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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 using \fB\-\-ecdh\-curve\fP, the groups for ecdh will also be picked
+from this list.
+.sp
+OpenVPN maps the curve name \fIsecp256r1\fP to \fIprime256v1\fP to allow
+specifying the same tls\-groups option for mbedTLS and OpenSSL.
+.sp
+Warning: this option not only affects elliptic curve certificates
+but also the key exchange in TLS 1.3 and using this option improperly
+will disable TLS 1.3.
+.TP
+.BI \-\-tls\-cert\-profile \ profile
+Set the allowed cryptographic algorithms for certificates according to
+\fBprofile\fP\&.
+.sp
+The following profiles are supported:
+.INDENT 7.0
+.TP
+.B \fBlegacy\fP (default)
+SHA1 and newer, RSA 2048\-bit+, any elliptic curve.
+.TP
+.B \fBpreferred\fP
+SHA2 and newer, RSA 2048\-bit+, any elliptic curve.
+.TP
+.B \fBsuiteb\fP
+SHA256/SHA384, ECDSA with P\-256 or P\-384.
+.UNINDENT
+.sp
+This option is only fully supported for mbed TLS builds. OpenSSL builds
+use the following approximation:
+.INDENT 7.0
+.TP
+.B \fBlegacy\fP (default)
+sets "security level 1"
+.TP
+.B \fBpreferred\fP
+sets "security level 2"
+.TP
+.B \fBsuiteb\fP
+sets "security level 3" and \fB\-\-tls\-cipher "SUITEB128"\fP\&.
+.UNINDENT
+.sp
+OpenVPN will migrate to \(aqpreferred\(aq as default in the future. Please
+ensure that your keys already comply.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \fIWARNING:\fP \fB\-\-tls\-ciphers\fP, \fB\-\-tls\-ciphersuites\fP and \fBtls\-groups\fP
+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!
+.UNINDENT
+.INDENT 0.0
+.TP
+.BI \-\-tls\-cipher \ l
+A list \fBl\fP of allowable TLS ciphers delimited by a colon ("\fB:\fP").
+.sp
+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.
+.sp
+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.
+.sp
+For OpenSSL, the \fB\-\-tls\-cipher\fP is used for TLS 1.2 and below.
+.sp
+Use \fB\-\-show\-tls\fP to see a list of TLS ciphers supported by your crypto
+library.
+.sp
+The default for \fB\-\-tls\-cipher\fP is to use mbed TLS\(aqs default cipher list
+when using mbed TLS or
+\fBDEFAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA\fP when
+using OpenSSL.
+.sp
+The default for \fI\-\-tls\-ciphersuites\fP is to use the crypto library\(aqs
+default.
+.TP
+.BI \-\-tls\-ciphersuites \ l
+Same as \fB\-\-tls\-cipher\fP but for TLS 1.3 and up. mbed TLS has no
+TLS 1.3 support yet and only the \fB\-\-tls\-cipher\fP setting is used.
+.TP
+.B \-\-tls\-client
+Enable TLS and assume client role during TLS handshake.
+.TP
+.BI \-\-tls\-crypt \ keyfile
+Encrypt and authenticate all control channel packets with the key from
+\fBkeyfile\fP\&. (See \fB\-\-tls\-auth\fP for more background.)
+.sp
+Encrypting (and authenticating) control channel packets:
+.INDENT 7.0
+.IP \(bu 2
+provides more privacy by hiding the certificate used for the TLS
+connection,
+.IP \(bu 2
+makes it harder to identify OpenVPN traffic as such,
+.IP \(bu 2
+provides "poor\-man\(aqs" post\-quantum security, against attackers who will
+never know the pre\-shared key (i.e. no forward secrecy).
+.UNINDENT
+.sp
+In contrast to \fB\-\-tls\-auth\fP, \fB\-\-tls\-crypt\fP does \fInot\fP require the
+user to set \fB\-\-key\-direction\fP\&.
+.sp
+\fBSecurity Considerations\fP
+.sp
+All peers use the same \fB\-\-tls\-crypt\fP pre\-shared group key to
+authenticate 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 conservative), 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.)
+.sp
+If IV collisions were to occur, this could result in the security of
+\fB\-\-tls\-crypt\fP degrading to the same security as using \fB\-\-tls\-auth\fP\&.
+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.
+.sp
+For large setups or setups where clients are not trusted, consider using
+\fB\-\-tls\-crypt\-v2\fP instead. That uses per\-client unique keys, and
+thereby improves the bounds to \(aqrotate a client key at least once per
+8000 years\(aq.
+.TP
+.BI \-\-tls\-crypt\-v2 \ keyfile
+Use client\-specific tls\-crypt keys.
+.sp
+For clients, \fBkeyfile\fP is a client\-specific tls\-crypt key. Such a key
+can be generated using the \fB\-\-genkey tls\-crypt\-v2\-client\fP option.
+.sp
+For servers, \fBkeyfile\fP is used to unwrap client\-specific keys supplied
+by the client during connection setup. This key must be the same as the
+key used to generate the client\-specific key (see \fB\-\-genkey
+tls\-crypt\-v2\-client\fP).
+.sp
+On servers, this option can be used together with the \fB\-\-tls\-auth\fP or
+\fB\-\-tls\-crypt\fP option. In that case, the server will detect whether the
+client is using client\-specific keys, and automatically select the right
+mode.
+.TP
+.BI \-\-tls\-crypt\-v2\-verify \ cmd
+Run command \fBcmd\fP to verify the metadata of the client\-specific
+tls\-crypt\-v2 key of a connecting client. This allows server
+administrators to reject client connections, before exposing the TLS
+stack (including the notoriously dangerous X.509 and ASN.1 stacks) to
+the connecting client.
+.sp
+OpenVPN supplies the following environment variables to the command:
+.INDENT 7.0
+.IP \(bu 2
+\fBscript_type\fP is set to \fBtls\-crypt\-v2\-verify\fP
+.IP \(bu 2
+\fBmetadata_type\fP is set to \fB0\fP if the metadata was user
+supplied, or \fB1\fP if it\(aqs a 64\-bit unix timestamp representing
+the key creation time.
+.IP \(bu 2
+\fBmetadata_file\fP contains the filename of a temporary file that
+contains the client metadata.
+.UNINDENT
+.sp
+The command can reject the connection by exiting with a non\-zero exit
+code.
+.TP
+.B \-\-tls\-exit
+Exit on TLS negotiation failure.
+.TP
+.BI \-\-tls\-export\-cert \ directory
+Store the certificates the clients use upon connection to this
+directory. This will be done before \fB\-\-tls\-verify\fP 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 certificate is
+available via the \fBpeer_cert\fP environment variable.
+.TP
+.B \-\-tls\-server
+Enable TLS and assume server role during TLS handshake. Note that
+OpenVPN is designed as a peer\-to\-peer application. The designation of
+client or server is only for the purpose of negotiating the TLS control
+channel.
+.TP
+.BI \-\-tls\-timeout \ n
+Packet retransmit timeout on TLS control channel if no acknowledgment
+from remote within \fBn\fP seconds (default \fB2\fP). When OpenVPN sends
+a control packet to its peer, it will expect to receive an
+acknowledgement within \fBn\fP 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.
+.TP
+.BI \-\-tls\-version\-min \ args
+Sets the minimum TLS version we will accept from the peer (default is
+"1.0").
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+tls\-version\-min version [\(aqor\-highest\(aq]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Examples for version include \fB1.0\fP, \fB1.1\fP, or \fB1.2\fP\&. If
+\fBor\-highest\fP is specified and version is not recognized, we will
+only accept the highest TLS version supported by the local SSL
+implementation.
+.TP
+.BI \-\-tls\-version\-max \ version
+Set the maximum TLS version we will use (default is the highest version
+supported). Examples for version include \fB1.0\fP, \fB1.1\fP, or
+\fB1.2\fP\&.
+.TP
+.BI \-\-verify\-hash \ args
+Specify SHA1 or SHA256 fingerprint for level\-1 cert.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+verify\-hash hash [algo]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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 \fBhash\fP or certificate verification
+will fail. Hash is specified as XX:XX:... For example:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBalgo\fP flag can be either \fBSHA1\fP or \fBSHA256\fP\&. If not
+provided, it defaults to \fBSHA1\fP\&.
+.TP
+.BI \-\-verify\-x509\-name \ args
+Accept connections only if a host\(aqs X.509 name is equal to \fBname.\fP The
+remote host must also pass all other tests of verification.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+verify\-x509 name type
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Which X.509 name is compared to \fBname\fP depends on the setting of type.
+\fBtype\fP can be \fBsubject\fP to match the complete subject DN
+(default), \fBname\fP to match a subject RDN or \fBname\-prefix\fP to
+match a subject RDN prefix. Which RDN is verified as name depends on the
+\fB\-\-x509\-username\-field\fP option. But it defaults to the common name
+(CN), e.g. a certificate with a subject DN
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+C=KG, ST=NA, L=Bishkek, CN=Server\-1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+would be matched by:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+verify\-x509\-name \(aqC=KG, ST=NA, L=Bishkek, CN=Server\-1\(aq
+verify\-x509\-name Server\-1 name
+verify\-x509\-name Server\- name\-prefix
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The last example is useful if you want a client to only accept
+connections to \fBServer\-1\fP, \fBServer\-2\fP, etc.
+.sp
+\fB\-\-verify\-x509\-name\fP is a useful replacement for the \fB\-\-tls\-verify\fP
+option to verify the remote host, because \fB\-\-verify\-x509\-name\fP works
+in a \fB\-\-chroot\fP environment without any dependencies.
+.sp
+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.
+.INDENT 7.0
+.TP
+.B \fINOTE:\fP
+Test against a name prefix only when you are using OpenVPN
+with a custom CA certificate that is under your control. Never use
+this option with type \fBname\-prefix\fP when your client
+certificates are signed by a third party, such as a commercial
+web CA.
+.UNINDENT
+.TP
+.BI \-\-x509\-track \ attribute
+Save peer X509 \fBattribute\fP value in environment for use by plugins and
+management interface. Prepend a \fB+\fP to \fBattribute\fP to save values
+from full cert chain. Values will be encoded as
+\fBX509_<depth>_<attribute>=<value>\fP\&. Multiple \fB\-\-x509\-track\fP
+options can be defined to track multiple attributes.
+.TP
+.BI \-\-x509\-username\-field \ args
+Field in the X.509 certificate subject to be used as the username
+(default \fBCN\fP).
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+x509\-username\-field [ext:]fieldname
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Typically, this option is specified with \fBfieldname\fP as
+either of the following:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+x509\-username\-field emailAddress
+x509\-username\-field ext:subjectAltName
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The first example uses the value of the \fBemailAddress\fP attribute
+in the certificate\(aqs Subject field as the username. The second example
+uses the \fBext:\fP prefix to signify that the X.509 extension
+\fBfieldname\fP \fBsubjectAltName\fP be searched for an rfc822Name
+(email) field to be used as the username. In cases where there are
+multiple email addresses in \fBext:fieldname\fP, the last occurrence
+is chosen.
+.sp
+When this option is used, the \fB\-\-verify\-x509\-name\fP option will match
+against the chosen \fBfieldname\fP instead of the Common Name.
+.sp
+Only the \fBsubjectAltName\fP and \fBissuerAltName\fP X.509
+extensions are supported.
+.sp
+\fBPlease note:\fP This option has a feature which will convert an
+all\-lowercase \fBfieldname\fP to uppercase characters, e.g.,
+\fBou\fP \-> \fBOU\fP\&. A mixed\-case \fBfieldname\fP or one having the
+\fBext:\fP prefix will be left as\-is. This automatic upcasing feature is
+deprecated and will be removed in a future release.
+.UNINDENT
+.SS PKCS#11 / SmartCard options
+.INDENT 0.0
+.TP
+.BI \-\-pkcs11\-cert\-private \ args
+Set if access to certificate object should be performed after login.
+Every provider has its own setting.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pkcs11\-cert\-private 0
+pkcs11\-cert\-private 1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-pkcs11\-id \ name
+Specify the serialized certificate id to be used. The id can be gotten
+by the standalone \fB\-\-show\-pkcs11\-ids\fP option.
+.TP
+.B \-\-pkcs11\-id\-management
+Acquire PKCS#11 id from management interface. In this case a
+\fBNEED\-STR \(aqpkcs11\-id\-request\(aq\fP real\-time message will be triggered,
+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.
+.TP
+.BI \-\-pkcs11\-pin\-cache \ seconds
+Specify how many seconds the PIN can be cached, the default is until the
+token is removed.
+.TP
+.BI \-\-pkcs11\-private\-mode \ mode
+Specify which method to use in order to perform private key operations.
+A different mode can be specified for each provider. Mode is encoded as
+hex number, and can be a mask one of the following:
+.sp
+\fB0\fP (default)   Try to determine automatically.
+.sp
+\fB1\fP             Use sign.
+.sp
+\fB2\fP             Use sign recover.
+.sp
+\fB4\fP             Use decrypt.
+.sp
+\fB8\fP             Use unwrap.
+.TP
+.BI \-\-pkcs11\-protected\-authentication \ args
+Use PKCS#11 protected authentication path, useful for biometric and
+external keypad devices. Every provider has its own setting.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+pkcs11\-protected\-authentication 0
+pkcs11\-protected\-authentication 1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-pkcs11\-providers \ provider
+Specify an RSA Security Inc. PKCS #11 Cryptographic Token Interface
+(Cryptoki) providers to load. This option can be used instead of
+\fB\-\-cert\fP, \fB\-\-key\fP and \fB\-\-pkcs12\fP\&.
+.sp
+If p11\-kit is present on the system, its \fBp11\-kit\-proxy.so\fP module
+will be loaded by default if either the \fB\-\-pkcs11\-id\fP or
+\fB\-\-pkcs11\-id\-management\fP options are specified without
+\fB\-\-pkcs11\-provider\fP being given.
+.TP
+.BI \-\-show\-pkcs11\-ids \ args
+(Standalone) Show PKCS#11 token object list.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+show\-pkcs11 [provider] [cert_private]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Specify \fBcert_private\fP as \fB1\fP if certificates are stored as
+private objects.
+.sp
+If \fIp11\-kit\fP is present on the system, the \fBprovider\fP argument is
+optional; if omitted the default \fBp11\-kit\-proxy.so\fP module will be
+queried.
+.sp
+\fB\-\-verb\fP option can be used BEFORE this option to produce debugging
+information.
+.UNINDENT
+.SH DATA CHANNEL CIPHER NEGOTIATION
+.sp
+OpenVPN 2.4 and higher have the capability to negotiate the data cipher that
+is used to encrypt data packets. This section describes the mechanism in more detail and the
+different backwards compatibility mechanism with older server and clients.
+.SS OpenVPN 2.5 and higher behaviour
+.sp
+When both client and server are at least running OpenVPN 2.5, that the order of
+the ciphers of the server\(aqs \fB\-\-data\-ciphers\fP is used to pick the the data cipher.
+That means that the first cipher in that list that is also in the client\(aqs
+\fB\-\-data\-ciphers\fP list is chosen. If no common cipher is found the client is rejected
+with a AUTH_FAILED message (as seen in client log):
+.INDENT 0.0
+.INDENT 3.5
+AUTH: Received control message: AUTH_FAILED,Data channel cipher negotiation failed (no shared cipher)
+.UNINDENT
+.UNINDENT
+.sp
+OpenVPN 2.5 will only allow the ciphers specified in \fB\-\-data\-ciphers\fP\&. To ensure
+backwards compatibility also if a cipher is specified using the \fB\-\-cipher\fP option
+it is automatically added to this list. If both options are unset the default is
+\fBAES\-256\-GCM:AES\-128\-GCM\fP\&.
+.SS OpenVPN 2.4 clients
+.sp
+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 \fB\-\-ncp\-disable\fP will always announce support for
+\fIAES\-256\-GCM\fP and \fIAES\-128\-GCM\fP to a server by sending \fBIV_NCP=2\fP\&.
+.sp
+This only causes a problem if \fB\-\-ncp\-ciphers\fP option has been changed from the
+default of \fBAES\-256\-GCM:AES\-128\-GCM\fP to a value that does not include
+these two ciphers. When a OpenVPN servers try to use \fIAES\-256\-GCM\fP or
+\fIAES\-128\-GCM\fP the connection will then fail. It is therefore recommended to
+always have the \fIAES\-256\-GCM\fP and \fIAES\-128\-GCM\fP ciphers to the \fB\-\-ncp\-ciphers\fP
+options to avoid this behaviour.
+.SS OpenVPN 3 clients
+.sp
+Clients based on the OpenVPN 3.x library (\fI\%https://github.com/openvpn/openvpn3/\fP)
+do not have a configurable \fB\-\-ncp\-ciphers\fP or \fB\-\-data\-ciphers\fP option. Instead
+these clients will announce support for all their supported AEAD ciphers
+(\fIAES\-256\-GCM\fP, \fIAES\-128\-GCM\fP and in newer versions also \fIChacha20\-Poly1305\fP).
+.sp
+To support OpenVPN 3.x based clients at least one of these ciphers needs to be
+included in the server\(aqs \fB\-\-data\-ciphers\fP option.
+.SS OpenVPN 2.3 and older clients (and clients with \fB\-\-ncp\-disable\fP)
+.sp
+When a client without cipher negotiation support connects to a server the
+cipher specified with the \fB\-\-cipher\fP option in the client configuration
+must be included in the \fB\-\-data\-ciphers\fP option of the server to allow
+the client to connect. Otherwise the client will be sent the \fBAUTH_FAILED\fP
+message that indicates no shared cipher.
+.sp
+If the client is 2.3 or older and has been configured with the
+\fB\-\-enable\-small\fP  \fB\&./configure\fP argument, using
+\fBdata\-ciphers\-fallback cipher\fP in the server config file with the explicit
+cipher used by the client is necessary.
+.SS OpenVPN 2.4 server
+.sp
+When a client indicates support for \fIAES\-128\-GCM\fP and \fIAES\-256\-GCM\fP
+(with \fBIV_NCP=2\fP) an OpenVPN 2.4 server will send the first
+cipher of the \fB\-\-ncp\-ciphers\fP 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  \fIAES\-128\-GCM\fP and \fIAES\-256\-GCM\fP to the client\(aqs \fB\-\-data\-ciphers\fP
+option is required. OpenVPN 2.5+ will only announce the \fBIV_NCP=2\fP flag if
+those ciphers are present.
+.SS OpenVPN 2.3 and older servers (and servers with \fB\-\-ncp\-disable\fP)
+.sp
+The cipher used by the server must be included in \fB\-\-data\-ciphers\fP to
+allow the client connecting to a server without cipher negotiation
+support.
+(For compatibility OpenVPN 2.5 will also accept the cipher set with
+\fB\-\-cipher\fP)
+.sp
+If the server is 2.3 or older and  has been configured with the
+\fB\-\-enable\-small\fP \fB\&./configure\fP argument, adding
+\fBdata\-ciphers\-fallback cipher\fP to the client config with the explicit
+cipher used by the server is necessary.
+.SS Blowfish in CBC mode (BF\-CBC) deprecation
+.sp
+The \fB\-\-cipher\fP option defaulted to \fBBF\-CBC\fP in OpenVPN 2.4 and older
+version. The default was never changed to ensure backwards compatibility.
+In OpenVPN 2.5 this behaviour has now been changed so that if the \fB\-\-cipher\fP
+is not explicitly set it does not allow the weak \fBBF\-CBC\fP cipher any more
+and needs to explicitly added as \fB\-\-cipher BFC\-CBC\fP or added to
+\fB\-\-data\-ciphers\fP\&.
+.sp
+We strongly recommend to switching away from BF\-CBC to a
+more secure cipher as soon as possible instead.
+.SH NETWORK CONFIGURATION
+.sp
+OpenVPN consists of two sides of network configuration.  One side is the
+\fIlink\fP between the local and remote side, the other side is the \fIvirtual
+network adapter\fP (tun/tap device).
+.SS Link Options
+.sp
+This link options section covers options related to the connection between
+the local and the remote host.
+.INDENT 0.0
+.TP
+.BI \-\-bind \ keywords
+Bind to local address and port. This is the default unless any of
+\fB\-\-proto tcp\-client\fP , \fB\-\-http\-proxy\fP or \fB\-\-socks\-proxy\fP are used.
+.sp
+If the optional \fBipv6only\fP keyword is present OpenVPN will bind only
+to IPv6 (as opposed to IPv6 and IPv4) when a IPv6 socket is opened.
+.TP
+.B \-\-float
+Allow remote peer to change its IP address and/or port number, such as
+due to DHCP (this is the default if \fB\-\-remote\fP is not used).
+\fB\-\-float\fP when specified with \fB\-\-remote\fP allows an OpenVPN session
+to initially connect to a peer at a known address, however if packets
+arrive from a new address and pass all authentication 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.
+.sp
+Essentially, \fB\-\-float\fP tells OpenVPN to accept authenticated packets
+from any address, not only the address which was specified in the
+\fB\-\-remote\fP option.
+.TP
+.BI \-\-fragment \ max
+Enable internal datagram fragmentation so that no UDP datagrams are sent
+which are larger than \fBmax\fP bytes.
+.sp
+The \fBmax\fP parameter is interpreted in the same way as the
+\fB\-\-link\-mtu\fP parameter, i.e. the UDP packet size after encapsulation
+overhead has been added in, but not including the UDP header itself.
+.sp
+The \fB\-\-fragment\fP option only makes sense when you are using the UDP
+protocol (\fB\-\-proto udp\fP).
+.sp
+\fB\-\-fragment\fP adds 4 bytes of overhead per datagram.
+.sp
+See the \fB\-\-mssfix\fP option below for an important related option to
+\fB\-\-fragment\fP\&.
+.sp
+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.
+.sp
+Having said that, there are circumstances where using OpenVPN\(aqs internal
+fragmentation capability may be your only option, such as tunneling a
+UDP multicast stream which requires fragmentation.
+.TP
+.BI \-\-keepalive \ args
+A helper directive designed to simplify the expression of \fB\-\-ping\fP and
+\fB\-\-ping\-restart\fP\&.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+keepalive interval timeout
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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 appropriate \fB\-\-ping\fP
+and \fB\-\-ping\-restart\fP options to the client. If used on both server and
+client, the values pushed from server will override the client local
+values.
+.sp
+The \fBtimeout\fP 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.
+.sp
+For example, \fB\-\-keepalive 10 60\fP expands as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+if mode server:
+    ping 10                    # Argument: interval
+    ping\-restart 120           # Argument: timeout*2
+    push "ping 10"             # Argument: interval
+    push "ping\-restart 60"     # Argument: timeout
+else
+    ping 10                    # Argument: interval
+    ping\-restart 60            # Argument: timeout
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-link\-mtu \ n
+Sets an upper bound on the size of UDP packets which are sent between
+OpenVPN peers. \fIIt\(aqs best not to set this parameter unless you know what
+you\(aqre doing.\fP
+.TP
+.BI \-\-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.
+.TP
+.BI \-\-lport \ port
+Set local TCP/UDP port number or name. Cannot be used together with
+\fB\-\-nobind\fP option.
+.TP
+.BI \-\-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 systems.
+.TP
+.BI \-\-mode \ m
+Set OpenVPN major mode. By default, OpenVPN runs in point\-to\-point mode
+(\fBp2p\fP). OpenVPN 2.0 introduces a new mode (\fBserver\fP) which
+implements a multi\-client server capability.
+.TP
+.BI \-\-mssfix \ max
+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 \fBmax\fP bytes. The default value is \fB1450\fP\&.
+.sp
+The \fBmax\fP parameter is interpreted in the same way as the
+\fB\-\-link\-mtu\fP 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 IPv4 packets to be transmitted over a link with MTU
+1473 or higher without IP level fragmentation.
+.sp
+The \fB\-\-mssfix\fP option only makes sense when you are using the UDP
+protocol for OpenVPN peer\-to\-peer communication, i.e. \fB\-\-proto udp\fP\&.
+.sp
+\fB\-\-mssfix\fP and \fB\-\-fragment\fP can be ideally used together, where
+\fB\-\-mssfix\fP 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), \fB\-\-fragment\fP will internally fragment them.
+.sp
+Both \fB\-\-fragment\fP and \fB\-\-mssfix\fP are designed to work around cases
+where Path MTU discovery is broken on the network path between OpenVPN
+peers.
+.sp
+The usual symptom of such a breakdown is an OpenVPN connection which
+successfully starts, but then stalls during active usage.
+.sp
+If \fB\-\-fragment\fP and \fB\-\-mssfix\fP are used together, \fB\-\-mssfix\fP will
+take its default \fBmax\fP parameter from the \fB\-\-fragment max\fP option.
+.sp
+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:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-tun\-mtu 1500 \-\-fragment 1300 \-\-mssfix
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-mtu\-disc \ type
+Should we do Path MTU discovery on TCP/UDP channel? Only supported on
+OSes such as Linux that supports the necessary system call to set.
+.sp
+Valid types:
+.sp
+\fBno\fP      Never send DF (Don\(aqt Fragment) frames
+.sp
+\fBmaybe\fP   Use per\-route hints
+.sp
+\fByes\fP     Always DF (Don\(aqt Fragment)
+.TP
+.B \-\-mtu\-test
+To empirically measure MTU on connection startup, add the \fB\-\-mtu\-test\fP
+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 \fB\-\-mtu\-test\fP process normally takes about 3
+minutes to complete.
+.TP
+.B \-\-nobind
+Do not bind to local address and port. The IP stack will allocate 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 connections by using the \-\-remote
+option.
+.TP
+.B \-\-passtos
+Set the TOS field of the tunnel packet to what the payload\(aqs TOS is.
+.TP
+.BI \-\-ping \ n
+Ping remote over the TCP/UDP control channel if no packets have been
+sent for at least \fBn\fP seconds (specify \fB\-\-ping\fP on both peers to
+cause ping packets to be sent in both directions since OpenVPN ping
+packets are not echoed like IP ping packets). When used in one of
+OpenVPN\(aqs secure modes (where \fB\-\-secret\fP, \fB\-\-tls\-server\fP or
+\fB\-\-tls\-client\fP is specified), the ping packet will be
+cryptographically secure.
+.sp
+This option has two intended uses:
+.INDENT 7.0
+.IP 1. 3
+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.
+.IP 2. 3
+To provide a basis for the remote to test the existence of its peer
+using the \fB\-\-ping\-exit\fP option.
+.UNINDENT
+.TP
+.BI \-\-ping\-exit \ n
+Causes OpenVPN to exit after \fBn\fP seconds pass without reception of a
+ping or other packet from remote. This option can be combined with
+\fB\-\-inactive\fP, \fB\-\-ping\fP and \fB\-\-ping\-exit\fP to create a two\-tiered
+inactivity disconnect.
+.sp
+For example,
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn [options...] \-\-inactive 3600 \-\-ping 10 \-\-ping\-exit 60
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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.
+.TP
+.BI \-\-ping\-restart \ n
+Similar to \fB\-\-ping\-exit\fP, but trigger a \fBSIGUSR1\fP restart after
+\fBn\fP seconds pass without reception of a ping or other packet from
+remote.
+.sp
+This option is useful in cases where the remote peer has a dynamic IP
+address and a low\-TTL DNS name is used to track the IP address using a
+service such as \fI\%http://dyndns.org/\fP + a dynamic DNS client such as
+\fBddclient\fP\&.
+.sp
+If the peer cannot be reached, a restart will be triggered, causing the
+hostname used with \fB\-\-remote\fP to be re\-resolved (if \fB\-\-resolv\-retry\fP
+is also specified).
+.sp
+In server mode, \fB\-\-ping\-restart\fP, \fB\-\-inactive\fP 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.
+.sp
+In client mode, the \fB\-\-ping\-restart\fP parameter is set to 120 seconds
+by default. This default will hold until the client pulls a replacement
+value from the server, based on the \fB\-\-keepalive\fP setting in the
+server configuration. To disable the 120 second default, set
+\fB\-\-ping\-restart 0\fP on the client.
+.sp
+See the signals section below for more information on \fBSIGUSR1\fP\&.
+.sp
+Note that the behavior of \fBSIGUSR1\fP can be modified by the
+\fB\-\-persist\-tun\fP, \fB\-\-persist\-key\fP, \fB\-\-persist\-local\-ip\fP and
+\fB\-\-persist\-remote\-ip\fP options.
+.sp
+Also note that \fB\-\-ping\-exit\fP and \fB\-\-ping\-restart\fP are mutually
+exclusive and cannot be used together.
+.TP
+.B \-\-ping\-timer\-rem
+Run the \fB\-\-ping\-exit\fP / \fB\-\-ping\-restart\fP timer only if we have a
+remote address. Use this option if you are starting the daemon in listen
+mode (i.e. without an explicit \fB\-\-remote\fP peer), and you don\(aqt want to
+start clocking timeouts until a remote peer connects.
+.TP
+.BI \-\-proto \ p
+Use protocol \fBp\fP for communicating with remote host. \fBp\fP can be
+\fBudp\fP, \fBtcp\-client\fP, or \fBtcp\-server\fP\&.
+.sp
+The default protocol is \fBudp\fP when \fB\-\-proto\fP is not specified.
+.sp
+For UDP operation, \fB\-\-proto udp\fP should be specified on both peers.
+.sp
+For TCP operation, one peer must use \fB\-\-proto tcp\-server\fP and the
+other must use \fB\-\-proto tcp\-client\fP\&. A peer started with
+\fBtcp\-server\fP will wait indefinitely for an incoming connection. A peer
+started with \fBtcp\-client\fP will attempt to connect, and if that fails,
+will sleep for 5 seconds (adjustable via the \fB\-\-connect\-retry\fP option)
+and try again infinite or up to N retries (adjustable via the
+\fB\-\-connect\-retry\-max\fP option). Both TCP client and server will
+simulate a SIGUSR1 restart signal if either side resets the connection.
+.sp
+OpenVPN is designed to operate optimally over UDP, but TCP capability 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.
+.sp
+This article outlines some of problems with tunneling IP over TCP:
+\fI\%http://sites.inka.de/sites/bigred/devel/tcp\-tcp.html\fP
+.sp
+There are certain cases, however, where using TCP may be advantageous
+from a security and robustness perspective, such as tunneling non\-IP or
+application\-level UDP protocols, or tunneling protocols which don\(aqt
+possess a built\-in reliability layer.
+.TP
+.BI \-\-port \ port
+TCP/UDP port number or port name for both local and remote (sets both
+\fB\-\-lport\fP and \fB\-\-rport\fP options to given port). The current default
+of 1194 represents the official IANA port number assignment for OpenVPN
+and has been used since version 2.0\-beta17. Previous versions used port
+5000 as the default.
+.TP
+.BI \-\-rport \ port
+Set TCP/UDP port number or name used by the \fB\-\-remote\fP option. The
+port can also be set directly using the \fB\-\-remote\fP option.
+.TP
+.BI \-\-replay\-window \ args
+Modify the replay protection sliding\-window size and time window.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+replay\-window n [t]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Use a replay protection sliding\-window of size \fBn\fP and a time window
+of \fBt\fP seconds.
+.sp
+By default \fBn\fP is 64 (the IPSec default) and \fBt\fP is 15 seconds.
+.sp
+This option is only relevant in UDP mode, i.e. when either \fB\-\-proto
+udp\fP is specified, or no \fB\-\-proto\fP option is specified.
+.sp
+When OpenVPN tunnels IP packets over UDP, there is the possibility that
+packets might be dropped or delivered out of order. Because 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 constraints.
+.INDENT 7.0
+.IP a. 3
+The packet cannot be a replay (unless \fB\-\-no\-replay\fP is
+specified, which disables replay protection altogether).
+.IP b. 3
+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 \fBn\fP\&.
+.IP c. 3
+If a packet arrives out of order, it will only be accepted if it
+arrives no later than \fBt\fP seconds after any packet containing a higher
+sequence number.
+.UNINDENT
+.sp
+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 \fBn\fP\&. Satellite links in particular often require this.
+.sp
+If you run OpenVPN at \fB\-\-verb 4\fP, you will see the message
+"Replay\-window backtrack occurred [x]" every time the maximum sequence
+number backtrack seen thus far increases. This can be used to calibrate
+\fBn\fP\&.
+.sp
+There is some controversy on the appropriate method of handling packet
+reordering at the security layer.
+.sp
+Namely, to what extent should the security layer protect the
+encapsulated protocol from attacks which masquerade as the kinds of
+normal packet loss and reordering that occur over IP networks?
+.sp
+The IPSec and OpenVPN approach is to allow packet reordering within a
+certain fixed sequence number window.
+.sp
+OpenVPN adds to the IPSec model by limiting the window size in time as
+well as sequence space.
+.sp
+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\(aqt allow it. Since TCP guarantees
+reliability, any packet loss or reordering event can be assumed to be an
+attack.
+.sp
+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.
+.sp
+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.
+.TP
+.BI \-\-replay\-persist \ file
+Persist replay\-protection state across sessions using \fBfile\fP to save
+and reload the state.
+.sp
+This option will strengthen protection against replay attacks,
+especially when you are using OpenVPN in a dynamic context (such as with
+\fB\-\-inetd\fP) when OpenVPN sessions are frequently started and stopped.
+.sp
+This option will keep a disk copy of the current replay protection 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.
+.sp
+This option only makes sense when replay protection is enabled (the
+default) and you are using either \fB\-\-secret\fP (shared\-secret key mode)
+or TLS mode with \fB\-\-tls\-auth\fP\&.
+.TP
+.BI \-\-socket\-flags \ flags
+Apply the given flags to the OpenVPN transport socket. Currently, only
+\fBTCP_NODELAY\fP is supported.
+.sp
+The \fBTCP_NODELAY\fP socket flag is useful in TCP mode, and causes the
+kernel to send tunnel packets immediately over the TCP connection without
+trying to group several smaller packets into a larger packet.  This can
+result in a considerably improvement in latency.
+.sp
+This option is pushable from server to client, and should be used on
+both client and server for maximum effect.
+.TP
+.B \-\-tcp\-nodelay
+This macro sets the \fBTCP_NODELAY\fP socket flag on the server as well
+as pushes it to connecting clients. The \fBTCP_NODELAY\fP 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, \fBTCP_NODELAY\fP is generally a good
+latency optimization.
+.sp
+The macro expands as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+if mode server:
+    socket\-flags TCP_NODELAY
+    push "socket\-flags TCP_NODELAY"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS Virtual Network Adapter (VPN interface)
+.sp
+Options in this section relates to configuration of the virtual tun/tap
+network interface, including setting the VPN IP address and network
+routing.
+.INDENT 0.0
+.TP
+.BI \-\-bind\-dev \ device
+(Linux only) Set \fBdevice\fP to bind the server socket to a
+\fI\%Virtual Routing and Forwarding\fP device
+.TP
+.B \-\-block\-ipv6
+On the client, instead of sending IPv6 packets over the VPN tunnel, all
+IPv6 packets are answered with an ICMPv6 no route host message. On the
+server, all IPv6 packets from clients are answered 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. \fB\-\-block\-ipv6\fP
+will use the remote IPv6 as source address of the ICMPv6 packets if set,
+otherwise will use \fBfe80::7\fP as source address.
+.sp
+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.
+.INDENT 7.0
+.TP
+.B \fBClient config\fP
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-ifconfig\-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1
+\-\-redirect\-gateway ipv6
+\-\-block\-ipv6
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.B \fBServer config\fP
+Push a "valid" ipv6 config to the client and block on the server
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-push "ifconfig\-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1"
+\-\-push "redirect\-gateway ipv6"
+\-\-block\-ipv6
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-dev \ device
+TUN/TAP virtual network device which can be \fBtunX\fP, \fBtapX\fP,
+\fBnull\fP or an arbitrary name string (\fBX\fP can be omitted for
+a dynamic device.)
+.sp
+See examples section below for an example on setting up a TUN device.
+.sp
+You must use either tun devices on both ends of the connection or tap
+devices on both ends. You cannot mix them, as they represent different
+underlying network layers:
+.INDENT 7.0
+.TP
+.B \fBtun\fP
+devices encapsulate IPv4 or IPv6 (OSI Layer 3)
+.TP
+.B \fBtap\fP
+devices encapsulate Ethernet 802.3 (OSI Layer 2).
+.UNINDENT
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+dev tun2
+dev tap4
+dev ovpn
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When the device name starts with \fBtun\fP or \fBtap\fP, the device
+type is extracted automatically.  Otherwise the \fB\-\-dev\-type\fP option
+needs to be added as well.
+.TP
+.BI \-\-dev\-node \ node
+Explicitly set the device node rather than using \fB/dev/net/tun\fP,
+\fB/dev/tun\fP, \fB/dev/tap\fP, etc. If OpenVPN cannot figure out
+whether \fBnode\fP is a TUN or TAP device based on the name, you should
+also specify \fB\-\-dev\-type tun\fP or \fB\-\-dev\-type tap\fP\&.
+.sp
+Under Mac OS X this option can be used to specify the default tun
+implementation. Using \fB\-\-dev\-node utun\fP forces usage of the native
+Darwin tun kernel support. Use \fB\-\-dev\-node utunN\fP to select a specific
+utun instance. To force using the \fBtun.kext\fP (\fB/dev/tunX\fP)
+use \fB\-\-dev\-node tun\fP\&. When not specifying a \fB\-\-dev\-node\fP option
+openvpn will first try to open utun, and fall back to tun.kext.
+.sp
+On Windows systems, select the TAP\-Win32 adapter which is named \fBnode\fP
+in the Network Connections Control Panel or the raw GUID of the adapter
+enclosed by braces. The \fB\-\-show\-adapters\fP 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.
+.TP
+.BI \-\-dev\-type \ device\-type
+Which device type are we using? \fBdevice\-type\fP should be \fBtun\fP
+(OSI Layer 3) or \fBtap\fP (OSI Layer 2). Use this option only if
+the TUN/TAP device used with \fB\-\-dev\fP does not begin with \fBtun\fP
+or \fBtap\fP\&.
+.TP
+.BI \-\-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 \fBtap\-windows6\fP driver by default or directly by OpenVPN
+if dhcp is disabled or the \fBwintun\fP driver is in use. The
+\fBOpenVPN for Android\fP client also handles them internally.
+.sp
+On all other platforms these options are only saved in the client\(aqs
+environment under the name \fBforeign_options_{n}\fP before the
+\fB\-\-up\fP script is called. A plugin or an \fB\-\-up\fP script must be used to
+pick up and interpret these as required. Many Linux distributions include
+such scripts and some third\-party user interfaces such as tunnelblick also
+come with scripts that process these options.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+dhcp\-options type [parm]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 7.0
+.TP
+.B \fBDOMAIN\fP \fBname\fP
+Set Connection\-specific DNS Suffix to \fBname\fP\&.
+.TP
+.B \fBDOMAIN\-SEARCH\fP \fBname\fP
+Add \fBname\fP to the domain search list.
+Repeat this option to add more entries. Up to
+10 domains are supported.
+.TP
+.B \fBDNS\fP \fBaddress\fP
+Set primary domain name server IPv4 or IPv6 address.
+Repeat this option to set secondary DNS server addresses.
+.sp
+Note: DNS IPv6 servers are currently set using netsh (the existing
+DHCP code can only do IPv4 DHCP, and that protocol only permits
+IPv4 addresses anywhere). The option will be put into the
+environment, so an \fB\-\-up\fP script could act upon it if needed.
+.TP
+.B \fBWINS\fP \fBaddress\fP
+Set primary WINS server address (NetBIOS over TCP/IP Name Server).
+Repeat this option to set secondary WINS server addresses.
+.TP
+.B \fBNBDD\fP \fBaddress\fP
+Set primary NBDD server address (NetBIOS over TCP/IP Datagram
+Distribution Server). Repeat this option to set secondary NBDD
+server addresses.
+.TP
+.B \fBNTP\fP \fBaddress\fP
+Set primary NTP server address (Network Time Protocol).
+Repeat this option to set secondary NTP server addresses.
+.TP
+.B \fBNBT\fP \fBtype\fP
+Set NetBIOS over TCP/IP Node type. Possible options:
+.INDENT 7.0
+.TP
+.B \fB1\fP
+b\-node (broadcasts)
+.TP
+.B \fB2\fP
+p\-node (point\-to\-point name queries to a WINS server)
+.TP
+.B \fB4\fP
+m\-node (broadcast then query name server)
+.TP
+.B \fB8\fP
+h\-node (query name server, then broadcast).
+.UNINDENT
+.TP
+.B \fBNBS\fP \fBscope\-id\fP
+Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID provides 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 single 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 computers 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
+NetBIOS scopes courtesy of \fI\%NeonSurge@abyss.com\fP)
+.TP
+.B \fBDISABLE\-NBT\fP
+Disable Netbios\-over\-TCP/IP.
+.UNINDENT
+.TP
+.BI \-\-ifconfig \ args
+Set TUN/TAP adapter parameters. It requires the \fIIP address\fP 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 \fB\-\-topology subnet\fP, the second argument
+is the subnet mask of the virtual network segment which is being created
+or connected to.
+.sp
+For TUN devices, which facilitate virtual point\-to\-point IP connections
+(when used in \fB\-\-topology net30\fP or \fBp2p\fP mode), the proper usage of
+\fB\-\-ifconfig\fP is to use two private IP addresses which are not a member
+of any existing subnet which is in use. The IP addresses may be
+consecutive and should have their order reversed on the remote peer.
+After the VPN is established, by pinging \fBrn\fP, you will be pinging
+across the VPN.
+.sp
+For TAP devices, which provide the ability to create virtual ethernet
+segments, or TUN devices in \fB\-\-topology subnet\fP mode (which create
+virtual "multipoint networks"), \fB\-\-ifconfig\fP 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 purpose).
+.sp
+This option, while primarily a proxy for the \fBifconfig\fP(8) command,
+is designed to simplify TUN/TAP tunnel configuration by providing a
+standard interface to the different ifconfig implementations on
+different platforms.
+.sp
+\fB\-\-ifconfig\fP parameters which are IP addresses can also be specified
+as a DNS or /etc/hosts file resolvable name.
+.sp
+For TAP devices, \fB\-\-ifconfig\fP should not be used if the TAP interface
+will be getting an IP address lease from a DHCP server.
+.sp
+Examples:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# tun device in net30/p2p mode
+ifconfig 10.8.0.2 10.8.0.1
+
+# tun/tap device in subnet mode
+ifconfig 10.8.0.2 255.255.255.0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-ifconfig\-ipv6 \ args
+Configure an IPv6 address on the \fItun\fP device.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ifconfig\-ipv6 ipv6addr/bits [ipv6remote]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBipv6addr/bits\fP argument is the IPv6 address to use. The
+second parameter is used as route target for \fB\-\-route\-ipv6\fP if no
+gateway is specified.
+.sp
+The \fB\-\-topology\fP option has no influence with \fB\-\-ifconfig\-ipv6\fP
+.TP
+.B \-\-ifconfig\-noexec
+Don\(aqt actually execute ifconfig/netsh commands, instead pass
+\fB\-\-ifconfig\fP parameters to scripts using environmental variables.
+.TP
+.B \-\-ifconfig\-nowarn
+Don\(aqt output an options consistency check warning if the \fB\-\-ifconfig\fP
+option on this side of the connection doesn\(aqt match the remote side.
+This is useful when you want to retain the overall benefits of the
+options consistency check (also see \fB\-\-disable\-occ\fP option) while only
+disabling the ifconfig component of the check.
+.sp
+For example, if you have a configuration where the local host uses
+\fB\-\-ifconfig\fP but the remote host does not, use \fB\-\-ifconfig\-nowarn\fP
+on the local host.
+.sp
+This option will also silence warnings about potential address conflicts
+which occasionally annoy more experienced users by triggering "false
+positive" warnings.
+.TP
+.BI \-\-lladdr \ address
+Specify the link layer address, more commonly known as the MAC address.
+Only applied to TAP devices.
+.TP
+.B \-\-persist\-tun
+Don\(aqt close and reopen TUN/TAP device or run up/down scripts across
+\fBSIGUSR1\fP or \fB\-\-ping\-restart\fP restarts.
+.sp
+\fBSIGUSR1\fP is a restart signal similar to \fBSIGHUP\fP, but which
+offers finer\-grained control over reset options.
+.TP
+.BI \-\-redirect\-gateway \ flags
+Automatically execute routing commands to cause all outgoing IP traffic
+to be redirected over the VPN. This is a client\-side option.
+.sp
+This option performs three steps:
+.INDENT 7.0
+.IP 1. 3
+Create a static route for the \fB\-\-remote\fP address which
+forwards to the pre\-existing default gateway. This is done so that
+\fB(3)\fP will not create a routing loop.
+.IP 2. 3
+Delete the default gateway route.
+.IP 3. 3
+Set the new default gateway to be the VPN endpoint address
+(derived either from \fB\-\-route\-gateway\fP or the second parameter to
+\fB\-\-ifconfig\fP when \fB\-\-dev tun\fP is specified).
+.UNINDENT
+.sp
+When the tunnel is torn down, all of the above steps are reversed so
+that the original default route is restored.
+.sp
+Option flags:
+.INDENT 7.0
+.TP
+.B \fBlocal\fP
+Add the \fBlocal\fP flag if both OpenVPN peers are directly
+connected via a common subnet, such as with wireless. The
+\fBlocal\fP flag will cause step \fB(1)\fP above to be omitted.
+.TP
+.B \fBautolocal\fP
+Try to automatically determine whether to enable \fBlocal\fP
+flag above.
+.TP
+.B \fBdef1\fP
+Use this flag to override the default gateway by using
+\fB0.0.0.0/1\fP and \fB128.0.0.0/1\fP rather than
+\fB0.0.0.0/0\fP\&. This has the benefit of overriding but not
+wiping out the original default gateway.
+.TP
+.B \fBbypass\-dhcp\fP
+Add a direct route to the DHCP server (if it is non\-local) which
+bypasses the tunnel (Available on Windows clients, may not be
+available on non\-Windows clients).
+.TP
+.B \fBbypass\-dns\fP
+Add a direct route to the DNS server(s) (if they are non\-local)
+which bypasses the tunnel (Available on Windows clients, may
+not be available on non\-Windows clients).
+.TP
+.B \fBblock\-local\fP
+Block access to local LAN when the tunnel is active, except for
+the LAN gateway itself. This is accomplished by routing the local
+LAN (except for the LAN gateway address) into the tunnel.
+.TP
+.B \fBipv6\fP
+Redirect IPv6 routing into the tunnel. This works similar to
+the \fBdef1\fP flag, that is, more specific IPv6 routes are added
+(\fB2000::/4\fP, \fB3000::/4\fP), covering the whole IPv6
+unicast space.
+.TP
+.B \fB!ipv4\fP
+Do not redirect IPv4 traffic \- typically used in the flag pair
+\fBipv6 !ipv4\fP to redirect IPv6\-only.
+.UNINDENT
+.TP
+.BI \-\-redirect\-private \ flags
+Like \fB\-\-redirect\-gateway\fP, but omit actually changing the default gateway.
+Useful when pushing private subnets.
+.TP
+.BI \-\-route \ args
+Add route to routing table after connection is established. Multiple
+routes can be specified. Routes will be automatically torn down in
+reverse order prior to TUN/TAP device close.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route network/IP
+route network/IP netmask
+route network/IP netmask gateway
+route network/IP netmask gateway metric
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This option is intended as a convenience proxy for the \fBroute\fP(8)
+shell command, while at the same time providing portable semantics
+across OpenVPN\(aqs platform space.
+.INDENT 7.0
+.TP
+.B \fBnetmask\fP
+defaults to \fB255.255.255.255\fP when not given
+.TP
+.B \fBgateway\fP
+default taken from \fB\-\-route\-gateway\fP or the second
+parameter to \fB\-\-ifconfig\fP when \fB\-\-dev tun\fP is specified.
+.TP
+.B \fBmetric\fP
+default taken from \fB\-\-route\-metric\fP if set, otherwise \fB0\fP\&.
+.UNINDENT
+.sp
+The default can be specified by leaving an option blank or setting it to
+\fBdefault\fP\&.
+.sp
+The \fBnetwork\fP and \fBgateway\fP parameters can also be specified as a
+DNS or \fB/etc/hosts\fP file resolvable name, or as one of three special
+keywords:
+.INDENT 7.0
+.TP
+.B \fBvpn_gateway\fP
+The remote VPN endpoint address (derived either from
+\fB\-\-route\-gateway\fP or the second parameter to \fB\-\-ifconfig\fP
+when \fB\-\-dev tun\fP is specified).
+.TP
+.B \fBnet_gateway\fP
+The pre\-existing IP default gateway, read from the
+routing table (not supported on all OSes).
+.TP
+.B \fBremote_host\fP
+The \fB\-\-remote\fP address if OpenVPN is being run in
+client mode, and is undefined in server mode.
+.UNINDENT
+.TP
+.BI \-\-route\-delay \ args
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route\-delay
+route\-delay n
+route\-delay n m
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Delay \fBn\fP seconds (default \fB0\fP) after connection establishment,
+before adding routes. If \fBn\fP is \fB0\fP, routes will be added
+immediately upon connection establishment. If \fB\-\-route\-delay\fP is
+omitted, routes will be added immediately after TUN/TAP device open and
+\fB\-\-up\fP script execution, before any \fB\-\-user\fP or \fB\-\-group\fP privilege
+downgrade (or \fB\-\-chroot\fP execution.)
+.sp
+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.
+.sp
+On Windows, \fB\-\-route\-delay\fP tries to be more intelligent by waiting
+\fBw\fP seconds (default \fB30\fP by default) for the TAP\-Win32 adapter
+to come up before adding routes.
+.TP
+.BI \-\-route\-ipv6 \ args
+Setup IPv6 routing in the system to send the specified IPv6 network into
+OpenVPN\(aqs \fItun\fP\&.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route\-ipv6 ipv6addr/bits [gateway] [metric]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The gateway parameter is only used for IPv6 routes across \fItap\fP devices,
+and if missing, the \fBipv6remote\fP field from \fB\-\-ifconfig\-ipv6\fP or
+\fB\-\-route\-ipv6\-gateway\fP is used.
+.TP
+.BI \-\-route\-gateway \ arg
+Specify a default \fIgateway\fP for use with \fB\-\-route\fP\&.
+.sp
+If \fBdhcp\fP is specified as the parameter, the gateway address will
+be extracted from a DHCP negotiation with the OpenVPN server\-side LAN.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route\-gateway gateway
+route\-gateway dhcp
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.BI \-\-route\-ipv6\-gateway \ gw
+Specify a default gateway \fBgw\fP for use with \fB\-\-route\-ipv6\fP\&.
+.TP
+.BI \-\-route\-metric \ m
+Specify a default metric \fBm\fP for use with \fB\-\-route\fP\&.
+.TP
+.B \-\-route\-noexec
+Don\(aqt add or remove routes automatically. Instead pass routes to
+\fB\-\-route\-up\fP script using environmental variables.
+.TP
+.B \-\-route\-nopull
+When used with \fB\-\-client\fP or \fB\-\-pull\fP, accept options pushed by
+server EXCEPT for routes, block\-outside\-dns and dhcp options like DNS
+servers.
+.sp
+When used on the client, this option effectively bars the server from
+adding routes to the client\(aqs routing table, however note that this
+option still allows the server to set the TCP/IP properties of the
+client\(aqs TUN/TAP interface.
+.TP
+.BI \-\-topology \ mode
+Configure virtual addressing topology when running in \fB\-\-dev tun\fP
+mode. This directive has no meaning in \fB\-\-dev tap\fP mode, which always
+uses a \fBsubnet\fP topology.
+.sp
+If you set this directive on the server, the \fB\-\-server\fP and
+\fB\-\-server\-bridge\fP directives will automatically push your chosen
+topology setting to clients as well. This directive can also be manually
+pushed to clients. Like the \fB\-\-dev\fP directive, this directive must
+always be compatible between client and server.
+.sp
+\fBmode\fP can be one of:
+.INDENT 7.0
+.TP
+.B \fBnet30\fP
+Use a point\-to\-point topology, by allocating one /30 subnet
+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 2.0.
+.TP
+.B \fBp2p\fP
+Use a point\-to\-point topology where the remote endpoint of
+the client\(aqs tun interface always points to the local endpoint of the
+server\(aqs tun interface. This mode allocates a single IP address per
+connecting client. Only use when none of the connecting clients are
+Windows systems.
+.TP
+.B \fBsubnet\fP
+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 \fB\-\-dev tap\fP 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 \fB\-\-topology\fP 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 \fBifconfig\fP(8) command which
+sets a subnet instead of a remote endpoint IP address.
+.UNINDENT
+.sp
+\fINote:\fP Using \fB\-\-topology subnet\fP changes the interpretation of the
+arguments of \fB\-\-ifconfig\fP to mean "address netmask", no longer "local
+remote".
+.TP
+.BI \-\-tun\-mtu \ n
+Take the TUN device MTU to be \fBn\fP and derive the link MTU from it
+(default \fB1500\fP). In most cases, you will probably want to leave
+this parameter set to its default value.
+.sp
+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.
+.sp
+MTU problems often manifest themselves as connections which hang during
+periods of active usage.
+.sp
+It\(aqs best to use the \fB\-\-fragment\fP and/or \fB\-\-mssfix\fP options to deal
+with MTU sizing issues.
+.TP
+.BI \-\-tun\-mtu\-extra \ n
+Assume that the TUN/TAP device might return as many as \fBn\fP bytes more
+than the \fB\-\-tun\-mtu\fP size on read. This parameter defaults to 0, which
+is sufficient for most TUN devices. TAP devices may introduce additional
+overhead in excess of the MTU size, and a setting of 32 is the default
+when TAP devices are used. This parameter only controls internal OpenVPN
+buffer sizing, so there is no transmission overhead associated with
+using a larger value.
+.UNINDENT
+.SS TUN/TAP standalone operations
+.sp
+These two standalone operations will require \fB\-\-dev\fP and optionally
+\fB\-\-user\fP and/or \fB\-\-group\fP\&.
+.INDENT 0.0
+.TP
+.B \-\-mktun
+(Standalone) Create a persistent tunnel on platforms which support them
+such as Linux. Normally TUN/TAP tunnels exist only for the period of
+time that an application has them open. This option takes advantage of
+the TUN/TAP driver\(aqs ability to build persistent tunnels that live
+through multiple instantiations of OpenVPN and die only when they are
+deleted or the machine is rebooted.
+.sp
+One of the advantages of persistent tunnels is that they eliminate the
+need for separate \fB\-\-up\fP and \fB\-\-down\fP scripts to run the appropriate
+\fBifconfig\fP(8) and \fBroute\fP(8) commands. These commands can be
+placed in the the same shell script which starts or terminates an
+OpenVPN session.
+.sp
+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 connectivity through the tunnel in the
+event of a DHCP reset of the peer\(aqs public IP address (see the
+\fB\-\-ipchange\fP option above).
+.sp
+One disadvantage of persistent tunnels is that it is harder to
+automatically configure their MTU value (see \fB\-\-link\-mtu\fP and
+\fB\-\-tun\-mtu\fP above).
+.sp
+On some platforms such as Windows, TAP\-Win32 tunnels are persistent by
+default.
+.TP
+.B \-\-rmtun
+(Standalone) Remove a persistent tunnel.
+.UNINDENT
+.SS Virtual Routing and Forwarding
+.sp
+Options in this section relates to configuration of virtual routing and
+forwarding in combination with the underlying operating system.
+.sp
+As of today this is only supported on Linux, a kernel >= 4.9 is
+recommended.
+.sp
+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 regular
+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.
+.sp
+Another option would be to put the tun/tap interface into a VRF. This could
+be done by an up\-script which uses the \fBip link set\fP command shown
+below.
+.SS VRF setup with iproute2
+.sp
+Create VRF \fBvrf_external\fP and map it to routing table \fB1023\fP
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ip link add vrf_external type vrf table 1023
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Move \fBeth0\fP into \fBvrf_external\fP
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ip link set master vrf_external dev eth0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Any prefixes configured on \fBeth0\fP will be moved from the :code\(gamain\(ga
+routing table into routing table \fI1023\fP
+.SS VRF setup with ifupdown
+.sp
+For Debian based Distributions \fBifupdown2\fP provides an almost drop\-in
+replacement for \fBifupdown\fP including VRFs and other features.
+A configuration for an interface \fBeth0\fP being part of VRF
+code:\fIvrf_external\fP could look like this:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+auto eth0
+iface eth0
+    address 192.0.2.42/24
+    address 2001:db8:08:15::42/64
+    gateway 192.0.2.1
+    gateway 2001:db8:08:15::1
+    vrf vrf_external
+
+auto vrf_external
+iface vrf_external
+    vrf\-table 1023
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS OpenVPN configuration
+.sp
+The OpenVPN configuration needs to contain this line:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+bind\-dev vrf_external
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Further reading
+.sp
+Wikipedia has nice page one VRFs: \fI\%https://en.wikipedia.org/wiki/Virtual_routing_and_forwarding\fP
+.sp
+This talk from the Network Track of FrOSCon 2018 provides an overview about
+advanced layer 2 and layer 3 features of Linux
+.INDENT 0.0
+.INDENT 3.5
+.INDENT 0.0
+.IP \(bu 2
+Slides: \fI\%https://www.slideshare.net/BarbarossaTM/l2l3\-fr\-fortgeschrittene\-helle\-und\-dunkle\-magie\-im\-linuxnetzwerkstack\fP
+.IP \(bu 2
+Video (german): \fI\%https://media.ccc.de/v/froscon2018\-2247\-l2_l3_fur_fortgeschrittene_\-_helle_und_dunkle_magie_im_linux\-netzwerkstack\fP
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SH SCRIPTING INTEGRATION
+.sp
+OpenVPN can execute external scripts in various phases of the lifetime of
+the OpenVPN process.
+.SS Script Order of Execution
+.INDENT 0.0
+.IP 1. 4
+\fB\-\-up\fP
+.sp
+Executed after TCP/UDP socket bind and TUN/TAP open.
+.IP 2. 4
+\fB\-\-tls\-verify\fP
+.sp
+Executed when we have a still untrusted remote peer.
+.IP 3. 4
+\fB\-\-ipchange\fP
+.sp
+Executed after connection authentication, or remote IP address change.
+.IP 4. 4
+\fB\-\-client\-connect\fP
+.sp
+Executed in \fB\-\-mode server\fP mode immediately after client
+authentication.
+.IP 5. 4
+\fB\-\-route\-up\fP
+.sp
+Executed after connection authentication, either immediately after, or
+some number of seconds after as defined by the \fB\-\-route\-delay\fP option.
+.IP 6. 4
+\fB\-\-route\-pre\-down\fP
+.sp
+Executed right before the routes are removed.
+.IP 7. 4
+\fB\-\-client\-disconnect\fP
+.sp
+Executed in \fB\-\-mode server\fP mode on client instance shutdown.
+.IP 8. 4
+\fB\-\-down\fP
+.sp
+Executed after TCP/UDP and TUN/TAP close.
+.IP 9. 4
+\fB\-\-learn\-address\fP
+.sp
+Executed in \fB\-\-mode server\fP mode whenever an IPv4 address/route or MAC
+address is added to OpenVPN\(aqs internal routing table.
+.IP 10. 4
+\fB\-\-auth\-user\-pass\-verify\fP
+.sp
+Executed in \fB\-\-mode server\fP mode on new client connections, when the
+client is still untrusted.
+.UNINDENT
+.SS SCRIPT HOOKS
+.INDENT 0.0
+.TP
+.BI \-\-auth\-user\-pass\-verify \ args
+Require the client to provide a username/password (possibly in addition
+to a client certificate) for authentication.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+auth\-user\-pass\-verify cmd method
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+OpenVPN will run command \fBcmd\fP to validate the username/password
+provided by the client.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+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.
+.sp
+If \fBmethod\fP is set to \fBvia\-env\fP, OpenVPN will call \fBscript\fP
+with the environmental variables \fBusername\fP and \fBpassword\fP
+set to the username/password strings provided by the client. \fIBeware\fP
+that this method is insecure on some platforms which make the environment
+of a process publicly visible to other unprivileged processes.
+.sp
+If \fBmethod\fP is set to \fBvia\-file\fP, 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 \fBscript\fP, and the file will be
+automatically deleted by OpenVPN after the script returns. The location
+of the temporary file is controlled by the \fB\-\-tmp\-dir\fP option, and
+will default to the current directory if unspecified. For security,
+consider setting \fB\-\-tmp\-dir\fP to a volatile storage medium such as
+\fB/dev/shm\fP (if available) to prevent the username/password file
+from touching the hard drive.
+.sp
+The script should examine the username and password, returning a success
+exit code (\fB0\fP) if the client\(aqs authentication request is to be
+accepted, or a failure code (\fB1\fP) to reject the client.
+.sp
+This directive is designed to enable a plugin\-style interface for
+extending OpenVPN\(aqs authentication capabilities.
+.sp
+To protect against a client passing a maliciously formed username or
+password string, the username string must consist only of these
+characters: alphanumeric, underbar (\(aq\fB_\fP\(aq), dash (\(aq\fB\-\fP\(aq),
+dot (\(aq\fB\&.\fP\(aq), or at (\(aq\fB@\fP\(aq). 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 (\(aq\fB_\fP\(aq).
+.sp
+Care must be taken by any user\-defined scripts to avoid creating a
+security vulnerability in the way that these strings are handled. Never
+use these strings in such a way that they might be escaped or evaluated
+by a shell interpreter.
+.sp
+For a sample script that performs PAM authentication, see
+\fBsample\-scripts/auth\-pam.pl\fP in the OpenVPN source distribution.
+.TP
+.BI \-\-client\-connect \ cmd
+Run command \fBcmd\fP on client connection.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+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.
+.sp
+The command is passed the common name and IP address of the
+just\-authenticated client as environmental variables (see environmental
+variable section below). The command is also passed the pathname of a
+freshly created temporary file as the last argument (after any arguments
+specified in \fBcmd\fP ), to be used by the command to pass dynamically
+generated config file directives back to OpenVPN.
+.sp
+If the script wants to generate a dynamic config file to be applied on
+the server when the client connects, it should write it to the file
+named by the last argument.
+.sp
+See the \fB\-\-client\-config\-dir\fP option below for options which can be
+legally used in a dynamically generated config file.
+.sp
+Note that the return value of \fBscript\fP is significant. If \fBscript\fP
+returns a non\-zero error status, it will cause the client to be
+disconnected.
+.sp
+If a \fB\-\-client\-connect\fP wants to defer the generating of the
+configuration then the script needs to use the
+\fBclient_connect_deferred_file\fP and
+\fBclient_connect_config_file\fP environment variables, and write
+status accordingly into these files.  See the \fI\%Environmental Variables\fP
+section for more details.
+.TP
+.BI \-\-client\-disconnect \ cmd
+Like \fB\-\-client\-connect\fP but called on client instance shutdown. Will
+not be called unless the \fB\-\-client\-connect\fP script and plugins (if
+defined) were previously called on this instance with successful (0)
+status returns.
+.sp
+The exception to this rule is if the \fB\-\-client\-disconnect\fP command or
+plugins are cascaded, and at least one client\-connect function
+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.
+.sp
+The \fB\-\-client\-disconnect\fP command is passed the same pathname as the
+corresponding \fB\-\-client\-connect\fP command as its last argument (after
+any arguments specified in \fBcmd\fP).
+.TP
+.BI \-\-down \ cmd
+Run command \fBcmd\fP after TUN/TAP device close (post \fB\-\-user\fP UID
+change and/or \fB\-\-chroot\fP ). \fBcmd\fP 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 using a
+backslash, and should be separated by one or more spaces.
+.sp
+Called with the same parameters and environmental variables as the
+\fB\-\-up\fP option above.
+.sp
+Note that if you reduce privileges by using \fB\-\-user\fP and/or
+\fB\-\-group\fP, your \fB\-\-down\fP script will also run at reduced privilege.
+.TP
+.B \-\-down\-pre
+Call \fB\-\-down\fP cmd/script before, rather than after, TUN/TAP close.
+.TP
+.BI \-\-ipchange \ cmd
+Run command \fBcmd\fP when our remote ip\-address is initially
+authenticated or changes.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+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.
+.sp
+When \fBcmd\fP is executed two arguments are appended after any arguments
+specified in \fBcmd\fP , as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmd ip address port number
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Don\(aqt use \fB\-\-ipchange\fP in \fB\-\-mode server\fP mode. Use a
+\fB\-\-client\-connect\fP script instead.
+.sp
+See the \fI\%Environmental Variables\fP section below for additional
+parameters passed as environmental variables.
+.sp
+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 \fB/etc/hosts\fP file with the current
+address of the peer. The script will be run every time the remote peer
+changes its IP address.
+.sp
+Similarly if \fIour\fP IP address changes due to DHCP, we should configure
+our IP address change script (see man page for \fBdhcpcd\fP(8)) to
+deliver a \fBSIGHUP\fP or \fBSIGUSR1\fP signal to OpenVPN. OpenVPN will
+then re\-establish a connection with its most recently authenticated
+peer on its new IP address.
+.TP
+.BI \-\-learn\-address \ cmd
+Run command \fBcmd\fP to validate client virtual addresses or routes.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+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.
+.sp
+Three arguments will be appended to any arguments in \fBcmd\fP as follows:
+.INDENT 7.0
+.TP
+.B \fB$1\fP \- [operation]
+\fB"add"\fP, \fB"update"\fP, or \fB"delete"\fP based on whether
+or not the address is being added to, modified, or deleted from
+OpenVPN\(aqs internal routing table.
+.TP
+.B \fB$2\fP \- [address]
+The address being learned or unlearned. This can be an IPv4 address
+such as \fB"198.162.10.14"\fP, an IPv4 subnet such as
+\fB"198.162.10.0/24"\fP, or an ethernet MAC address (when
+\fB\-\-dev tap\fP is being used) such as \fB"00:FF:01:02:03:04"\fP\&.
+.TP
+.B \fB$3\fP \- [common name]
+The common name on the certificate associated with the client linked
+to this address. Only present for \fB"add"\fP or \fB"update"\fP
+operations, not \fB"delete"\fP\&.
+.UNINDENT
+.sp
+On \fB"add"\fP or \fB"update"\fP methods, if the script returns
+a failure code (non\-zero), OpenVPN will reject the address and will not
+modify its internal routing table.
+.sp
+Normally, the \fBcmd\fP script will use the information provided above to
+set appropriate firewall entries on the VPN TUN/TAP interface. Since
+OpenVPN provides the association between virtual IP or MAC address and
+the client\(aqs authenticated common name, it allows a user\-defined script
+to configure firewall access policies with regard to the client\(aqs
+high\-level common name, rather than the low level client virtual
+addresses.
+.TP
+.BI \-\-route\-up \ cmd
+Run command \fBcmd\fP after routes are added, subject to \fB\-\-route\-delay\fP\&.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+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.
+.sp
+See the \fI\%Environmental Variables\fP section below for additional
+parameters passed as environmental variables.
+.TP
+.BI \-\-route\-pre\-down \ cmd
+Run command \fBcmd\fP before routes are removed upon disconnection.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+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.
+.sp
+See the \fI\%Environmental Variables\fP section below for additional
+parameters passed as environmental variables.
+.TP
+.BI \-\-setenv \ args
+Set a custom environmental variable \fBname=value\fP to pass to script.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+setenv name value
+setenv FORWARD_COMPATIBLE 1
+setenv opt config_option
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+By setting \fBFORWARD_COMPATIBLE\fP to \fB1\fP, 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.
+.sp
+This option should be used with caution, as there are good security
+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 encountered by older software
+versions.
+.sp
+It is also possible to tag a single directive so as not to trigger a
+fatal error if the directive isn\(aqt recognized. To do this, prepend the
+following before the directive: \fBsetenv opt\fP
+.sp
+Versions prior to OpenVPN 2.3.3 will always ignore options set with the
+\fBsetenv opt\fP directive.
+.sp
+See also \fB\-\-ignore\-unknown\-option\fP
+.TP
+.BI \-\-setenv\-safe \ args
+Set a custom environmental variable \fBOPENVPN_name\fP to \fBvalue\fP
+to pass to scripts.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+setenv\-safe name value
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This directive is designed to be pushed by the server to clients, and
+the prepending of \fBOPENVPN_\fP to the environmental variable is a
+safety precaution to prevent a \fBLD_PRELOAD\fP style attack from a
+malicious or compromised server.
+.TP
+.BI \-\-tls\-verify \ cmd
+Run command \fBcmd\fP to verify the X509 name of a pending TLS connection
+that has otherwise passed all other tests of certification (except for
+revocation via \fB\-\-crl\-verify\fP directive; the revocation test occurs
+after the \fB\-\-tls\-verify\fP test).
+.sp
+\fBcmd\fP should return \fB0\fP to allow the TLS handshake to proceed,
+or \fB1\fP to fail.
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+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.
+.sp
+When \fBcmd\fP is executed two arguments are appended after any arguments
+specified in \fBcmd\fP, as follows:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmd certificate_depth subject
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+These arguments are, respectively, the current certificate depth and the
+X509 subject distinguished name (dn) of the peer.
+.sp
+This feature is useful if the peer you want to trust has a certificate
+which was signed by a certificate authority who also signed many other
+certificates, where you don\(aqt 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 \fBverify\-cn\fP in the OpenVPN distribution.
+.sp
+See the \fI\%Environmental Variables\fP section below for additional
+parameters passed as environmental variables.
+.TP
+.BI \-\-up \ cmd
+Run command \fBcmd\fP after successful TUN/TAP device open (pre \fB\-\-user\fP
+UID change).
+.sp
+\fBcmd\fP consists of a path to a script (or executable program), optionally
+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.
+.sp
+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.
+.sp
+For \fB\-\-dev tun\fP execute as:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [init | restart]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For \fB\-\-dev tap\fP execute as:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [init | restart]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+See the \fI\%Environmental Variables\fP section below for additional
+parameters passed as environmental variables.
+.sp
+Note that if \fBcmd\fP includes arguments, all OpenVPN\-generated arguments
+will be appended to them to build an argument list with which the
+executable will be called.
+.sp
+Typically, \fBcmd\fP will run a script to add routes to the tunnel.
+.sp
+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 \fIinit.\fP If the \fB\-\-up\-restart\fP option is also used, the up script
+will be called for restarts as well. A restart is considered to be a
+partial reinitialization of OpenVPN where the TUN/TAP instance is
+preserved (the \fB\-\-persist\-tun\fP option will enable such preservation).
+A restart can be generated by a SIGUSR1 signal, a \fB\-\-ping\-restart\fP
+timeout, or a connection reset when the TCP protocol is enabled with the
+\fB\-\-proto\fP option. If a restart occurs, and \fB\-\-up\-restart\fP has been
+specified, the up script will be called with \fIrestart\fP as the last
+parameter.
+.INDENT 7.0
+.TP
+.B \fINOTE:\fP
+On restart, OpenVPN will not pass the full set of environment
+variables to the script. Namely, everything related 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 configured).
+.UNINDENT
+.sp
+The following standalone example shows how the \fB\-\-up\fP script can be
+called in both an initialization and restart context. (\fINOTE:\fP for
+security reasons, don\(aqt 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).
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-dev tun \-\-port 9999 \-\-verb 4 \-\-ping\-restart 10 \e
+        \-\-up \(aqecho up\(aq \-\-down \(aqecho down\(aq \-\-persist\-tun  \e
+        \-\-up\-restart
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Note that OpenVPN also provides the \fB\-\-ifconfig\fP option to
+automatically ifconfig the TUN device, eliminating the need to define an
+\fB\-\-up\fP script, unless you also want to configure routes in the
+\fB\-\-up\fP script.
+.sp
+If \fB\-\-ifconfig\fP is also specified, OpenVPN will pass the ifconfig
+local and remote endpoints on the command line to the \fB\-\-up\fP script so
+that they can be used to configure routes such as:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route add \-net 10.0.0.0 netmask 255.255.255.0 gw $5
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.B \-\-up\-delay
+Delay TUN/TAP open and possible \fB\-\-up\fP script execution until after
+TCP/UDP connection establishment with peer.
+.sp
+In \fB\-\-proto udp\fP mode, this option normally requires the use of
+\fB\-\-ping\fP to allow connection initiation to be sensed in the absence of
+tunnel data, since UDP is a "connectionless" protocol.
+.sp
+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 peer.
+.TP
+.B \-\-up\-restart
+Enable the \fB\-\-up\fP and \fB\-\-down\fP scripts to be called for restarts as
+well as initial program start. This option is described more fully above
+in the \fB\-\-up\fP option documentation.
+.UNINDENT
+.SS String Types and Remapping
+.sp
+In certain cases, OpenVPN will perform remapping of characters in
+strings. Essentially, any characters outside the set of permitted
+characters for each string type will be converted to underbar (\(aq_\(aq).
+.INDENT 0.0
+.TP
+.B \fIQ: Why is string remapping necessary?\fP
+It\(aqs an important security feature to prevent the malicious
+coding 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.
+.TP
+.B \fIQ: Can string remapping be disabled?\fP
+Yes, by using the \fB\-\-no\-name\-remapping\fP option, however this
+should be considered an advanced option.
+.UNINDENT
+.sp
+Here is a brief rundown of OpenVPN\(aqs current string types and the
+permitted character class for each string:
+.INDENT 0.0
+.TP
+.B \fIX509 Names\fP
+Alphanumeric, underbar (\(aq_\(aq), dash (\(aq\-\(aq), dot (\(aq.\(aq), at
+(\(aq@\(aq), colon (\(aq:\(aq), slash (\(aq/\(aq), and equal (\(aq=\(aq). Alphanumeric is
+defined as a character which will cause the C library isalnum() function
+to return true.
+.TP
+.B \fICommon Names\fP
+Alphanumeric, underbar (\(aq_\(aq), dash (\(aq\-\(aq), dot (\(aq.\(aq), and at (\(aq@\(aq).
+.TP
+.B \fI\-\-auth\-user\-pass username\fP
+Same as Common Name, with one exception:
+starting with OpenVPN 2.0.1, the username is passed to the
+\fBOPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY\fP plugin in its raw form,
+without string remapping.
+.TP
+.B \fI\-\-auth\-user\-pass password\fP
+Any "printable" character except CR or LF. Printable is defined to be
+a character which will cause the C library isprint() function to
+return true.
+.TP
+.B \fI\-\-client\-config\-dir filename as derived from common name or\(gausername\fP
+Alphanumeric, underbar (\(aq_\(aq), dash (\(aq\-\(aq), and dot (\(aq.\(aq) except for "."
+or ".." as standalone strings. As of v2.0.1\-rc6, the at (\(aq@\(aq) character
+has been added as well for compatibility with the common name character
+class.
+.TP
+.B \fIEnvironmental variable names\fP
+Alphanumeric or underbar (\(aq_\(aq).
+.TP
+.B \fIEnvironmental variable values\fP
+Any printable character.
+.UNINDENT
+.sp
+For all cases, characters in a string which are not members of the legal
+character class for that string type will be remapped to underbar
+(\(aq_\(aq).
+.SS Environmental Variables
+.sp
+Once set, a variable is persisted indefinitely until it is reset by a
+new value or a restart,
+.sp
+As of OpenVPN 2.0\-beta12, in server mode, environmental variables set by
+OpenVPN are scoped according to the client objects they are associated
+with, so there should not be any issues with scripts having access to
+stale, previously set variables which refer to different client
+instances.
+.INDENT 0.0
+.TP
+.B \fBbytes_received\fP
+Total number of bytes received from client during VPN session. Set prior
+to execution of the \fB\-\-client\-disconnect\fP script.
+.TP
+.B \fBbytes_sent\fP
+Total number of bytes sent to client during VPN session. Set prior to
+execution of the \fB\-\-client\-disconnect\fP script.
+.TP
+.B \fBclient_connect_config_file\fP
+The path to the configuration file that should be written to by the
+\fB\-\-client\-connect\fP script (optional, if per\-session configuration
+is desired).  This is the same file name as passed via command line
+argument on the call to the \fB\-\-client\-connect\fP script.
+.TP
+.B \fBclient_connect_deferred_file\fP
+This file can be optionally written to in order to to communicate a
+status code of the \fB\-\-client\-connect\fP script or plgin.  Only the
+first character in the file is relevant.  It must be either \fB1\fP
+to indicate normal script execution, \fB0\fP indicates an error (in
+the same way that a non zero exit status does) or \fB2\fP to indicate
+that the script deferred returning the config file.
+.sp
+For deferred (background) handling, the script or plugin MUST write
+\fB2\fP to the file to indicate the deferral and then return with
+exit code \fB0\fP to signal \fBdeferred handler started OK\fP\&.
+.sp
+A background process or similar must then take care of writing the
+configuration to the file indicated by the
+\fBclient_connect_config_file\fP environment variable and when
+finished, write the a \fB1\fP to this file (or \fB0\fP in case of
+an error).
+.sp
+The absence of any character in the file when the script finishes
+executing is interpreted the same as \fB1\fP\&. This allows scripts
+that are not written to support the defer mechanism to be used
+unmodified.
+.TP
+.B \fBcommon_name\fP
+The X509 common name of an authenticated client. Set prior to execution
+of \fB\-\-client\-connect\fP, \fB\-\-client\-disconnect\fP and
+\fB\-\-auth\-user\-pass\-verify\fP scripts.
+.TP
+.B \fBconfig\fP
+Name of first \fB\-\-config\fP file. Set on program initiation and reset on
+SIGHUP.
+.TP
+.B \fBdaemon\fP
+Set to "1" if the \fB\-\-daemon\fP directive is specified, or "0" otherwise.
+Set on program initiation and reset on SIGHUP.
+.TP
+.B \fBdaemon_log_redirect\fP
+Set to "1" if the \fB\-\-log\fP or \fB\-\-log\-append\fP directives are
+specified, or "0" otherwise. Set on program initiation and reset on
+SIGHUP.
+.TP
+.B \fBdev\fP
+The actual name of the TUN/TAP device, including a unit number if it
+exists. Set prior to \fB\-\-up\fP or \fB\-\-down\fP script execution.
+.TP
+.B \fBdev_idx\fP
+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 \fB\-\-up\fP or \fB\-\-down\fP script execution.
+.TP
+.B \fBforeign_option_{n}\fP
+An option pushed via \fB\-\-push\fP to a client which does not natively
+support it, such as \fB\-\-dhcp\-option\fP on a non\-Windows system, will be
+recorded to this environmental variable sequence prior to \fB\-\-up\fP
+script execution.
+.TP
+.B \fBifconfig_broadcast\fP
+The broadcast address for the virtual ethernet segment which is derived
+from the \fB\-\-ifconfig\fP option when \fB\-\-dev tap\fP is used. Set prior to
+OpenVPN calling the \fBifconfig\fP or \fBnetsh\fP (windows version
+of ifconfig) commands which normally occurs prior to \fB\-\-up\fP script
+execution.
+.TP
+.B \fBifconfig_ipv6_local\fP
+The local VPN endpoint IPv6 address specified in the
+\fB\-\-ifconfig\-ipv6\fP option (first parameter). Set prior to OpenVPN
+calling the \fBifconfig\fP or code:\fInetsh\fP (windows version of
+ifconfig) commands which normally occurs prior to \fB\-\-up\fP script
+execution.
+.TP
+.B \fBifconfig_ipv6_netbits\fP
+The prefix length of the IPv6 network on the VPN interface. Derived
+from the /nnn parameter of the IPv6 address in the \fB\-\-ifconfig\-ipv6\fP
+option (first parameter). Set prior to OpenVPN calling the
+\fBifconfig\fP or \fBnetsh\fP (windows version of ifconfig)
+commands which normally occurs prior to \fB\-\-up\fP script execution.
+.TP
+.B \fBifconfig_ipv6_remote\fP
+The remote VPN endpoint IPv6 address specified in the
+\fB\-\-ifconfig\-ipv6\fP option (second parameter). Set prior to OpenVPN
+calling the \fBifconfig\fP or \fBnetsh\fP (windows version of
+ifconfig) commands which normally occurs prior to \fB\-\-up\fP script
+execution.
+.TP
+.B \fBifconfig_local\fP
+The local VPN endpoint IP address specified in the \fB\-\-ifconfig\fP
+option (first parameter). Set prior to OpenVPN calling the
+\fBifconfig\fP or \fBnetsh\fP (windows version of ifconfig)
+commands which normally occurs prior to \fB\-\-up\fP script execution.
+.TP
+.B \fBifconfig_remote\fP
+The remote VPN endpoint IP address specified in the \fB\-\-ifconfig\fP
+option (second parameter) when \fB\-\-dev tun\fP is used. Set prior to
+OpenVPN calling the \fBifconfig\fP or \fBnetsh\fP (windows version
+of ifconfig) commands which normally occurs prior to \fB\-\-up\fP script
+execution.
+.TP
+.B \fBifconfig_netmask\fP
+The subnet mask of the virtual ethernet segment that is specified as
+the second parameter to \fB\-\-ifconfig\fP when \fB\-\-dev tap\fP is being
+used. Set prior to OpenVPN calling the \fBifconfig\fP or
+\fBnetsh\fP (windows version of ifconfig) commands which normally
+occurs prior to \fB\-\-up\fP script execution.
+.TP
+.B \fBifconfig_pool_local_ip\fP
+The local virtual IP address for the TUN/TAP tunnel taken from an
+\fB\-\-ifconfig\-push\fP directive if specified, or otherwise from the
+ifconfig pool (controlled by the \fB\-\-ifconfig\-pool\fP config file
+directive). Only set for \fB\-\-dev tun\fP tunnels. This option is set on
+the server prior to execution of the \fB\-\-client\-connect\fP and
+\fB\-\-client\-disconnect\fP scripts.
+.TP
+.B \fBifconfig_pool_netmask\fP
+The virtual IP netmask for the TUN/TAP tunnel taken from an
+\fB\-\-ifconfig\-push\fP directive if specified, or otherwise from the
+ifconfig pool (controlled by the \fB\-\-ifconfig\-pool\fP config file
+directive). Only set for \fB\-\-dev tap\fP tunnels. This option is set on
+the server prior to execution of the \fB\-\-client\-connect\fP and
+\fB\-\-client\-disconnect\fP scripts.
+.TP
+.B \fBifconfig_pool_remote_ip\fP
+The remote virtual IP address for the TUN/TAP tunnel taken from an
+\fB\-\-ifconfig\-push\fP directive if specified, or otherwise from the
+ifconfig pool (controlled by the \fB\-\-ifconfig\-pool\fP config file
+directive). This option is set on the server prior to execution of the
+\fB\-\-client\-connect\fP and \fB\-\-client\-disconnect\fP scripts.
+.TP
+.B \fBlink_mtu\fP
+The maximum packet size (not including the IP header) of tunnel data in
+UDP tunnel transport mode. Set prior to \fB\-\-up\fP or \fB\-\-down\fP script
+execution.
+.TP
+.B \fBlocal\fP
+The \fB\-\-local\fP parameter. Set on program initiation and reset on
+SIGHUP.
+.TP
+.B \fBlocal_port\fP
+The local port number or name, specified by \fB\-\-port\fP or \fB\-\-lport\fP\&.
+Set on program initiation and reset on SIGHUP.
+.TP
+.B \fBpassword\fP
+The password provided by a connecting client. Set prior to
+\fB\-\-auth\-user\-pass\-verify\fP script execution only when the \fBvia\-env\fP
+modifier is specified, and deleted from the environment after the script
+returns.
+.TP
+.B \fBproto\fP
+The \fB\-\-proto\fP parameter. Set on program initiation and reset on
+SIGHUP.
+.TP
+.B \fBremote_{n}\fP
+The \fB\-\-remote\fP parameter. Set on program initiation and reset on
+SIGHUP.
+.TP
+.B \fBremote_port_{n}\fP
+The remote port number, specified by \fB\-\-port\fP or \fB\-\-rport\fP\&. Set on
+program initiation and reset on SIGHUP.
+.TP
+.B \fBroute_net_gateway\fP
+The pre\-existing default IP gateway in the system routing table. Set
+prior to \fB\-\-up\fP script execution.
+.TP
+.B \fBroute_vpn_gateway\fP
+The default gateway used by \fB\-\-route\fP options, as specified in either
+the \fB\-\-route\-gateway\fP option or the second parameter to
+\fB\-\-ifconfig\fP when \fB\-\-dev tun\fP is specified. Set prior to \fB\-\-up\fP
+script execution.
+.TP
+.B \fBroute_{parm}_{n}\fP
+A set of variables which define each route to be added, and are set
+prior to \fB\-\-up\fP script execution.
+.sp
+\fBparm\fP will be one of \fBnetwork\fP, \fBnetmask"\fP,
+\fBgateway\fP, or \fBmetric\fP\&.
+.sp
+\fBn\fP is the OpenVPN route number, starting from 1.
+.sp
+If the network or gateway are resolvable DNS names, their IP address
+translations will be recorded rather than their names as denoted on the
+command line or configuration file.
+.TP
+.B \fBroute_ipv6_{parm}_{n}\fP
+A set of variables which define each IPv6 route to be added, and are
+set prior to \fB\-\-up\fP script execution.
+.sp
+\fBparm\fP will be one of \fBnetwork\fP or \fBgateway\fP
+(\fBnetmask\fP is contained as \fB/nnn\fP in the
+\fBroute_ipv6_network_{n}\fP, unlike IPv4 where it is passed in a
+separate environment variable).
+.sp
+\fBn\fP is the OpenVPN route number, starting from 1.
+.sp
+If the network or gateway are resolvable DNS names, their IP address
+translations will be recorded rather than their names as denoted on the
+command line or configuration file.
+.TP
+.B \fBpeer_cert\fP
+Temporary file name containing the client certificate upon connection.
+Useful in conjunction with \fB\-\-tls\-verify\fP\&.
+.TP
+.B \fBscript_context\fP
+Set to "init" or "restart" prior to up/down script execution. For more
+information, see documentation for \fB\-\-up\fP\&.
+.TP
+.B \fBscript_type\fP
+Prior to execution of any script, this variable is set to the type of
+script being run. It can be one of the following: \fBup\fP,
+\fBdown\fP, \fBipchange\fP, \fBroute\-up\fP, \fBtls\-verify\fP,
+\fBauth\-user\-pass\-verify\fP, \fBclient\-connect\fP,
+\fBclient\-disconnect\fP or \fBlearn\-address\fP\&. Set prior to
+execution of any script.
+.TP
+.B \fBsignal\fP
+The reason for exit or restart. Can be one of \fBsigusr1\fP,
+\fBsighup\fP, \fBsigterm\fP, \fBsigint\fP, \fBinactive\fP
+(controlled by \fB\-\-inactive\fP option), \fBping\-exit\fP (controlled
+by \fB\-\-ping\-exit\fP option), \fBping\-restart\fP (controlled by
+\fB\-\-ping\-restart\fP option), \fBconnection\-reset\fP (triggered on TCP
+connection reset), \fBerror\fP or \fBunknown\fP (unknown signal).
+This variable is set just prior to down script execution.
+.TP
+.B \fBtime_ascii\fP
+Client connection timestamp, formatted as a human\-readable time string.
+Set prior to execution of the \fB\-\-client\-connect\fP script.
+.TP
+.B \fBtime_duration\fP
+The duration (in seconds) of the client session which is now
+disconnecting. Set prior to execution of the \fB\-\-client\-disconnect\fP
+script.
+.TP
+.B \fBtime_unix\fP
+Client connection timestamp, formatted as a unix integer date/time
+value. Set prior to execution of the \fB\-\-client\-connect\fP script.
+.TP
+.B \fBtls_digest_{n}\fP / \fBtls_digest_sha256_{n}\fP
+Contains the certificate SHA1 / SHA256 fingerprint, where \fBn\fP is the
+verification level. Only set for TLS connections. Set prior to execution
+of \fB\-\-tls\-verify\fP script.
+.TP
+.B \fBtls_id_{n}\fP
+A series of certificate fields from the remote peer, where \fBn\fP is the
+verification level. Only set for TLS connections. Set prior to execution
+of \fB\-\-tls\-verify\fP script.
+.TP
+.B \fBtls_serial_{n}\fP
+The serial number of the certificate from the remote peer, where \fBn\fP
+is the verification level. Only set for TLS connections. Set prior to
+execution of \fB\-\-tls\-verify\fP script. This is in the form of a decimal
+string like "933971680", which is suitable for doing 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
+\fBcontrib/OCSP_check/OCSP_check.sh\fP script for an example.
+.TP
+.B \fBtls_serial_hex_{n}\fP
+Like \fBtls_serial_{n}\fP, but in hex form (e.g.
+\fB12:34:56:78:9A\fP).
+.TP
+.B \fBtun_mtu\fP
+The MTU of the TUN/TAP device. Set prior to \fB\-\-up\fP or \fB\-\-down\fP
+script execution.
+.TP
+.B \fBtrusted_ip\fP / \fBtrusted_ip6\fP)
+Actual IP address of connecting client or peer which has been
+authenticated. Set prior to execution of \fB\-\-ipchange\fP,
+\fB\-\-client\-connect\fP and \fB\-\-client\-disconnect\fP scripts. If using ipv6
+endpoints (udp6, tcp6), \fBtrusted_ip6\fP will be set instead.
+.TP
+.B \fBtrusted_port\fP
+Actual port number of connecting client or peer which has been
+authenticated. Set prior to execution of \fB\-\-ipchange\fP,
+\fB\-\-client\-connect\fP and \fB\-\-client\-disconnect\fP scripts.
+.TP
+.B \fBuntrusted_ip\fP / \fBuntrusted_ip6\fP
+Actual IP address of connecting client or peer which has not been
+authenticated yet. Sometimes used to \fInmap\fP the connecting host in a
+\fB\-\-tls\-verify\fP script to ensure it is firewalled properly. Set prior
+to execution of \fB\-\-tls\-verify\fP and \fB\-\-auth\-user\-pass\-verify\fP
+scripts. If using ipv6 endpoints (udp6, tcp6), \fBuntrusted_ip6\fP
+will be set instead.
+.TP
+.B \fBuntrusted_port\fP
+Actual port number of connecting client or peer which has not been
+authenticated yet. Set prior to execution of \fB\-\-tls\-verify\fP and
+\fB\-\-auth\-user\-pass\-verify\fP scripts.
+.TP
+.B \fBusername\fP
+The username provided by a connecting client. Set prior to
+\fB\-\-auth\-user\-pass\-verify\fP script execution only when the
+\fBvia\-env\fP modifier is specified.
+.TP
+.B \fBX509_{n}_{subject_field}\fP
+An X509 subject field from the remote peer certificate, where \fBn\fP is
+the verification level. Only set for TLS connections. Set prior to
+execution of \fB\-\-tls\-verify\fP script. This variable is similar to
+\fBtls_id_{n}\fP 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 "\fB_\fP"). For example, 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.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+X509_0_emailAddress=me@myhost.mydomain
+X509_0_CN=Test\-Client
+X509_0_O=OpenVPN\-TEST
+X509_0_ST=NA
+X509_0_C=KG
+X509_1_emailAddress=me@myhost.mydomain
+X509_1_O=OpenVPN\-TEST
+X509_1_L=BISHKEK
+X509_1_ST=NA
+X509_1_C=KG
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SS Management Interface Options
+.sp
+OpenVPN provides a feature rich socket based management interface for both
+server and client mode operations.
+.INDENT 0.0
+.TP
+.BI \-\-management \ args
+Enable a management server on a \fBsocket\-name\fP Unix socket on those
+platforms supporting it, or on a designated TCP port.
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+management socket\-name unix          #
+management socket\-name unix pw\-file  # (recommended)
+management IP port                   # (INSECURE)
+management IP port pw\-file           #
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBpw\-file\fP, if specified, is a password file where the password must
+be on first line. Instead of a filename it can use the keyword stdin
+which will prompt the user for a password to use when OpenVPN is
+starting.
+.sp
+For unix sockets, the default behaviour is to create a unix domain
+socket that may be connected to by any process. Use the
+\fB\-\-management\-client\-user\fP and \fB\-\-management\-client\-group\fP
+directives to restrict access.
+.sp
+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 \fBtunnel\fP\&. Tunnel mode will cause the management interface to
+listen for a TCP connection on the local VPN address of the TUN/TAP
+interface.
+.sp
+\fB*BEWARE*\fP of enabling the management interface over TCP. In these cases
+you should \fIALWAYS\fP make use of \fBpw\-file\fP to password protect the
+management interface. Any user who can connect to this TCP \fBIP:port\fP
+will be able to manage and control (and interfere with) the OpenVPN
+process. It is also strongly recommended to set IP to 127.0.0.1
+(localhost) to restrict accessibility of the management server to local
+clients.
+.sp
+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 \fBhelp\fP
+for a list of commands.
+.sp
+For detailed documentation on the management interface, see the
+\fImanagement\-notes.txt\fP file in the management folder of the OpenVPN
+source distribution.
+.TP
+.B \-\-management\-client
+Management interface will connect as a TCP/unix domain client to
+\fBIP:port\fP specified by \fB\-\-management\fP rather than listen as a TCP
+server or on a unix domain socket.
+.sp
+If the client connection fails to connect or is disconnected, a SIGTERM
+signal will be generated causing OpenVPN to quit.
+.TP
+.B \-\-management\-client\-auth
+Gives management interface client the responsibility to authenticate
+clients after their client certificate has been verified. See
+\fBmanagement\-notes.txt\fP in OpenVPN distribution for detailed notes.
+.TP
+.BI \-\-management\-client\-group \ g
+When the management interface is listening on a unix domain socket, only
+allow connections from group \fBg\fP\&.
+.TP
+.B \-\-management\-client\-pf
+Management interface clients must specify a packet filter file for each
+connecting client. See \fBmanagement\-notes.txt\fP in OpenVPN
+distribution for detailed notes.
+.TP
+.BI \-\-management\-client\-user \ u
+When the management interface is listening on a unix domain socket, only
+allow connections from user \fBu\fP\&.
+.TP
+.BI \-\-management\-external\-cert \ certificate\-hint
+Allows usage for external certificate instead of \fB\-\-cert\fP option
+(client\-only). \fBcertificate\-hint\fP is an arbitrary string which is
+passed to a management interface client as an argument of
+\fINEED\-CERTIFICATE\fP notification. Requires \fB\-\-management\-external\-key\fP\&.
+.TP
+.BI \-\-management\-external\-key \ args
+Allows usage for external private key file instead of \fB\-\-key\fP option
+(client\-only).
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+management\-external\-key
+management\-external\-key nopadding
+management\-external\-key pkcs1
+management\-external\-key nopadding pkcs1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The optional parameters \fBnopadding\fP and \fBpkcs1\fP signal
+support for different padding algorithms. See
+\fBdoc/mangement\-notes.txt\fP for a complete description of this
+feature.
+.TP
+.B \-\-management\-forget\-disconnect
+Make OpenVPN forget passwords when management session disconnects.
+.sp
+This directive does not affect the \fB\-\-http\-proxy\fP username/password.
+It is always cached.
+.TP
+.B \-\-management\-hold
+Start OpenVPN in a hibernating state, until a client of the management
+interface explicitly starts it with the \fBhold release\fP command.
+.TP
+.BI \-\-management\-log\-cache \ n
+Cache the most recent \fBn\fP lines of log file history for usage by the
+management channel.
+.TP
+.B \-\-management\-query\-passwords
+Query management channel for private key password and
+\fB\-\-auth\-user\-pass\fP username/password. Only query the management
+channel for inputs which ordinarily would have been queried from the
+console.
+.TP
+.B \-\-management\-query\-proxy
+Query management channel for proxy server information for a specific
+\fB\-\-remote\fP (client\-only).
+.TP
+.B \-\-management\-query\-remote
+Allow management interface to override \fB\-\-remote\fP directives
+(client\-only).
+.TP
+.B \-\-management\-signal
+Send SIGUSR1 signal to OpenVPN if management session disconnects. This
+is useful when you wish to disconnect an OpenVPN session on user logoff.
+For \fB\-\-management\-client\fP this option is not needed since a disconnect
+will always generate a \fBSIGTERM\fP\&.
+.TP
+.B \-\-management\-up\-down
+Report tunnel up/down events to management interface.
+.UNINDENT
+.SS Plug\-in Interface Options
+.sp
+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.
+.INDENT 0.0
+.TP
+.BI \-\-plugin \ args
+Loads an OpenVPN plug\-in module.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+plugin module\-name
+plugin module\-name "arguments"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBmodule\-name\fP 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 consists of multiple arguments it must be enclosed in
+double\-quotes (").  Multiple plugin modules may be loaded into one
+OpenVPN process.
+.sp
+The \fBmodule\-name\fP 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.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-plugin path         Effective directory used
+===================== =============================
+ myplug.so            DEFAULT_DIR/myplug.so
+ subdir/myplug.so     DEFAULT_DIR/subdir/myplug.so
+ ./subdir/myplug.so   CWD/subdir/myplug.so
+ /usr/lib/my/plug.so  /usr/lib/my/plug.so
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fBDEFAULT_DIR\fP is replaced by the default plug\-in directory, which is
+configured at the build time of OpenVPN. \fBCWD\fP is the current directory
+where OpenVPN was started or the directory OpenVPN have switched into
+via the \fB\-\-cd\fP option before the \fB\-\-plugin\fP option.
+.sp
+For more information and examples on how to build OpenVPN plug\-in
+modules, see the README file in the \fBplugin\fP folder of the OpenVPN
+source distribution.
+.sp
+If you are using an RPM install of OpenVPN, see
+\fB/usr/share/openvpn/plugin\fP\&. The documentation is in \fBdoc\fP and
+the actual plugin modules are in \fBlib\fP\&.
+.sp
+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 module/script controls an authentication function
+(such as tls\-verify, auth\-user\-pass\-verify, or client\-connect), then
+every module and script must return success (\fB0\fP) in order for the
+connection to be authenticated.
+.UNINDENT
+.SS Windows\-Specific Options
+.INDENT 0.0
+.TP
+.BI \-\-allow\-nonadmin \ TAP\-adapter
+(Standalone) Set \fBTAP\-adapter\fP to allow access from non\-administrative
+accounts. If \fBTAP\-adapter\fP 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 administrator.
+.TP
+.B \-\-block\-outside\-dns
+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.
+.sp
+This option is considered unknown on non\-Windows platforms and
+unsupported on Windows XP, resulting in fatal error. You may want to use
+\fB\-\-setenv opt\fP or \fB\-\-ignore\-unknown\-option\fP (not suitable for
+Windows XP) to ignore said error. Note that pushing unknown options from
+server does not trigger fatal errors.
+.TP
+.BI \-\-cryptoapicert \ select\-string
+\fI(Windows/OpenSSL Only)\fP Load the certificate and private key from the
+Windows Certificate System Store.
+.sp
+Use this option instead of \fB\-\-cert\fP and \fB\-\-key\fP\&.
+.sp
+This makes it possible to use any smart card, supported by Windows, 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.
+.sp
+To select a certificate, based on a substring search in the
+certificate\(aqs subject:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cryptoapicert "SUBJ:Peter Runestig"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+To select a certificate, based on certificate\(aqs thumbprint:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The thumbprint hex string can easily be copy\-and\-pasted from the Windows
+Certificate Store GUI.
+.TP
+.B \-\-dhcp\-release
+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.
+.TP
+.B \-\-dhcp\-renew
+Ask Windows to renew the TAP adapter lease on startup. This option is
+normally unnecessary, as Windows automatically triggers a DHCP
+renegotiation on the TAP adapter when it comes up, however if you set
+the TAP\-Win32 adapter Media Status property to "Always Connected", you
+may need this flag.
+.TP
+.BI \-\-ip\-win32 \ method
+When using \fB\-\-ifconfig\fP on Windows, set the TAP\-Win32 adapter IP
+address and netmask using \fBmethod\fP\&. Don\(aqt use this option unless you
+are also using \fB\-\-ifconfig\fP\&.
+.INDENT 7.0
+.TP
+.B \fBmanual\fP
+Don\(aqt set the IP address or netmask automatically. Instead
+output a message to the console telling the user to configure the
+adapter manually and indicating the IP/netmask which OpenVPN
+expects the adapter to be set to.
+.TP
+.B \fBdynamic [offset] [lease\-time]\fP
+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 protocol. There are, however, two
+prerequisites for using this mode:
+.INDENT 7.0
+.IP 1. 3
+The TCP/IP properties for the TAP\-Win32 adapter must be set
+to "Obtain an IP address automatically", and
+.IP 2. 3
+OpenVPN needs to claim an IP address in the subnet for use
+as the virtual DHCP server address.
+.UNINDENT
+.sp
+By default in \fB\-\-dev tap\fP mode, OpenVPN will take the normally
+unused first address in the subnet. For example, if your subnet is
+\fB192.168.4.0 netmask 255.255.255.0\fP, then OpenVPN will take
+the IP address \fB192.168.4.0\fP to use as the virtual DHCP
+server address.  In \fB\-\-dev tun\fP mode, OpenVPN will cause the DHCP
+server to masquerade as if it were coming from the remote endpoint.
+.sp
+The optional offset parameter is an integer which is > \fB\-256\fP
+and < \fB256\fP and which defaults to \-1. If offset is positive,
+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 broadcast address + offset.
+.sp
+The Windows \fBipconfig /all\fP 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 address. Having said that,
+different OpenVPN instantiations, including different ends of
+the same connection, can share the same virtual DHCP server
+address.
+.sp
+The \fBlease\-time\fP 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.
+.TP
+.B \fBnetsh\fP
+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.
+.TP
+.B \fBipapi\fP
+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 automatically."
+.TP
+.B \fBadaptive\fP (Default)
+Try \fBdynamic\fP method initially and fail over to \fBnetsh\fP
+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 installed on the client machine block
+the DHCP negotiation used by the TAP\-Win32 adapter. Note that if
+the \fBnetsh\fP 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 \fBadaptive\fP mode to use
+\fBnetsh\fP immediately, rather than trying \fBdynamic\fP first.
+.sp
+To "unstick" the \fBadaptive\fP mode from using \fBnetsh\fP,
+run OpenVPN at least once using the \fBdynamic\fP mode to restore
+the TAP\-Win32 adapter TCP/IP properties to a DHCP configuration.
+.UNINDENT
+.TP
+.B \-\-pause\-exit
+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.
+.TP
+.B \-\-register\-dns
+Run \fBipconfig /flushdns\fP and \fBipconfig /registerdns\fP on
+connection initiation. This is known to kick Windows into recognizing
+pushed DNS servers.
+.TP
+.BI \-\-route\-method \ m
+Which method \fBm\fP to use for adding routes on Windows?
+.INDENT 7.0
+.TP
+.B \fBadaptive\fP (default)
+Try IP helper API first. If that fails, fall back to the route.exe
+shell command.
+.TP
+.B \fBipapi\fP
+Use IP helper API.
+.TP
+.B \fBexe\fP
+Call the route.exe shell command.
+.UNINDENT
+.TP
+.BI \-\-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.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+service exit\-event [0|1]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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 service.
+.sp
+\fBexit\-event\fP 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.
+.sp
+The second parameter indicates the initial state of \fBexit\-event\fP and
+normally defaults to 0.
+.sp
+Multiple OpenVPN processes can be simultaneously executed with the same
+\fBexit\-event\fP parameter. In any case, the controlling process can
+signal \fBexit\-event\fP, causing all such OpenVPN processes to exit.
+.sp
+When executing an OpenVPN process using the \fB\-\-service\fP directive,
+OpenVPN will probably not have a console window to output status/error
+messages, therefore it is useful to use \fB\-\-log\fP or \fB\-\-log\-append\fP to
+write these messages to a file.
+.TP
+.B \-\-show\-adapters
+(Standalone) Show available TAP\-Win32 adapters which can be selected
+using the \fB\-\-dev\-node\fP option. On non\-Windows systems, the
+\fBifconfig\fP(8) command provides similar functionality.
+.TP
+.B \-\-show\-net
+(Standalone) Show OpenVPN\(aqs view of the system routing table and network
+adapter list.
+.TP
+.B \-\-show\-net\-up
+Output OpenVPN\(aqs 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.
+.TP
+.B \-\-show\-valid\-subnets
+(Standalone) Show valid subnets for \fB\-\-dev tun\fP emulation. Since the
+TAP\-Win32 driver exports an ethernet interface to Windows, and since TUN
+devices are point\-to\-point in nature, it is necessary for the TAP\-Win32
+driver to impose certain constraints on TUN endpoint address selection.
+.sp
+Namely, the point\-to\-point endpoints used in TUN device emulation must
+be the middle two addresses of a /30 subnet (netmask 255.255.255.252).
+.TP
+.BI \-\-tap\-sleep \ n
+Cause OpenVPN to sleep for \fBn\fP seconds immediately after the TAP\-Win32
+adapter state is set to "connected".
+.sp
+This option is intended to be used to troubleshoot problems with the
+\fB\-\-ifconfig\fP and \fB\-\-ip\-win32\fP options, and is used to give the
+TAP\-Win32 adapter time to come up before Windows IP Helper API
+operations are applied to it.
+.TP
+.BI \-\-win\-sys \ path
+Set the Windows system directory pathname to use when looking for system
+executables such as \fBroute.exe\fP and \fBnetsh.exe\fP\&. By default, if this
+directive is not specified, OpenVPN will use the SystemRoot environment
+variable.
+.sp
+This option has changed behaviour since OpenVPN 2.3. Earlier you had to
+define \fB\-\-win\-sys env\fP to use the SystemRoot environment variable,
+otherwise it defaulted to \fBC:\e\eWINDOWS\fP\&. It is not needed to use
+the \fBenv\fP keyword any more, and it will just be ignored. A warning is
+logged when this is found in the configuration file.
+.TP
+.BI \-\-windows\-driver \ drv
+Specifies which tun driver to use. Values are \fBtap\-windows6\fP
+(default) and \fBwintun\fP\&.  This is a Windows\-only option.
+\fBwintun\fP" requires \fB\-\-dev tun\fP and the OpenVPN process to run
+elevated, or be invoked using the Interactive Service.
+.UNINDENT
+.SS Standalone Debug Options
+.INDENT 0.0
+.TP
+.BI \-\-show\-gateway \ args
+(Standalone) Show current IPv4 and IPv6 default gateway and interface
+towards the gateway (if the protocol in question is enabled).
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+\-\-show\-gateway
+\-\-show\-gateway IPv6\-target
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If an IPv6 target address is passed as argument, the IPv6 route for this
+host is reported.
+.UNINDENT
+.SS Advanced Expert Options
+.sp
+These are options only required when special tweaking is needed, often
+used when debugging or testing out special usage scenarios.
+.INDENT 0.0
+.TP
+.BI \-\-hash\-size \ args
+Set the size of the real address hash table to \fBr\fP and the virtual
+address table to \fBv\fP\&.
+.sp
+Valid syntax:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+hash\-size r v
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+By default, both tables are sized at 256 buckets.
+.TP
+.BI \-\-bcast\-buffers \ n
+Allocate \fBn\fP buffers for broadcast datagrams (default \fB256\fP).
+.TP
+.B \-\-persist\-local\-ip
+Preserve initially resolved local IP address and port number across
+\fBSIGUSR1\fP or \fB\-\-ping\-restart\fP restarts.
+.TP
+.B \-\-persist\-remote\-ip
+Preserve most recently authenticated remote IP address and port number
+across \fBSIGUSR1\fP or \fB\-\-ping\-restart\fP restarts.
+.TP
+.BI \-\-prng \ args
+\fI(Advanced)\fP Change the PRNG (Pseudo\-random number generator) parameters
+.sp
+Valid syntaxes:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+prng alg
+prng alg nsl
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Changes the PRNG to use digest algorithm \fBalg\fP (default \fBsha1\fP),
+and set \fBnsl\fP (default \fB16\fP) to the size in bytes of the nonce
+secret length (between 16 and 64).
+.sp
+Set \fBalg\fP to \fBnone\fP to disable the PRNG and use the OpenSSL
+RAND_bytes function instead for all of OpenVPN\(aqs pseudo\-random number
+needs.
+.TP
+.BI \-\-rcvbuf \ size
+Set the TCP/UDP socket receive buffer size. Defaults to operating system
+default.
+.TP
+.BI \-\-shaper \ n
+Limit bandwidth of outgoing tunnel data to \fBn\fP bytes per second on the
+TCP/UDP port. Note that this will only work if mode is set to
+\fBp2p\fP\&.  If you want to limit the bandwidth in both directions, use
+this option on both peers.
+.sp
+OpenVPN uses the following algorithm to implement traffic shaping: Given
+a shaper rate of \fBn\fP bytes per second, after a datagram write of \fBb\fP
+bytes is queued on the TCP/UDP port, wait a minimum of \fB(b / n)\fP
+seconds before queuing the next write.
+.sp
+It should be noted that OpenVPN supports multiple tunnels between the
+same two peers, allowing you to construct full\-speed and reduced
+bandwidth tunnels at the same time, routing low\-priority data such as
+off\-site backups over the reduced bandwidth tunnel, and other data over
+the full\-speed tunnel.
+.sp
+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.
+.sp
+OpenVPN allows \fBn\fP to be between 100 bytes/sec and 100 Mbytes/sec.
+.TP
+.BI \-\-sndbuf \ size
+Set the TCP/UDP socket send buffer size. Defaults to operating system
+default.
+.TP
+.BI \-\-tcp\-queue\-limit \ n
+Maximum number of output packets queued before TCP (default \fB64\fP).
+.sp
+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 connection can support. When
+the number of output packets queued before sending to the TCP socket
+reaches this limit for a given client connection, OpenVPN will start to
+drop outgoing packets directed at this client.
+.TP
+.BI \-\-txqueuelen \ n
+\fI(Linux only)\fP Set the TX queue length on the TUN/TAP interface.
+Currently defaults to operating system default.
+.UNINDENT
+.SH UNSUPPORTED OPTIONS
+.sp
+Options listed in this section have been removed from OpenVPN and are no
+longer supported
+.INDENT 0.0
+.TP
+.B \-\-client\-cert\-not\-required
+Removed in OpenVPN 2.5.  This should be replaxed with
+\fB\-\-verify\-client\-cert none\fP\&.
+.TP
+.B \-\-ifconfig\-pool\-linear
+Removed in OpenVPN 2.5.  This should be replaced with \fB\-\-topology p2p\fP\&.
+.TP
+.B \-\-key\-method
+Removed in OpenVPN 2.5.  This option should not be used, as using the old
+\fBkey\-method\fP weakens the VPN tunnel security.  The old \fBkey\-method\fP
+was also only needed when the remote side was older than OpenVPN 2.0.
+.TP
+.B \-\-no\-iv
+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.
+.TP
+.B \-\-no\-replay
+Removed in OpenVPN 2.5.  This option should not be used as it weakens the
+VPN tunnel security.
+.TP
+.B \-\-ns\-cert\-type
+Removed in OpenVPN 2.5.  The \fBnsCertType\fP field is no longer supported
+in recent SSL/TLS libraries.  If your certificates does not include \fIkey
+usage\fP and \fIextended key usage\fP fields, they must be upgraded and the
+\fB\-\-remote\-cert\-tls\fP option should be used instead.
+.UNINDENT
+.SH CONNECTION PROFILES
+.sp
+Client configuration files may contain multiple remote servers which
+it will attempt to connect against.  But there are some configuration
+options which are related to specific \fB\-\-remote\fP options.  For these
+use cases, connection profiles are the solution.
+.sp
+By enacpulating the \fB\-\-remote\fP option and related options within
+\fB<connection>\fP and \fB</connection>\fP, these options are handled as a
+group.
+.sp
+An OpenVPN client will try each connection profile sequentially until it
+achieves a successful connection.
+.sp
+\fB\-\-remote\-random\fP can be used to initially "scramble" the connection
+list.
+.sp
+Here is an example of connection profile usage:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+client
+dev tun
+
+<connection>
+remote 198.19.34.56 1194 udp
+</connection>
+
+<connection>
+remote 198.19.34.56 443 tcp
+</connection>
+
+<connection>
+remote 198.19.34.56 443 tcp
+http\-proxy 192.168.0.8 8080
+</connection>
+
+<connection>
+remote 198.19.36.99 443 tcp
+http\-proxy 192.168.0.8 8080
+</connection>
+
+persist\-key
+persist\-tun
+pkcs12 client.p12
+remote\-cert\-tls server
+verb 3
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+First we try to connect to a server at 198.19.34.56:1194 using UDP. If
+that fails, we then try to connect to 198.19.34.56:443 using TCP. If
+that also fails, then try connecting through an HTTP proxy at
+192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to connect
+through the same proxy to a server at 198.19.36.99:443 using TCP.
+.sp
+The following OpenVPN options may be used inside of a \fB<connection>\fP
+block:
+.sp
+\fBbind\fP, \fBconnect\-retry\fP, \fBconnect\-retry\-max\fP, \fBconnect\-timeout\fP,
+\fBexplicit\-exit\-notify\fP, \fBfloat\fP, \fBfragment\fP, \fBhttp\-proxy\fP,
+\fBhttp\-proxy\-option\fP, \fBkey\-direction\fP, \fBlink\-mtu\fP, \fBlocal\fP,
+\fBlport\fP, \fBmssfix\fP, \fBmtu\-disc\fP, \fBnobind\fP, \fBport\fP, \fBproto\fP,
+\fBremote\fP, \fBrport\fP, \fBsocks\-proxy\fP, \fBtls\-auth\fP, \fBtls\-crypt\fP,
+\fBtun\-mtu and\fP, \fBtun\-mtu\-extra\fP\&.
+.sp
+A defaulting mechanism exists for specifying options to apply to all
+\fB<connection>\fP profiles. If any of the above options (with the
+exception of \fBremote\fP ) appear outside of a \fB<connection>\fP block,
+but in a configuration file which has one or more \fB<connection>\fP
+blocks, the option setting will be used as a default for
+\fB<connection>\fP blocks which follow it in the configuration file.
+.sp
+For example, suppose the \fBnobind\fP option were placed in the sample
+configuration file above, near the top of the file, before the first
+\fB<connection>\fP block. The effect would be as if \fBnobind\fP were
+declared in all \fB<connection>\fP blocks below it.
+.SH INLINE FILE SUPPORT
+.sp
+OpenVPN allows including files in the main configuration for the \fB\-\-ca\fP,
+\fB\-\-cert\fP, \fB\-\-dh\fP, \fB\-\-extra\-certs\fP, \fB\-\-key\fP, \fB\-\-pkcs12\fP,
+\fB\-\-secret\fP, \fB\-\-crl\-verify\fP, \fB\-\-http\-proxy\-user\-pass\fP, \fB\-\-tls\-auth\fP,
+\fB\-\-auth\-gen\-token\-secret\fP, \fB\-\-tls\-crypt\fP and \fB\-\-tls\-crypt\-v2\fP
+options.
+.sp
+Each inline file started by the line \fB<option>\fP and ended by the line
+\fB</option>\fP
+.sp
+Here is an example of an inline file usage
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+<cert>
+\-\-\-\-\-BEGIN CERTIFICATE\-\-\-\-\-
+[...]
+\-\-\-\-\-END CERTIFICATE\-\-\-\-\-
+</cert>
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When using the inline file feature with \fB\-\-pkcs12\fP the inline file has
+to be base64 encoded. Encoding of a .p12 file into base64 can be done
+for example with OpenSSL by running \fBopenssl base64 \-in input.p12\fP
+.SH SIGNALS
+.INDENT 0.0
+.TP
+.B \fBSIGHUP\fP
+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.
+.TP
+.B \fBSIGUSR1\fP
+Like \fBSIGHUP\(ga\fP, except don\(aqt re\-read configuration file, and
+possibly don\(aqt close and reopen TUN/TAP device, re\-read key files,
+preserve local IP address/port, or preserve most recently authenticated
+remote IP address/port based on \fB\-\-persist\-tun\fP, \fB\-\-persist\-key\fP,
+\fB\-\-persist\-local\-ip\fP and \fB\-\-persist\-remote\-ip\fP options respectively
+(see above).
+.sp
+This signal may also be internally generated by a timeout condition,
+governed by the \fB\-\-ping\-restart\fP option.
+.sp
+This signal, when combined with \fB\-\-persist\-remote\-ip\fP, may be sent
+when the underlying parameters of the host\(aqs network interface change
+such as when the host is a DHCP client and is assigned a new IP address.
+See \fB\-\-ipchange\fP for more information.
+.TP
+.B \fBSIGUSR2\fP
+Causes OpenVPN to display its current statistics (to the syslog file if
+\fB\-\-daemon\fP is used, or stdout otherwise).
+.TP
+.B \fBSIGINT\fP, \fBSIGTERM\fP
+Causes OpenVPN to exit gracefully.
+.UNINDENT
+.SH EXAMPLES
+.sp
+Prior to running these examples, you should have OpenVPN installed on
+two machines with network connectivity between them. If you have not yet
+installed OpenVPN, consult the INSTALL file included in the OpenVPN
+distribution.
+.SS Firewall Setup:
+.sp
+If firewalls exist between the two machines, they should be set to
+forward the port OpenVPN is configured to use, in both directions.
+The default for OpenVPN is 1194/udp.  If you do not have control
+over the firewalls between the two machines, you may still be able to
+use OpenVPN by adding \fB\-\-ping 15\fP to each of the \fBopenvpn\fP commands
+used below in the examples (this will cause each peer to send out a UDP
+ping to its remote peer once every 15 seconds which will cause many
+stateful firewalls to forward packets in both directions without an
+explicit firewall rule).
+.sp
+Please see your operating system guides for how to configure the firewall
+on your systems.
+.SS VPN Address Setup:
+.sp
+For purposes of our example, our two machines will be called
+\fBbob.example.com\fP and \fBalice.example.com\fP\&. If you are constructing a
+VPN over the internet, then replace \fBbob.example.com\fP and
+\fBalice.example.com\fP with the internet hostname or IP address that each
+machine will use to contact the other over the internet.
+.sp
+Now we will choose the tunnel endpoints. Tunnel endpoints are private IP
+addresses that only have meaning in the context of the VPN. Each machine
+will use the tunnel endpoint of the other machine to access it over the
+VPN. In our example, the tunnel endpoint for bob.example.com will be
+10.4.0.1 and for alice.example.com, 10.4.0.2.
+.sp
+Once the VPN is established, you have essentially created a secure
+alternate path between the two hosts which is addressed by using the
+tunnel endpoints. You can control which network traffic passes between
+the hosts (a) over the VPN or (b) independently of the VPN, by choosing
+whether to use (a) the VPN endpoint address or (b) the public internet
+address, to access the remote host. For example if you are on
+bob.example.com and you wish to connect to \fBalice.example.com\fP via
+\fBssh\fP without using the VPN (since \fBssh\fP has its own built\-in security)
+you would use the command \fBssh alice.example.com\fP\&. However in the same
+scenario, you could also use the command \fBtelnet 10.4.0.2\fP to create a
+telnet session with alice.example.com over the VPN, that would use the
+VPN to secure the session rather than \fBssh\fP\&.
+.sp
+You can use any address you wish for the tunnel endpoints but make sure
+that they are private addresses (such as those that begin with 10 or
+192.168) and that they are not part of any existing subnet on the
+networks of either peer, unless you are bridging. If you use an address
+that is part of your local subnet for either of the tunnel endpoints,
+you will get a weird feedback loop.
+.SS Example 1: A simple tunnel without security
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-remote alice.example.com \-\-dev tun1 \e
+         \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 9
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-remote bob.example.com \-\-dev tun1 \e
+         \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 9
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now verify the tunnel is working by pinging across the tunnel.
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ping 10.4.0.2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ping 10.4.0.1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fB\-\-verb 9\fP option will produce verbose output, similar to the
+\fBtcpdump\fP(8) program. Omit the \fB\-\-verb 9\fP option to have OpenVPN run
+quietly.
+.SS Example 2: A tunnel with static\-key security (i.e. using a pre\-shared secret)
+.sp
+First build a static key on bob.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-genkey \-\-secret key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This command will build a key file called \fBkey\fP (in ascii format). Now
+copy \fBkey\fP to \fBalice.example.com\fP over a secure medium such as by using
+the \fBscp\fP(1) program.
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-remote alice.example.com \-\-dev tun1  \e
+         \-\-ifconfig 10.4.0.1 10.4.0.2 \-\-verb 5 \e
+         \-\-secret key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-remote bob.example.com \-\-dev tun1   \e
+        \-\-ifconfig 10.4.0.2 10.4.0.1 \-\-verb 5 \e
+        \-\-secret key
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now verify the tunnel is working by pinging across the tunnel.
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ping 10.4.0.2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ping 10.4.0.1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Example 3: A tunnel with full TLS\-based security
+.sp
+For this test, we will designate \fBbob\fP as the TLS client and \fBalice\fP
+as the TLS server.
+.INDENT 0.0
+.TP
+.B \fINote:\fP
+The client or server designation only has
+meaning for the TLS subsystem. It has no bearing on OpenVPN\(aqs
+peer\-to\-peer, UDP\-based communication model.*
+.UNINDENT
+.sp
+First, build a separate certificate/key pair for both bob and alice (see
+above where \fB\-\-cert\fP is discussed for more info). Then construct
+Diffie Hellman parameters (see above where \fB\-\-dh\fP is discussed for
+more info). You can also use the included test files \fBclient.crt\fP,
+\fBclient.key\fP, \fBserver.crt\fP, \fBserver.key\fP and
+\fBca.crt\fP\&. The \fB\&.crt\fP files are certificates/public\-keys, the
+\fB\&.key\fP files are private keys, and \fBca.crt\fP is a certification
+authority who has signed both \fBclient.crt\fP and \fBserver.crt\fP\&.
+For Diffie Hellman parameters you can use the included file
+\fBdh2048.pem\fP\&.
+.INDENT 0.0
+.TP
+.B \fIWARNING:\fP
+All client, server, and certificate authority certificates
+and keys included in the OpenVPN distribution are totally
+insecure and should be used for testing only.
+.UNINDENT
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-remote alice.example.com \-\-dev tun1    \e
+        \-\-ifconfig 10.4.0.1 10.4.0.2             \e
+        \-\-tls\-client \-\-ca ca.crt                 \e
+        \-\-cert client.crt \-\-key client.key       \e
+        \-\-reneg\-sec 60 \-\-verb 5
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+openvpn \-\-remote bob.example.com \-\-dev tun1      \e
+        \-\-ifconfig 10.4.0.2 10.4.0.1             \e
+        \-\-tls\-server \-\-dh dh1024.pem \-\-ca ca.crt \e
+        \-\-cert server.crt \-\-key server.key       \e
+        \-\-reneg\-sec 60 \-\-verb 5
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now verify the tunnel is working by pinging across the tunnel.
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ping 10.4.0.2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ping 10.4.0.1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Notice the \fB\-\-reneg\-sec 60\fP option we used above. That tells OpenVPN
+to renegotiate the data channel keys every minute. Since we used
+\fB\-\-verb 5\fP above, you will see status information on each new key
+negotiation.
+.sp
+For production operations, a key renegotiation interval of 60 seconds is
+probably too frequent. Omit the \fB\-\-reneg\-sec 60\fP option to use
+OpenVPN\(aqs default key renegotiation interval of one hour.
+.SS Routing:
+.sp
+Assuming you can ping across the tunnel, the next step is to route a
+real subnet over the secure tunnel. Suppose that bob and alice have two
+network interfaces each, one connected to the internet, and the other to
+a private network. Our goal is to securely connect both private
+networks. We will assume that bob\(aqs private subnet is \fI10.0.0.0/24\fP and
+alice\(aqs is \fI10.0.1.0/24\fP\&.
+.sp
+First, ensure that IP forwarding is enabled on both peers. On Linux,
+enable routing:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+echo 1 > /proc/sys/net/ipv4/ip_forward
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This setting is not persistent.  Please see your operating systems
+documentation how to properly configure IP forwarding, which is also
+persistent through system boots.
+.sp
+If your system is configured with a firewall.  Please see your operating
+systems guide on how to configure the firewall.  You typically want to
+allow traffic coming from and going to the tun/tap adapter OpenVPN is
+configured to use.
+.sp
+On bob:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route add \-net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On alice:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+route add \-net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Now any machine on the \fI10.0.0.0/24\fP subnet can access any machine on the
+\fI10.0.1.0/24\fP subnet over the secure tunnel (or vice versa).
+.sp
+In a production environment, you could put the route command(s) in a
+script and execute with the \fB\-\-up\fP option.
+.SH FAQ
+.sp
+\fI\%https://community.openvpn.net/openvpn/wiki/FAQ\fP
+.SH HOWTO
+.sp
+For a more comprehensive guide to setting up OpenVPN in a production
+setting, see the OpenVPN HOWTO at
+\fI\%https://openvpn.net/community\-resources/how\-to/\fP
+.SH PROTOCOL
+.sp
+For a description of OpenVPN\(aqs underlying protocol, see
+\fI\%https://openvpn.net/community\-resources/openvpn\-protocol/\fP
+.SH WEB
+.sp
+OpenVPN\(aqs web site is at \fI\%https://openvpn.net/\fP
+.sp
+Go here to download the latest version of OpenVPN, subscribe to the
+mailing lists, read the mailing list archives, or browse the SVN
+repository.
+.SH BUGS
+.sp
+Report all bugs to the OpenVPN team \fI\%info@openvpn.net\fP
+.SH SEE ALSO
+.sp
+\fBdhcpcd\fP(8),
+\fBifconfig\fP(8),
+\fBopenssl\fP(1),
+\fBroute\fP(8),
+\fBscp\fP(1)
+\fBssh\fP(1)
+.SH NOTES
+.sp
+This product includes software developed by the OpenSSL Project
+(\fI\%https://www.openssl.org/\fP)
+.sp
+For more information on the TLS protocol, see
+\fI\%http://www.ietf.org/rfc/rfc2246.txt\fP
+.sp
+For more information on the LZO real\-time compression library see
+\fI\%https://www.oberhumer.com/opensource/lzo/\fP
+.SH COPYRIGHT
+.sp
+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.
+.SH AUTHORS
+.sp
+James Yonan \fI\%james@openvpn.net\fP
+.\" Generated by docutils manpage writer.
+.