.\"  OpenVPN -- An application to securely tunnel IP networks
 .\"             over a single TCP/UDP port, with support for SSL/TLS-based
 .\"             session authentication and key exchange,
 .\"             packet encryption, packet authentication, and
 .\"             packet compression.
 .\"

 .\"  Copyright (C) 2002-2018 OpenVPN Inc <sales@openvpn.net>

 .\"
 .\"  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.
 .\"
 .\"  This program is distributed in the hope that it will be useful,
 .\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
 .\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 .\"  GNU General Public License for more details.
 .\"

 .\"  You should have received a copy of the GNU General Public License along
 .\"  with this program; if not, write to the Free Software Foundation, Inc.,
 .\"  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

 .\"
 .\" Manual page for openvpn

 .\"

 .\" SH section heading
 .\" SS subsection heading
 .\" LP paragraph
 .\" IP indented paragraph
 .\" TP hanging label

 .\"

 .\" .nf -- no formatting
 .\" .fi -- resume formatting
 .\" .ft 3 -- boldface
 .\" .ft -- normal face
 .\" .in +|-{n} -- indent
 .\"

 .\" Support macros - this is not present on all platforms
 .\" Continuation line for .TP header.
 .de TQ
 .  br
 .  ns
 .  TP \\$1\" no doublequotes around argument!
 ..
 .\" End of TQ macro
 .TH openvpn 8 "28 February 2018"

 .\"*********************************************************
 .SH NAME
 openvpn \- secure IP tunnel daemon.
 .\"*********************************************************
 .SH SYNOPSIS

 .ft 3
 openvpn [ options ... ]
 .ft

 .\"*********************************************************
 .SH INTRODUCTION
 .LP
 OpenVPN is an open source VPN daemon by James Yonan.
 Because OpenVPN tries to
 be a universal VPN tool offering a great deal of flexibility,
 there are a lot of options on this manual page.
 If you're new to 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.
 
 Also note that there's more documentation and examples on
 the OpenVPN web site:
 .I http://openvpn.net/
 
 And if you would like to see a shorter version of this manual,
 see the openvpn usage message which can be obtained by
 running
 .B openvpn
 without any parameters.
 .\"*********************************************************
 .SH DESCRIPTION
 .LP
 OpenVPN is a robust and highly flexible VPN daemon.
 OpenVPN supports SSL/TLS security, ethernet bridging,
 TCP or UDP tunnel transport through proxies or NAT,
 support for dynamic IP addresses and DHCP,
 scalability to hundreds or thousands of users,
 and portability to most major OS platforms.
 
 OpenVPN is tightly bound to the OpenSSL library, and derives much
 of its crypto capabilities from it.
 
 OpenVPN supports
 conventional encryption

 using a pre\-shared secret key

 .B (Static Key mode)
 or
 public key security
 .B (SSL/TLS mode)
 using client & server certificates.
 OpenVPN also

 supports non\-encrypted TCP/UDP tunnels.

 
 OpenVPN is designed to work with the
 .B TUN/TAP
 virtual networking interface that exists on most platforms.
 
 Overall, OpenVPN aims to offer many of the key features of IPSec but
 with a relatively lightweight footprint.
 .\"*********************************************************
 .SH OPTIONS
 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.
 .\"*********************************************************
 .TP

 .B \-\-help

 Show options.
 .\"*********************************************************
 .TP

 .B \-\-config file

 Load additional config options from
 .B file
 where each line corresponds to one command line option,

 but with the leading '\-\-' removed.

 
 If

 .B \-\-config file

 is the only option to the openvpn command,
 the

 .B \-\-config

 can be removed, and the command can be given as
 .B openvpn file
 
 Note that
 configuration files can be nested to a reasonable depth.
 

 Double quotation or single quotation characters ("", '')
 can be used to enclose single parameters containing whitespace,

 and "#" or ";" characters in the first column
 can be used to denote comments.
 

 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:

 
 .nf

 .ft 3
 .in +4

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

 .in -4

 .ft
 .fi
 
 For example on Windows, use double backslashes to
 represent pathnames:
 
 .nf

 .ft 3
 .in +4

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

 .in -4

 .ft
 .fi
 
 For examples of configuration files,
 see
 .I http://openvpn.net/examples.html
 
 Here is an example configuration file:

 .nf

 .ft 3
 .in +4

 #
 # Sample OpenVPN configuration file for

 # using a pre\-shared static key.

 #
 # '#' or ';' may be used to delimit comments.
 
 # Use a dynamic tun device.
 dev tun
 
 # Our remote peer
 remote mypeer.mydomain
 
 # 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

 .in -4

 .ft
 .fi
 .\"*********************************************************
 .SS Tunnel Options:
 .TP

 .B \-\-mode m

 Set OpenVPN major mode.  By default, OpenVPN runs in

 point\-to\-point mode ("p2p").  OpenVPN 2.0 introduces
 a new mode ("server") which implements a multi\-client

 server capability.
 .\"*********************************************************
 .TP

 .B \-\-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

 .B \-\-remote host [port] [proto]

 Remote host name or IP address.  On the client, multiple

 .B \-\-remote

 options may be specified for redundancy, each referring

 to a different OpenVPN server.  Specifying multiple

 .B \-\-remote

 options for this purpose is a special case of the more

 general connection\-profile feature.  See the

 .B <connection>
 documentation below.

 
 The OpenVPN client will try to connect to a server at
 .B host:port
 in the order specified by the list of

 .B \-\-remote

 options.
 

 .B proto
 indicates the protocol to use when connecting with the
 remote, and may be "tcp" or "udp".
 

 For forcing IPv4 or IPv6 connection suffix tcp or udp
 with 4/6 like udp4/udp6/tcp4/tcp6.
 

 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.
 

 Note that since UDP is connectionless, connection failure

 is defined by the

 .B \-\-ping

 and

 .B \-\-ping\-restart

 options.
 

 Note the following corner case:  If you use multiple

 .B \-\-remote

 options, AND you are dropping root privileges on
 the client with

 .B \-\-user

 and/or

 .B \-\-group,

 AND the client is running a non\-Windows OS, if the client needs

 to switch to a different server, and that server pushes
 back different TUN/TAP or route 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.
 

 If

 .B \-\-remote

 is unspecified, OpenVPN will listen
 for packets from any IP address, but will not act on those packets unless
 they pass all authentication tests.  This requirement for 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).
 
 When used in TCP mode, 

 .B \-\-remote

 will act as a filter, rejecting connections from any host which does
 not match
 .B host.
 
 If
 .B host
 is a DNS name which resolves to multiple IP addresses,

 OpenVPN will try them in the order that the system getaddrinfo()
 presents them, so priorization and DNS randomization is done
 by the system library.  Unless an IP version is forced by the
 protocol specification (4/6 suffix), OpenVPN will try both IPv4
 and IPv6 addresses, in the order getaddrinfo() returns them.

 .\"*********************************************************
 .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

 .B <connection>
 Define a client connection
 profile.  Client connection profiles are groups of OpenVPN options that
 describe how to connect to a given OpenVPN server.  Client connection
 profiles are specified within an OpenVPN configuration file, and
 each profile is bracketed by
 .B <connection>
 and
 .B </connection>.
 
 An OpenVPN client will try each connection profile sequentially
 until it achieves a successful connection.  
 

 .B \-\-remote\-random

 can be used to initially "scramble" the connection
 list.
 
 Here is an example of connection profile usage:
 
 .nf

 .ft 3
 .in +4

 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

 .in -4

 .ft
 .fi
 
 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.
 
 The following OpenVPN options may be used inside of
 a
 .B <connection>
 block:
 
 .B bind,

 .B connect\-retry,
 .B connect\-retry\-max,
 .B connect\-timeout,
 .B explicit\-exit\-notify,

 .B float,

 .B fragment,

 .B http\-proxy,
 .B http\-proxy\-option,

 .B key\-direction,

 .B link\-mtu,

 .B local,
 .B lport,

 .B mssfix,

 .B mtu\-disc,

 .B nobind,
 .B port,
 .B proto,
 .B remote,
 .B rport,

 .B socks\-proxy,

 .B tls\-auth,
 .B tls\-crypt,

 .B tun\-mtu and
 .B tun\-mtu\-extra.

 
 A defaulting mechanism exists for specifying options to apply to
 all
 .B <connection>
 profiles.  If any of the above options (with the exception of
 .B remote
 ) appear outside of a
 .B <connection>
 block, but in a configuration file which has one or more
 .B <connection>
 blocks, the option setting will be used as a default for
 .B <connection>
 blocks which follow it in the configuration file.
 
 For example, suppose the
 .B nobind
 option were placed in the sample configuration file above, near
 the top of the file, before the first
 .B <connection>
 block.  The effect would be as if
 .B nobind
 were declared in all
 .B <connection>
 blocks below it.

 .\"*********************************************************
 .TP

 .B \-\-proto\-force p

 When iterating through connection profiles,
 only consider profiles using protocol
 .B p
 ('tcp'|'udp'). 

 .\"*********************************************************
 .TP

 .B \-\-remote\-random

 When multiple

 .B \-\-remote

 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 \-\-proto p

 Use protocol
 .B p
 for communicating with remote host.
 .B p
 can be
 .B udp,

 .B tcp\-client,

 or

 .B tcp\-server.

 
 The default protocol is
 .B udp
 when

 .B \-\-proto

 is not specified.
 
 For UDP operation,

 .B \-\-proto udp

 should be specified on both peers.
 
 For TCP operation, one peer must use

 .B \-\-proto tcp\-server

 and the other must use

 .B \-\-proto tcp\-client.

 A peer started with

 .B tcp\-server

 will wait indefinitely for an incoming connection.  A peer
 started with

 .B tcp\-client

 will attempt to connect, and if that fails, will sleep for 5
 seconds (adjustable via the

 .B \-\-connect\-retry

 option) and try again infinite or up to N retries (adjustable via the

 .B \-\-connect\-retry\-max

 option).  Both TCP client and server will simulate

 a SIGUSR1 restart signal if either side resets the connection.
 
 OpenVPN is designed to operate optimally over UDP, but TCP 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.
 
 This article outlines some of problems with tunneling IP over TCP:
 

 .I http://sites.inka.de/sites/bigred/devel/tcp\-tcp.html

 
 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't
 possess a built\-in reliability layer.

 .\"*********************************************************
 .TP

 .B \-\-connect\-retry n [max]

 Wait

 .B n

 seconds  between connection attempts (default=5). Repeated reconnection
 attempts are slowed down after 5 retries per remote by doubling the wait
 time after each unsuccessful attempt. The optional argument
 .B max
 specifies the maximum value of wait time in seconds at which it gets
 capped (default=300).

 .\"*********************************************************
 .TP

 .B \-\-connect\-retry\-max n

 .B n

 specifies the number of times each

 .B \-\-remote

 or

 .B <connection>

 entry is tried. Specifying

 .B n

 as one would try each entry exactly once. A successful connection
 resets the counter. (default=unlimited).

 .\"*********************************************************

 .TP

 .B \-\-show\-proxy\-settings

 Show sensed HTTP or SOCKS proxy settings. Currently, only Windows clients
 support this option.
 .\"*********************************************************
 .TP

 .B \-\-http\-proxy server port [authfile|'auto'|'auto\-nct'] [auth\-method]

 Connect to remote host through an HTTP proxy at address
 .B server
 and port
 .B port.

 If HTTP Proxy\-Authenticate is required,

 .B authfile
 is a file containing a username and password on 2 lines, or

 "stdin" to prompt from console. Its content can also be specified
 in the config file with the
 .B \-\-http\-proxy\-user\-pass
 option. (See section on inline files)

 .B auth\-method

 should be one of "none", "basic", or "ntlm".
 

 HTTP Digest authentication is supported as well, but only via
 the
 .B auto
 or

 .B auto\-nct

 flags (below).
 

 The
 .B auto
 flag causes OpenVPN to automatically determine the

 .B auth\-method

 and query stdin or the management interface for
 username/password credentials, if required.  This flag
 exists on OpenVPN 2.1 or higher.

 
 The

 .B auto\-nct

 flag (no clear\-text auth) instructs OpenVPN to automatically

 determine the authentication method, but to reject weak
 authentication protocols such as HTTP Basic Authentication.

 .\"*********************************************************
 .TP

 .B \-\-http\-proxy\-option type [parm]

 Set extended HTTP proxy options.
 Repeat to set multiple options.
 

 .B VERSION version \-\-

 Set HTTP version number to
 .B version
 (default=1.0).
 

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

 .B CUSTOM\-HEADER name content \-\-

 Adds the custom Header with
 .B name
 as name and
 .B content
 as the content of the custom HTTP header.

 .\"*********************************************************
 .TP

 .B \-\-socks\-proxy server [port] [authfile]

 Connect to remote host through a Socks5 proxy at address
 .B server
 and port
 .B port
 (default=1080).

 .B authfile
 (optional) is a file containing a username and password on 2 lines, or
 "stdin" to prompt from console.

 .\"*********************************************************
 .TP

 .B \-\-resolv\-retry n

 If hostname resolve fails for

 .B \-\-remote,

 retry resolve for
 .B n
 seconds before failing.
 
 Set
 .B n
 to "infinite" to retry indefinitely.
 
 By default,

 .B \-\-resolv\-retry infinite

 is enabled.  You can disable by setting n=0.
 .\"*********************************************************
 .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

 .B \-\-remote

 is not used).

 .B \-\-float

 when specified with

 .B \-\-remote

 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.

 
 Essentially,

 .B \-\-float

 tells OpenVPN to accept authenticated packets
 from any address, not only the address which was specified in the

 .B \-\-remote

 option.
 .\"*********************************************************
 .TP

 .B \-\-ipchange cmd

 Run command

 .B cmd

 when our remote ip\-address is initially authenticated or

 changes.
 

 .B cmd
 consists of a path to script (or executable program), optionally

 followed by arguments. The path and arguments may be single\- or double\-quoted

 and/or escaped using a backslash, and should be separated by one or more spaces.
 
 When
 .B cmd
 is executed two arguments are appended after any arguments specified in
 .B cmd
 , as follows:

 
 .B cmd ip_address port_number
 
 Don't use

 .B \-\-ipchange

 in

 .B \-\-mode server

 mode.  Use a

 .B \-\-client\-connect

 script instead.
 
 See the "Environmental Variables" section below for
 additional parameters passed as environmental variables.
 
 If you are running in a dynamic IP address environment where
 the IP addresses of either peer could change without notice,
 you can use this script, for example, to edit the
 .I /etc/hosts
 file with the current address of the peer.  The script will
 be run every time the remote peer changes its IP address.
 
 Similarly if
 .I our
 IP address changes due to DHCP, we should configure
 our IP address change script (see man page for
 .BR dhcpcd (8)
 ) to deliver a
 .B SIGHUP
 or
 .B SIGUSR1
 signal to OpenVPN.  OpenVPN will then
 reestablish a connection with its most recently authenticated
 peer on its new IP address.
 .\"*********************************************************
 .TP

 .B \-\-port port

 TCP/UDP port number or port name for both local and remote (sets both
 .B \-\-lport
 and
 .B \-\-rport
 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

 .B \-\-lport port

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

 .\"*********************************************************
 .TP

 .B \-\-rport port

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

 .\"*********************************************************
 .TP

 .B \-\-bind [ipv6only]

 Bind to local address and port. This is the default unless any of 

 .B \-\-proto tcp\-client

 ,

 .B \-\-http\-proxy

 or

 .B \-\-socks\-proxy

 are used.

 
 If the
 .B ipv6only
 keyword is present OpenVPN will bind only to IPv6 (as oposed
 to IPv6 and IPv4) when a IPv6 socket is opened.
 

 .\"*********************************************************
 .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

 .B \-\-remote

 option.
 .\"*********************************************************
 .TP

 .B \-\-dev tunX | tapX | null

 TUN/TAP virtual network device (
 .B X
 can be omitted for a dynamic device.)
 
 See examples section below
 for an example on setting up a TUN device.
 
 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.

 
 .B tun

 devices encapsulate IPv4 or IPv6 (OSI Layer 3) while

 .B tap

 devices encapsulate Ethernet 802.3 (OSI Layer 2).

 .\"*********************************************************
 .TP

 .B \-\-dev\-type device\-type

 Which device type are we using?

 .B device\-type

 should be
 .B tun

 (OSI Layer 3)

 or

 .B tap
 (OSI Layer 2).

 Use this option only if the TUN/TAP device used with

 .B \-\-dev

 does not begin with
 .B tun
 or
 .B tap.
 .\"*********************************************************
 .TP

 .B \-\-topology mode

 Configure virtual addressing topology when running in

 .B \-\-dev tun

 mode.  This directive has no meaning in

 .B \-\-dev tap

 mode, which always uses a
 .B subnet
 topology.
 
 If you set this directive on the server, the

 .B \-\-server

 and

 .B \-\-server\-bridge

 directives will automatically push your chosen topology setting to clients
 as well.  This directive can also be manually pushed to clients.  Like the

 .B \-\-dev

 directive, this directive must always be compatible between client and server.
 
 .B mode
 can be one of:
 

 .B net30 \-\-

 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.
 

 .B p2p \-\-

 Use a point\-to\-point topology where the remote endpoint of the client's

 tun interface always points to the local endpoint of the server's tun interface.
 This mode allocates a single IP address per connecting client.
 Only use
 when none of the connecting clients are Windows systems.  This mode
 is functionally equivalent to the

 .B \-\-ifconfig\-pool\-linear

 directive which is available in OpenVPN 2.0, is deprecated and will be
 removed in OpenVPN 2.5

 .B subnet \-\-

 Use a subnet rather than a point\-to\-point topology by

 configuring the tun interface with a local IP address and subnet mask,
 similar to the topology used in

 .B \-\-dev tap

 and ethernet bridging mode.
 This mode allocates a single IP address per connecting client and works on
 Windows as well.  Only available when server and clients are OpenVPN 2.1 or
 higher, or OpenVPN 2.0.x which has been manually patched with the

 .B \-\-topology

 directive code.  When used on Windows, requires version 8.2 or higher

 of the TAP\-Win32 driver.  When used on *nix, requires that the tun

 driver supports an
 .BR ifconfig (8)
 command which sets a subnet instead of a remote endpoint IP address.

 
 This option exists in OpenVPN 2.1 or higher.

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

 .\"*********************************************************
 .TP

 .B \-\-dev\-node node

 Explicitly set the device node rather than using
 /dev/net/tun, /dev/tun, /dev/tap, etc.  If OpenVPN
 cannot figure out whether
 .B node
 is a TUN or TAP device based on the name, you should
 also specify

 .B \-\-dev\-type tun

 or

 .B \-\-dev\-type tap.

 Under Mac OS X this option can be used to specify the default tun
 implementation. Using
 .B \-\-dev\-node utun
 forces usage of the native Darwin tun kernel support. Use
 .B \-\-dev\-node utunN
 to select a specific utun instance. To force using the tun.kext (/dev/tunX) use

 .B \-\-dev\-node tun\fR.
 When not specifying a

 .B \-\-dev\-node
 option openvpn will first try to open utun, and fall back to tun.kext.
 

 On Windows systems, select the TAP\-Win32 adapter which

 is named
 .B node
 in the Network Connections Control Panel or the
 raw GUID of the adapter enclosed by braces.
 The

 .B \-\-show\-adapters

 option under Windows can also be used

 to enumerate all available TAP\-Win32

 adapters and will show both the network
 connections control panel name and the GUID for

 each TAP\-Win32 adapter.

 .TP

 .B \-\-lladdr address

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

 .\"*********************************************************
 .TP

 .B \-\-iproute cmd

 Set alternate command to execute instead of default iproute2 command.
 May be used in order to execute OpenVPN in unprivileged environment.
 .\"*********************************************************
 .TP

 .B \-\-ifconfig l rn

 Set TUN/TAP adapter parameters. 
 .B l
 is the IP address of the local VPN endpoint.

 For TUN devices in point\-to\-point mode,

 .B rn
 is the IP address of the remote VPN endpoint.

 For TAP devices, or TUN devices used with
 .B \-\-topology subnet,

 .B rn

 is the subnet mask of the virtual network segment

 which is being created or connected to.
 
 For TUN devices, which facilitate virtual

 point\-to\-point IP connections (when used in

 .B \-\-topology net30
 or
 .B p2p
 mode),

 the proper usage of

 .B \-\-ifconfig

 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
 .B rn,
 you will be pinging across the VPN.
 
 For TAP devices, which provide
 the ability to create virtual

 ethernet segments, or TUN devices in

 .B \-\-topology subnet

 mode (which create virtual "multipoint networks"),

 .B \-\-ifconfig

 is used to set an IP address and
 subnet mask just as a physical
 ethernet adapter would be
 similarly configured.  If you are
 attempting to connect to a remote
 ethernet bridge, the IP address
 and subnet should be set to values
 which would be valid on the
 the bridged ethernet segment (note
 also that DHCP can be used for the
 same purpose).
 
 This option, while primarily a proxy for the
 .BR ifconfig (8)
 command, is designed to simplify TUN/TAP
 tunnel configuration by providing a
 standard interface to the different
 ifconfig implementations on different
 platforms.
 

 .B \-\-ifconfig

 parameters which are IP addresses can
 also be specified as a DNS or /etc/hosts
 file resolvable name.
 
 For TAP devices,

 .B \-\-ifconfig

 should not be used if the TAP interface will be
 getting an IP address lease from a DHCP
 server.
 .\"*********************************************************
 .TP

 .B \-\-ifconfig\-noexec

 Don't actually execute ifconfig/netsh commands, instead
 pass

 .B \-\-ifconfig

 parameters to scripts using environmental variables.
 .\"*********************************************************
 .TP

 .B \-\-ifconfig\-nowarn

 Don't output an options consistency check warning
 if the

 .B \-\-ifconfig

 option on this side of the
 connection doesn't match the remote side.  This is useful
 when you want to retain the overall benefits of the
 options consistency check (also see

 .B \-\-disable\-occ

 option) while only disabling the ifconfig component of
 the check.
 
 For example,
 if you have a configuration where the local host uses

 .B \-\-ifconfig

 but the remote host does not, use

 .B \-\-ifconfig\-nowarn

 on the local host.
 
 This option will also silence warnings about potential
 address conflicts which occasionally annoy more experienced
 users by triggering "false positive" warnings.
 .\"*********************************************************
 .TP

 .B \-\-route network/IP [netmask] [gateway] [metric]

 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.
 
 This option is intended as
 a convenience proxy for the
 .BR route (8)
 shell command,
 while at the same time providing portable semantics
 across OpenVPN's platform space.
 
 .B netmask

 default \-\- 255.255.255.255

 
 .B gateway

 default \-\- taken from

 .B \-\-route\-gateway

 or the second parameter to

 .B \-\-ifconfig

 when

 .B \-\-dev tun

 is specified.
 

 .B metric

 default \-\- taken from

 .B \-\-route\-metric

 otherwise 0.
 

 The default can be specified by leaving an option blank or setting
 it to "default".
 
 The
 .B network
 and
 .B gateway
 parameters can
 also be specified as a DNS or /etc/hosts
 file resolvable name, or as one of three special keywords:
 
 .B vpn_gateway

 \-\- The remote VPN endpoint address

 (derived either from

 .B \-\-route\-gateway

 or the second parameter to

 .B \-\-ifconfig

 when

 .B \-\-dev tun

 is specified).
 
 .B net_gateway

 \-\- The pre\-existing IP default gateway, read from the routing

 table (not supported on all OSes).
 
 .B remote_host

 \-\- The

 .B \-\-remote

 address if OpenVPN is being run in client mode, and is undefined in server mode.
 .\"*********************************************************

 .TP

 .B \-\-route\-gateway gw|'dhcp'

 Specify a default gateway
 .B gw
 for use with

 .B \-\-route.

 
 If
 .B dhcp
 is specified as the parameter,
 the gateway address will be extracted from a DHCP

 negotiation with the OpenVPN server\-side LAN.

 .\"*********************************************************

 .TP

 .B \-\-route\-metric m

 Specify a default metric
 .B m
 for use with

 .B \-\-route.

 .\"*********************************************************
 .TP

 .B \-\-route\-delay [n] [w]

 Delay
 .B n
 seconds (default=0) after connection
 establishment, before adding routes. If
 .B n
 is 0, routes will be added immediately upon connection
 establishment.  If

 .B \-\-route\-delay

 is omitted, routes will be added immediately after TUN/TAP device
 open and

 .B \-\-up

 script execution, before any

 .B \-\-user

 or 

 .B \-\-group

 privilege downgrade (or

 .B \-\-chroot

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

 .B \-\-route\-delay

 tries to be more intelligent by waiting
 .B w
 seconds (w=30 by default)

 for the TAP\-Win32 adapter to come up before adding routes.

 .\"*********************************************************
 .TP

 .B \-\-route\-up cmd

 Run command

 .B cmd
 after routes are added, subject to

 .B \-\-route\-delay.

 .B cmd
 consists of a path to script (or executable program), optionally

 followed by arguments. The path and arguments may be single\- or double\-quoted

 and/or escaped using a backslash, and should be separated by one or more spaces.
 

 See the "Environmental Variables" section below for
 additional parameters passed as environmental variables.

 .\"*********************************************************
 .TP

 .B \-\-route\-pre\-down cmd

 Run command
 .B cmd
 before routes are removed upon disconnection.

 
 .B cmd

 consists of a path to script (or executable program), optionally

 followed by arguments. The path and arguments may be single\- or double\-quoted

 and/or escaped using a backslash, and should be separated by one or more spaces.
 
 See the "Environmental Variables" section below for
 additional parameters passed as environmental variables.

 .\"*********************************************************
 .TP

 .B \-\-route\-noexec

 Don't add or remove routes automatically.  Instead pass routes to

 .B \-\-route\-up

 script using environmental variables.
 .\"*********************************************************
 .TP

 .B \-\-route\-nopull

 When used with

 .B \-\-client

 or

 .B \-\-pull,

 accept options pushed by server EXCEPT for routes, block\-outside\-dns and dhcp

 options like DNS servers.

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

 .B \-\-allow\-pull\-fqdn

 Allow client to pull DNS names from server (rather than being limited
 to IP address) for

 .B \-\-ifconfig,
 .B \-\-route,

 and

 .B \-\-route\-gateway.

 .\"*********************************************************
 .TP

 .B \-\-client\-nat snat|dnat network netmask alias

 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.
 
 .B network/netmask
 (for example 192.168.0.0/255.255.0.0)
 defines the local view of a resource from the client perspective, while
 .B alias/netmask
 (for example 10.64.0.0/255.255.0.0)
 defines the remote view from the server perspective.
 
 Use
 .B snat
 (source NAT) for resources owned by the client and
 .B dnat
 (destination NAT) for remote resources.
 
 Set

 .B \-\-verb 6

 for debugging info showing the transformation of src/dest
 addresses in packets.
 .\"*********************************************************
 .TP

 .B \-\-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.

 
 This option performs three steps:
 
 .B (1)
 Create a static route for the

 .B \-\-remote

 address which forwards to the pre\-existing default gateway.

 This is done so that
 .B (3)
 will not create a routing loop.
 
 .B (2)
 Delete the default gateway route.
 
 .B (3)
 Set the new default gateway to be the VPN endpoint address (derived either from

 .B \-\-route\-gateway

 or the second parameter to

 .B \-\-ifconfig

 when

 .B \-\-dev tun

 is specified).
 
 When the tunnel is torn down, all of the above steps are reversed so
 that the original default route is restored.
 

 Option flags:
 

 .B local \-\-

 Add the
 .B local

 flag if both OpenVPN peers are directly connected via a common subnet,

 such as with wireless.  The
 .B local
 flag will cause step
 .B 1
 above to be omitted.
 

 .B autolocal \-\-

 Try to automatically determine whether to enable
 .B local
 flag above.
 

 .B def1 \-\-

 Use this flag to override

 the default gateway by using 0.0.0.0/1 and 128.0.0.0/1
 rather than 0.0.0.0/0.  This has the benefit of overriding
 but not wiping out the original default gateway. 
 

 .B bypass\-dhcp \-\-
 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).

 .B bypass\-dns \-\-
 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).

 .B block\-local \-\-

 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.

 .B ipv6 \-\-

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

 .B !ipv4 \-\-
 Do not redirect IPv4 traffic \- typically used in the flag pair

 .B "ipv6 !ipv4"

 to redirect IPv6\-only.

 .\"*********************************************************
 .TP

 .B \-\-link\-mtu n

 Sets an upper bound on the size of UDP packets which are sent
 between OpenVPN peers.  It's best not to set this parameter unless
 you know what you're doing.
 .\"*********************************************************

 .\"*********************************************************

 .TP

 .B \-\-redirect\-private [flags]
 Like \-\-redirect\-gateway, but omit actually changing the default

 gateway.  Useful when pushing private subnets.
 .\"*********************************************************

 .TP

 .B \-\-tun\-mtu n

 Take the TUN device MTU to be
 .B n
 and derive the link MTU
 from it (default=1500).  In most cases, you will probably want to
 leave this parameter set to its default value.
 
 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 or data channels be sent unfragmented.
 
 MTU problems often manifest themselves as connections which
 hang during periods of active usage.
 
 It's best to use the

 .B \-\-fragment

 and/or

 .B \-\-mssfix

 options to deal with MTU sizing issues.
 .\"*********************************************************
 .TP

 .B \-\-tun\-mtu\-extra n

 Assume that the TUN/TAP device might return as many as
 .B n
 bytes more than the

 .B \-\-tun\-mtu

 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.
 .\"*********************************************************
 .TP

 .B \-\-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.
 
 .B 'no'

 \-\- Never send DF (Don't Fragment) frames

 .br
 .B 'maybe'

 \-\- Use per\-route hints

 .br
 .B 'yes'

 \-\- Always DF (Don't Fragment)

 .br
 .\"*********************************************************
 .TP

 .B \-\-mtu\-test

 To empirically measure MTU on connection startup,
 add the

 .B \-\-mtu\-test

 option to your configuration.
 OpenVPN will send ping packets of various sizes
 to the remote peer and measure the largest packets
 which were successfully received.  The

 .B \-\-mtu\-test

 process normally takes about 3 minutes to complete.
 .\"*********************************************************
 .TP

 .B \-\-fragment max

 Enable internal datagram fragmentation so
 that no UDP datagrams are sent which
 are larger than
 .B max
 bytes.
 
 The
 .B max
 parameter is interpreted in the same way as the

 .B \-\-link\-mtu

 parameter, i.e. the UDP packet size after encapsulation
 overhead has been added in, but not including
 the UDP header itself.
 
 The

 .B \-\-fragment

 option only makes sense when you are using the UDP protocol (

 .B \-\-proto udp

 ).
 

 .B \-\-fragment

 adds 4 bytes of overhead per datagram.
 
 See the

 .B \-\-mssfix

 option below for an important related option to

 .B \-\-fragment.

 
 It should also be noted that this option is not meant to replace
 UDP fragmentation at the IP stack level.  It is only meant as a
 last resort when path MTU discovery is broken.  Using this option
 is less efficient than fixing path MTU discovery for your IP link and
 using native IP fragmentation instead.
 
 Having said that, there are circumstances where using OpenVPN's
 internal fragmentation capability may be your only option, such
 as tunneling a UDP multicast stream which requires fragmentation.
 .\"*********************************************************
 .TP

 .B \-\-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
 .B max

 bytes. The default value is
 .B 1450.

 
 The
 .B max
 parameter is interpreted in the same way as the

 .B \-\-link\-mtu

 parameter, i.e. the UDP packet size after encapsulation
 overhead has been added in, but not including

 the UDP header itself. Resulting packet would be at most 28
 bytes larger for IPv4 and 48 bytes for IPv6 (20/40 bytes for IP
 header and 8 bytes for UDP header). Default value of 1450 allows
 IPv4 packets to be transmitted over a link with MTU 1473 or higher
 without IP level fragmentation.

 
 The

 .B \-\-mssfix

 option only makes sense when you are using the UDP protocol

 for OpenVPN peer\-to\-peer communication, i.e.

 .B \-\-proto udp.

 .B \-\-mssfix

 and

 .B \-\-fragment

 can be ideally used together, where

 .B \-\-mssfix

 will try to keep TCP from needing
 packet fragmentation in the first place,
 and if big packets come through anyhow
 (from protocols other than TCP),

 .B \-\-fragment

 will internally fragment them.
 
 Both

 .B \-\-fragment

 and

 .B \-\-mssfix

 are designed to work around cases where Path MTU discovery
 is broken on the network path between OpenVPN peers.
 
 The usual symptom of such a breakdown is an OpenVPN
 connection which successfully starts, but then stalls
 during active usage.
 
 If

 .B \-\-fragment

 and

 .B \-\-mssfix

 are used together,

 .B \-\-mssfix

 will take its default
 .B max
 parameter from the

 .B \-\-fragment max

 option.
 
 Therefore, one could lower the maximum UDP packet size

 to 1300 (a good first try for solving MTU\-related

 connection problems) with the following options:
 

 .B \-\-tun\-mtu 1500 \-\-fragment 1300 \-\-mssfix

 .\"*********************************************************
 .TP

 .B \-\-sndbuf size

 Set the TCP/UDP socket send buffer size.

 Defaults to operation system default.

 .\"*********************************************************
 .TP

 .B \-\-rcvbuf size

 Set the TCP/UDP socket receive buffer size.

 Defaults to operation system default.

 .\"*********************************************************
 .TP

 .B \-\-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

 .B \-\-socket\-flags flags...

 Apply the given flags to the OpenVPN transport socket.
 Currently, only
 .B TCP_NODELAY
 is supported.
 
 The
 .B TCP_NODELAY
 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.
 
 This option is pushable from server to client, and should be used
 on both client and server for maximum effect.
 .\"*********************************************************
 .TP

 .B \-\-txqueuelen n

 (Linux only) Set the TX queue length on the TUN/TAP interface.
 Currently defaults to 100.
 .\"*********************************************************
 .TP

 .B \-\-shaper n

 Limit bandwidth of outgoing tunnel data to
 .B n
 bytes per second on the TCP/UDP port.

 Note that this will only work if mode is set to p2p.

 If you want to limit the bandwidth
 in both directions, use this option on both peers.
 
 OpenVPN uses the following algorithm to implement
 traffic shaping: Given a shaper rate of
 .I n
 bytes per second, after a datagram write of
 .I b
 bytes is queued on the TCP/UDP port, wait a minimum of
 .I (b / n)
 seconds before queuing the next write.
 
 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.

 
 Also note that for low bandwidth tunnels
 (under 1000 bytes per second), you should probably
 use lower MTU values as well (see above), otherwise
 the packet latency will grow so large as to trigger
 timeouts in the TLS layer and TCP connections running
 over the tunnel.
 
 OpenVPN allows
 .B n
 to be between 100 bytes/sec and 100 Mbytes/sec.
 .\"*********************************************************
 .TP

 .B \-\-inactive n [bytes]

 Causes OpenVPN to exit after

 .B n

 seconds of inactivity on the TUN/TAP device. The time length of
 inactivity is measured since the last incoming or outgoing tunnel

 packet.  The default value is 0 seconds, which disables this feature.

 
 If the optional
 .B bytes
 parameter is included,

 exit if less than
 .B bytes
 of combined in/out traffic are produced on the tun/tap device
 in
 .B n
 seconds.
 
 In any case, OpenVPN's 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

 .B \-\-ping n

 Ping remote over the TCP/UDP control channel
 if no packets have been sent for at least
 .B n
 seconds (specify

 .B \-\-ping

 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's secure modes (where

 .B \-\-secret, \-\-tls\-server,

 or

 .B \-\-tls\-client

 is specified), the ping packet
 will be cryptographically secure.
 
 This option has two intended uses:
 
 (1) Compatibility
 with stateful firewalls.  The periodic ping will ensure that
 a stateful firewall rule which allows OpenVPN UDP packets to
 pass will not time out.
 
 (2) To provide a basis for the remote to test the existence
 of its peer using the

 .B \-\-ping\-exit

 option.
 .\"*********************************************************
 .TP

 .B \-\-ping\-exit n

 Causes OpenVPN to exit after
 .B n
 seconds pass without reception of a ping
 or other packet from remote.
 This option can be combined with

 .B \-\-inactive, \-\-ping,

 and

 .B \-\-ping\-exit

 to create a two\-tiered inactivity disconnect.

 
 For example,
 

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

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

 .B \-\-ping\-restart n

 Similar to

 .B \-\-ping\-exit,

 but trigger a
 .B SIGUSR1
 restart after
 .B n
 seconds pass without reception of a ping
 or other packet from remote.
 
 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
 .I http://dyndns.org/
 + a dynamic DNS client such
 as
 .B ddclient.
 
 If the peer cannot be reached, a restart will be triggered, causing
 the hostname used with

 .B \-\-remote

 to be re\-resolved (if

 .B \-\-resolv\-retry

 is also specified).
 
 In server mode,

 .B \-\-ping\-restart, \-\-inactive,

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

 .B \-\-ping\-restart

 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

 .B \-\-keepalive

 setting in the server configuration.
 To disable the 120 second default, set

 .B \-\-ping\-restart 0

 on the client.
 
 See the signals section below for more information
 on
 .B SIGUSR1.
 
 Note that the behavior of
 .B SIGUSR1
 can be modified by the

 .B \-\-persist\-tun, \-\-persist\-key, \-\-persist\-local\-ip,

 and

 .B \-\-persist\-remote\-ip

 options.
 
 Also note that

 .B \-\-ping\-exit

 and

 .B \-\-ping\-restart

 are mutually exclusive and cannot be used together.
 .\"*********************************************************
 .TP

 .B \-\-keepalive interval timeout

 A helper directive designed to simplify the expression of

 .B \-\-ping

 and

 .B \-\-ping\-restart.
 
 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

 .B \-\-ping
 and

 .B \-\-ping\-restart

 options to the client.  If used on both server and client,
 the values pushed from server will override the client local values.

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

 For example,

 .B \-\-keepalive 10 60

 expands as follows:
 
 .nf

 .ft 3
 .in +4

  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

 .in -4

 .ft
 .fi
 .\"*********************************************************
 .TP

 .B \-\-ping\-timer\-rem

 Run the

 .B \-\-ping\-exit

 /

 .B \-\-ping\-restart

 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

 .B \-\-remote

 peer), and you don't want to start clocking timeouts until a remote
 peer connects.
 .\"*********************************************************
 .TP

 .B \-\-persist\-tun

 Don't close and reopen TUN/TAP device or run up/down scripts
 across
 .B SIGUSR1
 or

 .B \-\-ping\-restart

 restarts.
 
 .B SIGUSR1
 is a restart signal similar to
 .B SIGHUP,

 but which offers finer\-grained control over

 reset options.
 .\"*********************************************************
 .TP

 .B \-\-persist\-key

 Don't re\-read key files across

 .B SIGUSR1
 or

 .B \-\-ping\-restart.

 
 This option can be combined with

 .B \-\-user nobody

 to allow restarts triggered by the
 .B SIGUSR1
 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.
 
 This option solves the problem by persisting keys across
 .B SIGUSR1

 resets, so they don't need to be re\-read.

 .\"*********************************************************
 .TP

 .B \-\-persist\-local\-ip

 Preserve initially resolved local IP address and port number
 across
 .B SIGUSR1
 or

 .B \-\-ping\-restart

 restarts.
 .\"*********************************************************
 .TP

 .B \-\-persist\-remote\-ip

 Preserve most recently authenticated remote IP address and port number
 across
 .B SIGUSR1
 or

 .B \-\-ping\-restart

 restarts.
 .\"*********************************************************
 .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

 .B \-\-user

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

 .B \-\-reneg

 options (see below), then are discarded.
 
 The downside
 of using

 .B \-\-mlock

 is that it will reduce the amount of physical
 memory available to other applications.
 .\"*********************************************************
 .TP

 .B \-\-up cmd

 Run command
 .B cmd
 after successful TUN/TAP device open

 (pre

 .B \-\-user

 UID change).
 
 .B cmd
 consists of a path to script (or executable program), optionally

 followed by arguments. The path and arguments may be single\- or double\-quoted

 and/or escaped using a backslash, and should be separated by one or more spaces.
 
 The up command is useful for specifying route

 commands which route IP traffic destined for
 private subnets which exist at the other
 end of the VPN connection into the tunnel.
 
 For

 .B \-\-dev tun

 execute as:
 
 .B cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [ init | restart ]
 
 For

 .B \-\-dev tap

 execute as:
 
 .B cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [ init | restart ]
 
 See the "Environmental Variables" section below for
 additional parameters passed as environmental variables.
 

 Note that if

 .B cmd

 includes arguments, all OpenVPN\-generated arguments will be appended

 to them to build an argument list with which the executable will be
 called.

 
 Typically,
 .B cmd
 will run a script to add routes to the tunnel.
 
 Normally the up script is called after the TUN/TAP device is opened.
 In this context, the last command line parameter passed to the script
 will be
 .I init.
 If the

 .B \-\-up\-restart

 option is also used, the up script will be called for restarts as
 well.  A restart is considered to be a partial reinitialization
 of OpenVPN where the TUN/TAP instance is preserved (the

 .B \-\-persist\-tun

 option will enable such preservation).  A restart
 can be generated by a SIGUSR1 signal, a

 .B \-\-ping\-restart

 timeout, or a connection reset when the TCP protocol is enabled
 with the

 .B \-\-proto

 option.  If a restart occurs, and

 .B \-\-up\-restart

 has been specified, the up script will be called with
 .I restart
 as the last parameter.
 

 NOTE: 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).
 

 The following standalone example shows how the

 .B \-\-up

 script can be called in both an initialization and restart context.
 (NOTE: for security reasons, don't run the following example unless UDP port
 9999 is blocked by your firewall.  Also, the example will run indefinitely,

 so you should abort with control\-c).

 .B openvpn \-\-dev tun \-\-port 9999 \-\-verb 4 \-\-ping\-restart 10 \-\-up 'echo up' \-\-down 'echo down' \-\-persist\-tun \-\-up\-restart

 
 Note that OpenVPN also provides the

 .B \-\-ifconfig

 option to automatically ifconfig the TUN device,
 eliminating the need to define an

 .B \-\-up

 script, unless you also want to configure routes
 in the

 .B \-\-up

 script.
 
 If

 .B \-\-ifconfig

 is also specified, OpenVPN will pass the ifconfig local
 and remote endpoints on the command line to the

 .B \-\-up

 script so that they can be used to configure routes such as:
 

 .B route add \-net 10.0.0.0 netmask 255.255.255.0 gw $5

 .\"*********************************************************
 .TP

 .B \-\-up\-delay

 Delay TUN/TAP open and possible

 .B \-\-up

 script execution
 until after TCP/UDP connection establishment with peer.
 
 In

 .B \-\-proto udp

 mode, this option normally requires the use of

 .B \-\-ping

 to allow connection initiation to be sensed in the absence
 of tunnel data, since UDP is a "connectionless" protocol.
 

 On Windows, this option will delay the TAP\-Win32 media state

 transitioning to "connected" until connection establishment,
 i.e. the receipt of the first authenticated packet from the peer.
 .\"*********************************************************
 .TP

 .B \-\-down cmd

 Run command
 .B cmd
 after TUN/TAP device close

 (post

 .B \-\-user

 UID change and/or

 .B \-\-chroot

 ).
 .B cmd
 consists of a path to script (or executable program), optionally

 followed by arguments. The path and arguments may be single\- or double\-quoted

 and/or escaped using a backslash, and should be separated by one or more spaces.
 
 Called with the same parameters and environmental

 variables as the

 .B \-\-up

 option above.
 
 Note that if you reduce privileges by using

 .B \-\-user

 and/or

 .B \-\-group,

 your

 .B \-\-down

 script will also run at reduced privilege.
 .\"*********************************************************
 .TP

 .B \-\-down\-pre

 Call

 .B \-\-down

 cmd/script before, rather than after, TUN/TAP close.
 .\"*********************************************************
 .TP

 .B \-\-up\-restart

 Enable the

 .B \-\-up

 and

 .B \-\-down

 scripts to be called for restarts as well as initial program start.
 This option is described more fully above in the

 .B \-\-up

 option documentation.
 .\"*********************************************************
 .TP

 .B \-\-setenv name value

 Set a custom environmental variable
 .B name=value
 to pass to script.
 .\"*********************************************************
 .TP

 .B \-\-setenv FORWARD_COMPATIBLE 1

 Relax config file syntax checking so that unknown directives
 will trigger a warning but not a fatal error,
 on the assumption that a given unknown directive might be valid
 in future OpenVPN versions.
 
 This option should be used with caution, as there are good 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.

 
 It is also possible to tag a single directive so as not to trigger
 a fatal error if the directive isn't recognized.  To do this,
 prepend the following before the directive:
 .B setenv opt

 Versions prior to OpenVPN 2.3.3 will always ignore options set with the
 .B setenv opt
 directive.
 

 See also

 .B \-\-ignore\-unknown\-option

 .\"*********************************************************
 .TP

 .B \-\-setenv\-safe name value

 Set a custom environmental variable
 .B OPENVPN_name=value
 to pass to script.
 
 This directive is designed to be pushed by the server to clients,
 and the prepending of "OPENVPN_" to the environmental variable
 is a safety precaution to prevent a LD_PRELOAD style attack
 from a malicious or compromised server.
 .\"*********************************************************

 .TP

 .B \-\-ignore\-unknown\-option opt1 opt2 opt3 ... optN

 When one of options
 .B opt1 ... optN
 is encountered in the configuration file the configuration
 file parsing does not fail if this OpenVPN version does not
 support the option. Multiple

 .B \-\-ignore\-unknown\-option

 options can be given to support a larger number of options to ignore.
 
 This option should be used with caution, as there are good 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.
 

 .B \-\-ignore\-unknown\-option

 is available since OpenVPN 2.3.3.
 .\"*********************************************************

 .TP

 .B \-\-script\-security level

 This directive offers policy\-level control over OpenVPN's usage of external programs

 and scripts.  Lower
 .B level
 values are more restrictive, higher values are more permissive.  Settings for

 .B level:
 

 .B 0 \-\-

 Strictly no calling of external programs.
 .br

 .B 1 \-\-

 (Default) Only call built\-in executables such as ifconfig, ip, route, or netsh.

 .br

 .B 2 \-\-

 Allow calling of built\-in executables and user\-defined scripts.

 .br

 .B 3 \-\-

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

 OpenVPN releases before v2.3 also supported a

 .B method

 flag which indicated how OpenVPN should call external commands and scripts.  This
 could be either
 .B execve
 or 
 .B system. 

 As of OpenVPN 2.3, this flag is no longer accepted.  In most *nix environments the execve()

 approach has been used without any issues.
 

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

 To run scripts in Windows in earlier OpenVPN
 versions you needed to either add a full path to the script interpreter which can parse the
 script or use the
 .B system

 flag to run these scripts.  As of OpenVPN 2.3 it is now a strict requirement to have

 full path to the script interpreter when running non\-executables files.

 This is not needed for executable files, such as .exe, .com, .bat or .cmd files.  For
 example, if you have a Visual Basic script, you must use this syntax now:

 .nf
 .ft 3
 .in +4

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

 .in -4
 .ft
 .fi

 Please note the single quote marks and the escaping of the backslashes (\\) and
 the space character.
 
 The reason the support for the
 .B system
 flag was removed is due to the security implications with shell expansions
 when executing scripts via the system() call.

 .\"*********************************************************
 .TP

 .B \-\-disable\-occ

 Don't output a warning message if option inconsistencies are detected between
 peers.  An example of an option inconsistency would be where one peer uses

 .B \-\-dev tun

 while the other peer uses

 .B \-\-dev tap.

 
 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

 .B \-\-user user

 Change the user ID of the OpenVPN process to
 .B user
 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's security features make
 this unlikely, it is provided as a second line of defense.
 
 By setting
 .B user
 to
 .I nobody
 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
 .B SIGUSR1
 signal
 (for example in response
 to a DHCP reset), you should make use of one or more of the

 .B \-\-persist

 options to ensure that OpenVPN doesn't need to execute any privileged

 operations in order to restart (such as re\-reading key files

 or running
 .BR ifconfig
 on the TUN device).
 .\"*********************************************************
 .TP

 .B \-\-group group

 Similar to the

 .B \-\-user

 option,
 this option changes the group ID of the OpenVPN process to
 .B group
 after initialization.
 .\"*********************************************************
 .TP

 .B \-\-cd dir

 Change directory to
 .B dir
 prior to reading any files such as
 configuration files, key files, scripts, etc.
 .B dir
 should be an absolute path, with a leading "/",
 and without any references
 to the current directory such as "." or "..".
 
 This option is useful when you are running
 OpenVPN in 

 .B \-\-daemon

 mode, and you want to consolidate all of
 your OpenVPN control files in one location.
 .\"*********************************************************
 .TP

 .B \-\-chroot dir

 Chroot to
 .B dir
 after initialization.  

 .B \-\-chroot

 essentially redefines
 .B dir
 as being the top
 level directory tree (/).  OpenVPN will therefore
 be unable to access any files outside this tree.
 This can be desirable from a security standpoint.
 
 Since the chroot operation is delayed until after
 initialization, most OpenVPN options that reference

 files will operate in a pre\-chroot context.

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

 Note: The SSL library will probably need /dev/urandom to be available inside
 the chroot directory

 .B dir.

 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

 .B \-\-setcon context

 Apply SELinux
 .B context
 after initialization. This
 essentially provides the ability to restrict OpenVPN's
 rights to only network I/O operations, thanks to
 SELinux. This goes further than

 .B \-\-user

 and

 .B \-\-chroot

 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).

 
 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.
 
 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

 .B \-\-persist\-key

 and

 .B \-\-persist\-tun

 options.
 .\"*********************************************************
 .TP

 .B \-\-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 /var/log/messages),

 except for the output of scripts and

 ifconfig commands,
 which will go to /dev/null unless otherwise redirected.
 The syslog redirection occurs immediately at the point
 that

 .B \-\-daemon

 is parsed on the command line even though
 the daemonization point occurs later.  If one of the

 .B \-\-log

 options is present, it will supercede syslog
 redirection.
 
 The optional
 .B progname
 parameter will cause OpenVPN to report its program name
 to the system logger as
 .B progname.
 This can be useful in linking OpenVPN messages
 in the syslog file with specific tunnels.
 When unspecified,
 .B progname
 defaults to "openvpn".
 
 When OpenVPN is run with the

 .B \-\-daemon

 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.
 

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

 
 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

 .B \-\-askpass
 option is used to tell OpenVPN to ask for the pass phrase (this

 requirement is new in v2.3.7, and is a consequence of calling daemon()

 before initializing the crypto layer).
 
 Further, using
 .B \-\-daemon
 together with

 .B \-\-auth\-user\-pass

 (entered on console) and

 .B \-\-auth\-nocache

 will fail as soon as key renegotiation (and reauthentication) occurs.

 .\"*********************************************************
 .TP

 .B \-\-syslog [progname]

 Direct log output to system logger, but do not become a daemon.
 See

 .B \-\-daemon

 directive above for description of
 .B progname
 parameter.

 .TP

 .B \-\-errors\-to\-stderr

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

 .\"*********************************************************
 .TP

 .B \-\-passtos

 Set the TOS field of the tunnel packet to what the payload's TOS is.
 .\"*********************************************************
 .TP

 .B \-\-inetd [wait|nowait] [progname]

 Use this option when OpenVPN is being run from the inetd or
 .BR xinetd(8)
 server.
 
 The
 .B wait/nowait
 option must match what is specified in the inetd/xinetd
 config file.  The
 .B nowait
 mode can only be used with

 .B \-\-proto tcp\-server.

 The default is
 .B wait.
 The
 .B nowait
 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:
 .I http://openvpn.net/faq.html#oneport
 
 This option precludes the use of

 .B \-\-daemon, \-\-local,

 or

 .B \-\-remote.

 Note that this option causes message and error output to be handled in the same
 way as the

 .B \-\-daemon

 option.  The optional
 .B progname
 parameter is also handled exactly as in

 .B \-\-daemon.

 
 Also note that in
 .B wait
 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:
 .I http://openvpn.net/1xhowto.html
 .\"*********************************************************
 .TP

 .B \-\-log file

 Output logging messages to
 .B file,
 including output to stdout/stderr which
 is generated by called scripts.
 If
 .B file
 already exists it will be truncated.
 This option takes effect
 immediately when it is parsed in the command line
 and will supercede syslog output if

 .B \-\-daemon

 or

 .B \-\-inetd

 is also specified.
 This option is persistent over the entire course of
 an OpenVPN instantiation and will not be reset by SIGHUP,
 SIGUSR1, or

 .B \-\-ping\-restart.

 
 Note that on Windows, when OpenVPN is started as a service,
 logging occurs by default without the need to specify
 this option.
 .\"*********************************************************
 .TP

 .B \-\-log\-append file

 Append logging messages to
 .B file.
 If
 .B file
 does not exist, it will be created.
 This option behaves exactly like

 .B \-\-log

 except that it appends to rather
 than truncating the log file.
 .\"*********************************************************
 .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

 .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

 .B \-\-writepid file

 Write OpenVPN's main process ID to
 .B file.
 .\"*********************************************************
 .TP

 .B \-\-nice n

 Change process priority after initialization
 (
 .B n
 greater than 0 is lower priority,
 .B n
 less than zero is higher priority).
 .\"*********************************************************
 .\".TP

 .\".B \-\-nice\-work n

 .\"Change priority of background TLS work thread.  The TLS thread
 .\"feature is enabled when OpenVPN is built
 .\"with pthread support, and you are running OpenVPN
 .\"in TLS mode (i.e. with

 .\".B \-\-tls\-client

 .\"or

 .\".B \-\-tls\-server

 .\"specified).
 .\"

 .\"Using a TLS thread offloads the CPU\-intensive process of SSL/TLS\-based

 .\"key exchange to a background thread so that it does not become
 .\"a latency bottleneck in the tunnel packet forwarding process.
 .\"
 .\"The parameter
 .\".B n
 .\"is interpreted exactly as with the

 .\".B \-\-nice

 .\"option above, but in relation to the work thread rather
 .\"than the main thread.
 .\"*********************************************************
 .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't support write blocking on UDP sockets
 or TUN/TAP devices.  In such cases, one can optimize the event loop
 by avoiding the poll/epoll/select call, improving CPU efficiency
 by 5% to 10%.
 

 This option can only be used on non\-Windows systems, when

 .B \-\-proto udp

 is specified, and when

 .B \-\-shaper

 is NOT specified.
 .\"*********************************************************
 .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
 .B \-\-local
 to force binding to one specific address only.  This option will
 add some extra lookups to the packet path to ensure that the UDP 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's not enabled by default.
 
 Note: this option is only relevant for UDP servers.
 

 Note 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).

 .\"*********************************************************
 .TP

 .B \-\-echo [parms...]

 Echo
 .B parms
 to log output.
 
 Designed to be used to send messages to a controlling application
 which is receiving the OpenVPN log output.
 .\"*********************************************************
 .TP

 .B \-\-remap\-usr1 signal

 Control whether internally or externally
 generated SIGUSR1 signals are remapped to
 SIGHUP (restart without persisting state) or
 SIGTERM (exit).
 
 .B signal
 can be set to "SIGHUP" or "SIGTERM".  By default, no remapping
 occurs.
 .\"*********************************************************
 .TP

 .B \-\-verb n

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

 .B 0 \-\-

 No output except fatal errors.
 .br

 .B 1 to 4 \-\-

 Normal usage range.
 .br

 .B 5 \-\-

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

 .B 6 to 11 \-\-

 Debug info range (see errlevel.h for additional
 information on debug levels).
 .\"*********************************************************
 .TP

 .B \-\-status file [n]

 Write operational status to
 .B file
 every
 .B n
 seconds.
 
 Status can also be written to the syslog by sending a
 .B SIGUSR2
 signal.

 
 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
 .B \-\-status\-version
 option in that case.
 
 For clients or instances running in point\-to\-point mode, it will contain the
 traffic statistics.

 .\"*********************************************************
 .TP

 .B \-\-status\-version [n]

 Set the status file format version number to
 .B n\fR.
 
 This only affects the status file on servers with multi\-client capability
 enabled.
 
 .B 1
 \-\- traditional format (default). The client list contains the following
 fields comma\-separated: Common Name, Real Address, Bytes Received, Bytes Sent,
 Connected Since.
 .br
 .B 2
 \-\- a more reliable format for external processing. Compared to version 1, the
 client list contains some additional fields: Virtual Address, Virtual IPv6

 Address, Username, Client ID, Peer ID, Data Channel Cipher.

 Future versions may extend the number of fields.
 .br
 .B 3
 \-\- identical to 2, but fields are tab\-separated.
 

 .\"*********************************************************
 .TP

 .B \-\-mute n

 Log at most
 .B n
 consecutive messages in the same category.  This is useful to
 limit repetitive logging of similar message types.
 .\"*********************************************************
 .TP

 .B \-\-compress [algorithm]
 Enable a compression algorithm.
 
 The
 .B algorithm

 parameter may be "lzo", "lz4", or empty.  LZO and LZ4
 are different compression algorithms, with LZ4 generally
 offering the best performance with least CPU usage.

 For backwards compatibility with OpenVPN versions before v2.4, use "lzo"

 (which is identical to the older option "\-\-comp\-lzo yes").

 
 If the
 .B algorithm
 parameter is empty, compression will be turned off, but the packet
 framing for compression will still be enabled, allowing a different
 setting to be pushed later.

 
 .B Security Considerations
 
 Compression and encryption is a tricky combination.  If an attacker knows or is
 able to control (parts of) the plaintext of packets that contain secrets, the
 attacker might be able to extract the secret if compression is enabled.  See
 e.g. the CRIME and BREACH attacks on TLS which also leverage compression to
 break encryption.  If you are not entirely sure that the above does not apply
 to your traffic, you are advised to *not* enable compression.
 

 .\"*********************************************************
 .TP

 .B \-\-comp\-lzo [mode]

 .B DEPRECATED
 This option will be removed in a future OpenVPN release.  Use the
 newer
 .B \-\-compress
 instead.
 

 Use LZO compression \-\- may add up to 1 byte per

 packet for incompressible data.

 .B mode
 may be "yes", "no", or "adaptive" (default).
 
 In a server mode setup, it is possible to selectively turn
 compression on or off for individual clients.
 

 First, make sure the client\-side config file enables selective

 compression by having at least one

 .B \-\-comp\-lzo

 directive, such as

 .B \-\-comp\-lzo no.

 This will turn off compression by default,
 but allow a future directive push from the server to
 dynamically change the
 on/off/adaptive setting.
 
 Next in a

 .B \-\-client\-config\-dir

 file, specify the compression setting for the client,
 for example:
 
 .nf

 .ft 3
 .in +4

 comp\-lzo yes
 push "comp\-lzo yes"

 .in -4

 .ft
 .fi
 
 The first line sets the

 .B comp\-lzo

 setting for the server
 side of the link, the second sets the client side.

 .\"*********************************************************
 .TP

 .B \-\-comp\-noadapt

 When used in conjunction with

 .B \-\-comp\-lzo,

 this option will disable OpenVPN's adaptive compression algorithm.
 Normally, adaptive compression is enabled with

 .B \-\-comp\-lzo.

 
 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 \-\-management socket\-name unix [pw\-file] \ \ \ \ \ (recommended)
 .TQ

 .B \-\-management IP port [pw\-file]

 Enable a management server on a
 .B socket\-name
 Unix socket on those platforms supporting it, or on
 a designated TCP port.
 
 .B pw\-file
 , 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.
 
 For unix sockets, the  default  behaviour  is to create a unix domain socket
 that may be connected to by any process.  Use the

 .B \-\-management\-client\-user

 and

 .B \-\-management\-client\-group

 directives to restrict access.
 
 The management interface provides a special mode where the TCP management link
 can operate over the tunnel itself.  To enable this mode, set IP to
 .B tunnel.
 Tunnel mode will cause the  management interface to listen for a
 TCP connection on the local VPN address of the TUN/TAP interface.
 
 .B BEWARE
 of enabling the management interface over TCP.  In  these cases you should
 .I ALWAYS
 make use of
 .B pw\-file
 to password protect the management interface.  Any user who can connect to this
 TCP
 .B IP:port
 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.
 
 While the management port is designed for  programmatic control of OpenVPN by
 other applications, it is possible to telnet to the port, using a telnet client
 in "raw" mode.  Once  connected, type "help" for a list of commands.
 
 For detailed documentation on the management interface, see the
 .I management\-notes.txt
 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

 .B IP:port
 specified by
 .B \-\-management

 rather than listen as a TCP server or on a unix domain socket.
 
 If the client connection fails to connect or is disconnected,
 a SIGTERM signal will be generated causing OpenVPN to quit.

 .\"*********************************************************
 .TP

 .B \-\-management\-query\-passwords

 Query management channel for private key password and

 .B \-\-auth\-user\-pass

 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
 .B \-\-remote

 (client\-only).

 .\"*********************************************************
 .TP

 .B \-\-management\-query\-remote

 Allow management interface to override

 .B \-\-remote

 directives (client\-only).

 .\"*********************************************************

 .TP

 .B \-\-management\-external\-key

 Allows usage for external private key file instead of
 .B \-\-key

 option (client\-only).

 .\"*********************************************************

 .TP

 .B \-\-management\-external\-cert certificate\-hint

 Allows usage for external certificate instead of
 .B \-\-cert

 option (client\-only).
 .B certificate\-hint

 is an arbitrary string which is passed to a management

 interface client as an argument of NEED\-CERTIFICATE notification.

 Requires \-\-management\-external\-key.

 .\"*********************************************************
 .TP

 .B \-\-management\-forget\-disconnect

 Make OpenVPN forget passwords when management session
 disconnects.
 
 This directive does not affect the

 .B \-\-http\-proxy

 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
 .B hold release
 command.
 .\"*********************************************************
 .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 \-\-management\-client this option is not needed since

 a disconnect will always generate a SIGTERM.

 .\"*********************************************************
 .TP

 .B \-\-management\-log\-cache n

 Cache the most recent
 .B n
 lines of log file history for usage
 by the management channel.
 .\"*********************************************************
 .TP

 .B \-\-management\-up\-down

 Report tunnel up/down events to management interface.
 .B 
 .\"*********************************************************
 .TP

 .B \-\-management\-client\-auth

 Gives management interface client the responsibility
 to authenticate clients after their client certificate

 has been verified.  See management\-notes.txt in OpenVPN

 distribution for detailed notes.
 .\"*********************************************************
 .TP

 .B \-\-management\-client\-pf

 Management interface clients must specify a packet

 filter file for each connecting client.  See management\-notes.txt

 in OpenVPN distribution for detailed notes.
 .\"*********************************************************
 .TP

 .B \-\-management\-client\-user u

 When the management interface is listening on a unix domain socket,
 only allow connections from user
 .B u.
 .\"*********************************************************
 .TP

 .B \-\-management\-client\-group g

 When the management interface is listening on a unix domain socket,
 only allow connections from group
 .B g.
 .\"*********************************************************
 .TP

 .B \-\-plugin module\-pathname [init\-string]
 Load plug\-in module from the file
 .B module\-pathname,

 passing

 .B init\-string

 as an argument
 to the module initialization function.  Multiple
 plugin modules may be loaded into one OpenVPN
 process.
 

 The

 .B module\-pathname

 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.
 
 .nf
 .ft 3
 .in +4
 .B \-\-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
 .in -4
 .fi
 

 DEFAULT_DIR is replaced by the default plug\-in directory,

 which is configured at the build time of OpenVPN.  CWD is the
 current directory where OpenVPN was started or the directory
 OpenVPN have swithed into via the

 .B \-\-cd

 option before the

 .B \-\-plugin

 option.
 

 For more information and examples on how to build OpenVPN

 plug\-in modules, see the README file in the

 .B plugin
 folder of the OpenVPN source distribution.
 
 If you are using an RPM install of OpenVPN, see
 /usr/share/openvpn/plugin.  The documentation is
 in
 .B doc
 and the actual plugin modules are in
 .B lib.
 
 Multiple plugin modules can be cascaded, and modules can be
 used in tandem with scripts.  The modules will be called by
 OpenVPN in the order that they are declared in the config
 file.  If both a plugin and script are configured for the same
 callback, the script will be called last.  If the
 return code of the 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 (0) in order for
 the connection to be authenticated.
 .\"*********************************************************

 .TP

 .B \-\-keying\-material\-exporter label len

 Save Exported Keying Material [RFC5705] of len bytes (must be
 between 16 and 4095 bytes) using label in environment
 (exported_keying_material) for use by plugins in
 OPENVPN_PLUGIN_TLS_FINAL callback.
 
 Note that exporter labels have the potential to collide with existing PRF
 labels. In order to prevent this, labels MUST begin with "EXPORTER".
 
 .\"*********************************************************

 .SS Server Mode

 Starting with OpenVPN 2.0, a multi\-client TCP/UDP server mode

 is supported, and can be enabled with the

 .B \-\-mode server

 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.
 .\"*********************************************************
 .TP

 .B \-\-server network netmask ['nopool']

 A helper directive designed to simplify the configuration
 of OpenVPN's server mode.  This directive will set up an
 OpenVPN server which will allocate addresses to clients
 out of the given network/netmask.  The server itself
 will take the ".1" address of the given network

 for use as the server\-side endpoint of the local

 TUN/TAP interface.
 
 For example,

 .B \-\-server 10.8.0.0 255.255.255.0

 expands as follows:
 
 .nf

 .ft 3
 .in +4

  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

 .in -4

 .ft
 .fi
 
 Don't use

 .B \-\-server

 if you are ethernet bridging.  Use

 .B \-\-server\-bridge

 instead.
 .\"*********************************************************
 .TP

 .B \-\-server\-bridge gateway netmask pool\-start\-IP pool\-end\-IP

 .TP

 .B \-\-server\-bridge ['nogw']

 
 A helper directive similar to

 .B \-\-server

 which is designed to simplify the configuration
 of OpenVPN's server mode in ethernet bridging configurations.
 

 If

 .B \-\-server\-bridge

 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 
 .B nogw
 flag (advanced) indicates that gateway information should not be
 pushed to the client.

 To configure ethernet bridging, you 
 must first use your OS's bridging capability
 to bridge the TAP interface with the ethernet
 NIC interface.  For example, on Linux this is done
 with the
 .B brctl
 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".

 
 Next you you must manually set the
 IP/netmask on the bridge interface.  The
 .B gateway
 and
 .B netmask
 parameters to

 .B \-\-server\-bridge

 can be set to either the IP/netmask of the
 bridge interface, or the IP/netmask of the
 default gateway/router on the bridged
 subnet.
 
 Finally, set aside a IP range in the bridged
 subnet,
 denoted by

 .B pool\-start\-IP

 and

 .B pool\-end\-IP,

 for OpenVPN to allocate to connecting
 clients.
 
 For example,

 .B server\-bridge 10.8.0.4 255.255.255.0 10.8.0.128 10.8.0.254

 expands as follows:
 
 .nf

 .ft 3
 .in +4

 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"

 .in -4

 .ft
 .fi

 
 In another example,

 .B \-\-server\-bridge

 (without parameters) expands as follows:
 
 .nf

 .ft 3
 .in +4

 mode server

 tls\-server

 push "route\-gateway dhcp"

 .in -4
 .ft
 .fi
 
 Or

 .B \-\-server\-bridge nogw

 expands as follows:
 
 .nf
 .ft 3
 .in +4
 mode server

 tls\-server

 .in -4

 .ft
 .fi

 .\"*********************************************************
 .TP

 .B \-\-push "option"

 Push a config file option back to the client for remote
 execution.  Note that
 .B
 option
 must be enclosed in double quotes ("").  The client must specify

 .B \-\-pull

 in its config file.  The set of options which can be
 pushed is limited by both feasibility and security.
 Some options such as those which would execute scripts
 are banned, since they would effectively allow a compromised
 server to execute arbitrary code on the client.
 Other options such as TLS or MTU parameters
 cannot be pushed because the client needs to know
 them before the connection to the server can be initiated.
 
 This is a partial list of options which can currently be pushed:

 .B \-\-route, \-\-route\-gateway, \-\-route\-delay, \-\-redirect\-gateway,
 .B \-\-ip\-win32, \-\-dhcp\-option,
 .B \-\-inactive, \-\-ping, \-\-ping\-exit, \-\-ping\-restart,

 .B \-\-setenv,

 .B \-\-auth\-token,

 .B \-\-persist\-key, \-\-persist\-tun, \-\-echo,
 .B \-\-comp\-lzo,
 .B \-\-socket\-flags,

 .B \-\-sndbuf, \-\-rcvbuf

 .\"*********************************************************
 .TP

 .B \-\-push\-reset

 Don't inherit the global push list for a specific client instance.

 Specify this option in a client\-specific context such

 as with a

 .B \-\-client\-config\-dir

 configuration file.  This option will ignore

 .B \-\-push

 options at the global config file level.

 .\"*********************************************************
 .TP
 .B \-\-push\-remove opt
 selectively remove all
 .B \-\-push
 options matching "opt" from the option list for a client.  "opt" is matched

 as a substring against the whole option string to\-be\-pushed to the client, so

 .B \-\-push\-remove route
 would remove all
 .B \-\-push route ...
 and

 .B \-\-push route\-ipv6 ...

 statements, while

 .B \-\-push\-remove 'route\-ipv6 2001:'

 would only remove IPv6 routes for 2001:... networks.
 
 .B \-\-push\-remove

 can only be used in a client\-specific context, like in a

 .B \-\-client\-config\-dir
 file, or
 .B \-\-client\-connect

 script or plugin \-\- similar to

 .B \-\-push\-reset,
 just more selective.
 
 NOTE: to
 .I change
 an option,
 .B \-\-push\-remove
 can be used to first remove the old value, and then add a new
 .B \-\-push
 option with the new value.

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

 .\"*********************************************************

 .TP

 .B \-\-push\-peer\-info

 Push additional information about the client to server.
 The following data is always pushed to the server:

 IV_VER=<version> \-\- the client OpenVPN version

 IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win] \-\- the client OS platform

 IV_LZO_STUB=1 \-\- if client was built with LZO stub capability

 IV_LZ4=1 \-\- if the client supports LZ4 compressions.

 IV_PROTO=2 \-\- if the client supports peer\-id floating mechansim

 IV_NCP=2 \-\- negotiable ciphers, client supports

 .B \-\-cipher
 pushed by the server, a value of 2 or greater indicates client

 supports AES\-GCM\-128 and AES\-GCM\-256.

 IV_GUI_VER=<gui_id> <version> \-\- the UI version of a UI if one is

 running, for example "de.blinkt.openvpn 0.5.47" for the
 Android app.
 
 When
 .B \-\-push\-peer\-info
 is enabled the additional information consists of the following data:
 

 IV_HWADDR=<mac address> \-\- the MAC address of clients default gateway

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

 IV_PLAT_VER=x.y \- the version of the operating system, e.g. 6.1 for Windows 7.

 UV_<name>=<value> \-\- client environment variables whose names start with "UV_"

 .\"*********************************************************
 .TP

 .B \-\-disable

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

 .B \-\-crl\-verify

 option).
 
 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

 .B \-\-client\-config\-dir

 or dynamically generated using a

 .B \-\-client\-connect

 script.
 .\"*********************************************************
 .TP

 .B \-\-ifconfig\-pool start\-IP end\-IP [netmask]

 Set aside a pool of subnets to be
 dynamically allocated to connecting clients, similar

 to a DHCP server.  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
 .B netmask
 parameter will also be pushed to clients.
 
 .\"*********************************************************
 .TP

 .B \-\-ifconfig\-pool\-persist file [seconds]
 Persist/unpersist ifconfig\-pool

 data to
 .B file,
 at
 .B seconds
 intervals (default=600), as well as on program startup and
 shutdown.
 

 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

 .B \-\-persist\-tun

 option.
 
 .B file

 is a comma\-delimited ASCII file, formatted as
 <Common\-Name>,<IP\-address>.

 
 If
 .B seconds
 = 0,
 .B file

 will be treated as read\-only.  This is useful if

 you would like to treat
 .B file
 as a configuration file.
 
 Note that the entries in this file are treated by OpenVPN as
 suggestions only, based on past associations between
 a common name and IP address.  They do not guarantee that the given common
 name will always receive the given IP address.  If you want guaranteed
 assignment, use

 .B \-\-ifconfig\-push

 .\"*********************************************************
 .TP

 .B \-\-ifconfig\-pool\-linear

 .B DEPRECATED
 This option will be removed in OpenVPN 2.5
 

 Modifies the

 .B \-\-ifconfig\-pool

 directive to
 allocate individual TUN interface addresses for
 clients rather than /30 subnets.  NOTE:  This option
 is incompatible with Windows clients.

 
 This option is deprecated, and should be replaced with

 .B \-\-topology p2p

 which is functionally equivalent.

 .\"*********************************************************
 .TP

 .B \-\-ifconfig\-push local remote\-netmask [alias]

 Push virtual IP endpoints for client tunnel,

 overriding the \-\-ifconfig\-pool dynamic allocation.

 
 The parameters
 .B local
 and

 .B remote\-netmask

 are set according to the

 .B \-\-ifconfig

 directive which you want to execute on the client machine to
 configure the remote end of the tunnel.  Note that the parameters
 .B local
 and

 .B remote\-netmask

 are from the perspective of the client, not the server.  They may be
 DNS names rather than IP addresses, in which case they will be resolved
 on the server at the time of client connection.
 

 The optional
 .B alias
 parameter may be used in cases where NAT causes the client view
 of its local endpoint to differ from the server view.  In this case

 .B local/remote\-netmask

 will refer to the server view while

 .B alias/remote\-netmask

 will refer to the client view.
 

 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

 .B \-\-client\-config\-dir

 or dynamically generated using a

 .B \-\-client\-connect

 script.
 
 Remember also to include a

 .B \-\-route

 directive in the main OpenVPN config file which encloses
 .B local,
 so that the kernel will know to route it
 to the server's TUN/TAP interface.
 
 OpenVPN's internal client IP address selection algorithm works as
 follows:
 
 .B 1

 \-\- Use

 .B \-\-client\-connect script

 generated file for static IP (first choice).
 .br
 .B 2

 \-\- Use

 .B \-\-client\-config\-dir

 file for static IP (next choice).
 .br
 .B 3

 \-\- Use

 .B \-\-ifconfig\-pool

 allocation for dynamic IP (last choice).
 .br
 .\"*********************************************************
 .TP

 .B \-\-iroute network [netmask]

 Generate an internal route to a specific
 client. The
 .B netmask
 parameter, if omitted, defaults to 255.255.255.255.
 
 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

 .B \-\-route

 directive).  The reason why two routes are needed
 is that the

 .B \-\-route

 directive routes the packet from the kernel
 to OpenVPN.  Once in OpenVPN, the

 .B \-\-iroute

 directive routes to the specific client.
 
 This option must be specified either in a client
 instance config file using

 .B \-\-client\-config\-dir

 or dynamically generated using a

 .B \-\-client\-connect

 script.
 
 The

 .B \-\-iroute

 directive also has an important interaction with

 .B \-\-push

 "route ...".

 .B \-\-iroute

 essentially defines a subnet which is owned by a
 particular client (we will call this client A).
 If you would like other clients to be able to reach A's
 subnet, you can use

 .B \-\-push

 "route ..."
 together with

 .B \-\-client\-to\-client

 to effect this.  In order for all clients to see
 A's subnet, OpenVPN must push this route to all clients
 EXCEPT for A, since the subnet is already owned by A.
 OpenVPN accomplishes this by not
 not pushing a route to a client
 if it matches one of the client's iroutes.
 .\"*********************************************************
 .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

 .B \-\-client\-to\-client

 flag tells OpenVPN to internally route client\-to\-client
 traffic rather than pushing all client\-originating traffic

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

 custom, per\-client rules.

 .\"*********************************************************
 .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

 .B \-\-client\-connect cmd

 Run

 .B command cmd
 on client connection.
 
 .B cmd
 consists of a path to script (or executable program), optionally

 followed by arguments. The path and arguments may be single\- or double\-quoted

 and/or escaped using a backslash, and should be separated by one or more spaces.
 
 The command is passed the common name

 and IP address of the just\-authenticated client

 as environmental variables (see 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
 .B cmd
 ), to be used by the command

 to pass dynamically generated config file directives back to OpenVPN.
 
 If the script wants to generate a dynamic config file
 to be applied on the server when the client connects,

 it should write it to the file named by the last argument.

 
 See the

 .B \-\-client\-config\-dir

 option below for options which
 can be legally used in a dynamically generated config file.
 
 Note that the return value of
 .B script
 is significant.  If
 .B script

 returns a non\-zero error status, it will cause the client

 to be disconnected.
 .\"*********************************************************
 .TP

 .B \-\-client\-disconnect cmd

 Like

 .B \-\-client\-connect

 but called on client instance shutdown.  Will not be called
 unless the

 .B \-\-client\-connect

 script and plugins (if defined)
 were previously called on this instance with
 successful (0) status returns.
 
 The exception to this rule is if the

 .B \-\-client\-disconnect

 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.

 
 The

 .B \-\-client\-disconnect

 command is passed the same pathname as the corresponding

 .B \-\-client\-connect

 command as its last argument. (after any arguments specified in
 .B cmd
 ).

 .B 
 .\"*********************************************************
 .TP

 .B \-\-client\-config\-dir dir

 Specify a directory
 .B dir
 for custom client config files.  After
 a connecting client has been authenticated, OpenVPN will
 look in this directory for a file having the same name
 as the client's X509 common name.  If a matching file

 exists, it will be opened and parsed for client\-specific

 configuration options.  If no matching file is found, OpenVPN
 will instead try to open and parse a default file called

 "DEFAULT", which may be provided but is not required. Note that
 the configuration files must be readable by the OpenVPN process
 after it has dropped it's root privileges.

 
 This file can specify a fixed IP address for a given
 client using

 .B \-\-ifconfig\-push,

 as well as fixed subnets owned by the client using

 .B \-\-iroute.

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

 options are legal in a client\-specific context:

 .B \-\-push, \-\-push\-reset, \-\-push\-remove, \-\-iroute, \-\-ifconfig\-push,

 and

 .B \-\-config.

 .\"*********************************************************
 .TP

 .B \-\-ccd\-exclusive

 Require, as a
 condition of authentication, that a connecting client has a

 .B \-\-client\-config\-dir

 file.
 .\"*********************************************************
 .TP

 .B \-\-tmp\-dir dir

 Specify a directory
 .B dir
 for temporary files.  This directory will be used by

 openvpn processes and script to communicate temporary
 data with openvpn main process. Note that
 the directory must be writable by the OpenVPN process
 after it has dropped it's root privileges.
 
 This directory will be used by in the following cases:
 
 *

 .B \-\-client\-connect

 scripts to dynamically generate client\-specific

 configuration files.

 
 *
 .B OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY
 plugin hook to return success/failure via auth_control_file
 when using deferred auth method
 
 *
 .B OPENVPN_PLUGIN_ENABLE_PF
 plugin hook to pass filtering rules via pf_file

 .\"*********************************************************
 .TP

 .B \-\-hash\-size r v

 Set the size of the real address hash table to
 .B r
 and the virtual address table to
 .B v.
 By default, both tables are sized at 256 buckets.
 .\"*********************************************************
 .TP

 .B \-\-bcast\-buffers n

 Allocate
 .B n
 buffers for broadcast datagrams (default=256).
 .\"*********************************************************
 .TP

 .B \-\-tcp\-queue\-limit n

 Maximum number of output packets queued before TCP (default=64).

 
 When OpenVPN is tunneling data from a TUN/TAP device to a
 remote client over a TCP connection, it is possible that the TUN/TAP device
 might produce data at a faster rate than the TCP 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

 .B \-\-tcp\-nodelay

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

 .ft 3
 .in +4

  if mode server:

    socket\-flags TCP_NODELAY
    push "socket\-flags TCP_NODELAY"

 .in -4

 .ft
 .fi
 .\"*********************************************************
 .TP

 .B \-\-max\-clients n

 Limit server to a maximum of
 .B n
 concurrent clients.
 .\"*********************************************************
 .TP

 .B \-\-max\-routes\-per\-client n

 Allow a maximum of
 .B n
 internal routes per client (default=256).
 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

 .B \-\-client\-config\-dir

 file or auto\-generated by a

 .B \-\-client\-connect

 script to override the global value for a particular client.
 
 Note that this
 directive affects OpenVPN's internal routing table, not the
 kernel routing table.
 .\"*********************************************************
 .TP

 .B \-\-stale\-routes\-check n [t]

 Remove routes haven't had activity for
 .B n
 seconds (i.e. the ageing time).
 
 This check is ran every
 .B t
 seconds (i.e. check interval).
 
 If
 .B t
 is not present it defaults to
 .B n
 
 This option helps to keep the dynamic routing table small.
 See also

 .B \-\-max\-routes\-per\-client

 .\"*********************************************************
 .TP

 .B \-\-connect\-freq n sec

 Allow a maximum of
 .B n
 new connections per
 .B sec 
 seconds from clients.  This is designed to contain DoS attacks which flood
 the server with connection requests using certificates which
 will ultimately fail to authenticate.
 
 This is an imperfect solution however, because in a real
 DoS scenario, legitimate connections might also be refused.
 
 For the best protection against DoS attacks in server mode,
 use

 .B \-\-proto udp

 and either
 .B \-\-tls\-auth
 or
 .B \-\-tls\-crypt\fR.

 .\"*********************************************************
 .TP

 .B \-\-learn\-address cmd

 Run command

 .B cmd
 to validate client virtual addresses or routes.
 
 .B cmd

 consists of a path to script (or executable program), optionally

 followed by arguments. The path and arguments may be single\- or double\-quoted

 and/or escaped using a backslash, and should be separated by one or more spaces.
 
 Three arguments will be appended to any arguments in
 .B cmd
 as follows:

 .B [1] operation \-\-

 "add", "update", or "delete" based on whether or not
 the address is being added to, modified, or deleted from
 OpenVPN's internal routing table.
 .br

 .B [2] address \-\-

 The address being learned or unlearned.  This can be
 an IPv4 address such as "198.162.10.14", an IPv4 subnet
 such as "198.162.10.0/24", or an ethernet MAC address (when

 .B \-\-dev tap

 is being used) such as "00:FF:01:02:03:04".
 .br

 .B [3] common name \-\-

 The common name on the certificate associated with the
 client linked to this address.  Only present for "add"
 or "update" operations, not "delete".
 
 On "add" or "update" methods, if the script returns

 a failure code (non\-zero), OpenVPN will reject the address

 and will not modify its internal routing table.
 
 Normally, the
 .B cmd
 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's authenticated common name,

 it allows a user\-defined script to configure firewall access
 policies with regard to the client's high\-level common name,

 rather than the low level client virtual addresses.
 .\"*********************************************************
 .TP

 .B \-\-auth\-user\-pass\-verify cmd method

 Require the client to provide a username/password (possibly
 in addition to a client certificate) for authentication.
 

 OpenVPN will run
 .B command cmd
 to validate the username/password

 provided by the client.
 

 .B cmd
 consists of a path to script (or executable program), optionally

 followed by arguments. The path and arguments may be single\- or double\-quoted

 and/or escaped using a backslash, and should be separated by one or more spaces.
 

 If
 .B method

 is set to "via\-env", OpenVPN will call

 .B script
 with the environmental variables
 .B username
 and
 .B password
 set to the username/password strings provided by the client.
 Be aware that this method is insecure on some platforms which
 make the environment of a process publicly visible to other
 unprivileged processes.
 
 If
 .B method

 is set to "via\-file", OpenVPN will write the username and

 password to the first two lines of a temporary file.  The filename
 will be passed as an argument to
 .B script,
 and the file will be automatically deleted by OpenVPN after
 the script returns.  The location of the temporary file is
 controlled by the

 .B \-\-tmp\-dir

 option, and will default to the current directory if unspecified.
 For security, consider setting 

 .B \-\-tmp\-dir

 to a volatile storage medium such as
 .B /dev/shm
 (if available) to prevent the username/password file from touching the hard drive.
 
 The script should examine the username
 and password,
 returning a success exit code (0) if the
 client's authentication request is to be accepted, or a failure
 code (1) to reject the client.
 

 This directive is designed to enable a plugin\-style interface

 for extending OpenVPN's authentication capabilities.
 
 To protect against a client passing a maliciously formed
 username or password string, the username string must
 consist only of these characters: alphanumeric, underbar

 ('_'), dash ('\-'), dot ('.'), or at ('@').  The password

 string can consist of any printable characters except for
 CR or LF.  Any illegal characters in either the username
 or password string will be converted to underbar ('_').
 

 Care must be taken by any user\-defined scripts to avoid

 creating a security vulnerability in the way that these
 strings are handled.  Never use these strings in such a way
 that they might be escaped or evaluated by a shell interpreter.
 
 For a sample script that performs PAM authentication, see

 .B sample\-scripts/auth\-pam.pl

 in the OpenVPN source distribution.
 .\"*********************************************************
 .TP

 .B \-\-auth\-gen\-token [lifetime]
 After successful user/password authentication, the OpenVPN
 server will with this option generate a temporary
 authentication token and push that to 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.
 
 The
 .B lifetime
 argument defines how long the generated token is valid.  The
 lifetime is defined in seconds.  If lifetime is not set
 or it is set to 0, the token will never expire.
 
 This feature is useful for environments which is 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.

 .\"*********************************************************
 .TP

 .B \-\-opt\-verify

 Clients that connect with options that are incompatible
 with those of the server will be disconnected.
 
 Options that will be compared for compatibility include

 dev\-type, link\-mtu, tun\-mtu, proto, ifconfig,

 comp\-lzo, fragment, keydir, cipher, auth, keysize, secret,
 no\-replay, no\-iv, tls\-auth, key\-method, tls\-server, and tls\-client.

 
 This option requires that

 .B \-\-disable\-occ