Changes between Version 1 and Version 2 of Openvpn22ManPage


Ignore:
Timestamp:
05/20/21 06:08:42 (12 months ago)
Author:
Samuli Seppänen
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Openvpn22ManPage

    v1 v2  
     1{{{#!comment
     2Editors note: awk code to clean up man2html output to remove un-wanted localhost URIs:
     3https://gist.github.com/QueuingKoala/5985986
     4}}}
     5
    16{{{
    2 #!div style="font-size: 80%"
    3 {{{
    4 openvpn(8)                                                                            openvpn(8)
    5 
    6 
    7 
    8 NAME
    9        openvpn - secure IP tunnel daemon.
    10 
    11 SYNOPSIS
    12        openvpn [ options ... ]
    13 
    14 INTRODUCTION
    15        OpenVPN  is an open source VPN daemon by James Yonan.  Because OpenVPN tries to be a uni‐
    16        versal VPN tool offering a great deal of flexibility, there are a lot of options on  this
    17        manual page.  If you're new to OpenVPN, you might want to skip ahead to the examples sec‐
    18        tion where you will see how to construct simple VPNs on the  command  line  without  even
    19        needing a configuration file.
    20 
    21        Also  note  that  there's  more  documentation  and  examples  on  the  OpenVPN web site:
    22        http://openvpn.net/
    23 
    24        And if you would like to see a shorter version of this manual, see the openvpn usage mes‐
    25        sage which can be obtained by running openvpn without any parameters.
    26 
    27 DESCRIPTION
    28        OpenVPN  is  a robust and highly flexible VPN daemon.  OpenVPN supports SSL/TLS security,
    29        ethernet bridging, TCP or UDP tunnel  transport  through  proxies  or  NAT,  support  for
    30        dynamic  IP addresses and DHCP, scalability to hundreds or thousands of users, and porta‐
    31        bility to most major OS platforms.
    32 
    33        OpenVPN is tightly bound to the OpenSSL library, and derives much of its crypto capabili‐
    34        ties from it.
    35 
    36        OpenVPN  supports conventional encryption using a pre-shared secret key (Static Key mode)
    37        or public key security (SSL/TLS mode) using client & server certificates.   OpenVPN  also
    38        supports non-encrypted TCP/UDP tunnels.
    39 
    40        OpenVPN  is designed to work with the TUN/TAP virtual networking interface that exists on
    41        most platforms.
    42 
    43        Overall, OpenVPN aims to offer many of the key features of IPSec but  with  a  relatively
    44        lightweight footprint.
    45 
    46 OPTIONS
    47        OpenVPN  allows  any option to be placed either on the command line or in a configuration
    48        file.  Though all command line options are preceded by a double-leading-dash ("--"), this
    49        prefix can be removed when an option is placed in a configuration file.
    50 
    51        --help Show options.
    52 
    53        --config file
    54               Load  additional  config options from file where each line corresponds to one com‐
    55               mand line option, but with the leading '--' removed.
    56 
    57               If --config file is the only option to the openvpn command, the  --config  can  be
    58               removed, and the command can be given as openvpn file
    59 
    60               Note that configuration files can be nested to a reasonable depth.
    61 
    62               Double  quotation  or  single quotation characters ("", '') can be used to enclose
    63               single parameters containing whitespace, and "#" or ";" characters  in  the  first
    64               column can be used to denote comments.
    65 
    66               Note that OpenVPN 2.0 and higher performs backslash-based shell escaping for char‐
    67               acters not in single quotations, so the following mappings should be observed:
    68 
    69                   \\       Maps to a single backslash character (\).
    70                   \"       Pass a literal doublequote character ("), don't
    71                            interpret it as enclosing a parameter.
    72                   \[SPACE] Pass a literal space or tab character, don't
    73                            interpret it as a parameter delimiter.
    74 
    75               For example on Windows, use double backslashes to represent pathnames:
    76 
    77                   secret "c:\\OpenVPN\\secret.key"
    78 
    79               For examples of configuration files, see http://openvpn.net/examples.html
    80 
    81               Here is an example configuration file:
    82 
    83                   #
    84                   # Sample OpenVPN configuration file for
    85                   # using a pre-shared static key.
    86                   #
    87                   # '#' or ';' may be used to delimit comments.
    88 
    89                   # Use a dynamic tun device.
    90                   dev tun
    91 
    92                   # Our remote peer
    93                   remote mypeer.mydomain
    94 
    95                   # 10.1.0.1 is our local VPN endpoint
    96                   # 10.1.0.2 is our remote VPN endpoint
    97                   ifconfig 10.1.0.1 10.1.0.2
    98 
    99                   # Our pre-shared static key
    100                   secret static.key
    101 
    102    Tunnel Options:
    103        --mode m
    104               Set OpenVPN major mode.  By default, OpenVPN runs in point-to-point mode  ("p2p").
    105               OpenVPN  2.0  introduces  a  new  mode  ("server") which implements a multi-client
    106               server capability.
    107 
    108        --local host
    109               Local host name or IP address for bind.  If specified, OpenVPN will bind  to  this
    110               address only.  If unspecified, OpenVPN will bind to all interfaces.
    111 
    112        --remote host [port] [proto]
    113               Remote  host  name or IP address.  On the client, multiple --remote options may be
    114               specified for redundancy, each referring to a different OpenVPN server.   Specify‐
    115               ing  multiple --remote options for this purpose is a special case of the more gen‐
    116               eral connection-profile feature.  See the <connection> documentation below.
    117 
    118               The OpenVPN client will try to connect to a server at host:port in the order spec‐
    119               ified by the list of --remote options.
    120 
    121               proto  indicates  the  protocol to use when connecting with the remote, and may be
    122               "tcp" or "udp".
    123 
    124               The client will move on to the next host in the list, in the event  of  connection
    125               failure.   Note  that  at  any given time, the OpenVPN client will at most be con‐
    126               nected to one server.
    127 
    128               Note that since UDP is connectionless, connection failure is defined by the --ping
    129               and --ping-restart options.
    130 
    131               Note the following corner case:  If you use multiple --remote options, AND you are
    132               dropping root privileges on the client with --user and/or --group, AND the  client
    133               is  running a non-Windows OS, if the client needs to switch to a different server,
    134               and that server pushes back different TUN/TAP or route settings,  the  client  may
    135               lack  the  necessary  privileges  to close and reopen the TUN/TAP interface.  This
    136               could cause the client to exit with a fatal error.
    137 
    138               If --remote is unspecified, OpenVPN will listen for packets from any  IP  address,
    139               but will not act on those packets unless they pass all authentication tests.  This
    140               requirement for authentication is binding on all potential peers, even those  from
    141               known  and  supposedly  trusted IP addresses (it is very easy to forge a source IP
    142               address on a UDP packet).
    143 
    144               When used in TCP mode, --remote will act as a filter, rejecting  connections  from
    145               any host which does not match host.
    146 
    147               If  host  is  a DNS name which resolves to multiple IP addresses, one will be ran‐
    148               domly chosen, providing a sort of basic load-balancing and failover capability.
    149 
    150        --remote-random-hostname
    151               Add a random string (6 characters) to first DNS label of hostname to  prevent  DNS
    152               caching.    For   example,   "foo.bar.gov"   would   be   modified   to  "<random-
    153               chars>.foo.bar.gov".
    154 
    155        <connection>
    156               Define a client connection profile.  Client  connection  profiles  are  groups  of
    157               OpenVPN  options  that  describe how to connect to a given OpenVPN server.  Client
    158               connection profiles are specified within an OpenVPN configuration file,  and  each
    159               profile is bracketed by <connection> and </connection>.
    160 
    161               An  OpenVPN client will try each connection profile sequentially until it achieves
    162               a successful connection.
    163 
    164               --remote-random can be used to initially "scramble" the connection list.
    165 
    166               Here is an example of connection profile usage:
    167 
    168                   client
    169                   dev tun
    170 
    171                   <connection>
    172                   remote 198.19.34.56 1194 udp
    173                   </connection>
    174 
    175                   <connection>
    176                   remote 198.19.34.56 443 tcp
    177                   </connection>
    178 
    179                   <connection>
    180                   remote 198.19.34.56 443 tcp
    181                   http-proxy 192.168.0.8 8080
    182                   http-proxy-retry
    183                   </connection>
    184 
    185                   <connection>
    186                   remote 198.19.36.99 443 tcp
    187                   http-proxy 192.168.0.8 8080
    188                   http-proxy-retry
    189                   </connection>
    190 
    191                   persist-key
    192                   persist-tun
    193                   pkcs12 client.p12
    194                   ns-cert-type server
    195                   verb 3
    196 
    197               First we try to connect to a server  at  198.19.34.56:1194  using  UDP.   If  that
    198               fails,  we then try to connect to 198.19.34.56:443 using TCP.  If that also fails,
    199               then try connecting through an HTTP proxy at 192.168.0.8:8080 to  198.19.34.56:443
    200               using  TCP.   Finally,  try  to  connect  through  the  same  proxy to a server at
    201               198.19.36.99:443 using TCP.
    202 
    203               The following OpenVPN options may be used inside of a <connection> block:
    204 
    205               bind, connect-retry, connect-retry-max, connect-timeout, float, http-proxy,  http-
    206               proxy-option,  http-proxy-retry,  http-proxy-timeout,  local, lport, nobind, port,
    207               proto, remote, rport, socks-proxy, and socks-proxy-retry.
    208 
    209               A defaulting mechanism exists for specifying options to apply to all  <connection>
    210               profiles.  If any of the above options (with the exception of remote ) appear out‐
    211               side of a <connection> block, but in a configuration file which has  one  or  more
    212               <connection> blocks, the option setting will be used as a default for <connection>
    213               blocks which follow it in the configuration file.
    214 
    215               For example, suppose the nobind option were placed  in  the  sample  configuration
    216               file  above,  near  the top of the file, before the first <connection> block.  The
    217               effect would be as if nobind were declared in all <connection> blocks below it.
    218 
    219        --proto-force p
    220               When iterating through connection profiles, only consider profiles using  protocol
    221               p ('tcp'|'udp').
    222 
    223        --remote-random
    224               When  multiple --remote address/ports are specified, or if connection profiles are
    225               being used, initially randomize the order of the list as a kind of basic load-bal‐
    226               ancing measure.
    227 
    228        --proto p
    229               Use  protocol  p for communicating with remote host.  p can be udp, tcp-client, or
    230               tcp-server.
    231 
    232               The default protocol is udp when --proto is not specified.
    233 
    234               For UDP operation, --proto udp should be specified on both peers.
    235 
    236               For TCP operation, one peer must use --proto tcp-server and  the  other  must  use
    237               --proto  tcp-client.  A peer started with tcp-server will wait indefinitely for an
    238               incoming connection.  A peer started with tcp-client will attempt to connect,  and
    239               if  that  fails,  will  sleep  for  5  seconds (adjustable via the --connect-retry
    240               option) and try again infinite or up to N retries (adjustable via  the  --connect-
    241               retry-max  option).   Both  TCP  client and server will simulate a SIGUSR1 restart
    242               signal if either side resets the connection.
    243 
    244               OpenVPN is designed to operate optimally over UDP, but TCP capability is  provided
    245               for situations where UDP cannot be used.  In comparison with UDP, TCP will usually
    246               be somewhat less efficient and less robust when used over unreliable or  congested
    247               networks.
    248 
    249               This article outlines some of problems with tunneling IP over TCP:
    250 
    251               http://sites.inka.de/sites/bigred/devel/tcp-tcp.html
    252 
    253               There are certain cases, however, where using TCP may be advantageous from a secu‐
    254               rity and robustness perspective, such as tunneling non-IP or application-level UDP
    255               protocols,  or  tunneling  protocols  which  don't  possess a built-in reliability
    256               layer.
    257 
    258        --connect-retry n
    259               For --proto tcp-client, take n as the number of seconds to wait between connection
    260               retries (default=5).
    261 
    262        --connect-timeout n
    263               For --proto tcp-client, set connection timeout to n seconds (default=10).
    264 
    265        --connect-retry-max n
    266               For  --proto  tcp-client,  take  n  as the number of retries of connection attempt
    267               (default=infinite).
    268 
    269        --auto-proxy
    270               Try to sense HTTP or SOCKS proxy  settings  automatically.   If  no  settings  are
    271               present,  a  direct connection will be attempted.  If both HTTP and SOCKS settings
    272               are present, HTTP will be preferred.  If the HTTP proxy server  requires  a  pass‐
    273               word,  it will be queried from stdin or the management interface.  If the underly‐
    274               ing OS doesn't support an API for returning proxy settings,  a  direct  connection
    275               will  be  attempted.   Currently, only Windows clients support this option via the
    276               InternetQueryOption API.  This option exists in OpenVPN 2.1 or higher.
    277 
    278        --show-proxy-settings
    279               Show sensed HTTP or SOCKS proxy settings. Currently, only Windows clients  support
    280               this option.
    281 
    282        --http-proxy server port [authfile|'auto'|'auto-nct'] [auth-method]
    283               Connect  to remote host through an HTTP proxy at address server and port port.  If
    284               HTTP Proxy-Authenticate is required, authfile is a file containing a username  and
    285               password on 2 lines, or "stdin" to prompt from console.
    286 
    287               auth-method should be one of "none", "basic", or "ntlm".
    288 
    289               HTTP Digest authentication is supported as well, but only via the auto or auto-nct
    290               flags (below).
    291 
    292               The auto flag causes OpenVPN to automatically determine the auth-method and  query
    293               stdin  or the management interface for username/password credentials, if required.
    294               This flag exists on OpenVPN 2.1 or higher.
    295 
    296               The auto-nct flag (no clear-text auth) instructs OpenVPN to  automatically  deter‐
    297               mine  the  authentication method, but to reject weak authentication protocols such
    298               as HTTP Basic Authentication.
    299 
    300        --http-proxy-retry
    301               Retry indefinitely on HTTP proxy errors.  If an HTTP proxy error occurs,  simulate
    302               a SIGUSR1 reset.
    303 
    304        --http-proxy-timeout n
    305               Set proxy timeout to n seconds, default=5.
    306 
    307        --http-proxy-option type [parm]
    308               Set extended HTTP proxy options.  Repeat to set multiple options.
    309 
    310               VERSION version -- Set HTTP version number to version (default=1.0).
    311 
    312               AGENT user-agent -- Set HTTP "User-Agent" string to user-agent.
    313 
    314        --socks-proxy server [port]
    315               Connect  to  remote  host  through  a Socks5 proxy at address server and port port
    316               (default=1080).
    317 
    318        --socks-proxy-retry
    319               Retry indefinitely on Socks proxy errors.  If a Socks proxy error occurs, simulate
    320               a SIGUSR1 reset.
    321 
    322        --resolv-retry n
    323               If  hostname  resolve fails for --remote, retry resolve for n seconds before fail‐
    324               ing.
    325 
    326               Set n to "infinite" to retry indefinitely.
    327 
    328               By default, --resolv-retry infinite is enabled.  You can disable by setting n=0.
    329 
    330        --float
    331               Allow remote peer to change its IP address and/or port number, such as due to DHCP
    332               (this  is  the  default  if  --remote  is  not used).  --float when specified with
    333               --remote allows an OpenVPN session to initially connect  to  a  peer  at  a  known
    334               address,  however if packets arrive from a new address and pass all authentication
    335               tests, the new address will take control of the session.  This is useful when  you
    336               are  connecting  to a peer which holds a dynamic address such as a dial-in user or
    337               DHCP client.
    338 
    339               Essentially, --float tells  OpenVPN  to  accept  authenticated  packets  from  any
    340               address, not only the address which was specified in the --remote option.
    341 
    342        --ipchange cmd
    343               Execute shell command cmd when our remote ip-address is initially authenticated or
    344               changes.
    345 
    346               Execute as:
    347 
    348               cmd ip_address port_number
    349 
    350               Don't use --ipchange  in  --mode  server  mode.   Use  a  --client-connect  script
    351               instead.
    352 
    353               See  the  "Environmental Variables" section below for additional parameters passed
    354               as environmental variables.
    355 
    356               Note that cmd can be a shell command with multiple arguments, in  which  case  all
    357               OpenVPN-generated  arguments will be appended to cmd to build a command line which
    358               will be passed to the script.
    359 
    360               If you are running in a dynamic IP address environment where the IP  addresses  of
    361               either  peer could change without notice, you can use this script, for example, to
    362               edit the /etc/hosts file with the current address of the peer.  The script will be
    363               run every time the remote peer changes its IP address.
    364 
    365               Similarly  if  our  IP  address  changes  due  to DHCP, we should configure our IP
    366               address change script (see man page for dhcpcd(8) ) to deliver a SIGHUP or SIGUSR1
    367               signal  to  OpenVPN.   OpenVPN  will  then  reestablish a connection with its most
    368               recently authenticated peer on its new IP address.
    369 
    370        --port port
    371               TCP/UDP port number for both local and remote.  The current default of 1194 repre‐
    372               sents the official IANA port number assignment for OpenVPN and has been used since
    373               version 2.0-beta17.  Previous versions used port 5000 as the default.
    374 
    375        --lport port
    376               TCP/UDP port number for bind.
    377 
    378        --rport port
    379               TCP/UDP port number for remote.
    380 
    381        --bind Bind to local address and port. This is the default unless  any  of  --proto  tcp-
    382               client , --http-proxy or --socks-proxy are used.
    383 
    384        --nobind
    385               Do  not bind to local address and port.  The IP stack will allocate a dynamic port
    386               for returning packets.  Since the value of the dynamic port could not be known  in
    387               advance by a peer, this option is only suitable for peers which will be initiating
    388               connections by using the --remote option.
    389 
    390        --dev tunX | tapX | null
    391               TUN/TAP virtual network device ( X can be omitted for a dynamic device.)
    392 
    393               See examples section below for an example on setting up a TUN device.
    394 
    395               You must use either tun devices on both ends of the connection or tap  devices  on
    396               both  ends.   You  cannot mix them, as they represent different underlying network
    397               layers.
    398 
    399               tun devices encapsulate IPv4 or IPv6 (OSI Layer 3) while tap  devices  encapsulate
    400               Ethernet 802.3 (OSI Layer 2).
    401 
    402        --dev-type device-type
    403               Which  device  type  are we using?  device-type should be tun (OSI Layer 3) or tap
    404               (OSI Layer 2).  Use this option only if the TUN/TAP device used  with  --dev  does
    405               not begin with tun or tap.
    406 
    407        --topology mode
    408               Configure virtual addressing topology when running in --dev tun mode.  This direc‐
    409               tive has no meaning in --dev tap mode, which always uses a subnet topology.
    410 
    411               If you set this directive on the server, the --server and  --server-bridge  direc‐
    412               tives  will  automatically  push  your chosen topology setting to clients as well.
    413               This directive can also be manually pushed to clients.  Like the --dev  directive,
    414               this directive must always be compatible between client and server.
    415 
    416               mode can be one of:
    417 
    418               net30  --  Use a point-to-point topology, by allocating one /30 subnet per client.
    419               This is designed to allow point-to-point semantics when some or all  of  the  con‐
    420               necting clients might be Windows systems.  This is the default on OpenVPN 2.0.
    421 
    422               p2p -- Use a point-to-point topology where the remote endpoint of the client's tun
    423               interface always points to the local endpoint of the server's tun interface.  This
    424               mode  allocates  a single IP address per connecting client.  Only use when none of
    425               the connecting clients are Windows systems.  This mode is functionally  equivalent
    426               to  the  --ifconfig-pool-linear directive which is available in OpenVPN 2.0 and is
    427               now deprecated.
    428 
    429               subnet -- Use a subnet rather than a point-to-point topology  by  configuring  the
    430               tun  interface  with  a  local IP address and subnet mask, similar to the topology
    431               used in --dev tap and ethernet bridging mode.  This mode  allocates  a  single  IP
    432               address  per  connecting client and works on Windows as well.  Only available when
    433               server and clients are OpenVPN 2.1 or higher, or OpenVPN 2.0.x which has been man‐
    434               ually  patched with the --topology directive code.  When used on Windows, requires
    435               version 8.2 or higher of the TAP-Win32 driver.  When used on *nix,  requires  that
    436               the  tun  driver  supports an ifconfig(8) command which sets a subnet instead of a
    437               remote endpoint IP address.
    438 
    439               This option exists in OpenVPN 2.1 or higher.
    440 
    441        --tun-ipv6
    442               Build a tun link capable of forwarding IPv6 traffic.  Should be used  in  conjunc‐
    443               tion  with  --dev  tun  or --dev tunX.  A warning will be displayed if no specific
    444               IPv6 TUN support for your OS has been compiled into OpenVPN.
    445 
    446        --dev-node node
    447               Explicitly set the device node rather than using /dev/net/tun, /dev/tun, /dev/tap,
    448               etc.   If  OpenVPN  cannot figure out whether node is a TUN or TAP device based on
    449               the name, you should also specify --dev-type tun or --dev-type tap.
    450 
    451               On Windows systems, select the TAP-Win32 adapter which is named node in  the  Net‐
    452               work  Connections Control Panel or the raw GUID of the adapter enclosed by braces.
    453               The --show-adapters option under Windows can also be used to enumerate all  avail‐
    454               able  TAP-Win32  adapters and will show both the network connections control panel
    455               name and the GUID for each TAP-Win32 adapter.
    456 
    457        --lladdr address
    458               Specify the link layer address, more commonly known  as  the  MAC  address.   Only
    459               applied to TAP devices.
    460 
    461        --iproute cmd
    462               Set alternate command to execute instead of default iproute2 command.  May be used
    463               in order to execute OpenVPN in unprivileged environment.
    464 
    465        --ifconfig l rn
    466               Set TUN/TAP adapter parameters.  l is the IP address of the  local  VPN  endpoint.
    467               For  TUN  devices,  rn  is  the  IP  address  of the remote VPN endpoint.  For TAP
    468               devices, rn is the subnet mask of the virtual ethernet segment which is being cre‐
    469               ated or connected to.
    470 
    471               For  TUN  devices,  which  facilitate  virtual  point-to-point IP connections, the
    472               proper usage of --ifconfig is to use two private IP addresses which are not a mem‐
    473               ber  of  any existing subnet which is in use.  The IP addresses may be consecutive
    474               and should have their order reversed on the remote peer.  After the VPN is  estab‐
    475               lished, by pinging rn, you will be pinging across the VPN.
    476 
    477               For  TAP  devices,  which provide the ability to create virtual ethernet segments,
    478               --ifconfig is used to set an IP address and subnet mask just as a physical  ether‐
    479               net  adapter would be similarly configured.  If you are attempting to connect to a
    480               remote ethernet bridge, the IP address and subnet should be set  to  values  which
    481               would  be  valid  on  the the bridged ethernet segment (note also that DHCP can be
    482               used for the same purpose).
    483 
    484               This option, while primarily a proxy for the ifconfig(8) command, is  designed  to
    485               simplify  TUN/TAP  tunnel  configuration  by providing a standard interface to the
    486               different ifconfig implementations on different platforms.
    487 
    488               --ifconfig parameters which are IP addresses can also be specified  as  a  DNS  or
    489               /etc/hosts file resolvable name.
    490 
    491               For  TAP  devices, --ifconfig should not be used if the TAP interface will be get‐
    492               ting an IP address lease from a DHCP server.
    493 
    494        --ifconfig-noexec
    495               Don't actually execute ifconfig/netsh commands, instead pass --ifconfig parameters
    496               to scripts using environmental variables.
    497 
    498        --ifconfig-nowarn
    499               Don't output an options consistency check warning if the --ifconfig option on this
    500               side of the connection doesn't match the remote side.  This  is  useful  when  you
    501               want  to  retain  the  overall benefits of the options consistency check (also see
    502               --disable-occ option) while only disabling the ifconfig component of the check.
    503 
    504               For example, if you have a configuration where the local host uses --ifconfig  but
    505               the remote host does not, use --ifconfig-nowarn on the local host.
    506 
    507               This  option  will  also  silence warnings about potential address conflicts which
    508               occasionally annoy more experienced users by triggering "false positive" warnings.
    509 
    510        --route network/IP [netmask] [gateway] [metric]
    511               Add route to routing table after connection is established.  Multiple  routes  can
    512               be  specified.   Routes  will be automatically torn down in reverse order prior to
    513               TUN/TAP device close.
    514 
    515               This option is intended as a convenience proxy for  the  route(8)  shell  command,
    516               while  at  the  same  time  providing portable semantics across OpenVPN's platform
    517               space.
    518 
    519               netmask default -- 255.255.255.255
    520 
    521               gateway default -- taken from --route-gateway or the second parameter to  --ifcon‐
    522               fig when --dev tun is specified.
    523 
    524               metric default -- taken from --route-metric otherwise 0.
    525 
    526               The  default  can  be  specified  by  leaving  an  option  blank  or setting it to
    527               "default".
    528 
    529               The network and gateway parameters can also be specified as a  DNS  or  /etc/hosts
    530               file resolvable name, or as one of three special keywords:
    531 
    532               vpn_gateway  -- The remote VPN endpoint address (derived either from --route-gate‐
    533               way or the second parameter to --ifconfig when --dev tun is specified).
    534 
    535               net_gateway -- The pre-existing IP default gateway, read from  the  routing  table
    536               (not supported on all OSes).
    537 
    538               remote_host -- The --remote address if OpenVPN is being run in client mode, and is
    539               undefined in server mode.
    540 
    541        --max-routes n
    542               Allow a maximum number of n --route options to be specified, either in  the  local
    543               configuration file, or pulled from an OpenVPN server.  By default, n=100.
    544 
    545        --route-gateway gw|'dhcp'
    546               Specify a default gateway gw for use with --route.
    547 
    548               If  dhcp is specified as the parameter, the gateway address will be extracted from
    549               a DHCP negotiation with the OpenVPN server-side LAN.
    550 
    551        --route-metric m
    552               Specify a default metric m for use with --route.
    553 
    554        --route-delay [n] [w]
    555               Delay n seconds (default=0) after connection establishment, before adding  routes.
    556               If  n  is  0,  routes will be added immediately upon connection establishment.  If
    557               --route-delay is omitted, routes will be added immediately  after  TUN/TAP  device
    558               open  and  --up script execution, before any --user or --group privilege downgrade
    559               (or --chroot execution.)
    560 
    561               This option is designed to be useful in scenarios where DHCP is used  to  set  tap
    562               adapter addresses.  The delay will give the DHCP handshake time to complete before
    563               routes are added.
    564 
    565               On Windows, --route-delay tries to be more intelligent by waiting w seconds  (w=30
    566               by default) for the TAP-Win32 adapter to come up before adding routes.
    567 
    568        --route-up cmd
    569               Execute shell command cmd after routes are added, subject to --route-delay.
    570 
    571               See  the  "Environmental Variables" section below for additional parameters passed
    572               as environmental variables.
    573 
    574               Note that cmd can be a shell command with multiple arguments.
    575 
    576        --route-noexec
    577               Don't add or remove routes  automatically.   Instead  pass  routes  to  --route-up
    578               script using environmental variables.
    579 
    580        --route-nopull
    581               When  used  with  --client  or  --pull, accept options pushed by server EXCEPT for
    582               routes.
    583 
    584               When used on the client, this option  effectively  bars  the  server  from  adding
    585               routes  to  the client's routing table, however note that this option still allows
    586               the server to set the TCP/IP properties of the client's TUN/TAP interface.
    587 
    588        --allow-pull-fqdn
    589               Allow client to pull DNS names from  server  (rather  than  being  limited  to  IP
    590               address) for --ifconfig, --route, and --route-gateway.
    591 
    592        --redirect-gateway flags...
    593               (Experimental)  Automatically  execute  routing  commands to cause all outgoing IP
    594               traffic to be redirected over the VPN.
    595 
    596               This option performs three steps:
    597 
    598               (1) Create a static route for the --remote address  which  forwards  to  the  pre-
    599               existing  default  gateway.   This  is  done so that (3) will not create a routing
    600               loop.
    601 
    602               (2) Delete the default gateway route.
    603 
    604               (3) Set the new default gateway to be the VPN  endpoint  address  (derived  either
    605               from --route-gateway or the second parameter to --ifconfig when --dev tun is spec‐
    606               ified).
    607 
    608               When the tunnel is torn down, all of the above steps  are  reversed  so  that  the
    609               original default route is restored.
    610 
    611               Option flags:
    612 
    613               local  --  Add the local flag if both OpenVPN servers are directly connected via a
    614               common subnet, such as with wireless.  The local flag will cause step 1  above  to
    615               be omitted.
    616 
    617               def1  --  Use  this  flag  to  override the default gateway by using 0.0.0.0/1 and
    618               128.0.0.0/1 rather than 0.0.0.0/0.  This has the benefit  of  overriding  but  not
    619               wiping out the original default gateway.
    620 
    621               bypass-dhcp  --  Add  a direct route to the DHCP server (if it is non-local) which
    622               bypasses the tunnel (Available on Windows clients, may not be  available  on  non-
    623               Windows clients).
    624 
    625               bypass-dns  --  Add  a  direct  route to the DNS server(s) (if they are non-local)
    626               which bypasses the tunnel (Available on Windows clients, may not be  available  on
    627               non-Windows clients).
    628 
    629               Using the def1 flag is highly recommended.
    630 
    631        --redirect-private [flags]
    632               Like  --redirect-gateway,  but omit actually changing the default gateway.  Useful
    633               when pushing private subnets.
    634 
    635        --link-mtu n
    636               Sets an upper bound on the size of UDP packets  which  are  sent  between  OpenVPN
    637               peers.  It's best not to set this parameter unless you know what you're doing.
    638 
    639        --tun-mtu n
    640               Take  the  TUN  device MTU to be n and derive the link MTU from it (default=1500).
    641               In most cases, you will probably want to leave this parameter set to  its  default
    642               value.
    643 
    644               The  MTU  (Maximum  Transmission Units) is the maximum datagram size in bytes that
    645               can be sent unfragmented over a particular network path.   OpenVPN  requires  that
    646               packets on the control or data channels be sent unfragmented.
    647 
    648               MTU problems often manifest themselves as connections which hang during periods of
    649               active usage.
    650 
    651               It's best to use the --fragment and/or --mssfix options to deal  with  MTU  sizing
    652               issues.
    653 
    654        --tun-mtu-extra n
    655               Assume  that  the  TUN/TAP  device  might  return as many as n bytes more than the
    656               --tun-mtu size on read.  This parameter defaults to 0,  which  is  sufficient  for
    657               most  TUN devices.  TAP devices may introduce additional overhead in excess of the
    658               MTU size, and a setting of 32 is the default when  TAP  devices  are  used.   This
    659               parameter  only  controls internal OpenVPN buffer sizing, so there is no transmis‐
    660               sion overhead associated with using a larger value.
    661 
    662        --mtu-disc type
    663               Should we do Path MTU discovery on TCP/UDP channel?  Only supported on  OSes  such
    664               as Linux that supports the necessary system call to set.
    665 
    666               'no' -- Never send DF (Don't Fragment) frames
    667               'maybe' -- Use per-route hints
    668               'yes' -- Always DF (Don't Fragment)
    669 
    670        --mtu-test
    671               To  empirically  measure  MTU  on connection startup, add the --mtu-test option to
    672               your configuration.  OpenVPN will send ping packets of various sizes to the remote
    673               peer and measure the largest packets which were successfully received.  The --mtu-
    674               test process normally takes about 3 minutes to complete.
    675 
    676        --fragment max
    677               Enable internal datagram fragmentation so that no UDP datagrams are sent which are
    678               larger than max bytes.
    679 
    680               The max parameter is interpreted in the same way as the --link-mtu parameter, i.e.
    681               the UDP packet size after encapsulation  overhead  has  been  added  in,  but  not
    682               including the UDP header itself.
    683 
    684               The  --fragment  option  only  makes  sense  when you are using the UDP protocol (
    685               --proto udp ).
    686 
    687               --fragment adds 4 bytes of overhead per datagram.
    688 
    689               See the --mssfix option below for an important related option to --fragment.
    690 
    691               It should also be noted that this option is not meant to replace UDP fragmentation
    692               at  the IP stack level.  It is only meant as a last resort when path MTU discovery
    693               is broken.  Using this option is less efficient than fixing path MTU discovery for
    694               your IP link and using native IP fragmentation instead.
    695 
    696               Having  said that, there are circumstances where using OpenVPN's internal fragmen‐
    697               tation capability may be your only option,  such  as  tunneling  a  UDP  multicast
    698               stream which requires fragmentation.
    699 
    700        --mssfix max
    701               Announce to TCP sessions running over the tunnel that they should limit their send
    702               packet sizes such that after OpenVPN has  encapsulated  them,  the  resulting  UDP
    703               packet  size that OpenVPN sends to its peer will not exceed max bytes. The default
    704               value is 1450.
    705 
    706               The max parameter is interpreted in the same way as the --link-mtu parameter, i.e.
    707               the  UDP  packet  size  after  encapsulation  overhead  has been added in, but not
    708               including the UDP header itself.
    709 
    710               The --mssfix option only makes sense when you are using the UDP protocol for Open‐
    711               VPN peer-to-peer communication, i.e.  --proto udp.
    712 
    713               --mssfix  and  --fragment can be ideally used together, where --mssfix will try to
    714               keep TCP from needing packet fragmentation in the first place, and if big  packets
    715               come  through  anyhow  (from protocols other than TCP), --fragment will internally
    716               fragment them.
    717 
    718               Both --fragment and --mssfix are designed to work around cases where Path MTU dis‐
    719               covery is broken on the network path between OpenVPN peers.
    720 
    721               The  usual symptom of such a breakdown is an OpenVPN connection which successfully
    722               starts, but then stalls during active usage.
    723 
    724               If --fragment and --mssfix are used together, --mssfix will take its  default  max
    725               parameter from the --fragment max option.
    726 
    727               Therefore,  one  could lower the maximum UDP packet size to 1300 (a good first try
    728               for solving MTU-related connection problems) with the following options:
    729 
    730               --tun-mtu 1500 --fragment 1300 --mssfix
    731 
    732        --sndbuf size
    733               Set the TCP/UDP socket send buffer size.  Currently defaults to 65536 bytes.
    734 
    735        --rcvbuf size
    736               Set the TCP/UDP socket receive buffer size.  Currently defaults to 65536 bytes.
    737 
    738        --socket-flags flags...
    739               Apply the given flags to the OpenVPN transport socket.  Currently, only  TCP_NODE‐
    740               LAY is supported.
    741 
    742               The  TCP_NODELAY  socket flag is useful in TCP mode, and causes the kernel to send
    743               tunnel packets immediately over the TCP connection without trying to group several
    744               smaller  packets into a larger packet.  This can result in a considerably improve‐
    745               ment in latency.
    746 
    747               This option is pushable from server to client, and should be used on  both  client
    748               and server for maximum effect.
    749 
    750        --txqueuelen n
    751               (Linux only) Set the TX queue length on the TUN/TAP interface.  Currently defaults
    752               to 100.
    753 
    754        --shaper n
    755               Limit bandwidth of outgoing tunnel data to n bytes per second on the TCP/UDP port.
    756               If  you  want  to  limit the bandwidth in both directions, use this option on both
    757               peers.
    758 
    759               OpenVPN uses the following algorithm to implement traffic shaping: Given a  shaper
    760               rate  of  n  bytes  per second, after a datagram write of b bytes is queued on the
    761               TCP/UDP port, wait a minimum of (b / n) seconds before queuing the next write.
    762 
    763               It should be noted that OpenVPN supports multiple tunnels  between  the  same  two
    764               peers,  allowing  you to construct full-speed and reduced bandwidth tunnels at the
    765               same time, routing low-priority data such as off-site  backups  over  the  reduced
    766               bandwidth tunnel, and other data over the full-speed tunnel.
    767 
    768               Also note that for low bandwidth tunnels (under 1000 bytes per second), you should
    769               probably use lower MTU values as well (see above), otherwise  the  packet  latency
    770               will  grow  so  large  as to trigger timeouts in the TLS layer and TCP connections
    771               running over the tunnel.
    772 
    773               OpenVPN allows n to be between 100 bytes/sec and 100 Mbytes/sec.
    774 
    775        --inactive n [bytes]
    776               Causes OpenVPN to exit after n seconds of inactivity on the  TUN/TAP  device.  The
    777               time  length  of inactivity is measured since the last incoming or outgoing tunnel
    778               packet.  The default value is 0 seconds, which disables this feature.
    779 
    780               If the optional bytes parameter is included, exit if less than bytes  of  combined
    781               in/out traffic are produced on the tun/tap device in n seconds.
    782 
    783               In  any  case, OpenVPN's internal ping packets (which are just keepalives) and TLS
    784               control packets are not considered "activity", nor are they counted as traffic, as
    785               they  are  used  internally  by  OpenVPN  and are not an indication of actual user
    786               activity.
    787 
    788        --ping n
    789               Ping remote over the TCP/UDP control channel if no packets have been sent  for  at
    790               least  n seconds (specify --ping on both peers to cause ping packets to be sent in
    791               both directions since OpenVPN ping packets are not echoed like IP  ping  packets).
    792               When  used  in  one  of  OpenVPN's  secure modes (where --secret, --tls-server, or
    793               --tls-client is specified), the ping packet will be cryptographically secure.
    794 
    795               This option has two intended uses:
    796 
    797               (1) Compatibility with stateful firewalls.  The periodic ping will ensure  that  a
    798               stateful firewall rule which allows OpenVPN UDP packets to pass will not time out.
    799 
    800               (2)  To provide a basis for the remote to test the existence of its peer using the
    801               --ping-exit option.
    802 
    803        --ping-exit n
    804               Causes OpenVPN to exit after n seconds pass without reception of a ping  or  other
    805               packet  from  remote.   This  option  can be combined with --inactive, --ping, and
    806               --ping-exit to create a two-tiered inactivity disconnect.
    807 
    808               For example,
    809 
    810               openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60
    811 
    812               when used on both peers will cause OpenVPN to exit within 60 seconds if  its  peer
    813               disconnects, but will exit after one hour if no actual tunnel data is exchanged.
    814 
    815        --ping-restart n
    816               Similar to --ping-exit, but trigger a SIGUSR1 restart after n seconds pass without
    817               reception of a ping or other packet from remote.
    818 
    819               This option is useful in cases where the remote peer has a dynamic IP address  and
    820               a  low-TTL  DNS  name  is  used  to  track  the IP address using a service such as
    821               http://dyndns.org/ + a dynamic DNS client such as ddclient.
    822 
    823               If the peer cannot be reached, a restart will be triggered, causing  the  hostname
    824               used with --remote to be re-resolved (if --resolv-retry is also specified).
    825 
    826               In server mode, --ping-restart, --inactive, or any other type of internally gener‐
    827               ated signal will always be applied to individual client instance objects, never to
    828               whole  server itself.  Note also in server mode that any internally generated sig‐
    829               nal which would normally cause a restart, will cause the deletion  of  the  client
    830               instance object instead.
    831 
    832               In  client  mode,  the  --ping-restart parameter is set to 120 seconds by default.
    833               This default will hold until the client pulls a replacement value from the server,
    834               based  on the --keepalive setting in the server configuration.  To disable the 120
    835               second default, set --ping-restart 0 on the client.
    836 
    837               See the signals section below for more information on SIGUSR1.
    838 
    839               Note that the behavior of SIGUSR1 can be modified by the --persist-tun, --persist-
    840               key, --persist-local-ip, and --persist-remote-ip options.
    841 
    842               Also note that --ping-exit and --ping-restart are mutually exclusive and cannot be
    843               used together.
    844 
    845        --keepalive n m
    846               A helper directive designed to simplify  the  expression  of  --ping  and  --ping-
    847               restart in server mode configurations.
    848 
    849               For example, --keepalive 10 60 expands as follows:
    850 
    851                    if mode server:
    852                      ping 10
    853                      ping-restart 120
    854                      push "ping 10"
    855                      push "ping-restart 60"
    856                    else
    857                      ping 10
    858                      ping-restart 60
    859 
    860        --ping-timer-rem
    861               Run  the --ping-exit / --ping-restart timer only if we have a remote address.  Use
    862               this option if you are starting  the  daemon  in  listen  mode  (i.e.  without  an
    863               explicit  --remote  peer),  and  you don't want to start clocking timeouts until a
    864               remote peer connects.
    865 
    866        --persist-tun
    867               Don't close and reopen TUN/TAP device or run up/down  scripts  across  SIGUSR1  or
    868               --ping-restart restarts.
    869 
    870               SIGUSR1 is a restart signal similar to SIGHUP, but which offers finer-grained con‐
    871               trol over reset options.
    872 
    873        --persist-key
    874               Don't re-read key files across SIGUSR1 or --ping-restart.
    875 
    876               This option can be combined with --user nobody to allow restarts triggered by  the
    877               SIGUSR1  signal.  Normally if you drop root privileges in OpenVPN, the daemon can‐
    878               not be restarted since it will now be unable to re-read protected key files.
    879 
    880               This option solves the problem by persisting keys across SIGUSR1 resets,  so  they
    881               don't need to be re-read.
    882 
    883        --persist-local-ip
    884               Preserve  initially  resolved  local  IP address and port number across SIGUSR1 or
    885               --ping-restart restarts.
    886 
    887        --persist-remote-ip
    888               Preserve most recently authenticated remote IP  address  and  port  number  across
    889               SIGUSR1 or --ping-restart restarts.
    890 
    891        --mlock
    892               Disable  paging  by calling the POSIX mlockall function.  Requires that OpenVPN be
    893               initially run as root (though OpenVPN can subsequently downgrade its UID using the
    894               --user option).
    895 
    896               Using  this  option ensures that key material and tunnel data are never written to
    897               disk due to virtual memory paging operations which occur under most modern operat‐
    898               ing  systems.   It ensures that even if an attacker was able to crack the box run‐
    899               ning OpenVPN, he would not be able to scan the system swap file to recover  previ‐
    900               ously  used  ephemeral  keys,  which are used for a period of time governed by the
    901               --reneg options (see below), then are discarded.
    902 
    903               The downside of using --mlock is that it will reduce the amount of physical memory
    904               available to other applications.
    905 
    906        --up cmd
    907               Shell command to run after successful TUN/TAP device open (pre --user UID change).
    908               The up script is useful for specifying route commands which route IP traffic  des‐
    909               tined  for private subnets which exist at the other end of the VPN connection into
    910               the tunnel.
    911 
    912               For --dev tun execute as:
    913 
    914               cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [ init | restart
    915               ]
    916 
    917               For --dev tap execute as:
    918 
    919               cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [ init | restart ]
    920 
    921               See  the  "Environmental Variables" section below for additional parameters passed
    922               as environmental variables.
    923 
    924               Note that cmd can be a shell command with multiple arguments, in  which  case  all
    925               OpenVPN-generated  arguments will be appended to cmd to build a command line which
    926               will be passed to the shell.
    927 
    928               Typically, cmd will run a script to add routes to the tunnel.
    929 
    930               Normally the up script is called after the TUN/TAP device is opened.  In this con‐
    931               text,  the  last command line parameter passed to the script will be init.  If the
    932               --up-restart option is also used, the up script will be  called  for  restarts  as
    933               well.   A  restart is considered to be a partial reinitialization of OpenVPN where
    934               the TUN/TAP instance is preserved  (the  --persist-tun  option  will  enable  such
    935               preservation).   A  restart can be generated by a SIGUSR1 signal, a --ping-restart
    936               timeout, or a connection reset when the TCP protocol is enabled with  the  --proto
    937               option.   If  a restart occurs, and --up-restart has been specified, the up script
    938               will be called with restart as the last parameter.
    939 
    940               The following standalone example shows how the --up script can be called  in  both
    941               an initialization and restart context.  (NOTE: for security reasons, don't run the
    942               following example unless UDP port 9999 is blocked by  your  firewall.   Also,  the
    943               example will run indefinitely, so you should abort with control-c).
    944 
    945               openvpn  --dev  tun  --port  9999 --verb 4 --ping-restart 10 --up 'echo up' --down
    946               'echo down' --persist-tun --up-restart
    947 
    948               Note that OpenVPN also provides the --ifconfig option  to  automatically  ifconfig
    949               the  TUN  device,  eliminating  the need to define an --up script, unless you also
    950               want to configure routes in the --up script.
    951 
    952               If --ifconfig is also specified, OpenVPN will pass the ifconfig local  and  remote
    953               endpoints  on the command line to the --up script so that they can be used to con‐
    954               figure routes such as:
    955 
    956               route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
    957 
    958        --up-delay
    959               Delay TUN/TAP open and possible --up script execution until after TCP/UDP  connec‐
    960               tion establishment with peer.
    961 
    962               In --proto udp mode, this option normally requires the use of --ping to allow con‐
    963               nection initiation to be sensed in the absence of tunnel  data,  since  UDP  is  a
    964               "connectionless" protocol.
    965 
    966               On  Windows,  this  option  will  delay the TAP-Win32 media state transitioning to
    967               "connected" until connection establishment, i.e. the receipt of the first  authen‐
    968               ticated packet from the peer.
    969 
    970        --down cmd
    971               Shell  command  to  run  after TUN/TAP device close (post --user UID change and/or
    972               --chroot ).  Called with the same parameters and environmental  variables  as  the
    973               --up option above.
    974 
    975               Note  that  if  you  reduce privileges by using --user and/or --group, your --down
    976               script will also run at reduced privilege.
    977 
    978        --down-pre
    979               Call --down cmd/script before, rather than after, TUN/TAP close.
    980 
    981        --up-restart
    982               Enable the --up and --down scripts to be called for restarts as  well  as  initial
    983               program start.  This option is described more fully above in the --up option docu‐
    984               mentation.
    985 
    986        --setenv name value
    987               Set a custom environmental variable name=value to pass to script.
    988 
    989        --setenv FORWARD_COMPATIBLE 1
    990               Relax config file syntax checking so that unknown directives will trigger a  warn‐
    991               ing  but not a fatal error, on the assumption that a given unknown directive might
    992               be valid in future OpenVPN versions.
    993 
    994               This option should be used with caution, as there are good  security  reasons  for
    995               having  OpenVPN  fail  if it detects problems in a config file.  Having said that,
    996               there are valid reasons for wanting new software features  to  gracefully  degrade
    997               when encountered by older software versions.
    998 
    999        --setenv-safe name value
    1000               Set a custom environmental variable OPENVPN_name=value to pass to script.
    1001 
    1002               This directive is designed to be pushed by the server to clients, and the prepend‐
    1003               ing of "OPENVPN_" to the environmental variable is a safety precaution to  prevent
    1004               a LD_PRELOAD style attack from a malicious or compromised server.
    1005 
    1006        --script-security level [method]
    1007               This  directive  offers policy-level control over OpenVPN's usage of external pro‐
    1008               grams and scripts.  Lower level values are more  restrictive,  higher  values  are
    1009               more permissive.  Settings for level:
    1010 
    1011               0 -- Strictly no calling of external programs.
    1012               1  --  (Default)  Only  call  built-in executables such as ifconfig, ip, route, or
    1013               netsh.
    1014               2 -- Allow calling of built-in executables and user-defined scripts.
    1015               3 -- Allow passwords to be passed to scripts via environmental  variables  (poten‐
    1016               tially unsafe).
    1017 
    1018               The  method  parameter  indicates  how  OpenVPN  should call external commands and
    1019               scripts.  Settings for method:
    1020 
    1021               execve -- (default) Use execve() function on Unix family OSes and  CreateProcess()
    1022               on Windows.
    1023               system  -- Use system() function (deprecated and less safe since the external pro‐
    1024               gram command line is subject to shell expansion).
    1025 
    1026               The --script-security option was introduced in OpenVPN 2.1_rc9.  For configuration
    1027               file compatibility with previous OpenVPN versions, use: --script-security 3 system
    1028 
    1029        --disable-occ
    1030               Don't  output  a  warning  message  if option inconsistencies are detected between
    1031               peers.  An example of an option inconsistency would be where one peer  uses  --dev
    1032               tun while the other peer uses --dev tap.
    1033 
    1034               Use  of  this  option is discouraged, but is provided as a temporary fix in situa‐
    1035               tions where a recent version of OpenVPN must connect to an old version.
    1036 
    1037        --user user
    1038               Change the user ID of the OpenVPN process to user after  initialization,  dropping
    1039               privileges  in  the  process.   This option is useful to protect the system in the
    1040               event that some hostile party was able to gain  control  of  an  OpenVPN  session.
    1041               Though  OpenVPN's security features make this unlikely, it is provided as a second
    1042               line of defense.
    1043 
    1044               By setting user to nobody or somebody similarly unprivileged,  the  hostile  party
    1045               would  be  limited  in what damage they could cause.  Of course once you take away
    1046               privileges, you cannot return them to an OpenVPN session.  This means,  for  exam‐
    1047               ple,  that if you want to reset an OpenVPN daemon with a SIGUSR1 signal (for exam‐
    1048               ple in response to a DHCP reset), you should make use of one or more of the --per‐
    1049               sist  options to ensure that OpenVPN doesn't need to execute any privileged opera‐
    1050               tions in order to restart (such as re-reading key files or running ifconfig on the
    1051               TUN device).
    1052 
    1053        --group group
    1054               Similar  to  the  --user  option,  this option changes the group ID of the OpenVPN
    1055               process to group after initialization.
    1056 
    1057        --cd dir
    1058               Change directory to dir prior to reading any files such  as  configuration  files,
    1059               key  files, scripts, etc.  dir should be an absolute path, with a leading "/", and
    1060               without any references to the current directory such as "." or "..".
    1061 
    1062               This option is useful when you are running OpenVPN in --daemon mode, and you  want
    1063               to consolidate all of your OpenVPN control files in one location.
    1064 
    1065        --chroot dir
    1066               Chroot  to  dir after initialization.  --chroot essentially redefines dir as being
    1067               the top level directory tree (/).  OpenVPN will therefore be unable to access  any
    1068               files outside this tree.  This can be desirable from a security standpoint.
    1069 
    1070               Since  the  chroot  operation  is delayed until after initialization, most OpenVPN
    1071               options that reference files will operate in a pre-chroot context.
    1072 
    1073               In many cases, the dir parameter can point to an empty directory, however  compli‐
    1074               cations  can  result when scripts or restarts are executed after the chroot opera‐
    1075               tion.
    1076 
    1077        --setcon context
    1078               Apply SELinux context after initialization. This essentially provides the  ability
    1079               to  restrict  OpenVPN's  rights to only network I/O operations, thanks to SELinux.
    1080               This goes further than --user and --chroot in that those two,  while  being  great
    1081               security  features,  unfortunately  do not protect against privilege escalation by
    1082               exploitation of a vulnerable system call. You can of course combine all three, but
    1083               please note that since setcon requires access to /proc you will have to provide it
    1084               inside the chroot directory (e.g. with mount --bind).
    1085 
    1086               Since the setcon operation is delayed until after initialization, OpenVPN  can  be
    1087               restricted  to  just network-related system calls, whereas by applying the context
    1088               before startup (such as the OpenVPN one provided in the  SELinux  Reference  Poli‐
    1089               cies) you will have to allow many things required only during initialization.
    1090 
    1091               Like  with  chroot, complications can result when scripts or restarts are executed
    1092               after the setcon operation, which is why you  should  really  consider  using  the
    1093               --persist-key and --persist-tun options.
    1094 
    1095        --daemon [progname]
    1096               Become  a  daemon  after  all initialization functions are completed.  This option
    1097               will cause all message and error output to be sent to the  syslog  file  (such  as
    1098               /var/log/messages),  except for the output of shell scripts and ifconfig commands,
    1099               which will go to /dev/null unless otherwise redirected.   The  syslog  redirection
    1100               occurs  immediately  at the point that --daemon is parsed on the command line even
    1101               though the daemonization point occurs later.  If  one  of  the  --log  options  is
    1102               present, it will supercede syslog redirection.
    1103 
    1104               The  optional  progname parameter will cause OpenVPN to report its program name to
    1105               the system logger as progname.  This can be useful in linking OpenVPN messages  in
    1106               the  syslog  file  with  specific tunnels.  When unspecified, progname defaults to
    1107               "openvpn".
    1108 
    1109               When OpenVPN is run with the --daemon option, it will try to  delay  daemonization
    1110               until  the  majority  of  initialization functions which are capable of generating
    1111               fatal errors are complete.  This means that initialization scripts  can  test  the
    1112               return  status  of the openvpn command for a fairly reliable indication of whether
    1113               the command has correctly initialized and  entered  the  packet  forwarding  event
    1114               loop.
    1115 
    1116               In  OpenVPN, the vast majority of errors which occur after initialization are non-
    1117               fatal.
    1118 
    1119        --syslog [progname]
    1120               Direct log output to system logger, but do not  become  a  daemon.   See  --daemon
    1121               directive above for description of progname parameter.
    1122 
    1123        --passtos
    1124               Set the TOS field of the tunnel packet to what the payload's TOS is.
    1125 
    1126        --inetd [wait|nowait] [progname]
    1127               Use this option when OpenVPN is being run from the inetd or xinetd(8) server.
    1128 
    1129               The  wait/nowait  option  must  match what is specified in the inetd/xinetd config
    1130               file.  The nowait mode can only be used with --proto tcp-server.  The  default  is
    1131               wait.   The nowait mode can be used to instantiate the OpenVPN daemon as a classic
    1132               TCP server, where client connection requests are serviced on a single port number.
    1133               For  additional  information  on  this kind of configuration, see the OpenVPN FAQ:
    1134               http://openvpn.net/faq.html#oneport
    1135 
    1136               This option precludes the use of --daemon, --local, or --remote.  Note  that  this
    1137               option causes message and error output to be handled in the same way as the --dae‐
    1138               mon option.  The optional progname parameter is also handled exactly as in  --dae‐
    1139               mon.
    1140 
    1141               Also  note that in wait mode, each OpenVPN tunnel requires a separate TCP/UDP port
    1142               and a separate inetd or xinetd entry.  See the OpenVPN 1.x HOWTO for an example on
    1143               using OpenVPN with xinetd: http://openvpn.net/1xhowto.html
    1144 
    1145        --log file
    1146               Output logging messages to file, including output to stdout/stderr which is gener‐
    1147               ated by called scripts.  If file already exists it will be truncated.  This option
    1148               takes  effect immediately when it is parsed in the command line and will supercede
    1149               syslog output if --daemon or --inetd is also specified.  This option is persistent
    1150               over  the  entire  course  of  an  OpenVPN  instantiation and will not be reset by
    1151               SIGHUP, SIGUSR1, or --ping-restart.
    1152 
    1153               Note that on Windows, when OpenVPN is started as  a  service,  logging  occurs  by
    1154               default without the need to specify this option.
    1155 
    1156        --log-append file
    1157               Append  logging  messages  to  file.   If file does not exist, it will be created.
    1158               This option behaves exactly like --log except that it appends to rather than trun‐
    1159               cating the log file.
    1160 
    1161        --suppress-timestamps
    1162               Avoid  writing  timestamps  to  log  messages,  even  when they otherwise would be
    1163               prepended. In particular, this applies to log messages sent to stdout.
    1164 
    1165        --writepid file
    1166               Write OpenVPN's main process ID to file.
    1167 
    1168        --nice n
    1169               Change process priority after initialization ( n greater than 0 is lower priority,
    1170               n less than zero is higher priority).
    1171 
    1172        --fast-io
    1173               (Experimental)   Optimize   TUN/TAP/UDP   I/O   writes   by  avoiding  a  call  to
    1174               poll/epoll/select prior to the write operation.  The purpose of such a call  would
    1175               normally  be  to  block  until  the device or socket is ready to accept the write.
    1176               Such blocking is unnecessary on some platforms which don't support write  blocking
    1177               on UDP sockets or TUN/TAP devices.  In such cases, one can optimize the event loop
    1178               by avoiding the poll/epoll/select call, improving CPU efficiency by 5% to 10%.
    1179 
    1180               This option can only be used on non-Windows systems, when --proto  udp  is  speci‐
    1181               fied, and when --shaper is NOT specified.
    1182 
    1183        --multihome
    1184               Configure a multi-homed UDP server.  This option can be used when OpenVPN has been
    1185               configured to listen on all interfaces, and will attempt to bind  client  sessions
    1186               to  the  interface  on  which packets are being received, so that outgoing packets
    1187               will be sent out of the same interface.  Note that this option  is  only  relevant
    1188               for UDP servers and currently is only implemented on Linux.
    1189 
    1190               Note:  clients  connecting  to a --multihome server should always use the --nobind
    1191               option.
    1192 
    1193        --echo [parms...]
    1194               Echo parms to log output.
    1195 
    1196               Designed to be used to send messages to a controlling application which is receiv‐
    1197               ing the OpenVPN log output.
    1198 
    1199        --remap-usr1 signal
    1200               Control whether internally or externally generated SIGUSR1 signals are remapped to
    1201               SIGHUP (restart without persisting state) or SIGTERM (exit).
    1202 
    1203               signal can be set to "SIGHUP" or "SIGTERM".  By default, no remapping occurs.
    1204 
    1205        --verb n
    1206               Set output verbosity to n (default=1).  Each level shows all info from the  previ‐
    1207               ous levels.  Level 3 is recommended if you want a good summary of what's happening
    1208               without being swamped by output.
    1209 
    1210               0 -- No output except fatal errors.
    1211               1 to 4 -- Normal usage range.
    1212               5 -- Output R and W characters to the console for  each  packet  read  and  write,
    1213               uppercase is used for TCP/UDP packets and lowercase is used for TUN/TAP packets.
    1214               6  to  11  -- Debug info range (see errlevel.h for additional information on debug
    1215               levels).
    1216 
    1217        --status file [n]
    1218               Write operational status to file every n seconds.
    1219 
    1220               Status can also be written to the syslog by sending a SIGUSR2 signal.
    1221 
    1222        --status-version [n]
    1223               Choose the status file format version number.  Currently n can be 1, 2, or  3  and
    1224               defaults to 1.
    1225 
    1226        --mute n
    1227               Log  at most n consecutive messages in the same category.  This is useful to limit
    1228               repetitive logging of similar message types.
    1229 
    1230        --comp-lzo [mode]
    1231               Use fast LZO compression -- may add up to 1 byte  per  packet  for  incompressible
    1232               data.  mode may be "yes", "no", or "adaptive" (default).
    1233 
    1234               In  a  server mode setup, it is possible to selectively turn compression on or off
    1235               for individual clients.
    1236 
    1237               First, make sure the client-side config file enables selective compression by hav‐
    1238               ing  at least one --comp-lzo directive, such as --comp-lzo no.  This will turn off
    1239               compression by default, but allow a future  directive  push  from  the  server  to
    1240               dynamically change the on/off/adaptive setting.
    1241 
    1242               Next  in  a  --client-config-dir  file,  specify  the  compression setting for the
    1243               client, for example:
    1244 
    1245                   comp-lzo yes
    1246                   push "comp-lzo yes"
    1247 
    1248               The first line sets the comp-lzo setting for the server side of the link, the sec‐
    1249               ond sets the client side.
    1250 
    1251        --comp-noadapt
    1252               When used in conjunction with --comp-lzo, this option will disable OpenVPN's adap‐
    1253               tive compression  algorithm.   Normally,  adaptive  compression  is  enabled  with
    1254               --comp-lzo.
    1255 
    1256               Adaptive  compression  tries  to  optimize  the  case  where  you have compression
    1257               enabled, but you are  sending  predominantly  uncompressible  (or  pre-compressed)
    1258               packets  over  the tunnel, such as an FTP or rsync transfer of a large, compressed
    1259               file.  With adaptive compression, OpenVPN will periodically sample the compression
    1260               process  to  measure  its  efficiency.   If the data being sent over the tunnel is
    1261               already compressed, the compression efficiency will be very low, triggering  open‐
    1262               vpn to disable compression for a period of time until the next re-sample test.
    1263 
    1264        --management IP port [pw-file]
    1265               Enable a TCP server on IP:port to handle daemon management functions.  pw-file, if
    1266               specified, is a password file (password on first line) or "stdin" to  prompt  from
    1267               standard  input.   The  password  provided will set the password which TCP clients
    1268               will need to provide in order to access management functions.
    1269 
    1270               The management interface can also listen on a unix domain socket, for those  plat‐
    1271               forms that support it.  To use a unix domain socket, specify the unix socket path‐
    1272               name in place of IP and set port to 'unix'.  While the default behavior is to cre‐
    1273               ate  a  unix  domain socket that may be connected to by any process, the --manage‐
    1274               ment-client-user and --management-client-group directives can be used to  restrict
    1275               access.
    1276 
    1277               The management interface provides a special mode where the TCP management link can
    1278               operate over the tunnel itself.  To enable this mode, set IP =  "tunnel".   Tunnel
    1279               mode  will  cause  the  management interface to listen for a TCP connection on the
    1280               local VPN address of the TUN/TAP interface.
    1281 
    1282               While the management port is designed for programmatic control of OpenVPN by other
    1283               applications, it is possible to telnet to the port, using a telnet client in "raw"
    1284               mode.  Once connected, type "help" for a list of commands.
    1285 
    1286               For detailed documentation  on  the  management  interface,  see  the  management-
    1287               notes.txt file in the management folder of the OpenVPN source distribution.
    1288 
    1289               It  is  strongly  recommended  that IP be set to 127.0.0.1 (localhost) to restrict
    1290               accessibility of the management server to local clients.
    1291 
    1292        --management-client
    1293               Management interface will connect as a TCP client to IP:port specified  by  --man‐
    1294               agement rather than listen as a TCP server.
    1295 
    1296        --management-query-passwords
    1297               Query  management  channel  for  private  key  password and --auth-user-pass user‐
    1298               name/password.  Only query the management  channel  for  inputs  which  ordinarily
    1299               would have been queried from the console.
    1300 
    1301        --management-forget-disconnect
    1302               Make OpenVPN forget passwords when management session disconnects.
    1303 
    1304               This  directive  does not affect the --http-proxy username/password.  It is always
    1305               cached.
    1306 
    1307        --management-hold
    1308               Start OpenVPN in a hibernating state, until a client of the  management  interface
    1309               explicitly starts it with the hold release command.
    1310 
    1311        --management-signal
    1312               Send  SIGUSR1 signal to OpenVPN if management session disconnects.  This is useful
    1313               when you wish to disconnect an OpenVPN session on user logoff.
    1314 
    1315        --management-log-cache n
    1316               Cache the most recent n lines of log file history  for  usage  by  the  management
    1317               channel.
    1318 
    1319        --management-client-auth
    1320               Gives management interface client the responsibility to authenticate clients after
    1321               their client certificate has been verified.  See management-notes.txt  in  OpenVPN
    1322               distribution for detailed notes.
    1323 
    1324        --management-client-pf
    1325               Management interface clients must specify a packet filter file for each connecting
    1326               client.  See management-notes.txt in OpenVPN distribution for detailed notes.
    1327 
    1328        --management-client-user u
    1329               When the management interface is listening on a unix  domain  socket,  only  allow
    1330               connections from user u.
    1331 
    1332        --management-client-group g
    1333               When  the  management  interface  is listening on a unix domain socket, only allow
    1334               connections from group g.
    1335 
    1336        --plugin module-pathname [init-string]
    1337               Load plug-in module from the file module-pathname, passing init-string as an argu‐
    1338               ment to the module initialization function.  Multiple plugin modules may be loaded
    1339               into one OpenVPN process.
    1340 
    1341               For more information and examples on how to build OpenVPN plug-in modules, see the
    1342               README file in the plugin folder of the OpenVPN source distribution.
    1343 
    1344               If  you  are  using an RPM install of OpenVPN, see /usr/share/openvpn/plugin.  The
    1345               documentation is in doc and the actual plugin modules are in lib.
    1346 
    1347               Multiple plugin modules can be cascaded, and modules can be used  in  tandem  with
    1348               scripts.   The  modules  will  be  called  by  OpenVPN  in the order that they are
    1349               declared in the config file.  If both a plugin and script are configured  for  the
    1350               same  callback,  the  script  will be called last.  If the return code of the mod‐
    1351               ule/script controls an authentication function  (such  as  tls-verify,  auth-user-
    1352               pass-verify,  or client-connect), then every module and script must return success
    1353               (0) in order for the connection to be authenticated.
    1354 
    1355    Server Mode
    1356        Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is supported,  and  can  be
    1357        enabled  with  the --mode server option.  In server mode, OpenVPN will listen on a single
    1358        port for incoming client connections.  All client connections will be  routed  through  a
    1359        single tun or tap interface.  This mode is designed for scalability and should be able to
    1360        support hundreds or even thousands of clients on  sufficiently  fast  hardware.   SSL/TLS
    1361        authentication must be used in this mode.
    1362 
    1363        --server network netmask
    1364               A  helper  directive  designed  to  simplify the configuration of OpenVPN's server
    1365               mode.  This directive will set up an OpenVPN server which will allocate  addresses
    1366               to clients out of the given network/netmask.  The server itself will take the ".1"
    1367               address of the given network for use as the  server-side  endpoint  of  the  local
    1368               TUN/TAP interface.
    1369 
    1370               For example, --server 10.8.0.0 255.255.255.0 expands as follows:
    1371 
    1372                    mode server
    1373                    tls-server
    1374                    push "topology [topology]"
    1375 
    1376                    if dev tun AND (topology == net30 OR topology == p2p):
    1377                      ifconfig 10.8.0.1 10.8.0.2
    1378                      if !nopool:
    1379                        ifconfig-pool 10.8.0.4 10.8.0.251
    1380                      route 10.8.0.0 255.255.255.0
    1381                      if client-to-client:
    1382                        push "route 10.8.0.0 255.255.255.0"
    1383                      else if topology == net30:
    1384                        push "route 10.8.0.1"
    1385 
    1386                    if dev tap OR (dev tun AND topology == subnet):
    1387                      ifconfig 10.8.0.1 255.255.255.0
    1388                      if !nopool:
    1389                        ifconfig-pool 10.8.0.2 10.8.0.254 255.255.255.0
    1390                      push "route-gateway 10.8.0.1"
    1391 
    1392               Don't use --server if you are ethernet bridging.  Use --server-bridge instead.
    1393 
    1394        --server-bridge gateway netmask pool-start-IP pool-end-IP
    1395 
    1396        --server-bridge ['nogw']
    1397 
    1398               A  helper directive similar to --server which is designed to simplify the configu‐
    1399               ration of OpenVPN's server mode in ethernet bridging configurations.
    1400 
    1401               If --server-bridge is used without any parameters, it  will  enable  a  DHCP-proxy
    1402               mode,  where  connecting  OpenVPN clients will receive an IP address for their TAP
    1403               adapter from the DHCP server running on the OpenVPN server-side  LAN.   Note  that
    1404               only  clients that support the binding of a DHCP client with the TAP adapter (such
    1405               as Windows) can support this mode.  The optional nogw  flag  (advanced)  indicates
    1406               that gateway information should not be pushed to the client.
    1407 
    1408               To  configure  ethernet bridging, you must first use your OS's bridging capability
    1409               to bridge the TAP interface with the ethernet  NIC  interface.   For  example,  on
    1410               Linux this is done with the brctl tool, and with Windows XP it is done in the Net‐
    1411               work Connections Panel by selecting the ethernet and TAP adapters and right-click‐
    1412               ing on "Bridge Connections".
    1413 
    1414               Next  you you must manually set the IP/netmask on the bridge interface.  The gate‐
    1415               way and netmask parameters to --server-bridge can be set to either the  IP/netmask
    1416               of  the  bridge  interface, or the IP/netmask of the default gateway/router on the
    1417               bridged subnet.
    1418 
    1419               Finally, set aside a IP range in the bridged subnet, denoted by pool-start-IP  and
    1420               pool-end-IP, for OpenVPN to allocate to connecting clients.
    1421 
    1422               For example, server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 10.8.0.254 expands as
    1423               follows:
    1424 
    1425                   mode server
    1426                   tls-server
    1427 
    1428                   ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0
    1429                   push "route-gateway 10.8.0.4"
    1430 
    1431               In another example, --server-bridge (without parameters) expands as follows:
    1432 
    1433                   mode server
    1434                   tls-server
    1435 
    1436                   push "route-gateway dhcp"
    1437 
    1438               Or --server-bridge nogw expands as follows:
    1439 
    1440                   mode server
    1441                   tls-server
    1442 
    1443        --push option
    1444               Push a config file option back to the client  for  remote  execution.   Note  that
    1445               option  must be enclosed in double quotes ("").  The client must specify --pull in
    1446               its config file.  The set of options which can be pushed is limited by both feasi‐
    1447               bility  and  security.  Some options such as those which would execute scripts are
    1448               banned, since they would effectively allow a compromised server to  execute  arbi‐
    1449               trary  code  on the client.  Other options such as TLS or MTU parameters cannot be
    1450               pushed because the client needs to know them before the connection to  the  server
    1451               can be initiated.
    1452 
    1453               This is a partial list of options which can currently be pushed: --route, --route-
    1454               gateway, --route-delay, --redirect-gateway, --ip-win32, --dhcp-option, --inactive,
    1455               --ping,   --ping-exit,  --ping-restart,  --setenv,  --persist-key,  --persist-tun,
    1456               --echo, --comp-lzo, --socket-flags, --sndbuf, --rcvbuf
    1457 
    1458        --push-reset
    1459               Don't inherit the global push list for a specific client instance.   Specify  this
    1460               option  in a client-specific context such as with a --client-config-dir configura‐
    1461               tion file.  This option will ignore --push  options  at  the  global  config  file
    1462               level.
    1463 
    1464        --disable
    1465               Disable a particular client (based on the common name) from connecting.  Don't use
    1466               this option to disable a client due to key or  password  compromise.   Use  a  CRL
    1467               (certificate revocation list) instead (see the --crl-verify option).
    1468 
    1469               This  option  must be associated with a specific client instance, which means that
    1470               it must be specified either in a client instance config file  using  --client-con‐
    1471               fig-dir or dynamically generated using a --client-connect script.
    1472 
    1473        --ifconfig-pool start-IP end-IP [netmask]
    1474               Set  aside  a  pool  of subnets to be dynamically allocated to connecting clients,
    1475               similar to a DHCP server.  For tun-style tunnels, each client will be given a  /30
    1476               subnet  (for interoperability with Windows clients).  For tap-style tunnels, indi‐
    1477               vidual addresses will be allocated, and the optional netmask parameter  will  also
    1478               be pushed to clients.
    1479 
    1480 
    1481        --ifconfig-pool-persist file [seconds]
    1482               Persist/unpersist  ifconfig-pool data to file, at seconds intervals (default=600),
    1483               as well as on program startup and shutdown.
    1484 
    1485               The goal of this option is to provide  a  long-term  association  between  clients
    1486               (denoted  by  their  common name) and the virtual IP address assigned to them from
    1487               the ifconfig-pool.  Maintaining  a  long-term  association  is  good  for  clients
    1488               because it allows them to effectively use the --persist-tun option.
    1489 
    1490               file is a comma-delimited ASCII file, formatted as <Common-Name>,<IP-address>.
    1491 
    1492               If  seconds  =  0, file will be treated as read-only.  This is useful if you would
    1493               like to treat file as a configuration file.
    1494 
    1495               Note that the entries in this file are treated by  OpenVPN  as  suggestions  only,
    1496               based  on  past  associations  between  a common name and IP address.  They do not
    1497               guarantee that the given common name will always receive the given IP address.  If
    1498               you want guaranteed assignment, use --ifconfig-push
    1499 
    1500        --ifconfig-pool-linear
    1501               Modifies  the  --ifconfig-pool  directive  to  allocate  individual  TUN interface
    1502               addresses for clients rather than /30 subnets.  NOTE:  This option is incompatible
    1503               with Windows clients.
    1504 
    1505               This  option  is  deprecated,  and should be replaced with --topology p2p which is
    1506               functionally equivalent.
    1507 
    1508        --ifconfig-push local remote-netmask
    1509               Push virtual IP  endpoints  for  client  tunnel,  overriding  the  --ifconfig-pool
    1510               dynamic allocation.
    1511 
    1512               The parameters local and remote-netmask are set according to the --ifconfig direc‐
    1513               tive which you want to execute on the client machine to configure the  remote  end
    1514               of  the  tunnel.   Note  that the parameters local and remote-netmask are from the
    1515               perspective of the client, not the server.  They may be DNS names rather  than  IP
    1516               addresses, in which case they will be resolved on the server at the time of client
    1517               connection.
    1518 
    1519               This option must be associated with a specific client instance, which  means  that
    1520               it  must  be specified either in a client instance config file using --client-con‐
    1521               fig-dir or dynamically generated using a --client-connect script.
    1522 
    1523               Remember also to include a --route directive in the main OpenVPN config file which
    1524               encloses  local,  so that the kernel will know to route it to the server's TUN/TAP
    1525               interface.
    1526 
    1527               OpenVPN's internal client IP address selection algorithm works as follows:
    1528 
    1529               1 -- Use --client-connect script generated file for static IP (first choice).
    1530               2 -- Use --client-config-dir file for static IP (next choice).
    1531               3 -- Use --ifconfig-pool allocation for dynamic IP (last choice).
    1532 
    1533        --iroute network [netmask]
    1534               Generate an internal route to a specific client. The netmask parameter,  if  omit‐
    1535               ted, defaults to 255.255.255.255.
    1536 
    1537               This directive can be used to route a fixed subnet from the server to a particular
    1538               client, regardless of where the client is connecting from.  Remember that you must
    1539               also  add  the  route  to  the  system routing table as well (such as by using the
    1540               --route directive).  The reason why two routes are  needed  is  that  the  --route
    1541               directive  routes  the  packet  from  the kernel to OpenVPN.  Once in OpenVPN, the
    1542               --iroute directive routes to the specific client.
    1543 
    1544               This option must be specified either  in  a  client  instance  config  file  using
    1545               --client-config-dir or dynamically generated using a --client-connect script.
    1546 
    1547               The  --iroute directive also has an important interaction with --push "route ...".
    1548               --iroute essentially defines a subnet which is owned by a  particular  client  (we
    1549               will call this client A).  If you would like other clients to be able to reach A's
    1550               subnet, you can use --push "route ..."  together with --client-to-client to effect
    1551               this.  In order for all clients to see A's subnet, OpenVPN must push this route to
    1552               all clients EXCEPT for A, since the subnet is already owned by A.  OpenVPN  accom‐
    1553               plishes  this  by  not  not  pushing  a route to a client if it matches one of the
    1554               client's iroutes.
    1555 
    1556        --client-to-client
    1557               Because the OpenVPN server mode handles multiple clients through a single  tun  or
    1558               tap  interface,  it  is  effectively  a router.  The --client-to-client flag tells
    1559               OpenVPN to internally route  client-to-client  traffic  rather  than  pushing  all
    1560               client-originating traffic to the TUN/TAP interface.
    1561 
    1562               When  this option is used, each client will "see" the other clients which are cur‐
    1563               rently connected.  Otherwise, each client will only see  the  server.   Don't  use
    1564               this option if you want to firewall tunnel traffic using custom, per-client rules.
    1565 
    1566        --duplicate-cn
    1567               Allow  multiple clients with the same common name to concurrently connect.  In the
    1568               absence of this option, OpenVPN will disconnect a client instance upon  connection
    1569               of a new client having the same common name.
    1570 
    1571        --client-connect script
    1572               Run  script  on  client  connection.   The script is passed the common name and IP
    1573               address of the just-authenticated client as environmental variables (see  environ‐
    1574               mental  variable  section  below).   The  script  is also passed the pathname of a
    1575               freshly created temporary file as $1 (i.e. the first command line argument), to be
    1576               used  by  the  script to pass dynamically generated config file directives back to
    1577               OpenVPN.
    1578 
    1579               If the script wants to generate a dynamic config file to be applied on the  server
    1580               when the client connects, it should write it to the file named by $1.
    1581 
    1582               See  the --client-config-dir option below for options which can be legally used in
    1583               a dynamically generated config file.
    1584 
    1585               Note that the return value of script is significant.  If script returns a non-zero
    1586               error status, it will cause the client to be disconnected.
    1587 
    1588        --client-disconnect
    1589               Like  --client-connect but called on client instance shutdown.  Will not be called
    1590               unless the --client-connect script and plugins (if defined) were previously called
    1591               on this instance with successful (0) status returns.
    1592 
    1593               The  exception  to  this  rule is if the --client-disconnect script or plugins are
    1594               cascaded, and at least one client-connect function  succeeded,  then  ALL  of  the
    1595               client-disconnect  functions  for  scripts  and  plugins  will be called on client
    1596               instance object deletion, even in cases where some of the  related  client-connect
    1597               functions returned an error status.
    1598 
    1599        --client-config-dir dir
    1600               Specify a directory dir for custom client config files.  After a connecting client
    1601               has been authenticated, OpenVPN will look in this directory for a file having  the
    1602               same name as the client's X509 common name.  If a matching file exists, it will be
    1603               opened and parsed for client-specific configuration options.  If no matching  file
    1604               is  found,  OpenVPN  will  instead  try  to  open  and parse a default file called
    1605               "DEFAULT", which may be provided but is not required. Note that the  configuration
    1606               files must be readable by the OpenVPN process after it has dropped it's root priv‐
    1607               ileges.
    1608 
    1609               This file can specify a fixed IP address for a given client using --ifconfig-push,
    1610               as well as fixed subnets owned by the client using --iroute.
    1611 
    1612               One of the useful properties of this option is that it allows client configuration
    1613               files to be conveniently created, edited, or removed while  the  server  is  live,
    1614               without needing to restart the server.
    1615 
    1616               The  following  options  are  legal  in a client-specific context: --push, --push-
    1617               reset, --iroute, --ifconfig-push, and --config.
    1618 
    1619        --ccd-exclusive
    1620               Require, as a  condition  of  authentication,  that  a  connecting  client  has  a
    1621               --client-config-dir file.
    1622 
    1623        --tmp-dir dir
    1624               Specify a directory dir for temporary files.  This directory will be used by open‐
    1625               vpn processes and script to communicate temporary data with openvpn main  process.
    1626               Note  that  the  directory  must  be  writable by the OpenVPN process after it has
    1627               dropped it's root privileges.
    1628 
    1629               This directory will be used by in the following cases:
    1630 
    1631               * --client-connect scripts to dynamically generate  client-specific  configuration
    1632               files.
    1633 
    1634               *  OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY  plugin hook to return success/failure via
    1635               auth_control_file when using deferred auth method
    1636 
    1637               * OPENVPN_PLUGIN_ENABLE_PF plugin hook to pass filtering rules via pf_file
    1638 
    1639        --hash-size r v
    1640               Set the size of the real address hash table to r and the virtual address table  to
    1641               v.  By default, both tables are sized at 256 buckets.
    1642 
    1643        --bcast-buffers n
    1644               Allocate n buffers for broadcast datagrams (default=256).
    1645 
    1646        --tcp-queue-limit n
    1647               Maximum number of output packets queued before TCP (default=64).
    1648 
    1649               When OpenVPN is tunneling data from a TUN/TAP device to a remote client over a TCP
    1650               connection, it is possible that the TUN/TAP device might produce data at a  faster
    1651               rate  than  the  TCP  connection  can  support.  When the number of output packets
    1652               queued before sending to the TCP socket reaches this limit for a given client con‐
    1653               nection, OpenVPN will start to drop outgoing packets directed at this client.
    1654 
    1655        --tcp-nodelay
    1656               This  macro sets the TCP_NODELAY socket flag on the server as well as pushes it to
    1657               connecting clients.  The TCP_NODELAY flag disables  the  Nagle  algorithm  on  TCP
    1658               sockets  causing  packets  to  be transmitted immediately with low latency, rather
    1659               than waiting a short period of time in order to aggregate several packets  into  a
    1660               larger  containing packet.  In VPN applications over TCP, TCP_NODELAY is generally
    1661               a good latency optimization.
    1662 
    1663               The macro expands as follows:
    1664 
    1665                    if mode server:
    1666                      socket-flags TCP_NODELAY
    1667                      push "socket-flags TCP_NODELAY"
    1668 
    1669        --max-clients n
    1670               Limit server to a maximum of n concurrent clients.
    1671 
    1672        --max-routes-per-client n
    1673               Allow a maximum of n internal routes per client (default=256).  This  is  designed
    1674               to  help  contain DoS attacks where an authenticated client floods the server with
    1675               packets appearing to come from many unique MAC addresses, forcing  the  server  to
    1676               deplete  virtual memory as its internal routing table expands.  This directive can
    1677               be used in a --client-config-dir file  or  auto-generated  by  a  --client-connect
    1678               script to override the global value for a particular client.
    1679 
    1680               Note  that this directive affects OpenVPN's internal routing table, not the kernel
    1681               routing table.
    1682 
    1683        --connect-freq n sec
    1684               Allow a maximum of n new connections  per  sec  seconds  from  clients.   This  is
    1685               designed  to  contain  DoS attacks which flood the server with connection requests
    1686               using certificates which will ultimately fail to authenticate.
    1687 
    1688               This is an imperfect solution however, because in a real DoS scenario,  legitimate
    1689               connections might also be refused.
    1690 
    1691               For  the  best  protection against DoS attacks in server mode, use --proto udp and
    1692               --tls-auth.
    1693 
    1694        --learn-address cmd
    1695               Run script or shell command cmd to validate client virtual addresses or routes.
    1696 
    1697               cmd will be executed with 3 parameters:
    1698 
    1699               [1] operation -- "add", "update", or "delete" based on whether or not the  address
    1700               is being added to, modified, or deleted from OpenVPN's internal routing table.
    1701               [2]  address  --  The  address  being  learned  or unlearned.  This can be an IPv4
    1702               address such as "198.162.10.14", an IPv4 subnet such as "198.162.10.0/24",  or  an
    1703               ethernet MAC address (when --dev tap is being used) such as "00:FF:01:02:03:04".
    1704               [3]  common  name -- The common name on the certificate associated with the client
    1705               linked to this address.  Only  present  for  "add"  or  "update"  operations,  not
    1706               "delete".
    1707 
    1708               On  "add"  or  "update"  methods, if the script returns a failure code (non-zero),
    1709               OpenVPN will reject the address and will not modify its internal routing table.
    1710 
    1711               Normally, the cmd script will use the information provided above to set  appropri‐
    1712               ate  firewall  entries  on  the VPN TUN/TAP interface.  Since OpenVPN provides the
    1713               association between virtual IP or MAC address and the client's authenticated  com‐
    1714               mon  name,  it  allows a user-defined script to configure firewall access policies
    1715               with regard to the client's high-level common name,  rather  than  the  low  level
    1716               client virtual addresses.
    1717 
    1718        --auth-user-pass-verify script method
    1719               Require  the  client  to  provide  a  username/password (possibly in addition to a
    1720               client certificate) for authentication.
    1721 
    1722               OpenVPN will execute script as a shell command to validate  the  username/password
    1723               provided by the client.
    1724 
    1725               If  method  is  set  to "via-env", OpenVPN will call script with the environmental
    1726               variables username and password set to the username/password strings  provided  by
    1727               the  client.   Be  aware that this method is insecure on some platforms which make
    1728               the environment of a process publicly visible to other unprivileged processes.
    1729 
    1730               If method is set to "via-file", OpenVPN will write the username  and  password  to
    1731               the  first two lines of a temporary file.  The filename will be passed as an argu‐
    1732               ment to script, and the file will be automatically deleted by  OpenVPN  after  the
    1733               script returns.  The location of the temporary file is controlled by the --tmp-dir
    1734               option, and will default to the current directory if unspecified.   For  security,
    1735               consider  setting  --tmp-dir  to  a  volatile  storage medium such as /dev/shm (if
    1736               available) to prevent the username/password file from touching the hard drive.
    1737 
    1738               The script should examine the username and password, returning a success exit code
    1739               (0)  if  the  client's authentication request is to be accepted, or a failure code
    1740               (1) to reject the client.
    1741 
    1742               This directive is designed to enable a plugin-style interface for extending  Open‐
    1743               VPN's authentication capabilities.
    1744 
    1745               To  protect  against  a  client  passing a maliciously formed username or password
    1746               string, the username string must consist only of these  characters:  alphanumeric,
    1747               underbar  ('_'), dash ('-'), dot ('.'), or at ('@').  The password string can con‐
    1748               sist of any printable characters except for CR or LF.  Any illegal  characters  in
    1749               either the username or password string will be converted to underbar ('_').
    1750 
    1751               Care  must  be taken by any user-defined scripts to avoid creating a security vul‐
    1752               nerability in the way that these strings are handled.  Never use these strings  in
    1753               such a way that they might be escaped or evaluated by a shell interpreter.
    1754 
    1755               For  a  sample  script  that performs PAM authentication, see sample-scripts/auth-
    1756               pam.pl in the OpenVPN source distribution.
    1757 
    1758        --opt-verify
    1759               Clients that connect with options that are incompatible with those of  the  server
    1760               will be disconnected.
    1761 
    1762               Options  that  will be compared for compatibility include dev-type, link-mtu, tun-
    1763               mtu, proto, tun-ipv6, ifconfig, comp-lzo, fragment, keydir, cipher, auth, keysize,
    1764               secret, no-replay, no-iv, tls-auth, key-method, tls-server, and tls-client.
    1765 
    1766               This option requires that --disable-occ NOT be used.
    1767 
    1768        --auth-user-pass-optional
    1769               Allow  connections  by clients that do not specify a username/password.  Normally,
    1770               when --auth-user-pass-verify  or  --management-client-auth  is  specified  (or  an
    1771               authentication  plugin  module), the OpenVPN server daemon will require connecting
    1772               clients to specify a username and password.  This option makes the submission of a
    1773               username/password  by  clients  optional,  passing the responsibility to the user-
    1774               defined authentication module/script to accept or deny the client based  on  other
    1775               factors  (such  as  the  setting of X509 certificate fields).  When this option is
    1776               used, and a connecting client does  not  submit  a  username/password,  the  user-
    1777               defined  authentication  module/script will see the username and password as being
    1778               set to empty strings ("").  The authentication module/script MUST  have  logic  to
    1779               detect this condition and respond accordingly.
    1780 
    1781        --client-cert-not-required
    1782               Don't require client certificate, client will authenticate using username/password
    1783               only.  Be aware that using this directive is less secure than  requiring  certifi‐
    1784               cates from all clients.
    1785 
    1786               If  you  use this directive, the entire responsibility of authentication will rest
    1787               on your --auth-user-pass-verify script, so keep in mind that bugs in  your  script
    1788               could potentially compromise the security of your VPN.
    1789 
    1790               If  you  don't use this directive, but you also specify an --auth-user-pass-verify
    1791               script, then OpenVPN will perform double authentication.  The  client  certificate
    1792               verification  AND the --auth-user-pass-verify script will need to succeed in order
    1793               for a client to be authenticated and accepted onto the VPN.
    1794 
    1795        --username-as-common-name
    1796               For --auth-user-pass-verify authentication, use the authenticated username as  the
    1797               common name, rather than the common name from the client cert.
    1798 
    1799        --no-name-remapping
    1800               Allow  Common  Name,  X509  Subject, and username strings to include any printable
    1801               character including space, but excluding control characters such as tab,  newline,
    1802               and carriage-return.
    1803 
    1804               By  default,  OpenVPN  will  remap any character other than alphanumeric, underbar
    1805               ('_'), dash ('-'), dot ('.'), and slash ('/') to underbar ('_').  The X509 Subject
    1806               string  as returned by the tls_id environmental variable, can additionally contain
    1807               colon (':') or equal ('=').
    1808 
    1809               While name remapping is performed for security reasons to reduce  the  possibility
    1810               of introducing string expansion security vulnerabilities in user-defined authenti‐
    1811               cation scripts, this option is provided for those cases where it is  desirable  to
    1812               disable the remapping feature.  Don't use this option unless you know what you are
    1813               doing!
    1814 
    1815        --port-share host port
    1816               When run in TCP server mode, share the OpenVPN port with another application, such
    1817               as  an  HTTPS server.  If OpenVPN senses a connection to its port which is using a
    1818               non-OpenVPN protocol, it will proxy the connection to  the  server  at  host:port.
    1819               Currently  only designed to work with HTTP/HTTPS, though it would be theoretically
    1820               possible to extend to other protocols such as ssh.
    1821 
    1822               Not implemented on Windows.
    1823 
    1824    Client Mode
    1825        Use client mode when connecting to an OpenVPN server which has --server, --server-bridge,
    1826        or --mode server in it's configuration.
    1827 
    1828        --client
    1829               A  helper  directive  designed  to  simplify the configuration of OpenVPN's client
    1830               mode.  This directive is equivalent to:
    1831 
    1832                    pull
    1833                    tls-client
    1834 
    1835        --pull This option must be used on a client which is connecting to a multi-client server.
    1836               It  indicates  to OpenVPN that it should accept options pushed by the server, pro‐
    1837               vided they are part of the legal set of pushable options  (note  that  the  --pull
    1838               option is implied by --client ).
    1839 
    1840               In  particular,  --pull  allows  the  server  to push routes to the client, so you
    1841               should not use --pull or --client in situations where you don't trust  the  server
    1842               to have control over the client's routing table.
    1843 
    1844        --auth-user-pass [up]
    1845               Authenticate  with  server using username/password.  up is a file containing user‐
    1846               name/password on 2 lines (Note: OpenVPN will only read passwords from a file if it
    1847               has  been built with the --enable-password-save configure option, or on Windows by
    1848               defining ENABLE_PASSWORD_SAVE in win/settings.in).
    1849 
    1850               If up is omitted, username/password will be prompted from the console.
    1851 
    1852               The server configuration must specify an --auth-user-pass-verify script to  verify
    1853               the username/password provided by the client.
    1854 
    1855        --auth-retry type
    1856               Controls how OpenVPN responds to username/password verification errors such as the
    1857               client-side response to an AUTH_FAILED message from  the  server  or  verification
    1858               failure of the private key password.
    1859 
    1860               Normally  used  to prevent auth errors from being fatal on the client side, and to
    1861               permit username/password requeries in case of error.
    1862 
    1863               An AUTH_FAILED message is generated by the server if the client fails --auth-user-
    1864               pass  authentication,  or  if  the  server-side --client-connect script returns an
    1865               error status when the client tries to connect.
    1866 
    1867               type can be one of:
    1868 
    1869               none -- Client will exit with a fatal error (this is the default).
    1870               nointeract -- Client will retry the connection without requerying for  an  --auth-
    1871               user-pass username/password.  Use this option for unattended clients.
    1872               interact  --  Client will requery for an --auth-user-pass username/password and/or
    1873               private key password before attempting a reconnection.
    1874 
    1875               Note that while this option cannot be pushed, it can be controlled from  the  man‐
    1876               agement interface.
    1877 
    1878        --server-poll-timeout n
    1879               when polling possible remote servers to connect to in a round-robin fashion, spend
    1880               no more than n seconds waiting for a response before trying the next server.
    1881 
    1882        --explicit-exit-notify [n]
    1883               In UDP client mode or point-to-point mode, send server/peer an  exit  notification
    1884               if  tunnel  is  restarted  or  OpenVPN  process  is  exited.   In  client mode, on
    1885               exit/restart, this option will tell the server to  immediately  close  its  client
    1886               instance  object  rather  than waiting for a timeout.  The n parameter (default=1)
    1887               controls the maximum number of attempts that the client will  try  to  resend  the
    1888               exit  notification  message.   OpenVPN will not send any exit notifications unless
    1889               this option is enabled.
    1890 
    1891    Data Channel Encryption Options:
    1892        These options are meaningful for both Static & TLS-negotiated key modes (must be compati‐
    1893        ble between peers).
    1894 
    1895        --secret file [direction]
    1896               Enable Static Key encryption mode (non-TLS).  Use pre-shared secret file which was
    1897               generated with --genkey.
    1898 
    1899               The optional direction parameter enables the use of 4  distinct  keys  (HMAC-send,
    1900               cipher-encrypt,  HMAC-receive,  cipher-decrypt),  so that each data flow direction
    1901               has a different set of HMAC and cipher keys.  This has a number of desirable secu‐
    1902               rity  properties  including  eliminating  certain  kinds of DoS and message replay
    1903               attacks.
    1904 
    1905               When the direction parameter is omitted, 2 keys are used bidirectionally, one  for
    1906               HMAC and the other for encryption/decryption.
    1907 
    1908               The  direction parameter should always be complementary on either side of the con‐
    1909               nection, i.e. one side should use "0" and the other should use "1", or both  sides
    1910               should omit it altogether.
    1911 
    1912               The direction parameter requires that file contains a 2048 bit key.  While pre-1.5
    1913               versions of OpenVPN generate 1024 bit key files, any version of OpenVPN which sup‐
    1914               ports  the  direction  parameter,  will  also support 2048 bit key file generation
    1915               using the --genkey option.
    1916 
    1917               Static key encryption mode has certain advantages, the primary being ease of  con‐
    1918               figuration.
    1919 
    1920               There  are  no  certificates or certificate authorities or complicated negotiation
    1921               handshakes and protocols.  The only requirement is that you  have  a  pre-existing
    1922               secure  channel  with  your  peer  (such as ssh ) to initially copy the key.  This
    1923               requirement, along with the fact that your key never changes unless  you  manually
    1924               generate  a  new one, makes it somewhat less secure than TLS mode (see below).  If
    1925               an attacker manages to steal your key, everything that was ever encrypted with  it
    1926               is compromised.  Contrast that to the perfect forward secrecy features of TLS mode
    1927               (using Diffie Hellman key exchange), where even if an attacker was able  to  steal
    1928               your private key, he would gain no information to help him decrypt past sessions.
    1929 
    1930               Another  advantageous  aspect  of Static Key encryption mode is that it is a hand‐
    1931               shake-free protocol without any distinguishing signature or  feature  (such  as  a
    1932               header  or  protocol handshake sequence) that would mark the ciphertext packets as
    1933               being generated by OpenVPN.  Anyone eavesdropping on the wire  would  see  nothing
    1934               but random-looking data.
    1935 
    1936        --auth alg
    1937               Authenticate  packets  with HMAC using message digest algorithm alg.  (The default
    1938               is SHA1 ).  HMAC is a commonly used message authentication  algorithm  (MAC)  that
    1939               uses  a data string, a secure hash algorithm, and a key, to produce a digital sig‐
    1940               nature.
    1941 
    1942               OpenVPN's usage of HMAC is to first encrypt a  packet,  then  HMAC  the  resulting
    1943               ciphertext.
    1944 
    1945               In  static-key encryption mode, the HMAC key is included in the key file generated
    1946               by --genkey.  In TLS mode, the  HMAC  key  is  dynamically  generated  and  shared
    1947               between  peers  via  the TLS control channel.  If OpenVPN receives a packet with a
    1948               bad HMAC it will drop the packet.  HMAC usually adds 16 or 20  bytes  per  packet.
    1949               Set alg=none to disable authentication.
    1950 
    1951               For           more           information           on           HMAC           see
    1952               http://www.cs.ucsd.edu/users/mihir/papers/hmac.html
    1953 
    1954        --cipher alg
    1955               Encrypt packets with cipher algorithm alg.  The default is BF-CBC, an abbreviation
    1956               for  Blowfish in Cipher Block Chaining mode.  Blowfish has the advantages of being
    1957               fast, very secure, and allowing key sizes of up to 448 bits.  Blowfish is designed
    1958               to be used in situations where keys are changed infrequently.
    1959 
    1960               For more information on blowfish, see http://www.counterpane.com/blowfish.html
    1961 
    1962               To  see  other  ciphers  that  are  available with OpenVPN, use the --show-ciphers
    1963               option.
    1964 
    1965               OpenVPN supports the CBC, CFB, and OFB cipher modes, however  CBC  is  recommended
    1966               and CFB and OFB should be considered advanced modes.
    1967 
    1968               Set alg=none to disable encryption.
    1969 
    1970        --keysize n
    1971               Size  of  cipher  key in bits (optional).  If unspecified, defaults to cipher-spe‐
    1972               cific default.  The --show-ciphers option (see below) shows all available  OpenSSL
    1973               ciphers,  their  default  key sizes, and whether the key size can be changed.  Use
    1974               care in changing a cipher's default key size.  Many ciphers have not  been  exten‐
    1975               sively  cryptanalyzed with non-standard key lengths, and a larger key may offer no
    1976               real guarantee of greater security, or may even reduce security.
    1977 
    1978        --prng alg [nsl]
    1979               (Advanced) For PRNG (Pseudo-random number generator),  use  digest  algorithm  alg
    1980               (default=sha1),  and set nsl (default=16) to the size in bytes of the nonce secret
    1981               length (between 16 and 64).
    1982 
    1983               Set alg=none to disable the PRNG and use the OpenSSL RAND_bytes  function  instead
    1984               for all of OpenVPN's pseudo-random number needs.
    1985 
    1986        --engine [engine-name]
    1987               Enable OpenSSL hardware-based crypto engine functionality.
    1988 
    1989               If engine-name is specified, use a specific crypto engine.  Use the --show-engines
    1990               standalone option to list the crypto engines which are supported by OpenSSL.
    1991 
    1992        --no-replay
    1993               (Advanced) Disable OpenVPN's protection against replay attacks.   Don't  use  this
    1994               option  unless  you  are  prepared  to  make  a  tradeoff of greater efficiency in
    1995               exchange for less security.
    1996 
    1997               OpenVPN provides datagram replay protection by default.
    1998 
    1999               Replay protection is accomplished by tagging each outgoing datagram with an  iden‐
    2000               tifier  that  is  guaranteed  to  be unique for the key being used.  The peer that
    2001               receives the datagram will check for the uniqueness of  the  identifier.   If  the
    2002               identifier  was  already  received  in  a previous datagram, OpenVPN will drop the
    2003               packet.  Replay protection is important to defeat attacks  such  as  a  SYN  flood
    2004               attack, where the attacker listens in the wire, intercepts a TCP SYN packet (iden‐
    2005               tifying it by the context in which it occurs in relation to other  packets),  then
    2006               floods the receiving peer with copies of this packet.
    2007 
    2008               OpenVPN's  replay  protection is implemented in slightly different ways, depending
    2009               on the key management mode you have selected.
    2010 
    2011               In Static Key mode or when using an CFB or OFB mode cipher, OpenVPN uses a 64  bit
    2012               unique identifier that combines a time stamp with an incrementing sequence number.
    2013 
    2014               When using TLS mode for key exchange and a CBC cipher mode, OpenVPN uses only a 32
    2015               bit sequence number without a time stamp, since OpenVPN can guarantee the  unique‐
    2016               ness  of this value for each key.  As in IPSec, if the sequence number is close to
    2017               wrapping back to zero, OpenVPN will trigger a new key exchange.
    2018 
    2019               To check for replays, OpenVPN uses the sliding window algorithm used by IPSec.
    2020 
    2021        --replay-window n [t]
    2022               Use a replay protection sliding-window of size n and a time window of t seconds.
    2023 
    2024               By default n is 64 (the IPSec default) and t is 15 seconds.
    2025 
    2026               This option is only relevant in  UDP  mode,  i.e.   when  either  --proto  udp  is
    2027               specifed, or no --proto option is specified.
    2028 
    2029               When  OpenVPN  tunnels  IP packets over UDP, there is the possibility that packets
    2030               might be dropped or delivered out of order.  Because OpenVPN, like IPSec, is  emu‐
    2031               lating the physical network layer, it will accept an out-of-order packet sequence,
    2032               and will deliver such packets in the same order they were received to  the  TCP/IP
    2033               protocol stack, provided they satisfy several constraints.
    2034 
    2035               (a) The packet cannot be a replay (unless --no-replay is specified, which disables
    2036               replay protection altogether).
    2037 
    2038               (b) If a packet arrives out of order, it will only be accepted if  the  difference
    2039               between  its  sequence  number  and the highest sequence number received so far is
    2040               less than n.
    2041 
    2042               (c) If a packet arrives out of order, it will only be accepted if  it  arrives  no
    2043               later than t seconds after any packet containing a higher sequence number.
    2044 
    2045               If you are using a network link with a large pipeline (meaning that the product of
    2046               bandwidth and latency is high), you may want to use a larger value for n.   Satel‐
    2047               lite links in particular often require this.
    2048 
    2049               If  you run OpenVPN at --verb 4, you will see the message "Replay-window backtrack
    2050               occurred [x]" every time the maximum  sequence  number  backtrack  seen  thus  far
    2051               increases.  This can be used to calibrate n.
    2052 
    2053               There  is some controversy on the appropriate method of handling packet reordering
    2054               at the security layer.
    2055 
    2056               Namely, to what extent should the security layer protect the encapsulated protocol
    2057               from  attacks  which  masquerade as the kinds of normal packet loss and reordering
    2058               that occur over IP networks?
    2059 
    2060               The IPSec and OpenVPN approach is to allow  packet  reordering  within  a  certain
    2061               fixed sequence number window.
    2062 
    2063               OpenVPN  adds  to  the  IPSec model by limiting the window size in time as well as
    2064               sequence space.
    2065 
    2066               OpenVPN also adds TCP transport as an option (not offered by IPSec) in which  case
    2067               OpenVPN  can adopt a very strict attitude towards message deletion and reordering:
    2068               Don't allow it.  Since TCP guarantees reliability, any packet loss  or  reordering
    2069               event can be assumed to be an attack.
    2070 
    2071               In this sense, it could be argued that TCP tunnel transport is preferred when tun‐
    2072               neling non-IP or UDP application protocols which might be vulnerable to a  message
    2073               deletion or reordering attack which falls within the normal operational parameters
    2074               of IP networks.
    2075 
    2076               So I would make the statement that one should never tunnel a  non-IP  protocol  or
    2077               UDP  application  protocol over UDP, if the protocol might be vulnerable to a mes‐
    2078               sage deletion or reordering attack that falls within the normal operating  parame‐
    2079               ters  of what is to be expected from the physical IP layer.  The problem is easily
    2080               fixed by simply using TCP as the VPN transport layer.
    2081 
    2082        --mute-replay-warnings
    2083               Silence the output of replay warnings, which are a common false alarm on WiFi net‐
    2084               works.   This  option preserves the security of the replay protection code without
    2085               the verbosity associated with warnings about duplicate packets.
    2086 
    2087        --replay-persist file
    2088               Persist replay-protection state across sessions using file to save and reload  the
    2089               state.
    2090 
    2091               This option will strengthen protection against replay attacks, especially when you
    2092               are using OpenVPN in a dynamic context (such as with --inetd)  when  OpenVPN  ses‐
    2093               sions are frequently started and stopped.
    2094 
    2095               This option will keep a disk copy of the current replay protection state (i.e. the
    2096               most recent packet timestamp and sequence number received from the  remote  peer),
    2097               so that if an OpenVPN session is stopped and restarted, it will reject any replays
    2098               of packets which were already received by the prior session.
    2099 
    2100               This option only makes sense when replay protection is enabled (the  default)  and
    2101               you  are  using  either  --secret (shared-secret key mode) or TLS mode with --tls-
    2102               auth.
    2103 
    2104        --no-iv
    2105               (Advanced) Disable OpenVPN's use of IV (cipher initialization vector).  Don't  use
    2106               this  option  unless  you are prepared to make a tradeoff of greater efficiency in
    2107               exchange for less security.
    2108 
    2109               OpenVPN uses an IV by default, and requires it for CFB and OFB cipher modes (which
    2110               are totally insecure without it).  Using an IV is important for security when mul‐
    2111               tiple messages are being encrypted/decrypted with the same key.
    2112 
    2113               IV is implemented differently depending on the cipher mode used.
    2114 
    2115               In CBC mode, OpenVPN uses a pseudo-random IV for each packet.
    2116 
    2117               In CFB/OFB mode, OpenVPN uses a unique sequence number and time stamp as  the  IV.
    2118               In  fact,  in CFB/OFB mode, OpenVPN uses a datagram space-saving optimization that
    2119               uses the unique identifier for datagram replay protection as the IV.
    2120 
    2121        --test-crypto
    2122               Do a self-test of OpenVPN's crypto options by encrypting and decrypting test pack‐
    2123               ets  using  the data channel encryption options specified above.  This option does
    2124               not require a peer to function, and therefore can be specified  without  --dev  or
    2125               --remote.
    2126 
    2127               The typical usage of --test-crypto would be something like this:
    2128 
    2129               openvpn --test-crypto --secret key
    2130 
    2131               or
    2132 
    2133               openvpn --test-crypto --secret key --verb 9
    2134 
    2135               This option is very useful to test OpenVPN after it has been ported to a new plat‐
    2136               form, or to isolate problems in the compiler, OpenSSL crypto library, or OpenVPN's
    2137               crypto code.  Since it is a self-test mode, problems with encryption and authenti‐
    2138               cation can be debugged independently of network and tunnel issues.
    2139 
    2140    TLS Mode Options:
    2141        TLS mode is the most powerful crypto mode of OpenVPN in both  security  and  flexibility.
    2142        TLS  mode  works  by  establishing control and data channels which are multiplexed over a
    2143        single TCP/UDP port.  OpenVPN initiates a TLS session over the control channel  and  uses
    2144        it  to exchange cipher and HMAC keys to protect the data channel.  TLS mode uses a robust
    2145        reliability layer over the UDP connection for all control  channel  communication,  while
    2146        the data channel, over which encrypted tunnel data passes, is forwarded without any medi‐
    2147        ation.  The result is the best of both worlds: a fast data channel that forwards over UDP
    2148        with  only  the  overhead  of encrypt, decrypt, and HMAC functions, and a control channel
    2149        that provides all of the security features of TLS, including certificate-based  authenti‐
    2150        cation and Diffie Hellman forward secrecy.
    2151 
    2152        To  use  TLS  mode, each peer that runs OpenVPN should have its own local certificate/key
    2153        pair ( --cert and --key ), signed by the root certificate which is specified in --ca.
    2154 
    2155        When two OpenVPN peers connect, each presents its local certificate to the  other.   Each
    2156        peer  will  then  check that its partner peer presented a certificate which was signed by
    2157        the master root certificate as specified in --ca.
    2158 
    2159        If that check on both peers succeeds, then the TLS negotiation will succeed, both OpenVPN
    2160        peers will exchange temporary session keys, and the tunnel will begin passing data.
    2161 
    2162        The  OpenVPN distribution contains a set of scripts for managing RSA certificates & keys,
    2163        located in the easy-rsa subdirectory.
    2164 
    2165        The easy-rsa package is also rendered in web form here: http://openvpn.net/easyrsa.html
    2166 
    2167        --tls-server
    2168               Enable TLS and assume server role during TLS  handshake.   Note  that  OpenVPN  is
    2169               designed  as  a  peer-to-peer application.  The designation of client or server is
    2170               only for the purpose of negotiating the TLS control channel.
    2171 
    2172        --tls-client
    2173               Enable TLS and assume client role during TLS handshake.
    2174 
    2175        --ca file
    2176               Certificate authority (CA) file in .pem format, also referred to as the root  cer‐
    2177               tificate.   This  file can have multiple certificates in .pem format, concatenated
    2178               together.  You can construct your own certificate authority certificate  and  pri‐
    2179               vate key by using a command such as:
    2180 
    2181               openssl req -nodes -new -x509 -keyout ca.key -out ca.crt
    2182 
    2183               Then edit your openssl.cnf file and edit the certificate variable to point to your
    2184               new root certificate ca.crt.
    2185 
    2186               For testing purposes only, the OpenVPN distribution includes a sample CA  certifi‐
    2187               cate (ca.crt).  Of course you should never use the test certificates and test keys
    2188               distributed with OpenVPN in a production environment, since by virtue of the  fact
    2189               that they are distributed with OpenVPN, they are totally insecure.
    2190 
    2191        --capath dir
    2192               Directory  containing trusted certificates (CAs and CRLs).  Available with OpenSSL
    2193               version >= 0.9.7 dev.
    2194 
    2195        --dh file
    2196               File containing Diffie Hellman parameters in  .pem  format  (required  for  --tls-
    2197               server only). Use
    2198 
    2199               openssl dhparam -out dh1024.pem 1024
    2200 
    2201               to  generate your own, or use the existing dh1024.pem file included with the Open‐
    2202               VPN distribution.  Diffie Hellman parameters may be considered public.
    2203 
    2204        --cert file
    2205               Local peer's signed certificate in .pem format -- must be signed by a  certificate
    2206               authority whose certificate is in --ca file.  Each peer in an OpenVPN link running
    2207               in TLS mode should have its own certificate and private key  file.   In  addition,
    2208               each  certificate  should  have  been signed by the key of a certificate authority
    2209               whose public key resides in the --ca certificate authority file.  You  can  easily
    2210               make  your  own certificate authority (see above) or pay money to use a commercial
    2211               service such as thawte.com (in which case you  will  be  helping  to  finance  the
    2212               world's second space tourist :).  To generate a certificate, you can use a command
    2213               such as:
    2214 
    2215               openssl req -nodes -new -keyout mycert.key -out mycert.csr
    2216 
    2217               If your certificate authority private key lives on another machine, copy the  cer‐
    2218               tificate signing request (mycert.csr) to this other machine (this can be done over
    2219               an insecure channel such as email).  Now sign the certificate with a command  such
    2220               as:
    2221 
    2222               openssl ca -out mycert.crt -in mycert.csr
    2223 
    2224               Now  copy  the certificate (mycert.crt) back to the peer which initially generated
    2225               the .csr file (this can be over a public medium).  Note that the openssl  ca  com‐
    2226               mand  reads  the  location of the certificate authority key from its configuration
    2227               file such as /usr/share/ssl/openssl.cnf -- note also that for certificate  author‐
    2228               ity functions, you must set up the files index.txt (may be empty) and serial (ini‐
    2229               tialize to 01 ).
    2230 
    2231        --key file
    2232               Local peer's private key in .pem format.  Use the private key which was  generated
    2233               when you built your peer's certificate (see -cert file above).
    2234 
    2235        --pkcs12 file
    2236               Specify  a PKCS #12 file containing local private key, local certificate, and root
    2237               CA certificate.  This option can be used instead of --ca, --cert, and --key.
    2238 
    2239        --pkcs11-cert-private [0|1]...
    2240               Set if access to certificate  object  should  be  performed  after  login.   Every
    2241               provider has its own setting.
    2242 
    2243        --pkcs11-id name
    2244               Specify  the  serialized  certificate  id  to be used. The id can be gotten by the
    2245               standalone --show-pkcs11-ids option.
    2246 
    2247        --pkcs11-id-management
    2248               Acquire PKCS#11 id from management interface. In this case a NEED-STR  'pkcs11-id-
    2249               request'  real-time message will be triggered, application may use pkcs11-id-count
    2250               command to retrieve available number of certificates, and pkcs11-id-get command to
    2251               retrieve certificate id and certificate body.
    2252 
    2253        --pkcs11-pin-cache seconds
    2254               Specify  how many seconds the PIN can be cached, the default is until the token is
    2255               removed.
    2256 
    2257        --pkcs11-protected-authentication [0|1]...
    2258               Use PKCS#11 protected authentication path, useful for biometric and external  key‐
    2259               pad devices.  Every provider has its own setting.
    2260 
    2261        --pkcs11-providers provider...
    2262               Specify  a  RSA  Security  Inc.  PKCS #11 Cryptographic Token Interface (Cryptoki)
    2263               providers to load.  This  option  can  be  used  instead  of  --cert,  --key,  and
    2264               --pkcs12.
    2265 
    2266        --pkcs11-private-mode mode...
    2267               Specify which method to use in order to perform private key operations.  A differ‐
    2268               ent mode can be specified for each provider.  Mode is encoded as hex  number,  and
    2269               can be a mask one of the following:
    2270 
    2271               0 (default) -- Try to determind automatically.
    2272               1 -- Use sign.
    2273               2 -- Use sign recover.
    2274               4 -- Use decrypt.
    2275               8 -- Use unwrap.
    2276 
    2277        --cryptoapicert select-string
    2278               Load  the  certificate  and  private key from the Windows Certificate System Store
    2279               (Windows Only).
    2280 
    2281               Use this option instead of --cert and --key.
    2282 
    2283               This makes it possible to use any smart card, supported by Windows, but  also  any
    2284               kind of certificate, residing in the Cert Store, where you have access to the pri‐
    2285               vate key.  This option has been tested with a  couple  of  different  smart  cards
    2286               (GemSAFE, Cryptoflex, and Swedish Post Office eID) on the client side, and also an
    2287               imported PKCS12 software certificate on the server side.
    2288 
    2289               To select a certificate, based on a substring search in the certificate's subject:
    2290 
    2291               cryptoapicert "SUBJ:Peter Runestig"
    2292 
    2293               To select a certificate, based on certificate's thumbprint:
    2294 
    2295               cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."
    2296 
    2297               The thumbprint hex string can easily be copy-and-pasted from the Windows  Certifi‐
    2298               cate Store GUI.
    2299 
    2300 
    2301        --key-method m
    2302               Use  data  channel  key  negotiation  method m.  The key method must match on both
    2303               sides of the connection.
    2304 
    2305               After OpenVPN negotiates a TLS session, a new set of keys for protecting the  tun‐
    2306               nel data channel is generated and exchanged over the TLS session.
    2307 
    2308               In  method 1 (the default for OpenVPN 1.x), both sides generate random encrypt and
    2309               HMAC-send keys which are forwarded to the other host over the TLS channel.
    2310 
    2311               In method 2, (the default for OpenVPN 2.0) the  client  generates  a  random  key.
    2312               Both  client  and  server also generate some random seed material.  All key source
    2313               material is exchanged over the TLS channel. The actual keys  are  generated  using
    2314               the TLS PRF function, taking source entropy from both client and server.  Method 2
    2315               is designed to closely parallel the key generation process used by TLS 1.0.
    2316 
    2317               Note that in TLS mode, two separate levels of keying occur:
    2318 
    2319               (1) The TLS connection is initially negotiated, with both sides of the  connection
    2320               producing certificates and verifying the certificate (or other authentication info
    2321               provided) of the other side.  The --key-method parameter has  no  effect  on  this
    2322               process.
    2323 
    2324               (2)  After  the  TLS  connection is established, the tunnel session keys are sepa‐
    2325               rately negotiated over the existing secure TLS channel.  Here, --key-method deter‐
    2326               mines the derivation of the tunnel session keys.
    2327 
    2328        --tls-cipher l
    2329               A  list  l  of allowable TLS ciphers delimited by a colon (":").  If you require a
    2330               high level of security, you may want to set this parameter manually, to prevent  a
    2331               version  rollback  attack  where  a  man-in-the-middle attacker tries to force two
    2332               peers to negotiate to the lowest level of security they both support.  Use --show-
    2333               tls to see a list of supported TLS ciphers.
    2334 
    2335        --tls-timeout n
    2336               Packet  retransmit timeout on TLS control channel if no acknowledgment from remote
    2337               within n seconds (default=2).  When OpenVPN sends a control packet to its peer, it
    2338               will  expect  to receive an acknowledgement within n seconds or it will retransmit
    2339               the packet, subject to a TCP-like exponential backoff algorithm.   This  parameter
    2340               only  applies  to  control  channel  packets.   Data  channel packets (which carry
    2341               encrypted tunnel data) are never  acknowledged,  sequenced,  or  retransmitted  by
    2342               OpenVPN  because  the  higher level network protocols running on top of the tunnel
    2343               such as TCP expect this role to be left to them.
    2344 
    2345        --reneg-bytes n
    2346               Renegotiate data channel key after n bytes sent or received (disabled by default).
    2347               OpenVPN  allows  the  lifetime  of  a  key  to  be  expressed as a number of bytes
    2348               encrypted/decrypted, a number of packets, or a number of seconds.  A key renegoti‐
    2349               ation will be forced if any of these three criteria are met by either peer.
    2350 
    2351        --reneg-pkts n
    2352               Renegotiate  data  channel  key  after  n  packets  sent and received (disabled by
    2353               default).
    2354 
    2355        --reneg-sec n
    2356               Renegotiate data channel key after n seconds (default=3600).
    2357 
    2358               When using dual-factor authentication, note that this default value may cause  the
    2359               end user to be challenged to reauthorize once per hour.
    2360 
    2361               Also, keep in mind that this option can be used on both the client and server, and
    2362               whichever uses the lower value will be the one to trigger  the  renegotiation.   A
    2363               common  mistake  is  to  set --reneg-sec to a higher value on either the client or
    2364               server, while the other side of the connection is still using the default value of
    2365               3600  seconds,  meaning that the renegotiation will still occur once per 3600 sec‐
    2366               onds.  The solution is to increase --reneg-sec on both the client and  server,  or
    2367               set  it  to 0 on one side of the connection (to disable), and to your chosen value
    2368               on the other side.
    2369 
    2370        --hand-window n
    2371               Handshake Window -- the TLS-based key exchange must finalize within n  seconds  of
    2372               handshake  initiation  by any peer (default = 60 seconds).  If the handshake fails
    2373               we will attempt to reset our connection with our peer and try again.  Even in  the
    2374               event  of  handshake  failure we will still use our expiring key for up to --tran-
    2375               window seconds to maintain continuity of transmission of tunnel data.
    2376 
    2377        --tran-window n
    2378               Transition window -- our old key can live this many seconds  after  a  new  a  key
    2379               renegotiation begins (default = 3600 seconds).  This feature allows for a graceful
    2380               transition from old to new key, and removes the key  renegotiation  sequence  from
    2381               the critical path of tunnel data forwarding.
    2382 
    2383        --single-session
    2384               After  initially connecting to a remote peer, disallow any new connections.  Using
    2385               this option means that a remote peer cannot connect, disconnect, and  then  recon‐
    2386               nect.
    2387 
    2388               If  the  daemon is reset by a signal or --ping-restart, it will allow one new con‐
    2389               nection.
    2390 
    2391               --single-session can be used with --ping-exit or --inactive  to  create  a  single
    2392               dynamic session that will exit when finished.
    2393 
    2394        --tls-exit
    2395               Exit on TLS negotiation failure.
    2396 
    2397        --tls-auth file [direction]
    2398               Add  an  additional layer of HMAC authentication on top of the TLS control channel
    2399               to protect against DoS attacks.
    2400 
    2401               In a nutshell, --tls-auth enables a kind of "HMAC firewall" on  OpenVPN's  TCP/UDP
    2402               port, where TLS control channel packets bearing an incorrect HMAC signature can be
    2403               dropped immediately without response.
    2404 
    2405               file (required) is a key file which can be in one of two formats:
    2406 
    2407               (1) An OpenVPN static key file generated by --genkey (required if direction param‐
    2408               eter is used).
    2409 
    2410               (2) A freeform passphrase file.  In this case the HMAC key will be derived by tak‐
    2411               ing a secure hash of this file, similar to the md5sum(1) or sha1sum(1) commands.
    2412 
    2413               OpenVPN will first try format (1), and if the file fails to parse as a static  key
    2414               file, format (2) will be used.
    2415 
    2416               See the --secret option for more information on the optional direction parameter.
    2417 
    2418               --tls-auth  is recommended when you are running OpenVPN in a mode where it is lis‐
    2419               tening for packets from any IP address, such as when --remote is not specified, or
    2420               --remote is specified with --float.
    2421 
    2422               The  rationale  for  this  feature  is  as  follows.   TLS requires a multi-packet
    2423               exchange before it is able to  authenticate  a  peer.   During  this  time  before
    2424               authentication, OpenVPN is allocating resources (memory and CPU) to this potential
    2425               peer.  The potential peer is also exposing many parts of OpenVPN and  the  OpenSSL
    2426               library  to the packets it is sending.  Most successful network attacks today seek
    2427               to either exploit bugs in programs (such as buffer overflow attacks)  or  force  a
    2428               program  to  consume  so  many  resources that it becomes unusable.  Of course the
    2429               first line of defense is always to produce clean, well-audited code.  OpenVPN  has
    2430               been  written  with  buffer  overflow attack prevention as a top priority.  But as
    2431               history has shown, many of the most widely used network  applications  have,  from
    2432               time to time, fallen to buffer overflow attacks.
    2433 
    2434               So  as  a second line of defense, OpenVPN offers this special layer of authentica‐
    2435               tion on top of the TLS control channel so that every packet on the control channel
    2436               is authenticated by an HMAC signature and a unique ID for replay protection.  This
    2437               signature will also help protect against DoS  (Denial  of  Service)  attacks.   An
    2438               important  rule  of  thumb in reducing vulnerability to DoS attacks is to minimize
    2439               the amount of resources a potential, but as yet unauthenticated, client is able to
    2440               consume.
    2441 
    2442               --tls-auth does this by signing every TLS control channel packet with an HMAC sig‐
    2443               nature, including packets which are sent before the TLS level has had a chance  to
    2444               authenticate  the  peer.  The result is that packets without the correct signature
    2445               can be dropped immediately upon reception, before they have a  chance  to  consume
    2446               additional system resources such as by initiating a TLS handshake.  --tls-auth can
    2447               be strengthened by adding the --replay-persist option which  will  keep  OpenVPN's
    2448               replay protection state in a file so that it is not lost across restarts.
    2449 
    2450               It  should be emphasized that this feature is optional and that the passphrase/key
    2451               file used with --tls-auth gives a peer nothing more than the power to  initiate  a
    2452               TLS handshake.  It is not used to encrypt or authenticate any tunnel data.
    2453 
    2454        --askpass [file]
    2455               Get certificate password from console or file before we daemonize.
    2456 
    2457               For  the  extremely security conscious, it is possible to protect your private key
    2458               with a password.  Of course this means that  every  time  the  OpenVPN  daemon  is
    2459               started  you  must be there to type the password.  The --askpass option allows you
    2460               to start OpenVPN from the command line.  It will query you for a  password  before
    2461               it  daemonizes.   To  protect  a  private  key with a password you should omit the
    2462               -nodes option when you use the openssl command line tool  to  manage  certificates
    2463               and private keys.
    2464 
    2465               If file is specified, read the password from the first line of file.  Keep in mind
    2466               that storing your password in a file to a certain  extent  invalidates  the  extra
    2467               security  provided  by  using an encrypted key (Note: OpenVPN will only read pass‐
    2468               words from a file if it has been built with the  --enable-password-save  configure
    2469               option, or on Windows by defining ENABLE_PASSWORD_SAVE in win/settings.in).
    2470 
    2471        --auth-nocache
    2472               Don't cache --askpass or --auth-user-pass username/passwords in virtual memory.
    2473 
    2474               If  specified,  this  directive  will  cause  OpenVPN  to immediately forget user‐
    2475               name/password inputs after they are used.  As a result, when OpenVPN needs a user‐
    2476               name/password,  it  will  prompt for input from stdin, which may be multiple times
    2477               during the duration of an OpenVPN session.
    2478 
    2479               This directive does not affect the --http-proxy username/password.  It  is  always
    2480               cached.
    2481 
    2482        --tls-verify cmd
    2483               Execute shell command cmd to verify the X509 name of a pending TLS connection that
    2484               has otherwise passed all other tests of certification (except for  revocation  via
    2485               --crl-verify directive; the revocation test occurs after the --tls-verify test).
    2486 
    2487               cmd should return 0 to allow the TLS handshake to proceed, or 1 to fail.
    2488 
    2489               Note  that  cmd  is a command line and as such may (if enclosed in quotes) contain
    2490               whitespace separated arguments.  The first word of cmd is  the  shell  command  to
    2491               execute and the remaining words are its arguments.  When cmd is executed two argu‐
    2492               ments are appended, as follows:
    2493 
    2494               cmd certificate_depth X509_NAME_oneline
    2495 
    2496               These arguments are, respectively, the current certificate depth and the X509 com‐
    2497               mon name (cn) of the peer.
    2498 
    2499               This  feature  is useful if the peer you want to trust has a certificate which was
    2500               signed by a certificate authority who also signed many other  certificates,  where
    2501               you  don't  necessarily  want  to trust all of them, but rather be selective about
    2502               which peer certificate you will accept.  This feature allows you to write a script
    2503               which will test the X509 name on a certificate and decide whether or not it should
    2504               be accepted.  For a simple perl script which will test the common  name  field  on
    2505               the certificate, see the file verify-cn in the OpenVPN distribution.
    2506 
    2507               See  the  "Environmental Variables" section below for additional parameters passed
    2508               as environmental variables.
    2509 
    2510        --tls-export-cert directory
    2511               Store the certificates the clients uses upon connection to  this  directory.  This
    2512               will be done before --tls-verify is called.  The certificates will use a temporary
    2513               name and will be deleted when the tls-verify script returns.  The file  name  used
    2514               for the certificate is available via the peer_cert environment variable.
    2515 
    2516        --x509-username-field fieldname
    2517               Field  in x509 certificate subject to be used as username (default=CN).  Fieldname
    2518               will be uppercased before matching. When this option  is  used,  the  --tls-remote
    2519               option will match against the chosen fieldname instead of the CN.
    2520 
    2521        --tls-remote name
    2522               Accept  connections  only from a host with X509 name or common name equal to name.
    2523               The remote host must also pass all other tests of verification.
    2524 
    2525               NOTE: Because tls-remote may test against a common  name  prefix,  only  use  this
    2526               option  when you are using OpenVPN with a custom CA certificate that is under your
    2527               control.  Never use this option when your client  certificates  are  signed  by  a
    2528               third party, such as a commercial web CA.
    2529 
    2530               Name  can  also  be a common name prefix, for example if you want a client to only
    2531               accept connections to "Server-1", "Server-2", etc.,  you  can  simply  use  --tls-
    2532               remote Server
    2533 
    2534               Using  a common name prefix is a useful alternative to managing a CRL (Certificate
    2535               Revocation List) on the client, since it allows the client to refuse all  certifi‐
    2536               cates except for those associated with designated servers.
    2537 
    2538               --tls-remote  is  a  useful  replacement for the --tls-verify option to verify the
    2539               remote host, because --tls-remote works in a --chroot environment too.
    2540 
    2541        --ns-cert-type client|server
    2542               Require that peer certificate was signed with an explicit  nsCertType  designation
    2543               of "client" or "server".
    2544 
    2545               This is a useful security option for clients, to ensure that the host they connect
    2546               with is a designated server.
    2547 
    2548               See the easy-rsa/build-key-server script for an example of how to generate a  cer‐
    2549               tificate with the nsCertType field set to "server".
    2550 
    2551               If  the server certificate's nsCertType field is set to "server", then the clients
    2552               can verify this with --ns-cert-type server.
    2553 
    2554               This is an important security precaution to protect  against  a  man-in-the-middle
    2555               attack  where an authorized client attempts to connect to another client by imper‐
    2556               sonating the server.  The attack is easily prevented by having clients verify  the
    2557               server certificate using any one of --ns-cert-type, --tls-remote, or --tls-verify.
    2558 
    2559        --remote-cert-ku v...
    2560               Require that peer certificate was signed with an explicit key usage.
    2561 
    2562               This is a useful security option for clients, to ensure that the host they connect
    2563               to is a designated server.
    2564 
    2565               The key usage should be encoded in hex, more than one key usage can be specified.
    2566 
    2567        --remote-cert-eku oid
    2568               Require that peer certificate was signed with an explicit extended key usage.
    2569 
    2570               This is a useful security option for clients, to ensure that the host they connect
    2571               to is a designated server.
    2572 
    2573               The extended key usage should be encoded in oid notation, or OpenSSL symbolic rep‐
    2574               resentation.
    2575 
    2576        --remote-cert-tls client|server
    2577               Require that peer certificate was signed with an explicit key usage  and  extended
    2578               key usage based on RFC3280 TLS rules.
    2579 
    2580               This is a useful security option for clients, to ensure that the host they connect
    2581               to is a designated server.
    2582 
    2583               The --remote-cert-tls client option is equivalent to  --remote-cert-ku  80  08  88
    2584               --remote-cert-eku "TLS Web Client Authentication"
    2585 
    2586               The key usage is digitalSignature and/or keyAgreement.
    2587 
    2588               The  --remote-cert-tls  server  option  is  equivalent  to  --remote-cert-ku a0 88
    2589               --remote-cert-eku "TLS Web Server Authentication"
    2590 
    2591               The key usage is digitalSignature and ( keyEncipherment or keyAgreement ).
    2592 
    2593               This is an important security precaution to protect  against  a  man-in-the-middle
    2594               attack  where an authorized client attempts to connect to another client by imper‐
    2595               sonating the server.  The attack is easily prevented by having clients verify  the
    2596               server certificate using any one of --remote-cert-tls, --tls-remote, or --tls-ver‐
    2597               ify.
    2598 
    2599        --crl-verify crl
    2600               Check peer certificate against the file crl in PEM format.
    2601 
    2602               A CRL (certificate revocation list) is used when a particular key  is  compromised
    2603               but when the overall PKI is still intact.
    2604 
    2605               Suppose you had a PKI consisting of a CA, root certificate, and a number of client
    2606               certificates.  Suppose a laptop computer containing a client key  and  certificate
    2607               was  stolen.   By  adding the stolen certificate to the CRL file, you could reject
    2608               any connection which attempts to use it, while preserving the overall integrity of
    2609               the PKI.
    2610 
    2611               The  only  time  when it would be necessary to rebuild the entire PKI from scratch
    2612               would be if the root certificate key itself was compromised.
    2613 
    2614    SSL Library information:
    2615        --show-ciphers
    2616               (Standalone) Show all cipher algorithms to use with the --cipher option.
    2617 
    2618        --show-digests
    2619               (Standalone) Show all message digest algorithms to use with the --auth option.
    2620 
    2621        --show-tls
    2622               (Standalone) Show all TLS ciphers (TLS used only as a control channel).   The  TLS
    2623               ciphers will be sorted from highest preference (most secure) to lowest.
    2624 
    2625        --show-engines
    2626               (Standalone)  Show  currently available hardware-based crypto acceleration engines
    2627               supported by the OpenSSL library.
    2628 
    2629    Generate a random key:
    2630        Used only for non-TLS static key encryption mode.
    2631 
    2632        --genkey
    2633               (Standalone) Generate a random key to be used as a shared secret, for use with the
    2634               --secret  option.   This  file  must  be  shared with the peer over a pre-existing
    2635               secure channel such as scp(1)
    2636 
    2637        --secret file
    2638               Write key to file.
    2639 
    2640    TUN/TAP persistent tunnel config mode:
    2641        Available with linux 2.4.7+.  These options comprise a standalone mode of  OpenVPN  which
    2642        can be used to create and delete persistent tunnels.
    2643 
    2644        --mktun
    2645               (Standalone)  Create  a  persistent tunnel on platforms which support them such as
    2646               Linux.  Normally TUN/TAP tunnels exist only for the period of time that an  appli‐
    2647               cation has them open.  This option takes advantage of the TUN/TAP driver's ability
    2648               to build persistent tunnels that live through multiple instantiations  of  OpenVPN
    2649               and die only when they are deleted or the machine is rebooted.
    2650 
    2651               One  of  the  advantages of persistent tunnels is that they eliminate the need for
    2652               separate --up and --down scripts to run the appropriate ifconfig(8)  and  route(8)
    2653               commands.   These commands can be placed in the the same shell script which starts
    2654               or terminates an OpenVPN session.
    2655 
    2656               Another advantage is that open connections through the TUN/TAP-based  tunnel  will
    2657               not be reset if the OpenVPN peer restarts.  This can be useful to provide uninter‐
    2658               rupted connectivity through the tunnel in the event of a DHCP reset of the  peer's
    2659               public IP address (see the --ipchange option above).
    2660 
    2661               One  disadvantage of persistent tunnels is that it is harder to automatically con‐
    2662               figure their MTU value (see --link-mtu and --tun-mtu above).
    2663 
    2664               On some platforms such as Windows, TAP-Win32 tunnels are persistent by default.
    2665 
    2666        --rmtun
    2667               (Standalone) Remove a persistent tunnel.
    2668 
    2669        --dev tunX | tapX
    2670               TUN/TAP device
    2671 
    2672        --user user
    2673               Optional user to be owner of this tunnel.
    2674 
    2675        --group group
    2676               Optional group to be owner of this tunnel.
    2677 
    2678    Windows-Specific Options:
    2679        --win-sys path|'env'
    2680               Set the Windows system directory pathname to use when looking for system  executa‐
    2681               bles such as route.exe and netsh.exe.  By default, if this directive is not speci‐
    2682               fied, the pathname will be set to "C:\WINDOWS"
    2683 
    2684               The special string 'env' indicates that the pathname should be read from the  Sys‐
    2685               temRoot environmental variable.
    2686 
    2687        --ip-win32 method
    2688               When using --ifconfig on Windows, set the TAP-Win32 adapter IP address and netmask
    2689               using method.  Don't use this option unless you are also using --ifconfig.
    2690 
    2691               manual -- Don't set the IP address or netmask  automatically.   Instead  output  a
    2692               message  to  the  console  telling  the user to configure the adapter manually and
    2693               indicating the IP/netmask which OpenVPN expects the adapter to be set to.
    2694 
    2695               dynamic [offset] [lease-time] -- Automatically set the IP address and  netmask  by
    2696               replying  to  DHCP  query messages generated by the kernel.  This mode is probably
    2697               the "cleanest" solution for setting the TCP/IP properties since it uses the  well-
    2698               known  DHCP  protocol.  There are, however, two prerequisites for using this mode:
    2699               (1) The TCP/IP properties for the TAP-Win32 adapter must be set to "Obtain  an  IP
    2700               address automatically," and (2) OpenVPN needs to claim an IP address in the subnet
    2701               for use as the virtual DHCP server address.  By default in --dev tap mode, OpenVPN
    2702               will  take  the normally unused first address in the subnet.  For example, if your
    2703               subnet is 192.168.4.0 netmask 255.255.255.0, then OpenVPN will take the IP address
    2704               192.168.4.0 to use as the virtual DHCP server address.  In --dev tun mode, OpenVPN
    2705               will cause the DHCP server to masquerade as if it were coming from the remote end‐
    2706               point.   The optional offset parameter is an integer which is > -256 and < 256 and
    2707               which defaults to 0.  If offset is positive, the DHCP server  will  masquerade  as
    2708               the  IP  address  at  network  address  + offset.  If offset is negative, the DHCP
    2709               server will masquerade as the IP address at broadcast address + offset.  The  Win‐
    2710               dows ipconfig /all command can be used to show what Windows thinks the DHCP server
    2711               address is.  OpenVPN will "claim" this  address,  so  make  sure  to  use  a  free
    2712               address.   Having said that, different OpenVPN instantiations, including different
    2713               ends of the same connection, can share the same virtual DHCP server address.   The
    2714               lease-time  parameter  controls the lease time of the DHCP assignment given to the
    2715               TAP-Win32 adapter, and is denoted in seconds.  Normally a very long lease time  is
    2716               preferred  because  it  prevents routes involving the TAP-Win32 adapter from being
    2717               lost when the system goes to sleep.  The default lease time is one year.
    2718 
    2719               netsh -- Automatically set the IP address and netmask using the  Windows  command-
    2720               line "netsh" command.  This method appears to work correctly on Windows XP but not
    2721               Windows 2000.
    2722 
    2723               ipapi -- Automatically set the IP address and netmask using the Windows IP  Helper
    2724               API.   This  approach  does not have ideal semantics, though testing has indicated
    2725               that it works okay in practice.  If you use this option, it is best to  leave  the
    2726               TCP/IP  properties  for the TAP-Win32 adapter in their default state, i.e. "Obtain
    2727               an IP address automatically."
    2728 
    2729               adaptive -- (Default) Try dynamic method initially and fail over to netsh  if  the
    2730               DHCP  negotiation with the TAP-Win32 adapter does not succeed in 20 seconds.  Such
    2731               failures have been known to  occur  when  certain  third-party  firewall  packages
    2732               installed  on  the client machine block the DHCP negotiation used by the TAP-Win32
    2733               adapter.  Note that if the netsh failover occurs,  the  TAP-Win32  adapter  TCP/IP
    2734               properties  will  be reset from DHCP to static, and this will cause future OpenVPN
    2735               startups using the adaptive mode to use  netsh  immediately,  rather  than  trying
    2736               dynamic  first.   To  "unstick" the adaptive mode from using netsh, run OpenVPN at
    2737               least once using the dynamic mode to restore the TAP-Win32 adapter TCP/IP  proper‐
    2738               ties to a DHCP configuration.
    2739 
    2740        --route-method m
    2741               Which method m to use for adding routes on Windows?
    2742 
    2743               adaptive  (default)  --  Try IP helper API first.  If that fails, fall back to the
    2744               route.exe shell command.
    2745               ipapi -- Use IP helper API.
    2746               exe -- Call the route.exe shell command.
    2747 
    2748        --dhcp-option type [parm]
    2749               Set extended TAP-Win32 TCP/IP properties, must be used with --ip-win32 dynamic  or
    2750               --ip-win32  adaptive.  This option can be used to set additional TCP/IP properties
    2751               on the TAP-Win32 adapter, and is particularly useful for  configuring  an  OpenVPN
    2752               client to access a Samba server across the VPN.
    2753 
    2754               DOMAIN name -- Set Connection-specific DNS Suffix.
    2755 
    2756               DNS  addr  --  Set  primary domain name server address.  Repeat this option to set
    2757               secondary DNS server addresses.
    2758 
    2759               WINS addr -- Set primary WINS server address (NetBIOS over  TCP/IP  Name  Server).
    2760               Repeat this option to set secondary WINS server addresses.
    2761 
    2762               NBDD addr -- Set primary NBDD server address (NetBIOS over TCP/IP Datagram Distri‐
    2763               bution Server) Repeat this option to set secondary NBDD server addresses.
    2764 
    2765               NTP addr -- Set primary NTP server address (Network Time Protocol).   Repeat  this
    2766               option to set secondary NTP server addresses.
    2767 
    2768               NBT  type  --  Set  NetBIOS  over  TCP/IP Node type.  Possible options: 1 = b-node
    2769               (broadcasts), 2 = p-node (point-to-point name queries to a WINS server),  4  =  m-
    2770               node  (broadcast  then query name server), and 8 = h-node (query name server, then
    2771               broadcast).
    2772 
    2773               NBS scope-id -- Set NetBIOS over TCP/IP Scope. A  NetBIOS  Scope  ID  provides  an
    2774               extended  naming  service  for  the NetBIOS over TCP/IP (Known as NBT) module. The
    2775               primary purpose of a NetBIOS scope ID is to isolate NetBIOS traffic  on  a  single
    2776               network  to only those nodes with the same NetBIOS scope ID.  The NetBIOS scope ID
    2777               is a character string that is appended to the NetBIOS name. The NetBIOS  scope  ID
    2778               on  two  hosts  must  match, or the two hosts will not be able to communicate. The
    2779               NetBIOS Scope ID also allows computers to use the same computer name, as they have
    2780               different  scope  IDs. The Scope ID becomes a part of the NetBIOS name, making the
    2781               name unique.  (This description of NetBIOS scopes courtesy of NeonSurge@abyss.com)
    2782 
    2783               DISABLE-NBT -- Disable Netbios-over-TCP/IP.
    2784 
    2785               Note that if --dhcp-option is pushed via  --push  to  a  non-windows  client,  the
    2786               option  will  be saved in the client's environment before the up script is called,
    2787               under the name "foreign_option_{n}".
    2788 
    2789        --tap-sleep n
    2790               Cause OpenVPN to sleep for n seconds immediately after the TAP-Win32 adapter state
    2791               is set to "connected".
    2792 
    2793               This  option  is  intended to be used to troubleshoot problems with the --ifconfig
    2794               and --ip-win32 options, and is used to give the TAP-Win32 adapter time to come  up
    2795               before Windows IP Helper API operations are applied to it.
    2796 
    2797        --show-net-up
    2798               Output  OpenVPN's view of the system routing table and network adapter list to the
    2799               syslog or log file after the TUN/TAP adapter has been brought up  and  any  routes
    2800               have been added.
    2801 
    2802        --dhcp-renew
    2803               Ask  Windows  to  renew the TAP adapter lease on startup.  This option is normally
    2804               unnecessary, as Windows automatically triggers a DHCP  renegotiation  on  the  TAP
    2805               adapter  when  it  comes up, however if you set the TAP-Win32 adapter Media Status
    2806               property to "Always Connected", you may need this flag.
    2807 
    2808        --dhcp-release
    2809               Ask Windows to release the TAP adapter lease on shutdown.   This  option  has  the
    2810               same caveats as --dhcp-renew above.
    2811 
    2812        --register-dns
    2813               Run net stop dnscache, net start dnscache, ipconfig /flushdns and ipconfig /regis‐
    2814               terdns on connection initiation.  This is known to kick Windows  into  recognizing
    2815               pushed DNS servers.
    2816 
    2817        --pause-exit
    2818               Put  up a "press any key to continue" message on the console prior to OpenVPN pro‐
    2819               gram exit.  This option is automatically used by the Windows explorer when OpenVPN
    2820               is run on a configuration file using the right-click explorer menu.
    2821 
    2822        --service exit-event [0|1]
    2823               Should  be used when OpenVPN is being automatically executed by another program in
    2824               such a context that no interaction with the user via display or keyboard is possi‐
    2825               ble.  In general, end-users should never need to explicitly use this option, as it
    2826               is automatically added by the OpenVPN service wrapper when a given OpenVPN config‐
    2827               uration is being run as a service.
    2828 
    2829               exit-event is the name of a Windows global event object, and OpenVPN will continu‐
    2830               ously monitor the state of this event object and exit when it becomes signaled.
    2831 
    2832               The second parameter indicates  the  initial  state  of  exit-event  and  normally
    2833               defaults to 0.
    2834 
    2835               Multiple OpenVPN processes can be simultaneously executed with the same exit-event
    2836               parameter.  In any case, the controlling process can  signal  exit-event,  causing
    2837               all such OpenVPN processes to exit.
    2838 
    2839               When  executing  an  OpenVPN  process  using the --service directive, OpenVPN will
    2840               probably not have a console window to output status/error messages,  therefore  it
    2841               is useful to use --log or --log-append to write these messages to a file.
    2842 
    2843        --show-adapters
    2844               (Standalone)  Show  available  TAP-Win32  adapters which can be selected using the
    2845               --dev-node option.  On non-Windows systems, the ifconfig(8) command provides simi‐
    2846               lar functionality.
    2847 
    2848        --allow-nonadmin [TAP-adapter]
    2849               (Standalone) Set TAP-adapter to allow access from non-administrative accounts.  If
    2850               TAP-adapter is omitted, all TAP adapters on the system will be configured to allow
    2851               non-admin  access.   The non-admin access setting will only persist for the length
    2852               of time that the TAP-Win32 device object and driver remain loaded, and  will  need
    2853               to  be re-enabled after a reboot, or if the driver is unloaded and reloaded.  This
    2854               directive can only be used by an administrator.
    2855 
    2856        --show-valid-subnets
    2857               (Standalone) Show valid subnets for --dev  tun  emulation.   Since  the  TAP-Win32
    2858               driver  exports an ethernet interface to Windows, and since TUN devices are point-
    2859               to-point in nature, it is necessary for the TAP-Win32  driver  to  impose  certain
    2860               constraints on TUN endpoint address selection.
    2861 
    2862               Namely, the point-to-point endpoints used in TUN device emulation must be the mid‐
    2863               dle two addresses of a /30 subnet (netmask 255.255.255.252).
    2864 
    2865        --show-net
    2866               (Standalone) Show OpenVPN's view of the system routing table and  network  adapter
    2867               list.
    2868 
    2869    PKCS#11 Standalone Options:
    2870        --show-pkcs11-ids provider [cert_private]
    2871               (Standalone) Show PKCS#11 token object list. Specify cert_private as 1 if certifi‐
    2872               cates are stored as private objects.
    2873 
    2874               --verb option can be used BEFORE this option to produce debugging information.
    2875 
    2876 SCRIPTING AND ENVIRONMENTAL VARIABLES
    2877        OpenVPN exports a series of environmental variables for use by user-defined scripts.
    2878 
    2879    Script Order of Execution
    2880        --up   Executed after TCP/UDP socket bind and TUN/TAP open.
    2881 
    2882        --tls-verify
    2883               Executed when we have a still untrusted remote peer.
    2884 
    2885        --ipchange
    2886               Executed after connection authentication, or remote IP address change.
    2887 
    2888        --client-connect
    2889               Executed in --mode server mode immediately after client authentication.
    2890 
    2891        --route-up
    2892               Executed after connection authentication, either immediately after, or some number
    2893               of seconds after as defined by the --route-delay option.
    2894 
    2895        --client-disconnect
    2896               Executed in --mode server mode on client instance shutdown.
    2897 
    2898        --down Executed after TCP/UDP and TUN/TAP close.
    2899 
    2900        --learn-address
    2901               Executed  in  --mode  server mode whenever an IPv4 address/route or MAC address is
    2902               added to OpenVPN's internal routing table.
    2903 
    2904        --auth-user-pass-verify
    2905               Executed in --mode server mode on new client connections, when the client is still
    2906               untrusted.
    2907 
    2908    String Types and Remapping
    2909        In  certain cases, OpenVPN will perform remapping of characters in strings.  Essentially,
    2910        any characters outside the set of permitted characters for each string type will be  con‐
    2911        verted to underbar ('_').
    2912 
    2913        Q: Why is string remapping necessary?
    2914 
    2915        A:  It's  an  important  security feature to prevent the malicious coding of strings from
    2916        untrusted sources to be passed as parameters to scripts, saved in the  environment,  used
    2917        as a common name, translated to a filename, etc.
    2918 
    2919        Q: Can string remapping be disabled?
    2920 
    2921        A:  Yes,  by  using  the --no-name-remapping option, however this should be considered an
    2922        advanced option.
    2923 
    2924        Here is a brief rundown of OpenVPN's current string types  and  the  permitted  character
    2925        class for each string:
    2926 
    2927        X509  Names:  Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), at ('@'), colon (':'),
    2928        slash ('/'), and equal ('=').  Alphanumeric is defined as a character  which  will  cause
    2929        the C library isalnum() function to return true.
    2930 
    2931        Common Names: Alphanumeric, underbar ('_'), dash ('-'), dot ('.'), and at ('@').
    2932 
    2933        --auth-user-pass username: Same as Common Name, with one exception: starting with OpenVPN
    2934        2.0.1, the username is passed to the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin  in  its
    2935        raw form, without string remapping.
    2936 
    2937        --auth-user-pass  password:  Any  "printable"  character  except  CR or LF.  Printable is
    2938        defined to be a character which will cause the C library  isprint()  function  to  return
    2939        true.
    2940 
    2941        --client-config-dir  filename  as  derived  from  common  name or username: Alphanumeric,
    2942        underbar ('_'), dash ('-'), and dot ('.') except for "." or ".." as  standalone  strings.
    2943        As of 2.0.1-rc6, the at ('@') character has been added as well for compatibility with the
    2944        common name character class.
    2945 
    2946        Environmental variable names: Alphanumeric or underbar ('_').
    2947 
    2948        Environmental variable values: Any printable character.
    2949 
    2950        For all cases, characters in a string which are not members of the legal character  class
    2951        for that string type will be remapped to underbar ('_').
    2952 
    2953    Environmental Variables
    2954        Once  set,  a  variable  is  persisted indefinitely until it is reset by a new value or a
    2955        restart,
    2956 
    2957        As of OpenVPN 2.0-beta12, in server mode, environmental  variables  set  by  OpenVPN  are
    2958        scoped  according  to the client objects they are associated with, so there should not be
    2959        any issues with scripts having access to stale, previously set variables which  refer  to
    2960        different client instances.
    2961 
    2962        bytes_received
    2963               Total  number of bytes received from client during VPN session.  Set prior to exe‐
    2964               cution of the --client-disconnect script.
    2965 
    2966        bytes_sent
    2967               Total number of bytes sent to client during VPN session.  Set prior  to  execution
    2968               of the --client-disconnect script.
    2969 
    2970        common_name
    2971               The  X509  common  name  of  an  authenticated  client.  Set prior to execution of
    2972               --client-connect, --client-disconnect, and --auth-user-pass-verify scripts.
    2973 
    2974        config Name of first --config file.  Set on program initiation and reset on SIGHUP.
    2975 
    2976        daemon Set to "1" if the --daemon directive is specified, or "0" otherwise.  Set on  pro‐
    2977               gram initiation and reset on SIGHUP.
    2978 
    2979        daemon_log_redirect
    2980               Set  to  "1"  if the --log or --log-append directives are specified, or "0" other‐
    2981               wise.  Set on program initiation and reset on SIGHUP.
    2982 
    2983        dev    The actual name of the TUN/TAP device, including a unit number if it exists.   Set
    2984               prior to --up or --down script execution.
    2985 
    2986        foreign_option_{n}
    2987               An  option  pushed via --push to a client which does not natively support it, such
    2988               as --dhcp-option on a non-Windows system, will be recorded to  this  environmental
    2989               variable sequence prior to --up script execution.
    2990 
    2991        ifconfig_broadcast
    2992               The  broadcast  address for the virtual ethernet segment which is derived from the
    2993               --ifconfig option when --dev tap is used.  Set prior to OpenVPN calling the ifcon‐
    2994               fig or netsh (windows version of ifconfig) commands which normally occurs prior to
    2995               --up script execution.
    2996 
    2997        ifconfig_local
    2998               The local VPN endpoint IP address specified in the --ifconfig option (first param‐
    2999               eter).   Set  prior  to  OpenVPN calling the ifconfig or netsh (windows version of
    3000               ifconfig) commands which normally occurs prior to --up script execution.
    3001 
    3002        ifconfig_remote
    3003               The remote VPN endpoint IP address specified  in  the  --ifconfig  option  (second
    3004               parameter)  when  --dev tun is used.  Set prior to OpenVPN calling the ifconfig or
    3005               netsh (windows version of ifconfig) commands which normally occurs prior  to  --up
    3006               script execution.
    3007 
    3008        ifconfig_netmask
    3009               The  subnet  mask  of the virtual ethernet segment that is specified as the second
    3010               parameter to --ifconfig when --dev tap is being used.  Set prior to OpenVPN  call‐
    3011               ing  the  ifconfig  or netsh (windows version of ifconfig) commands which normally
    3012               occurs prior to --up script execution.
    3013 
    3014        ifconfig_pool_local_ip
    3015               The local virtual IP address for the TUN/TAP tunnel taken from an  --ifconfig-push
    3016               directive  if  specified,  or  otherwise from the ifconfig pool (controlled by the
    3017               --ifconfig-pool config file directive).  Only set for  --dev  tun  tunnels.   This
    3018               option  is  set  on  the  server  prior  to  execution of the --client-connect and
    3019               --client-disconnect scripts.
    3020 
    3021        ifconfig_pool_netmask
    3022               The virtual IP netmask for the TUN/TAP tunnel taken from an --ifconfig-push direc‐
    3023               tive if specified, or otherwise from the ifconfig pool (controlled by the --ifcon‐
    3024               fig-pool config file directive).  Only set for --dev tap tunnels.  This option  is
    3025               set  on the server prior to execution of the --client-connect and --client-discon‐
    3026               nect scripts.
    3027 
    3028        ifconfig_pool_remote_ip
    3029               The remote virtual IP address for the TUN/TAP tunnel taken from an --ifconfig-push
    3030               directive  if  specified,  or  otherwise from the ifconfig pool (controlled by the
    3031               --ifconfig-pool config file directive).  This option is set on the server prior to
    3032               execution of the --client-connect and --client-disconnect scripts.
    3033 
    3034        link_mtu
    3035               The maximum packet size (not including the IP header) of tunnel data in UDP tunnel
    3036               transport mode.  Set prior to --up or --down script execution.
    3037 
    3038        local  The --local parameter.  Set on program initiation and reset on SIGHUP.
    3039 
    3040        local_port
    3041               The local port number, specified by --port or --lport.  Set on program  initiation
    3042               and reset on SIGHUP.
    3043 
    3044        password
    3045               The  password provided by a connecting client.  Set prior to --auth-user-pass-ver‐
    3046               ify script execution only when the via-env modifier is specified, and deleted from
    3047               the environment after the script returns.
    3048 
    3049        proto  The --proto parameter.  Set on program initiation and reset on SIGHUP.
    3050 
    3051        remote_{n}
    3052               The --remote parameter.  Set on program initiation and reset on SIGHUP.
    3053 
    3054        remote_port_{n}
    3055               The remote port number, specified by --port or --rport.  Set on program initiation
    3056               and reset on SIGHUP.
    3057 
    3058        route_net_gateway
    3059               The pre-existing default IP gateway in the system routing  table.   Set  prior  to
    3060               --up script execution.
    3061 
    3062        route_vpn_gateway
    3063               The  default  gateway used by --route options, as specified in either the --route-
    3064               gateway option or the second parameter to --ifconfig when --dev tun is  specified.
    3065               Set prior to --up script execution.
    3066 
    3067        route_{parm}_{n}
    3068               A  set of variables which define each route to be added, and are set prior to --up
    3069               script execution.
    3070 
    3071               parm will be one of "network", "netmask", "gateway", or "metric".
    3072 
    3073               n is the OpenVPN route number, starting from 1.
    3074 
    3075               If the network or gateway are resolvable DNS names, their IP address  translations
    3076               will be recorded rather than their names as denoted on the command line or config‐
    3077               uration file.
    3078 
    3079        peer_cert
    3080               Temporary file name containing the client certificate upon connection.  Useful  in
    3081               conjunction with --tls-verify
    3082 
    3083        script_context
    3084               Set  to  "init" or "restart" prior to up/down script execution.  For more informa‐
    3085               tion, see documentation for --up.
    3086 
    3087        script_type
    3088               Prior to execution of any script, this variable is set to the type of script being
    3089               run.   It  can  be one of the following: up, down, ipchange, route-up, tls-verify,
    3090               auth-user-pass-verify, client-connect, client-disconnect, or learn-address.
    3091 
    3092        signal The reason for exit or restart.  Can be one of sigusr1, sighup,  sigterm,  sigint,
    3093               inactive  (controlled  by --inactive option), ping-exit (controlled by --ping-exit
    3094               option), ping-restart  (controlled  by  --ping-restart  option),  connection-reset
    3095               (triggered  on  TCP  connection  reset), error, or unknown (unknown signal).  This
    3096               variable is set just prior to down script execution.
    3097 
    3098        time_ascii
    3099               Client connection timestamp, formatted as a human-readable time string.  Set prior
    3100               to execution of the --client-connect script.
    3101 
    3102        time_duration
    3103               The  duration  (in seconds) of the client session which is now disconnecting.  Set
    3104               prior to execution of the --client-disconnect script.
    3105 
    3106        time_unix
    3107               Client connection timestamp, formatted as a unix  integer  date/time  value.   Set
    3108               prior to execution of the --client-connect script.
    3109 
    3110        tls_id_{n}
    3111               A  series  of certificate fields from the remote peer, where n is the verification
    3112               level.  Only set for TLS connections.  Set  prior  to  execution  of  --tls-verify
    3113               script.
    3114 
    3115        tls_serial_{n}
    3116               The  serial number of the certificate from the remote peer, where n is the verifi‐
    3117               cation level.  Only set for TLS connections.  Set prior to execution of --tls-ver‐
    3118               ify script. This is in the form of a hex string like "37AB46E0", which is suitable
    3119               for doing serial-based OCSP queries (with OpenSSL, you have to prepend "0x" to the
    3120               string).  If  something goes wrong while reading the value from the certificate it
    3121               will be  an  empty  string,  so  your  code  should  check  that.   See  the  con‐
    3122               trib/OCSP_check/OCSP_check.sh script for an example.
    3123 
    3124        tun_mtu
    3125               The MTU of the TUN/TAP device.  Set prior to --up or --down script execution.
    3126 
    3127        trusted_ip
    3128               Actual  IP address of connecting client or peer which has been authenticated.  Set
    3129               prior  to  execution  of  --ipchange,  --client-connect,  and  --client-disconnect
    3130               scripts.
    3131 
    3132        trusted_port
    3133               Actual port number of connecting client or peer which has been authenticated.  Set
    3134               prior  to  execution  of  --ipchange,  --client-connect,  and  --client-disconnect
    3135               scripts.
    3136 
    3137        untrusted_ip
    3138               Actual  IP  address  of connecting client or peer which has not been authenticated
    3139               yet.  Sometimes used to nmap the connecting  host  in  a  --tls-verify  script  to
    3140               ensure  it  is  firewalled  properly.   Set prior to execution of --tls-verify and
    3141               --auth-user-pass-verify scripts.
    3142 
    3143        untrusted_port
    3144               Actual port number of connecting client or peer which has not  been  authenticated
    3145               yet.  Set prior to execution of --tls-verify and --auth-user-pass-verify scripts.
    3146 
    3147        username
    3148               The  username provided by a connecting client.  Set prior to --auth-user-pass-ver‐
    3149               ify script execution only when the via-env modifier is specified.
    3150 
    3151        X509_{n}_{subject_field}
    3152               An X509 subject field from the remote peer certificate, where n is  the  verifica‐
    3153               tion level.  Only set for TLS connections.  Set prior to execution of --tls-verify
    3154               script.  This variable is similar to tls_id_{n} except the component X509  subject
    3155               fields  are  broken  out,  and  no  string  remapping occurs on these field values
    3156               (except for remapping of control characters to "_").  For example,  the  following
    3157               variables  would  be set on the OpenVPN server using the sample client certificate
    3158               in sample-keys (client.crt).  Note that the verification level is 0 for the client
    3159               certificate and 1 for the CA certificate.
    3160 
    3161                   X509_0_emailAddress=me@myhost.mydomain
    3162                   X509_0_CN=Test-Client
    3163                   X509_0_O=OpenVPN-TEST
    3164                   X509_0_ST=NA
    3165                   X509_0_C=KG
    3166                   X509_1_emailAddress=me@myhost.mydomain
    3167                   X509_1_O=OpenVPN-TEST
    3168                   X509_1_L=BISHKEK
    3169                   X509_1_ST=NA
    3170                   X509_1_C=KG
    3171 
    3172 SIGNALS
    3173        SIGHUP Cause  OpenVPN  to close all TUN/TAP and network connections, restart, re-read the
    3174               configuration file (if any), and reopen TUN/TAP and network connections.
    3175 
    3176        SIGUSR1
    3177               Like SIGHUP, except don't re-read configuration file, and possibly don't close and
    3178               reopen  TUN/TAP device, re-read key files, preserve local IP address/port, or pre‐
    3179               serve most recently authenticated remote IP address/port based  on  --persist-tun,
    3180               --persist-key,  --persist-local-ip,  and  --persist-remote-ip options respectively
    3181               (see above).
    3182 
    3183               This signal may also be internally generated by a timeout condition,  governed  by
    3184               the --ping-restart option.
    3185 
    3186               This signal, when combined with --persist-remote-ip, may be sent when the underly‐
    3187               ing parameters of the host's network interface change such as when the host  is  a
    3188               DHCP  client  and  is  assigned  a  new IP address.  See --ipchange above for more
    3189               information.
    3190 
    3191        SIGUSR2
    3192               Causes OpenVPN to display its current statistics (to the syslog file  if  --daemon
    3193               is used, or stdout otherwise).
    3194 
    3195        SIGINT, SIGTERM
    3196               Causes OpenVPN to exit gracefully.
    3197 
    3198 TUN/TAP DRIVER SETUP
    3199        If  you  are  running Linux 2.4.7 or higher, you probably have the TUN/TAP driver already
    3200        installed.  If so, there are still a few things you need to do:
    3201 
    3202        Make device: mknod /dev/net/tun c 10 200
    3203 
    3204        Load driver: modprobe tun
    3205 
    3206 EXAMPLES
    3207        Prior to running these examples, you should have OpenVPN installed on two  machines  with
    3208        network  connectivity  between  them.  If you have not yet installed OpenVPN, consult the
    3209        INSTALL file included in the OpenVPN distribution.
    3210 
    3211    TUN/TAP Setup:
    3212        If you are using Linux 2.4 or higher, make the tun device node and load the tun module:
    3213 
    3214               mknod /dev/net/tun c 10 200
    3215 
    3216               modprobe tun
    3217 
    3218        If you installed from RPM, the mknod step may be omitted, because the  RPM  install  does
    3219        that for you.
    3220 
    3221        Only Linux 2.4 and newer are supported.
    3222 
    3223        For other platforms, consult the INSTALL file at http://openvpn.net/install.html for more
    3224        information.
    3225 
    3226    Firewall Setup:
    3227        If firewalls exist between the two machines, they should be set to forward UDP port  1194
    3228        in  both  directions.   If  you  do  not  have control over the firewalls between the two
    3229        machines, you may still be able to use OpenVPN by adding --ping 15 to each of the openvpn
    3230        commands  used below in the examples (this will cause each peer to send out a UDP ping to
    3231        its remote peer once every 15 seconds which will cause many stateful firewalls to forward
    3232        packets in both directions without an explicit firewall rule).
    3233 
    3234        If  you  are  using  a Linux iptables-based firewall, you may need to enter the following
    3235        command to allow incoming packets on the TUN device:
    3236 
    3237               iptables -A INPUT -i tun+ -j ACCEPT
    3238 
    3239        See the firewalls section below for more information on  configuring  firewalls  for  use
    3240        with OpenVPN.
    3241 
    3242    VPN Address Setup:
    3243        For  purposes of our example, our two machines will be called may.kg and june.kg.  If you
    3244        are constructing a VPN over the internet, then replace may.kg and june.kg with the inter‐
    3245        net  hostname  or  IP  address  that  each machine will use to contact the other over the
    3246        internet.
    3247 
    3248        Now we will choose the tunnel endpoints.  Tunnel endpoints are private IP addresses  that
    3249        only  have  meaning in the context of the VPN.  Each machine will use the tunnel endpoint
    3250        of the other machine to access it over the VPN.  In our example, the tunnel endpoint  for
    3251        may.kg will be 10.4.0.1 and for june.kg, 10.4.0.2.
    3252 
    3253        Once the VPN is established, you have essentially created a secure alternate path between
    3254        the two hosts which is addressed by using the tunnel endpoints.  You  can  control  which
    3255        network  traffic  passes  between  the hosts (a) over the VPN or (b) independently of the
    3256        VPN, by choosing whether to use (a) the VPN endpoint address or (b) the  public  internet
    3257        address, to access the remote host. For example if you are on may.kg and you wish to con‐
    3258        nect to june.kg via ssh without using the VPN (since ssh has its own  built-in  security)
    3259        you  would use the command ssh june.kg.  However in the same scenario, you could also use
    3260        the command telnet 10.4.0.2 to create a telnet session with june.kg over  the  VPN,  that
    3261        would use the VPN to secure the session rather than ssh.
    3262 
    3263        You  can  use  any  address you wish for the tunnel endpoints but make sure that they are
    3264        private addresses (such as those that begin with 10 or 192.168) and  that  they  are  not
    3265        part  of any existing subnet on the networks of either peer, unless you are bridging.  If
    3266        you use an address that is part of your local subnet for either of the tunnel  endpoints,
    3267        you will get a weird feedback loop.
    3268 
    3269    Example 1: A simple tunnel without security
    3270        On may:
    3271 
    3272               openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 --verb 9
    3273 
    3274        On june:
    3275 
    3276               openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 --verb 9
    3277 
    3278        Now verify the tunnel is working by pinging across the tunnel.
    3279 
    3280        On may:
    3281 
    3282               ping 10.4.0.2
    3283 
    3284        On june:
    3285 
    3286               ping 10.4.0.1
    3287 
    3288        The --verb 9 option will produce verbose output, similar to the tcpdump(8) program.  Omit
    3289        the --verb 9 option to have OpenVPN run quietly.
    3290 
    3291    Example 2: A tunnel with static-key security (i.e. using a pre-shared secret)
    3292        First build a static key on may.
    3293 
    3294               openvpn --genkey --secret key
    3295 
    3296        This command will build a random key file called key (in ascii format).  Now copy key  to
    3297        june over a secure medium such as by using the scp(1) program.
    3298 
    3299        On may:
    3300 
    3301               openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 --verb 5 --secret
    3302               key
    3303 
    3304        On june:
    3305 
    3306               openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 --verb 5  --secret
    3307               key
    3308 
    3309        Now verify the tunnel is working by pinging across the tunnel.
    3310 
    3311        On may:
    3312 
    3313               ping 10.4.0.2
    3314 
    3315        On june:
    3316 
    3317               ping 10.4.0.1
    3318 
    3319    Example 3: A tunnel with full TLS-based security
    3320        For  this test, we will designate may as the TLS client and june as the TLS server.  Note
    3321        that client or server designation only has meaning for the TLS subsystem. It has no bear‐
    3322        ing on OpenVPN's peer-to-peer, UDP-based communication model.
    3323 
    3324        First,  build  a  separate  certificate/key  pair  for both may and june (see above where
    3325        --cert is discussed for more info).  Then construct Diffie Hellman parameters (see  above
    3326        where  --dh  is  discussed  for  more  info).   You  can also use the included test files
    3327        client.crt, client.key, server.crt, server.key and ca.crt.  The .crt files  are  certifi‐
    3328        cates/public-keys, the .key files are private keys, and ca.crt is a certification author‐
    3329        ity who has signed both client.crt and server.crt.  For Diffie Hellman parameters you can
    3330        use  the included file dh1024.pem.  Note that all client, server, and certificate author‐
    3331        ity certificates and keys included in the OpenVPN distribution are totally  insecure  and
    3332        should be used for testing only.
    3333 
    3334        On may:
    3335 
    3336               openvpn --remote june.kg --dev tun1 --ifconfig 10.4.0.1 10.4.0.2 --tls-client --ca
    3337               ca.crt --cert client.crt --key client.key --reneg-sec 60 --verb 5
    3338 
    3339        On june:
    3340 
    3341               openvpn --remote may.kg --dev tun1 --ifconfig 10.4.0.2 10.4.0.1 --tls-server  --dh
    3342               dh1024.pem --ca ca.crt --cert server.crt --key server.key --reneg-sec 60 --verb 5
    3343 
    3344        Now verify the tunnel is working by pinging across the tunnel.
    3345 
    3346        On may:
    3347 
    3348               ping 10.4.0.2
    3349 
    3350        On june:
    3351 
    3352               ping 10.4.0.1
    3353 
    3354        Notice  the  --reneg-sec  60 option we used above.  That tells OpenVPN to renegotiate the
    3355        data channel keys every minute.  Since we used --verb 5 above, you will see status infor‐
    3356        mation on each new key negotiation.
    3357 
    3358        For  production  operations,  a  key renegotiation interval of 60 seconds is probably too
    3359        frequent.  Omit the --reneg-sec 60 option to  use  OpenVPN's  default  key  renegotiation
    3360        interval of one hour.
    3361 
    3362    Routing:
    3363        Assuming you can ping across the tunnel, the next step is to route a real subnet over the
    3364        secure tunnel.  Suppose that may and june have two network interfaces each, one connected
    3365        to  the  internet,  and  the other to a private network.  Our goal is to securely connect
    3366        both private networks.  We will assume that  may's  private  subnet  is  10.0.0.0/24  and
    3367        june's is 10.0.1.0/24.
    3368 
    3369        First, ensure that IP forwarding is enabled on both peers.  On Linux, enable routing:
    3370 
    3371               echo 1 > /proc/sys/net/ipv4/ip_forward
    3372 
    3373        and enable TUN packet forwarding through the firewall:
    3374 
    3375               iptables -A FORWARD -i tun+ -j ACCEPT
    3376 
    3377        On may:
    3378 
    3379               route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2
    3380 
    3381        On june:
    3382 
    3383               route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1
    3384 
    3385        Now  any machine on the 10.0.0.0/24 subnet can access any machine on the 10.0.1.0/24 sub‐
    3386        net over the secure tunnel (or vice versa).
    3387 
    3388        In a production environment, you could put the route command(s) in  a  shell  script  and
    3389        execute with the --up option.
    3390 
    3391 FIREWALLS
    3392        OpenVPN's  usage  of a single UDP port makes it fairly firewall-friendly.  You should add
    3393        an entry to your firewall rules to allow incoming OpenVPN packets.  On Linux 2.4+:
    3394 
    3395               iptables -A INPUT -p udp -s 1.2.3.4 --dport 1194 -j ACCEPT
    3396 
    3397        This will allow incoming packets on UDP port 1194 (OpenVPN's default UDP  port)  from  an
    3398        OpenVPN peer at 1.2.3.4.
    3399 
    3400        If you are using HMAC-based packet authentication (the default in any of OpenVPN's secure
    3401        modes), having the firewall filter on source address can be  considered  optional,  since
    3402        HMAC  packet authentication is a much more secure method of verifying the authenticity of
    3403        a packet source.  In that case:
    3404 
    3405               iptables -A INPUT -p udp --dport 1194 -j ACCEPT
    3406 
    3407        would be adequate and would not render the host inflexible with respect to its peer  hav‐
    3408        ing a dynamic IP address.
    3409 
    3410        OpenVPN  also  works  well on stateful firewalls.  In some cases, you may not need to add
    3411        any static rules to the firewall list if you are using a stateful firewall that knows how
    3412        to  track UDP connections.  If you specify --ping n, OpenVPN will be guaranteed to send a
    3413        packet to its peer at least once every n seconds.  If n is less than the  stateful  fire‐
    3414        wall  connection  timeout,  you  can  maintain an OpenVPN connection indefinitely without
    3415        explicit firewall rules.
    3416 
    3417        You should also add firewall rules to allow incoming IP traffic on  TUN  or  TAP  devices
    3418        such as:
    3419 
    3420               iptables -A INPUT -i tun+ -j ACCEPT
    3421 
    3422        to allow input packets from tun devices,
    3423 
    3424               iptables -A FORWARD -i tun+ -j ACCEPT
    3425 
    3426        to  allow input packets from tun devices to be forwarded to other hosts on the local net‐
    3427        work,
    3428 
    3429               iptables -A INPUT -i tap+ -j ACCEPT
    3430 
    3431        to allow input packets from tap devices, and
    3432 
    3433               iptables -A FORWARD -i tap+ -j ACCEPT
    3434 
    3435        to allow input packets from tap devices to be forwarded to other hosts on the local  net‐
    3436        work.
    3437 
    3438        These  rules  are secure if you use packet authentication, since no incoming packets will
    3439        arrive on a TUN or TAP virtual device unless they first pass an HMAC authentication test.
    3440 
    3441 FAQ
    3442        http://openvpn.net/faq.html
    3443 
    3444 HOWTO
    3445        For a more comprehensive guide to setting up OpenVPN in a  production  setting,  see  the
    3446        OpenVPN HOWTO at http://openvpn.net/howto.html
    3447 
    3448 PROTOCOL
    3449        For a description of OpenVPN's underlying protocol, see http://openvpn.net/security.html
    3450 
    3451 WEB
    3452        OpenVPN's web site is at http://openvpn.net/
    3453 
    3454        Go  here  to download the latest version of OpenVPN, subscribe to the mailing lists, read
    3455        the mailing list archives, or browse the SVN repository.
    3456 
    3457 BUGS
    3458        Report all bugs to the OpenVPN team <info@openvpn.net>.
    3459 
    3460 SEE ALSO
    3461        dhcpcd(8), ifconfig(8), openssl(1), route(8), scp(1) ssh(1)
    3462 
    3463 NOTES
    3464        This product includes software developed by the OpenSSL Project ( http://www.openssl.org/
    3465        )
    3466 
    3467        For more information on the TLS protocol, see http://www.ietf.org/rfc/rfc2246.txt
    3468 
    3469        For  more  information  on  the  LZO  real-time  compression library see http://www.ober‐
    3470        humer.com/opensource/lzo/
    3471 
    3472 COPYRIGHT
    3473        Copyright (C) 2002-2010 OpenVPN Technologies, Inc. This program is free software; you can
    3474        redistribute  it  and/or modify it under the terms of the GNU General Public License ver‐
    3475        sion 2 as published by the Free Software Foundation.
    3476 
    3477 AUTHORS
    3478        James Yonan <jim@yonan.net>
    3479 
    3480 
    3481 
    3482                                         17 November 2008                              openvpn(8)
     7#!html
     8Section: Maintenance Commands (8)<BR><A HREF="#index">Index</A>
     9
     10
     11<A NAME="lbAB">&nbsp;</A>
     12<H2>NAME</H2>
     13
     14openvpn - secure IP tunnel daemon.
     15
     16<A NAME="lbAC">&nbsp;</A>
     17<H2>SYNOPSIS</H2>
     18
     19<B>
     20openvpn [ options ... ]
     21</B>
     22
     23<A NAME="lbAD">&nbsp;</A>
     24<H2>INTRODUCTION</H2>
     25
     26<P>
     27
     28OpenVPN is an open source VPN daemon by James Yonan.
     29Because OpenVPN tries to
     30be a universal VPN tool offering a great deal of flexibility,
     31there are a lot of options on this manual page.
     32If you're new to OpenVPN, you might want to skip ahead to the
     33examples section where you will see how to construct simple
     34VPNs on the command line without even needing a configuration file.
     35<P>
     36Also note that there's more documentation and examples on
     37the OpenVPN web site:
     38<I><A HREF="http://openvpn.net/">http://openvpn.net/</A></I>
     39
     40<P>
     41And if you would like to see a shorter version of this manual,
     42see the openvpn usage message which can be obtained by
     43running
     44<B>openvpn</B>
     45
     46without any parameters.
     47
     48<A NAME="lbAE">&nbsp;</A>
     49<H2>DESCRIPTION</H2>
     50
     51<P>
     52
     53OpenVPN is a robust and highly flexible VPN daemon.
     54OpenVPN supports SSL/TLS security, ethernet bridging,
     55TCP or UDP tunnel transport through proxies or NAT,
     56support for dynamic IP addresses and DHCP,
     57scalability to hundreds or thousands of users,
     58and portability to most major OS platforms.
     59<P>
     60OpenVPN is tightly bound to the OpenSSL library, and derives much
     61of its crypto capabilities from it.
     62<P>
     63OpenVPN supports
     64conventional encryption
     65using a pre-shared secret key
     66<B>(Static Key mode)</B>
     67
     68or
     69public key security
     70<B>(SSL/TLS mode)</B>
     71
     72using client &amp; server certificates.
     73OpenVPN also
     74supports non-encrypted TCP/UDP tunnels. 
     75<P>
     76OpenVPN is designed to work with the
     77<B>TUN/TAP</B>
     78
     79virtual networking interface that exists on most platforms.
     80<P>
     81Overall, OpenVPN aims to offer many of the key features of IPSec but
     82with a relatively lightweight footprint.
     83
     84<A NAME="lbAF">&nbsp;</A>
     85<H2>OPTIONS</H2>
     86
     87OpenVPN allows any option to be placed either on the command line
     88or in a configuration file.  Though all command line options are preceded
     89by a double-leading-dash (&quot;--&quot;), this prefix can be removed when
     90an option is placed in a configuration file.
     91
     92<DL COMPACT>
     93<DT><B>--help</B>
     94
     95<DD>
     96Show options.
     97
     98<DT><B>--config file</B>
     99
     100<DD>
     101Load additional config options from
     102<B>file</B>
     103
     104where each line corresponds to one command line option,
     105but with the leading '--' removed.
     106<P>
     107If
     108<B>--config file</B>
     109
     110is the only option to the openvpn command,
     111the
     112<B>--config</B>
     113
     114can be removed, and the command can be given as
     115<B>openvpn file</B>
     116
     117<P>
     118Note that
     119configuration files can be nested to a reasonable depth.
     120<P>
     121Double quotation or single quotation characters (&quot;&quot;, '')
     122can be used to enclose single parameters containing whitespace,
     123and &quot;#&quot; or &quot;;&quot; characters in the first column
     124can be used to denote comments.
     125<P>
     126Note that OpenVPN 2.0 and higher performs backslash-based shell
     127escaping for characters not in single quotations,
     128so the following mappings should be observed:
     129<P>
     130<PRE>
     131<B>\\       Maps to a single backslash character (\).
     132\&quot;       Pass a literal doublequote character (&quot;), don't
     133         interpret it as enclosing a parameter.
     134\[SPACE] Pass a literal space or tab character, don't
     135         interpret it as a parameter delimiter.
     136</B></PRE>
     137
     138<P>
     139For example on Windows, use double backslashes to
     140represent pathnames:
     141<P>
     142<PRE>
     143<B>secret &quot;c:\\OpenVPN\\secret.key&quot;
     144</B></PRE>
     145
     146<P>
     147For examples of configuration files,
     148see
     149<I><A HREF="http://openvpn.net/examples.html">http://openvpn.net/examples.html</A></I>
     150
     151<P>
     152Here is an example configuration file:
     153<P>
     154<PRE>
     155<B>#
     156# Sample OpenVPN configuration file for
     157# using a pre-shared static key.
     158#
     159# '#' or ';' may be used to delimit comments.
     160
     161# Use a dynamic tun device.
     162dev tun
     163
     164# Our remote peer
     165remote mypeer.mydomain
     166
     167# 10.1.0.1 is our local VPN endpoint
     168# 10.1.0.2 is our remote VPN endpoint
     169ifconfig 10.1.0.1 10.1.0.2
     170
     171# Our pre-shared static key
     172secret static.key
     173</B></PRE>
     174
     175
     176</DL>
     177<A NAME="lbAG">&nbsp;</A>
     178<H3>Tunnel Options:</H3>
     179
     180<DL COMPACT>
     181<DT><B>--mode m</B>
     182
     183<DD>
     184Set OpenVPN major mode.  By default, OpenVPN runs in
     185point-to-point mode (&quot;p2p&quot;).  OpenVPN 2.0 introduces
     186a new mode (&quot;server&quot;) which implements a multi-client
     187server capability.
     188
     189<DT><B>--local host</B>
     190
     191<DD>
     192Local host name or IP address for bind.
     193If specified, OpenVPN will bind to this address only.
     194If unspecified, OpenVPN will bind to all interfaces.
     195
     196<DT><B>--remote host [port] [proto]</B>
     197
     198<DD>
     199Remote host name or IP address.  On the client, multiple
     200<B>--remote</B>
     201
     202options may be specified for redundancy, each referring
     203to a different OpenVPN server.  Specifying multiple
     204<B>--remote</B>
     205
     206options for this purpose is a special case of the more
     207general connection-profile feature.  See the
     208<B>&lt;connection&gt;</B>
     209
     210documentation below.
     211<P>
     212The OpenVPN client will try to connect to a server at
     213<B>host:port</B>
     214
     215in the order specified by the list of
     216<B>--remote</B>
     217
     218options.
     219<P>
     220<B>proto</B>
     221
     222indicates the protocol to use when connecting with the
     223remote, and may be &quot;tcp&quot; or &quot;udp&quot;.
     224<P>
     225The client will move on to the next host in the list,
     226in the event of connection failure.
     227Note that at any given time, the OpenVPN client
     228will at most be connected to
     229one server.
     230<P>
     231Note that since UDP is connectionless, connection failure
     232is defined by the
     233<B>--ping</B>
     234
     235and
     236<B>--ping-restart</B>
     237
     238options.
     239<P>
     240Note the following corner case:  If you use multiple
     241<B>--remote</B>
     242
     243options, AND you are dropping root privileges on
     244the client with
     245<B>--user</B>
     246
     247and/or
     248<B>--group,</B>
     249
     250AND the client is running a non-Windows OS, if the client needs
     251to switch to a different server, and that server pushes
     252back different TUN/TAP or route settings, the client may lack
     253the necessary privileges to close and reopen the TUN/TAP interface.
     254This could cause the client to exit with a fatal error.
     255<P>
     256If
     257<B>--remote</B>
     258
     259is unspecified, OpenVPN will listen
     260for packets from any IP address, but will not act on those packets unless
     261they pass all authentication tests.  This requirement for authentication
     262is binding on all potential peers, even those from known and supposedly
     263trusted IP addresses (it is very easy to forge a source IP address on
     264a UDP packet).
     265<P>
     266When used in TCP mode,
     267<B>--remote</B>
     268
     269will act as a filter, rejecting connections from any host which does
     270not match
     271<B>host.</B>
     272
     273<P>
     274If
     275<B>host</B>
     276
     277is a DNS name which resolves to multiple IP addresses,
     278one will be randomly
     279chosen, providing a sort of basic load-balancing and
     280failover capability.
     281
     282<DT><B>--remote-random-hostname</B>
     283
     284<DD>
     285Add a random string (6 characters) to first DNS label of hostname to prevent
     286DNS caching.  For example, &quot;foo.bar.gov&quot; would be modified to
     287&quot;&lt;random-chars&gt;.foo.bar.gov&quot;.
     288
     289<DT><B>&lt;connection&gt;</B>
     290
     291<DD>
     292Define a client connection
     293profile.  Client connection profiles are groups of OpenVPN options that
     294describe how to connect to a given OpenVPN server.  Client connection
     295profiles are specified within an OpenVPN configuration file, and
     296each profile is bracketed by
     297<B>&lt;connection&gt;</B>
     298
     299and
     300<B>&lt;/connection&gt;.</B>
     301
     302<P>
     303An OpenVPN client will try each connection profile sequentially
     304until it achieves a successful connection. 
     305<P>
     306<B>--remote-random</B>
     307
     308can be used to initially &quot;scramble&quot; the connection
     309list.
     310<P>
     311Here is an example of connection profile usage:
     312<P>
     313<PRE>
     314<B>client
     315dev tun
     316
     317&lt;connection&gt;
     318remote 198.19.34.56 1194 udp
     319&lt;/connection&gt;
     320
     321&lt;connection&gt;
     322remote 198.19.34.56 443 tcp
     323&lt;/connection&gt;
     324
     325&lt;connection&gt;
     326remote 198.19.34.56 443 tcp
     327http-proxy 192.168.0.8 8080
     328http-proxy-retry
     329&lt;/connection&gt;
     330
     331&lt;connection&gt;
     332remote 198.19.36.99 443 tcp
     333http-proxy 192.168.0.8 8080
     334http-proxy-retry
     335&lt;/connection&gt;
     336
     337persist-key
     338persist-tun
     339pkcs12 client.p12
     340ns-cert-type server
     341verb 3
     342</B></PRE>
     343
     344<P>
     345First we try to connect to a server at 198.19.34.56:1194 using UDP.
     346If that fails, we then try to connect to 198.19.34.56:443 using TCP.
     347If that also fails, then try connecting through an HTTP proxy at
     348192.168.0.8:8080 to 198.19.34.56:443 using TCP.  Finally, try to
     349connect through the same proxy to a server at 198.19.36.99:443
     350using TCP.
     351<P>
     352The following OpenVPN options may be used inside of
     353a
     354<B>&lt;connection&gt;</B>
     355
     356block:
     357<P>
     358<B>bind,</B>
     359
     360<B>connect-retry,</B>
     361
     362<B>connect-retry-max,</B>
     363
     364<B>connect-timeout,</B>
     365
     366<B>float,</B>
     367
     368<B>http-proxy,</B>
     369
     370<B>http-proxy-option,</B>
     371
     372<B>http-proxy-retry,</B>
     373
     374<B>http-proxy-timeout,</B>
     375
     376<B>local,</B>
     377
     378<B>lport,</B>
     379
     380<B>nobind,</B>
     381
     382<B>port,</B>
     383
     384<B>proto,</B>
     385
     386<B>remote,</B>
     387
     388<B>rport,</B>
     389
     390<B>socks-proxy, and</B>
     391
     392<B>socks-proxy-retry.</B>
     393
     394<P>
     395A defaulting mechanism exists for specifying options to apply to
     396all
     397<B>&lt;connection&gt;</B>
     398
     399profiles.  If any of the above options (with the exception of
     400<B>remote</B>
     401
     402) appear outside of a
     403<B>&lt;connection&gt;</B>
     404
     405block, but in a configuration file which has one or more
     406<B>&lt;connection&gt;</B>
     407
     408blocks, the option setting will be used as a default for
     409<B>&lt;connection&gt;</B>
     410
     411blocks which follow it in the configuration file.
     412<P>
     413For example, suppose the
     414<B>nobind</B>
     415
     416option were placed in the sample configuration file above, near
     417the top of the file, before the first
     418<B>&lt;connection&gt;</B>
     419
     420block.  The effect would be as if
     421<B>nobind</B>
     422
     423were declared in all
     424<B>&lt;connection&gt;</B>
     425
     426blocks below it.
     427
     428<DT><B>--proto-force p</B>
     429
     430<DD>
     431When iterating through connection profiles,
     432only consider profiles using protocol
     433<B>p</B>
     434
     435('tcp'|'udp').
     436
     437<DT><B>--remote-random</B>
     438
     439<DD>
     440When multiple
     441<B>--remote</B>
     442
     443address/ports are specified, or if connection profiles are being
     444used, initially randomize the order of the list
     445as a kind of basic load-balancing measure.
     446
     447<DT><B>--proto p</B>
     448
     449<DD>
     450Use protocol
     451<B>p</B>
     452
     453for communicating with remote host.
     454<B>p</B>
     455
     456can be
     457<B>udp,</B>
     458
     459<B>tcp-client,</B>
     460
     461or
     462<B>tcp-server.</B>
     463
     464<P>
     465The default protocol is
     466<B>udp</B>
     467
     468when
     469<B>--proto</B>
     470
     471is not specified.
     472<P>
     473For UDP operation,
     474<B>--proto udp</B>
     475
     476should be specified on both peers.
     477<P>
     478For TCP operation, one peer must use
     479<B>--proto tcp-server</B>
     480
     481and the other must use
     482<B>--proto tcp-client.</B>
     483
     484A peer started with
     485<B>tcp-server</B>
     486
     487will wait indefinitely for an incoming connection.  A peer
     488started with
     489<B>tcp-client</B>
     490
     491will attempt to connect, and if that fails, will sleep for 5
     492seconds (adjustable via the
     493<B>--connect-retry</B>
     494
     495option) and try again infinite or up to N retries (adjustable via the
     496<B>--connect-retry-max</B>
     497
     498option).  Both TCP client and server will simulate
     499a SIGUSR1 restart signal if either side resets the connection.
     500<P>
     501OpenVPN is designed to operate optimally over UDP, but TCP capability is provided
     502for situations where UDP cannot be used.
     503In comparison with UDP, TCP will usually be
     504somewhat less efficient and less robust when used over unreliable or congested
     505networks.
     506<P>
     507This article outlines some of problems with tunneling IP over TCP:
     508<P>
     509<I><A HREF="http://sites.inka.de/sites/bigred/devel/tcp-tcp.html">http://sites.inka.de/sites/bigred/devel/tcp-tcp.html</A></I>
     510
     511<P>
     512There are certain cases, however, where using TCP may be advantageous from
     513a security and robustness perspective, such as tunneling non-IP or
     514application-level UDP protocols, or tunneling protocols which don't
     515possess a built-in reliability layer.
     516
     517<DT><B>--connect-retry n</B>
     518
     519<DD>
     520For
     521<B>--proto tcp-client,</B>
     522
     523take
     524<B>n</B>
     525
     526as the
     527number of seconds to wait
     528between connection retries (default=5).
     529
     530<DT><B>--connect-timeout n</B>
     531
     532<DD>
     533For
     534<B>--proto tcp-client,</B>
     535
     536set connection timeout to
     537<B>n</B>
     538
     539seconds (default=10).
     540
     541<DT><B>--connect-retry-max n</B>
     542
     543<DD>
     544For
     545<B>--proto tcp-client,</B>
     546
     547take
     548<B>n</B>
     549
     550as the
     551number of retries of connection attempt (default=infinite).
     552
     553<DT><B>--auto-proxy</B>
     554
     555<DD>
     556Try to sense HTTP or SOCKS proxy settings automatically.
     557If no settings are present, a direct connection will be attempted.
     558If both HTTP and SOCKS settings are present, HTTP will be preferred.
     559If the HTTP proxy server requires a password, it will be queried from
     560stdin or the management interface.  If the underlying OS doesn't support an API for
     561returning proxy settings, a direct connection will be attempted.
     562Currently, only Windows clients support this option via the
     563InternetQueryOption API.
     564This option exists in OpenVPN 2.1 or higher.
     565
     566<DT><B>--show-proxy-settings</B>
     567
     568<DD>
     569Show sensed HTTP or SOCKS proxy settings. Currently, only Windows clients
     570support this option.
     571
     572<DT><B>--http-proxy server port [authfile|'auto'|'auto-nct'] [auth-method]</B>
     573
     574<DD>
     575Connect to remote host through an HTTP proxy at address
     576<B>server</B>
     577
     578and port
     579<B>port.</B>
     580
     581If HTTP Proxy-Authenticate is required,
     582<B>authfile</B>
     583
     584is a file containing a username and password on 2 lines, or
     585&quot;stdin&quot; to prompt from console.
     586<P>
     587<B>auth-method</B>
     588
     589should be one of &quot;none&quot;, &quot;basic&quot;, or &quot;ntlm&quot;.
     590<P>
     591HTTP Digest authentication is supported as well, but only via
     592the
     593<B>auto</B>
     594
     595or
     596<B>auto-nct</B>
     597
     598flags (below).
     599<P>
     600The
     601<B>auto</B>
     602
     603flag causes OpenVPN to automatically determine the
     604<B>auth-method</B>
     605
     606and query stdin or the management interface for
     607username/password credentials, if required.  This flag
     608exists on OpenVPN 2.1 or higher.
     609<P>
     610The
     611<B>auto-nct</B>
     612
     613flag (no clear-text auth) instructs OpenVPN to automatically
     614determine the authentication method, but to reject weak
     615authentication protocols such as HTTP Basic Authentication.
     616
     617<DT><B>--http-proxy-retry</B>
     618
     619<DD>
     620Retry indefinitely on HTTP proxy errors.  If an HTTP proxy error
     621occurs, simulate a SIGUSR1 reset.
     622
     623<DT><B>--http-proxy-timeout n</B>
     624
     625<DD>
     626Set proxy timeout to
     627<B>n</B>
     628
     629seconds, default=5.
     630
     631<DT><B>--http-proxy-option type [parm]</B>
     632
     633<DD>
     634Set extended HTTP proxy options.
     635Repeat to set multiple options.
     636<P>
     637<B>VERSION version --</B>
     638
     639Set HTTP version number to
     640<B>version</B>
     641
     642(default=1.0).
     643<P>
     644<B>AGENT user-agent --</B>
     645
     646Set HTTP &quot;User-Agent&quot; string to
     647<B>user-agent.</B>
     648
     649
     650<DT><B>--socks-proxy server [port]</B>
     651
     652<DD>
     653Connect to remote host through a Socks5 proxy at address
     654<B>server</B>
     655
     656and port
     657<B>port</B>
     658
     659(default=1080).
     660
     661<DT><B>--socks-proxy-retry</B>
     662
     663<DD>
     664Retry indefinitely on Socks proxy errors.  If a Socks proxy error
     665occurs, simulate a SIGUSR1 reset.
     666
     667<DT><B>--resolv-retry n</B>
     668
     669<DD>
     670If hostname resolve fails for
     671<B>--remote,</B>
     672
     673retry resolve for
     674<B>n</B>
     675
     676seconds before failing.
     677<P>
     678Set
     679<B>n</B>
     680
     681to &quot;infinite&quot; to retry indefinitely.
     682<P>
     683By default,
     684<B>--resolv-retry infinite</B>
     685
     686is enabled.  You can disable by setting n=0.
     687
     688<DT><B>--float</B>
     689
     690<DD>
     691Allow remote peer to change its IP address and/or port number, such as due to
     692DHCP (this is the default if
     693<B>--remote</B>
     694
     695is not used).
     696<B>--float</B>
     697
     698when specified with
     699<B>--remote</B>
     700
     701allows an OpenVPN session to initially connect to a peer
     702at a known address, however if packets arrive from a new
     703address and pass all authentication tests, the new address
     704will take control of the session.  This is useful when
     705you are connecting to a peer which holds a dynamic address
     706such as a dial-in user or DHCP client.
     707<P>
     708Essentially,
     709<B>--float</B>
     710
     711tells OpenVPN to accept authenticated packets
     712from any address, not only the address which was specified in the
     713<B>--remote</B>
     714
     715option.
     716
     717<DT><B>--ipchange cmd</B>
     718
     719<DD>
     720Execute shell command
     721<B>cmd</B>
     722
     723when our remote ip-address is initially authenticated or
     724changes.
     725<P>
     726Execute as:
     727<P>
     728<B>cmd ip_address port_number</B>
     729
     730<P>
     731Don't use
     732<B>--ipchange</B>
     733
     734in
     735<B>--mode server</B>
     736
     737mode.  Use a
     738<B>--client-connect</B>
     739
     740script instead.
     741<P>
     742See the &quot;Environmental Variables&quot; section below for
     743additional parameters passed as environmental variables.
     744<P>
     745Note that
     746<B>cmd</B>
     747
     748can be a shell command with multiple arguments, in which
     749case all OpenVPN-generated arguments will be appended
     750to
     751<B>cmd</B>
     752
     753to build a command line which will be passed to the script.
     754<P>
     755If you are running in a dynamic IP address environment where
     756the IP addresses of either peer could change without notice,
     757you can use this script, for example, to edit the
     758<I>/etc/hosts</I>
     759
     760file with the current address of the peer.  The script will
     761be run every time the remote peer changes its IP address.
     762<P>
     763Similarly if
     764<I>our</I>
     765
     766IP address changes due to DHCP, we should configure
     767our IP address change script (see man page for
     768<B><A HREF="/man/man2html?8+dhcpcd">dhcpcd</A></B>(8)
     769
     770) to deliver a
     771<B>SIGHUP</B>
     772
     773or
     774<B>SIGUSR1</B>
     775
     776signal to OpenVPN.  OpenVPN will then
     777reestablish a connection with its most recently authenticated
     778peer on its new IP address.
     779
     780<DT><B>--port port</B>
     781
     782<DD>
     783TCP/UDP port number for both local and remote.  The current
     784default of 1194 represents the official IANA port number
     785assignment for OpenVPN and has been used since version 2.0-beta17.
     786Previous versions used port 5000 as the default.
     787
     788<DT><B>--lport port</B>
     789
     790<DD>
     791TCP/UDP port number for bind.
     792
     793<DT><B>--rport port</B>
     794
     795<DD>
     796TCP/UDP port number for remote.
     797
     798<DT><B>--bind</B>
     799
     800<DD>
     801Bind to local address and port. This is the default unless any of
     802<B>--proto tcp-client</B>
     803
     804,
     805<B>--http-proxy</B>
     806
     807or
     808<B>--socks-proxy</B>
     809
     810are used.
     811
     812<DT><B>--nobind</B>
     813
     814<DD>
     815Do not bind to local address and port.  The IP stack will allocate
     816a dynamic port for returning packets.  Since the value of the dynamic port
     817could not be known in advance by a peer, this option is only suitable for
     818peers which will be initiating connections by using the
     819<B>--remote</B>
     820
     821option.
     822
     823<DT><B>--dev tunX | tapX | null</B>
     824
     825<DD>
     826TUN/TAP virtual network device (
     827<B>X</B>
     828
     829can be omitted for a dynamic device.)
     830<P>
     831See examples section below
     832for an example on setting up a TUN device.
     833<P>
     834You must use either tun devices on both ends of the connection
     835or tap devices on both ends.  You cannot mix them, as they
     836represent different underlying network layers.
     837<P>
     838<B>tun</B>
     839
     840devices encapsulate IPv4 or IPv6 (OSI Layer 3) while
     841<B>tap</B>
     842
     843devices encapsulate Ethernet 802.3 (OSI Layer 2).
     844
     845<DT><B>--dev-type device-type</B>
     846
     847<DD>
     848Which device type are we using?
     849<B>device-type</B>
     850
     851should be
     852<B>tun</B>
     853
     854(OSI Layer 3)
     855or
     856<B>tap</B>
     857
     858(OSI Layer 2).
     859Use this option only if the TUN/TAP device used with
     860<B>--dev</B>
     861
     862does not begin with
     863<B>tun</B>
     864
     865or
     866<B>tap.</B>
     867
     868
     869<DT><B>--topology mode</B>
     870
     871<DD>
     872Configure virtual addressing topology when running in
     873<B>--dev tun</B>
     874
     875mode.  This directive has no meaning in
     876<B>--dev tap</B>
     877
     878mode, which always uses a
     879<B>subnet</B>
     880
     881topology.
     882<P>
     883If you set this directive on the server, the
     884<B>--server</B>
     885
     886and
     887<B>--server-bridge</B>
     888
     889directives will automatically push your chosen topology setting to clients
     890as well.  This directive can also be manually pushed to clients.  Like the
     891<B>--dev</B>
     892
     893directive, this directive must always be compatible between client and server.
     894<P>
     895<B>mode</B>
     896
     897can be one of:
     898<P>
     899<B>net30 --</B>
     900
     901Use a point-to-point topology, by allocating one /30 subnet per client.
     902This is designed to allow point-to-point semantics when some
     903or all of the connecting clients might be Windows systems.  This is the
     904default on OpenVPN 2.0.
     905<P>
     906<B>p2p --</B>
     907
     908Use a point-to-point topology where the remote endpoint of the client's
     909tun interface always points to the local endpoint of the server's tun interface.
     910This mode allocates a single IP address per connecting client.
     911Only use
     912when none of the connecting clients are Windows systems.  This mode
     913is functionally equivalent to the
     914<B>--ifconfig-pool-linear</B>
     915
     916directive which is available in OpenVPN 2.0 and is now deprecated.
     917<P>
     918<B>subnet --</B>
     919
     920Use a subnet rather than a point-to-point topology by
     921configuring the tun interface with a local IP address and subnet mask,
     922similar to the topology used in
     923<B>--dev tap</B>
     924
     925and ethernet bridging mode.
     926This mode allocates a single IP address per connecting client and works on
     927Windows as well.  Only available when server and clients are OpenVPN 2.1 or
     928higher, or OpenVPN 2.0.x which has been manually patched with the
     929<B>--topology</B>
     930
     931directive code.  When used on Windows, requires version 8.2 or higher
     932of the TAP-Win32 driver.  When used on *nix, requires that the tun
     933driver supports an
     934<B><A HREF="/man/man2html?8+ifconfig">ifconfig</A></B>(8)
     935
     936command which sets a subnet instead of a remote endpoint IP address.
     937<P>
     938This option exists in OpenVPN 2.1 or higher.
     939
     940<DT><B>--tun-ipv6</B>
     941
     942<DD>
     943Build a tun link capable of forwarding IPv6 traffic.
     944Should be used in conjunction with
     945<B>--dev tun</B>
     946
     947or
     948<B>--dev tunX.</B>
     949
     950A warning will be displayed
     951if no specific IPv6 TUN support for your OS has been compiled into OpenVPN.
     952
     953<DT><B>--dev-node node</B>
     954
     955<DD>
     956Explicitly set the device node rather than using
     957/dev/net/tun, /dev/tun, /dev/tap, etc.  If OpenVPN
     958cannot figure out whether
     959<B>node</B>
     960
     961is a TUN or TAP device based on the name, you should
     962also specify
     963<B>--dev-type tun</B>
     964
     965or
     966<B>--dev-type tap.</B>
     967
     968<P>
     969On Windows systems, select the TAP-Win32 adapter which
     970is named
     971<B>node</B>
     972
     973in the Network Connections Control Panel or the
     974raw GUID of the adapter enclosed by braces.
     975The
     976<B>--show-adapters</B>
     977
     978option under Windows can also be used
     979to enumerate all available TAP-Win32
     980adapters and will show both the network
     981connections control panel name and the GUID for
     982each TAP-Win32 adapter.
     983<DT><B>--lladdr address</B>
     984
     985<DD>
     986Specify the link layer address, more commonly known as the MAC address.
     987Only applied to TAP devices.
     988
     989<DT><B>--iproute cmd</B>
     990
     991<DD>
     992Set alternate command to execute instead of default iproute2 command.
     993May be used in order to execute OpenVPN in unprivileged environment.
     994
     995<DT><B>--ifconfig l rn</B>
     996
     997<DD>
     998Set TUN/TAP adapter parameters.
     999<B>l</B>
     1000
     1001is the IP address of the local VPN endpoint.
     1002For TUN devices,
     1003<B>rn</B>
     1004
     1005is the IP address of the remote VPN endpoint.
     1006For TAP devices,
     1007<B>rn</B>
     1008
     1009is the subnet mask of the virtual ethernet segment
     1010which is being created or connected to.
     1011<P>
     1012For TUN devices, which facilitate virtual
     1013point-to-point IP connections,
     1014the proper usage of
     1015<B>--ifconfig</B>
     1016
     1017is to use two private IP addresses
     1018which are not a member of any
     1019existing subnet which is in use.
     1020The IP addresses may be consecutive
     1021and should have their order reversed
     1022on the remote peer.  After the VPN
     1023is established, by pinging
     1024<B>rn,</B>
     1025
     1026you will be pinging across the VPN.
     1027<P>
     1028For TAP devices, which provide
     1029the ability to create virtual
     1030ethernet segments,
     1031<B>--ifconfig</B>
     1032
     1033is used to set an IP address and
     1034subnet mask just as a physical
     1035ethernet adapter would be
     1036similarly configured.  If you are
     1037attempting to connect to a remote
     1038ethernet bridge, the IP address
     1039and subnet should be set to values
     1040which would be valid on the
     1041the bridged ethernet segment (note
     1042also that DHCP can be used for the
     1043same purpose).
     1044<P>
     1045This option, while primarily a proxy for the
     1046<B><A HREF="/man/man2html?8+ifconfig">ifconfig</A></B>(8)
     1047
     1048command, is designed to simplify TUN/TAP
     1049tunnel configuration by providing a
     1050standard interface to the different
     1051ifconfig implementations on different
     1052platforms.
     1053<P>
     1054<B>--ifconfig</B>
     1055
     1056parameters which are IP addresses can
     1057also be specified as a DNS or /etc/hosts
     1058file resolvable name.
     1059<P>
     1060For TAP devices,
     1061<B>--ifconfig</B>
     1062
     1063should not be used if the TAP interface will be
     1064getting an IP address lease from a DHCP
     1065server.
     1066
     1067<DT><B>--ifconfig-noexec</B>
     1068
     1069<DD>
     1070Don't actually execute ifconfig/netsh commands, instead
     1071pass
     1072<B>--ifconfig</B>
     1073
     1074parameters to scripts using environmental variables.
     1075
     1076<DT><B>--ifconfig-nowarn</B>
     1077
     1078<DD>
     1079Don't output an options consistency check warning
     1080if the
     1081<B>--ifconfig</B>
     1082
     1083option on this side of the
     1084connection doesn't match the remote side.  This is useful
     1085when you want to retain the overall benefits of the
     1086options consistency check (also see
     1087<B>--disable-occ</B>
     1088
     1089option) while only disabling the ifconfig component of
     1090the check.
     1091<P>
     1092For example,
     1093if you have a configuration where the local host uses
     1094<B>--ifconfig</B>
     1095
     1096but the remote host does not, use
     1097<B>--ifconfig-nowarn</B>
     1098
     1099on the local host.
     1100<P>
     1101This option will also silence warnings about potential
     1102address conflicts which occasionally annoy more experienced
     1103users by triggering &quot;false positive&quot; warnings.
     1104
     1105<DT><B>--route network/IP [netmask] [gateway] [metric]</B>
     1106
     1107<DD>
     1108Add route to routing table after connection is established.
     1109Multiple routes can be specified.  Routes will be
     1110automatically torn down in reverse order prior to
     1111TUN/TAP device close.
     1112<P>
     1113This option is intended as
     1114a convenience proxy for the
     1115<B><A HREF="/man/man2html?8+route">route</A></B>(8)
     1116
     1117shell command,
     1118while at the same time providing portable semantics
     1119across OpenVPN's platform space.
     1120<P>
     1121<B>netmask</B>
     1122
     1123default -- 255.255.255.255
     1124<P>
     1125<B>gateway</B>
     1126
     1127default -- taken from
     1128<B>--route-gateway</B>
     1129
     1130or the second parameter to
     1131<B>--ifconfig</B>
     1132
     1133when
     1134<B>--dev tun</B>
     1135
     1136is specified.
     1137<P>
     1138<B>metric</B>
     1139
     1140default -- taken from
     1141<B>--route-metric</B>
     1142
     1143otherwise 0.
     1144<P>
     1145The default can be specified by leaving an option blank or setting
     1146it to &quot;default&quot;.
     1147<P>
     1148The
     1149<B>network</B>
     1150
     1151and
     1152<B>gateway</B>
     1153
     1154parameters can
     1155also be specified as a DNS or /etc/hosts
     1156file resolvable name, or as one of three special keywords:
     1157<P>
     1158<B>vpn_gateway</B>
     1159
     1160-- The remote VPN endpoint address
     1161(derived either from
     1162<B>--route-gateway</B>
     1163
     1164or the second parameter to
     1165<B>--ifconfig</B>
     1166
     1167when
     1168<B>--dev tun</B>
     1169
     1170is specified).
     1171<P>
     1172<B>net_gateway</B>
     1173
     1174-- The pre-existing IP default gateway, read from the routing
     1175table (not supported on all OSes).
     1176<P>
     1177<B>remote_host</B>
     1178
     1179-- The
     1180<B>--remote</B>
     1181
     1182address if OpenVPN is being run in client mode, and is undefined in server mode.
     1183
     1184<DT><B>--max-routes n</B>
     1185
     1186<DD>
     1187Allow a maximum number of n
     1188<B>--route</B>
     1189
     1190options to be specified, either in the local configuration file,
     1191or pulled from an OpenVPN server.  By default, n=100.
     1192
     1193<DT><B>--route-gateway gw|'dhcp'</B>
     1194
     1195<DD>
     1196Specify a default gateway
     1197<B>gw</B>
     1198
     1199for use with
     1200<B>--route.</B>
     1201
     1202<P>
     1203If
     1204<B>dhcp</B>
     1205
     1206is specified as the parameter,
     1207the gateway address will be extracted from a DHCP
     1208negotiation with the OpenVPN server-side LAN.
     1209
     1210<DT><B>--route-metric m</B>
     1211
     1212<DD>
     1213Specify a default metric
     1214<B>m</B>
     1215
     1216for use with
     1217<B>--route.</B>
     1218
     1219
     1220<DT><B>--route-delay [n] [w]</B>
     1221
     1222<DD>
     1223Delay
     1224<B>n</B>
     1225
     1226seconds (default=0) after connection
     1227establishment, before adding routes. If
     1228<B>n</B>
     1229
     1230is 0, routes will be added immediately upon connection
     1231establishment.  If
     1232<B>--route-delay</B>
     1233
     1234is omitted, routes will be added immediately after TUN/TAP device
     1235open and
     1236<B>--up</B>
     1237
     1238script execution, before any
     1239<B>--user</B>
     1240
     1241or
     1242<B>--group</B>
     1243
     1244privilege downgrade (or
     1245<B>--chroot</B>
     1246
     1247execution.)
     1248<P>
     1249This option is designed to be useful in scenarios where DHCP is
     1250used to set
     1251tap adapter addresses.  The delay will give the DHCP handshake
     1252time to complete before routes are added.
     1253<P>
     1254On Windows,
     1255<B>--route-delay</B>
     1256
     1257tries to be more intelligent by waiting
     1258<B>w</B>
     1259
     1260seconds (w=30 by default)
     1261for the TAP-Win32 adapter to come up before adding routes.
     1262
     1263<DT><B>--route-up cmd</B>
     1264
     1265<DD>
     1266Execute shell command
     1267<B>cmd</B>
     1268
     1269after routes are added, subject to
     1270<B>--route-delay.</B>
     1271
     1272<P>
     1273See the &quot;Environmental Variables&quot; section below for
     1274additional parameters passed as environmental variables.
     1275<P>
     1276Note that
     1277<B>cmd</B>
     1278
     1279can be a shell command with multiple arguments.
     1280
     1281<DT><B>--route-noexec</B>
     1282
     1283<DD>
     1284Don't add or remove routes automatically.  Instead pass routes to
     1285<B>--route-up</B>
     1286
     1287script using environmental variables.
     1288
     1289<DT><B>--route-nopull</B>
     1290
     1291<DD>
     1292When used with
     1293<B>--client</B>
     1294
     1295or
     1296<B>--pull,</B>
     1297
     1298accept options pushed by server EXCEPT for routes.
     1299<P>
     1300When used on the client, this option effectively bars the
     1301server from adding routes to the client's routing table,
     1302however note that this option still allows the server
     1303to set the TCP/IP properties of the client's TUN/TAP interface.
     1304
     1305<DT><B>--allow-pull-fqdn</B>
     1306
     1307<DD>
     1308Allow client to pull DNS names from server (rather than being limited
     1309to IP address) for
     1310<B>--ifconfig,</B>
     1311
     1312<B>--route,</B>
     1313
     1314and
     1315<B>--route-gateway.</B>
     1316
     1317
     1318<DT><B>--redirect-gateway flags...</B>
     1319
     1320<DD>
     1321(Experimental) Automatically execute routing commands to cause all outgoing IP traffic
     1322to be redirected over the VPN.
     1323<P>
     1324This option performs three steps:
     1325<P>
     1326<B>(1)</B>
     1327
     1328Create a static route for the
     1329<B>--remote</B>
     1330
     1331address which forwards to the pre-existing default gateway.
     1332This is done so that
     1333<B>(3)</B>
     1334
     1335will not create a routing loop.
     1336<P>
     1337<B>(2)</B>
     1338
     1339Delete the default gateway route.
     1340<P>
     1341<B>(3)</B>
     1342
     1343Set the new default gateway to be the VPN endpoint address (derived either from
     1344<B>--route-gateway</B>
     1345
     1346or the second parameter to
     1347<B>--ifconfig</B>
     1348
     1349when
     1350<B>--dev tun</B>
     1351
     1352is specified).
     1353<P>
     1354When the tunnel is torn down, all of the above steps are reversed so
     1355that the original default route is restored.
     1356<P>
     1357Option flags:
     1358<P>
     1359<B>local --</B>
     1360
     1361Add the
     1362<B>local</B>
     1363
     1364flag if both OpenVPN servers are directly connected via a common subnet,
     1365such as with wireless.  The
     1366<B>local</B>
     1367
     1368flag will cause step
     1369<B>1</B>
     1370
     1371above to be omitted.
     1372<P>
     1373<B>def1 --</B>
     1374
     1375Use this flag to override
     1376the default gateway by using 0.0.0.0/1 and 128.0.0.0/1
     1377rather than 0.0.0.0/0.  This has the benefit of overriding
     1378but not wiping out the original default gateway.
     1379<P>
     1380<B>bypass-dhcp --</B>
     1381
     1382Add a direct route to the DHCP server (if it is non-local) which
     1383bypasses the tunnel
     1384(Available on Windows clients, may not be available
     1385on non-Windows clients).
     1386<P>
     1387<B>bypass-dns --</B>
     1388
     1389Add a direct route to the DNS server(s) (if they are non-local) which
     1390bypasses the tunnel
     1391(Available on Windows clients, may not be available
     1392on non-Windows clients).
     1393<P>
     1394Using the def1 flag is highly recommended.
     1395
     1396<DT><B>--redirect-private [flags]</B>
     1397
     1398<DD>
     1399Like --redirect-gateway, but omit actually changing the default
     1400gateway.  Useful when pushing private subnets.
     1401
     1402<DT><B>--link-mtu n</B>
     1403
     1404<DD>
     1405Sets an upper bound on the size of UDP packets which are sent
     1406between OpenVPN peers.  It's best not to set this parameter unless
     1407you know what you're doing.
     1408
     1409<DT><B>--tun-mtu n</B>
     1410
     1411<DD>
     1412Take the TUN device MTU to be
     1413<B>n</B>
     1414
     1415and derive the link MTU
     1416from it (default=1500).  In most cases, you will probably want to
     1417leave this parameter set to its default value.
     1418<P>
     1419The MTU (Maximum Transmission Units) is
     1420the maximum datagram size in bytes that can be sent unfragmented
     1421over a particular network path.  OpenVPN requires that packets
     1422on the control or data channels be sent unfragmented.
     1423<P>
     1424MTU problems often manifest themselves as connections which
     1425hang during periods of active usage.
     1426<P>
     1427It's best to use the
     1428<B>--fragment</B>
     1429
     1430and/or
     1431<B>--mssfix</B>
     1432
     1433options to deal with MTU sizing issues.
     1434
     1435<DT><B>--tun-mtu-extra n</B>
     1436
     1437<DD>
     1438Assume that the TUN/TAP device might return as many as
     1439<B>n</B>
     1440
     1441bytes more than the
     1442<B>--tun-mtu</B>
     1443
     1444size on read.  This parameter defaults to 0, which is sufficient for
     1445most TUN devices.  TAP devices may introduce additional overhead in excess
     1446of the MTU size, and a setting of 32 is the default when TAP devices are used.
     1447This parameter only controls internal OpenVPN buffer sizing,
     1448so there is no transmission overhead associated with using a larger value.
     1449
     1450<DT><B>--mtu-disc type</B>
     1451
     1452<DD>
     1453Should we do Path MTU discovery on TCP/UDP channel?  Only supported on OSes such
     1454as Linux that supports the necessary system call to set.
     1455<P>
     1456<B>'no'</B>
     1457
     1458-- Never send DF (Don't Fragment) frames
     1459<BR>
     1460
     1461<B>'maybe'</B>
     1462
     1463-- Use per-route hints
     1464<BR>
     1465
     1466<B>'yes'</B>
     1467
     1468-- Always DF (Don't Fragment)
     1469<BR>
     1470
     1471
     1472<DT><B>--mtu-test</B>
     1473
     1474<DD>
     1475To empirically measure MTU on connection startup,
     1476add the
     1477<B>--mtu-test</B>
     1478
     1479option to your configuration.
     1480OpenVPN will send ping packets of various sizes
     1481to the remote peer and measure the largest packets
     1482which were successfully received.  The
     1483<B>--mtu-test</B>
     1484
     1485process normally takes about 3 minutes to complete.
     1486
     1487<DT><B>--fragment max</B>
     1488
     1489<DD>
     1490Enable internal datagram fragmentation so
     1491that no UDP datagrams are sent which
     1492are larger than
     1493<B>max</B>
     1494
     1495bytes.
     1496<P>
     1497The
     1498<B>max</B>
     1499
     1500parameter is interpreted in the same way as the
     1501<B>--link-mtu</B>
     1502
     1503parameter, i.e. the UDP packet size after encapsulation
     1504overhead has been added in, but not including
     1505the UDP header itself.
     1506<P>
     1507The
     1508<B>--fragment</B>
     1509
     1510option only makes sense when you are using the UDP protocol (
     1511<B>--proto udp</B>
     1512
     1513).
     1514<P>
     1515<B>--fragment</B>
     1516
     1517adds 4 bytes of overhead per datagram.
     1518<P>
     1519See the
     1520<B>--mssfix</B>
     1521
     1522option below for an important related option to
     1523<B>--fragment.</B>
     1524
     1525<P>
     1526It should also be noted that this option is not meant to replace
     1527UDP fragmentation at the IP stack level.  It is only meant as a
     1528last resort when path MTU discovery is broken.  Using this option
     1529is less efficient than fixing path MTU discovery for your IP link and
     1530using native IP fragmentation instead.
     1531<P>
     1532Having said that, there are circumstances where using OpenVPN's
     1533internal fragmentation capability may be your only option, such
     1534as tunneling a UDP multicast stream which requires fragmentation.
     1535
     1536<DT><B>--mssfix max</B>
     1537
     1538<DD>
     1539Announce to TCP sessions running over the tunnel that they should limit
     1540their send packet sizes such that after OpenVPN has encapsulated them,
     1541the resulting UDP packet size that OpenVPN sends to its peer will not
     1542exceed
     1543<B>max</B>
     1544
     1545bytes. The default value is
     1546<B>1450.</B>
     1547
     1548<P>
     1549The
     1550<B>max</B>
     1551
     1552parameter is interpreted in the same way as the
     1553<B>--link-mtu</B>
     1554
     1555parameter, i.e. the UDP packet size after encapsulation
     1556overhead has been added in, but not including
     1557the UDP header itself.
     1558<P>
     1559The
     1560<B>--mssfix</B>
     1561
     1562option only makes sense when you are using the UDP protocol
     1563for OpenVPN peer-to-peer communication, i.e.
     1564<B>--proto udp.</B>
     1565
     1566<P>
     1567<B>--mssfix</B>
     1568
     1569and
     1570<B>--fragment</B>
     1571
     1572can be ideally used together, where
     1573<B>--mssfix</B>
     1574
     1575will try to keep TCP from needing
     1576packet fragmentation in the first place,
     1577and if big packets come through anyhow
     1578(from protocols other than TCP),
     1579<B>--fragment</B>
     1580
     1581will internally fragment them.
     1582<P>
     1583Both
     1584<B>--fragment</B>
     1585
     1586and
     1587<B>--mssfix</B>
     1588
     1589are designed to work around cases where Path MTU discovery
     1590is broken on the network path between OpenVPN peers.
     1591<P>
     1592The usual symptom of such a breakdown is an OpenVPN
     1593connection which successfully starts, but then stalls
     1594during active usage.
     1595<P>
     1596If
     1597<B>--fragment</B>
     1598
     1599and
     1600<B>--mssfix</B>
     1601
     1602are used together,
     1603<B>--mssfix</B>
     1604
     1605will take its default
     1606<B>max</B>
     1607
     1608parameter from the
     1609<B>--fragment max</B>
     1610
     1611option.
     1612<P>
     1613Therefore, one could lower the maximum UDP packet size
     1614to 1300 (a good first try for solving MTU-related
     1615connection problems) with the following options:
     1616<P>
     1617<B>--tun-mtu 1500 --fragment 1300 --mssfix</B>
     1618
     1619
     1620<DT><B>--sndbuf size</B>
     1621
     1622<DD>
     1623Set the TCP/UDP socket send buffer size.
     1624Currently defaults to 65536 bytes.
     1625
     1626<DT><B>--rcvbuf size</B>
     1627
     1628<DD>
     1629Set the TCP/UDP socket receive buffer size.
     1630Currently defaults to 65536 bytes.
     1631
     1632<DT><B>--socket-flags flags...</B>
     1633
     1634<DD>
     1635Apply the given flags to the OpenVPN transport socket.
     1636Currently, only
     1637<B>TCP_NODELAY</B>
     1638
     1639is supported.
     1640<P>
     1641The
     1642<B>TCP_NODELAY</B>
     1643
     1644socket flag is useful in TCP mode, and causes the kernel
     1645to send tunnel packets immediately over the TCP connection without
     1646trying to group several smaller packets into a larger packet.
     1647This can result in a considerably improvement in latency.
     1648<P>
     1649This option is pushable from server to client, and should be used
     1650on both client and server for maximum effect.
     1651
     1652<DT><B>--txqueuelen n</B>
     1653
     1654<DD>
     1655(Linux only) Set the TX queue length on the TUN/TAP interface.
     1656Currently defaults to 100.
     1657
     1658<DT><B>--shaper n</B>
     1659
     1660<DD>
     1661Limit bandwidth of outgoing tunnel data to
     1662<B>n</B>
     1663
     1664bytes per second on the TCP/UDP port.
     1665If you want to limit the bandwidth
     1666in both directions, use this option on both peers.
     1667<P>
     1668OpenVPN uses the following algorithm to implement
     1669traffic shaping: Given a shaper rate of
     1670<I>n</I>
     1671
     1672bytes per second, after a datagram write of
     1673<I>b</I>
     1674
     1675bytes is queued on the TCP/UDP port, wait a minimum of
     1676<I>(b / n)</I>
     1677
     1678seconds before queuing the next write.
     1679<P>
     1680It should be noted that OpenVPN supports multiple
     1681tunnels between the same two peers, allowing you
     1682to construct full-speed and reduced bandwidth tunnels
     1683at the same time,
     1684routing low-priority data such as off-site backups
     1685over the reduced bandwidth tunnel, and other data
     1686over the full-speed tunnel.
     1687<P>
     1688Also note that for low bandwidth tunnels
     1689(under 1000 bytes per second), you should probably
     1690use lower MTU values as well (see above), otherwise
     1691the packet latency will grow so large as to trigger
     1692timeouts in the TLS layer and TCP connections running
     1693over the tunnel.
     1694<P>
     1695OpenVPN allows
     1696<B>n</B>
     1697
     1698to be between 100 bytes/sec and 100 Mbytes/sec.
     1699
     1700<DT><B>--inactive n [bytes]</B>
     1701
     1702<DD>
     1703Causes OpenVPN to exit after
     1704<B>n</B>
     1705
     1706seconds of inactivity on the TUN/TAP device. The time length of
     1707inactivity is measured since the last incoming or outgoing tunnel
     1708packet.  The default value is 0 seconds, which disables this feature.
     1709<P>
     1710If the optional
     1711<B>bytes</B>
     1712
     1713parameter is included,
     1714exit if less than
     1715<B>bytes</B>
     1716
     1717of combined in/out traffic are produced on the tun/tap device
     1718in
     1719<B>n</B>
     1720
     1721seconds.
     1722<P>
     1723In any case, OpenVPN's internal ping packets (which are just
     1724keepalives) and TLS control packets are not considered
     1725&quot;activity&quot;, nor are they counted as traffic, as they are used
     1726internally by OpenVPN and are not an indication of actual user
     1727activity.
     1728
     1729<DT><B>--ping n</B>
     1730
     1731<DD>
     1732Ping remote over the TCP/UDP control channel
     1733if no packets have been sent for at least
     1734<B>n</B>
     1735
     1736seconds (specify
     1737<B>--ping</B>
     1738
     1739on both peers to cause ping packets to be sent in both directions since
     1740OpenVPN ping packets are not echoed like IP ping packets).
     1741When used in one of OpenVPN's secure modes (where
     1742<B>--secret, --tls-server,</B>
     1743
     1744or
     1745<B>--tls-client</B>
     1746
     1747is specified), the ping packet
     1748will be cryptographically secure.
     1749<P>
     1750This option has two intended uses:
     1751<P>
     1752(1) Compatibility
     1753with stateful firewalls.  The periodic ping will ensure that
     1754a stateful firewall rule which allows OpenVPN UDP packets to
     1755pass will not time out.
     1756<P>
     1757(2) To provide a basis for the remote to test the existence
     1758of its peer using the
     1759<B>--ping-exit</B>
     1760
     1761option.
     1762
     1763<DT><B>--ping-exit n</B>
     1764
     1765<DD>
     1766Causes OpenVPN to exit after
     1767<B>n</B>
     1768
     1769seconds pass without reception of a ping
     1770or other packet from remote.
     1771This option can be combined with
     1772<B>--inactive, --ping,</B>
     1773
     1774and
     1775<B>--ping-exit</B>
     1776
     1777to create a two-tiered inactivity disconnect.
     1778<P>
     1779For example,
     1780<P>
     1781<B>openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60</B>
     1782
     1783<P>
     1784when used on both peers will cause OpenVPN to exit within 60
     1785seconds if its peer disconnects, but will exit after one
     1786hour if no actual tunnel data is exchanged.
     1787
     1788<DT><B>--ping-restart n</B>
     1789
     1790<DD>
     1791Similar to
     1792<B>--ping-exit,</B>
     1793
     1794but trigger a
     1795<B>SIGUSR1</B>
     1796
     1797restart after
     1798<B>n</B>
     1799
     1800seconds pass without reception of a ping
     1801or other packet from remote.
     1802<P>
     1803This option is useful in cases
     1804where the remote peer has a dynamic IP address and
     1805a low-TTL DNS name is used to track the IP address using
     1806a service such as
     1807<I><A HREF="http://dyndns.org/">http://dyndns.org/</A></I>
     1808
     1809+ a dynamic DNS client such
     1810as
     1811<B>ddclient.</B>
     1812
     1813<P>
     1814If the peer cannot be reached, a restart will be triggered, causing
     1815the hostname used with
     1816<B>--remote</B>
     1817
     1818to be re-resolved (if
     1819<B>--resolv-retry</B>
     1820
     1821is also specified).
     1822<P>
     1823In server mode,
     1824<B>--ping-restart, --inactive,</B>
     1825
     1826or any other type of internally generated signal will always be
     1827applied to
     1828individual client instance objects, never to whole server itself.
     1829Note also in server mode that any internally generated signal
     1830which would normally cause a restart, will cause the deletion
     1831of the client instance object instead.
     1832<P>
     1833In client mode, the
     1834<B>--ping-restart</B>
     1835
     1836parameter is set to 120 seconds by default.  This default will
     1837hold until the client pulls a replacement value from the server, based on
     1838the
     1839<B>--keepalive</B>
     1840
     1841setting in the server configuration.
     1842To disable the 120 second default, set
     1843<B>--ping-restart 0</B>
     1844
     1845on the client.
     1846<P>
     1847See the signals section below for more information
     1848on
     1849<B>SIGUSR1.</B>
     1850
     1851<P>
     1852Note that the behavior of
     1853<B>SIGUSR1</B>
     1854
     1855can be modified by the
     1856<B>--persist-tun, --persist-key, --persist-local-ip,</B>
     1857
     1858and
     1859<B>--persist-remote-ip</B>
     1860
     1861options.
     1862<P>
     1863Also note that
     1864<B>--ping-exit</B>
     1865
     1866and
     1867<B>--ping-restart</B>
     1868
     1869are mutually exclusive and cannot be used together.
     1870
     1871<DT><B>--keepalive n m</B>
     1872
     1873<DD>
     1874A helper directive designed to simplify the expression of
     1875<B>--ping</B>
     1876
     1877and
     1878<B>--ping-restart</B>
     1879
     1880in server mode configurations.
     1881<P>
     1882For example,
     1883<B>--keepalive 10 60</B>
     1884
     1885expands as follows:
     1886<P>
     1887<PRE>
     1888<B> if mode server:
     1889   ping 10
     1890   ping-restart 120
     1891   push &quot;ping 10&quot;
     1892   push &quot;ping-restart 60&quot;
     1893 else
     1894   ping 10
     1895   ping-restart 60
     1896</B></PRE>
     1897
     1898
     1899<DT><B>--ping-timer-rem</B>
     1900
     1901<DD>
     1902Run the
     1903<B>--ping-exit</B>
     1904
     1905/
     1906<B>--ping-restart</B>
     1907
     1908timer only if we have a remote address.  Use this option if you are
     1909starting the daemon in listen mode (i.e. without an explicit
     1910<B>--remote</B>
     1911
     1912peer), and you don't want to start clocking timeouts until a remote
     1913peer connects.
     1914
     1915<DT><B>--persist-tun</B>
     1916
     1917<DD>
     1918Don't close and reopen TUN/TAP device or run up/down scripts
     1919across
     1920<B>SIGUSR1</B>
     1921
     1922or
     1923<B>--ping-restart</B>
     1924
     1925restarts.
     1926<P>
     1927<B>SIGUSR1</B>
     1928
     1929is a restart signal similar to
     1930<B>SIGHUP,</B>
     1931
     1932but which offers finer-grained control over
     1933reset options.
     1934
     1935<DT><B>--persist-key</B>
     1936
     1937<DD>
     1938Don't re-read key files across
     1939<B>SIGUSR1</B>
     1940
     1941or
     1942<B>--ping-restart.</B>
     1943
     1944<P>
     1945This option can be combined with
     1946<B>--user nobody</B>
     1947
     1948to allow restarts triggered by the
     1949<B>SIGUSR1</B>
     1950
     1951signal.
     1952Normally if you drop root privileges in OpenVPN,
     1953the daemon cannot be restarted since it will now be unable to re-read protected
     1954key files.
     1955<P>
     1956This option solves the problem by persisting keys across
     1957<B>SIGUSR1</B>
     1958
     1959resets, so they don't need to be re-read.
     1960
     1961<DT><B>--persist-local-ip</B>
     1962
     1963<DD>
     1964Preserve initially resolved local IP address and port number
     1965across
     1966<B>SIGUSR1</B>
     1967
     1968or
     1969<B>--ping-restart</B>
     1970
     1971restarts.
     1972
     1973<DT><B>--persist-remote-ip</B>
     1974
     1975<DD>
     1976Preserve most recently authenticated remote IP address and port number
     1977across
     1978<B>SIGUSR1</B>
     1979
     1980or
     1981<B>--ping-restart</B>
     1982
     1983restarts.
     1984
     1985<DT><B>--mlock</B>
     1986
     1987<DD>
     1988Disable paging by calling the POSIX mlockall function.
     1989Requires that OpenVPN be initially run as root (though
     1990OpenVPN can subsequently downgrade its UID using the
     1991<B>--user</B>
     1992
     1993option).
     1994<P>
     1995Using this option ensures that key material and tunnel
     1996data are never written to disk due to virtual
     1997memory paging operations which occur under most
     1998modern operating systems.  It ensures that even if an
     1999attacker was able to crack the box running OpenVPN, he
     2000would not be able to scan the system swap file to
     2001recover previously used
     2002ephemeral keys, which are used for a period of time
     2003governed by the
     2004<B>--reneg</B>
     2005
     2006options (see below), then are discarded.
     2007<P>
     2008The downside
     2009of using
     2010<B>--mlock</B>
     2011
     2012is that it will reduce the amount of physical
     2013memory available to other applications.
     2014
     2015<DT><B>--up cmd</B>
     2016
     2017<DD>
     2018Shell command to run after successful TUN/TAP device open
     2019(pre
     2020<B>--user</B>
     2021
     2022UID change).  The up script is useful for specifying route
     2023commands which route IP traffic destined for
     2024private subnets which exist at the other
     2025end of the VPN connection into the tunnel.
     2026<P>
     2027For
     2028<B>--dev tun</B>
     2029
     2030execute as:
     2031<P>
     2032<B>cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [ init | restart ]</B>
     2033
     2034<P>
     2035For
     2036<B>--dev tap</B>
     2037
     2038execute as:
     2039<P>
     2040<B>cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [ init | restart ]</B>
     2041
     2042<P>
     2043See the &quot;Environmental Variables&quot; section below for
     2044additional parameters passed as environmental variables.
     2045<P>
     2046Note that
     2047<B>cmd</B>
     2048
     2049can be a shell command with multiple arguments, in which
     2050case all OpenVPN-generated arguments will be appended
     2051to
     2052<B>cmd</B>
     2053
     2054to build a command line which will be passed to the shell.
     2055<P>
     2056Typically,
     2057<B>cmd</B>
     2058
     2059will run a script to add routes to the tunnel.
     2060<P>
     2061Normally the up script is called after the TUN/TAP device is opened.
     2062In this context, the last command line parameter passed to the script
     2063will be
     2064<I>init.</I>
     2065
     2066If the
     2067<B>--up-restart</B>
     2068
     2069option is also used, the up script will be called for restarts as
     2070well.  A restart is considered to be a partial reinitialization
     2071of OpenVPN where the TUN/TAP instance is preserved (the
     2072<B>--persist-tun</B>
     2073
     2074option will enable such preservation).  A restart
     2075can be generated by a SIGUSR1 signal, a
     2076<B>--ping-restart</B>
     2077
     2078timeout, or a connection reset when the TCP protocol is enabled
     2079with the
     2080<B>--proto</B>
     2081
     2082option.  If a restart occurs, and
     2083<B>--up-restart</B>
     2084
     2085has been specified, the up script will be called with
     2086<I>restart</I>
     2087
     2088as the last parameter.
     2089<P>
     2090The following standalone example shows how the
     2091<B>--up</B>
     2092
     2093script can be called in both an initialization and restart context.
     2094(NOTE: for security reasons, don't run the following example unless UDP port
     20959999 is blocked by your firewall.  Also, the example will run indefinitely,
     2096so you should abort with control-c).
     2097<P>
     2098<B>openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 --up 'echo up' --down 'echo down' --persist-tun --up-restart</B>
     2099
     2100<P>
     2101Note that OpenVPN also provides the
     2102<B>--ifconfig</B>
     2103
     2104option to automatically ifconfig the TUN device,
     2105eliminating the need to define an
     2106<B>--up</B>
     2107
     2108script, unless you also want to configure routes
     2109in the
     2110<B>--up</B>
     2111
     2112script.
     2113<P>
     2114If
     2115<B>--ifconfig</B>
     2116
     2117is also specified, OpenVPN will pass the ifconfig local
     2118and remote endpoints on the command line to the
     2119<B>--up</B>
     2120
     2121script so that they can be used to configure routes such as:
     2122<P>
     2123<B>route add -net 10.0.0.0 netmask 255.255.255.0 gw $5</B>
     2124
     2125
     2126<DT><B>--up-delay</B>
     2127
     2128<DD>
     2129Delay TUN/TAP open and possible
     2130<B>--up</B>
     2131
     2132script execution
     2133until after TCP/UDP connection establishment with peer.
     2134<P>
     2135In
     2136<B>--proto udp</B>
     2137
     2138mode, this option normally requires the use of
     2139<B>--ping</B>
     2140
     2141to allow connection initiation to be sensed in the absence
     2142of tunnel data, since UDP is a &quot;connectionless&quot; protocol.
     2143<P>
     2144On Windows, this option will delay the TAP-Win32 media state
     2145transitioning to &quot;connected&quot; until connection establishment,
     2146i.e. the receipt of the first authenticated packet from the peer.
     2147
     2148<DT><B>--down cmd</B>
     2149
     2150<DD>
     2151Shell command to run after TUN/TAP device close
     2152(post
     2153<B>--user</B>
     2154
     2155UID change and/or
     2156<B>--chroot</B>
     2157
     2158).  Called with the same parameters and environmental
     2159variables as the
     2160<B>--up</B>
     2161
     2162option above.
     2163<P>
     2164Note that if you reduce privileges by using
     2165<B>--user</B>
     2166
     2167and/or
     2168<B>--group,</B>
     2169
     2170your
     2171<B>--down</B>
     2172
     2173script will also run at reduced privilege.
     2174
     2175<DT><B>--down-pre</B>
     2176
     2177<DD>
     2178Call
     2179<B>--down</B>
     2180
     2181cmd/script before, rather than after, TUN/TAP close.
     2182
     2183<DT><B>--up-restart</B>
     2184
     2185<DD>
     2186Enable the
     2187<B>--up</B>
     2188
     2189and
     2190<B>--down</B>
     2191
     2192scripts to be called for restarts as well as initial program start.
     2193This option is described more fully above in the
     2194<B>--up</B>
     2195
     2196option documentation.
     2197
     2198<DT><B>--setenv name value</B>
     2199
     2200<DD>
     2201Set a custom environmental variable
     2202<B>name=value</B>
     2203
     2204to pass to script.
     2205
     2206<DT><B>--setenv FORWARD_COMPATIBLE 1</B>
     2207
     2208<DD>
     2209Relax config file syntax checking so that unknown directives
     2210will trigger a warning but not a fatal error,
     2211on the assumption that a given unknown directive might be valid
     2212in future OpenVPN versions.
     2213<P>
     2214This option should be used with caution, as there are good security
     2215reasons for having OpenVPN fail if it detects problems in a
     2216config file.  Having said that, there are valid reasons for wanting
     2217new software features to gracefully degrade when encountered by
     2218older software versions.
     2219
     2220<DT><B>--setenv-safe name value</B>
     2221
     2222<DD>
     2223Set a custom environmental variable
     2224<B>OPENVPN_name=value</B>
     2225
     2226to pass to script.
     2227<P>
     2228This directive is designed to be pushed by the server to clients,
     2229and the prepending of &quot;OPENVPN_&quot; to the environmental variable
     2230is a safety precaution to prevent a LD_PRELOAD style attack
     2231from a malicious or compromised server.
     2232
     2233<DT><B>--script-security level [method]</B>
     2234
     2235<DD>
     2236This directive offers policy-level control over OpenVPN's usage of external programs
     2237and scripts.  Lower
     2238<B>level</B>
     2239
     2240values are more restrictive, higher values are more permissive.  Settings for
     2241<B>level:</B>
     2242
     2243<P>
     2244<B>0 --</B>
     2245
     2246Strictly no calling of external programs.
     2247<BR>
     2248
     2249<B>1 --</B>
     2250
     2251(Default) Only call built-in executables such as ifconfig, ip, route, or netsh.
     2252<BR>
     2253
     2254<B>2 --</B>
     2255
     2256Allow calling of built-in executables and user-defined scripts.
     2257<BR>
     2258
     2259<B>3 --</B>
     2260
     2261Allow passwords to be passed to scripts via environmental variables (potentially unsafe).
     2262<P>
     2263The
     2264<B>method</B>
     2265
     2266parameter indicates how OpenVPN should call external commands and scripts.
     2267Settings for
     2268<B>method:</B>
     2269
     2270<P>
     2271<B>execve --</B>
     2272
     2273(default) Use execve() function on Unix family OSes and CreateProcess() on Windows.
     2274<BR>
     2275
     2276<B>system --</B>
     2277
     2278Use system() function (deprecated and less safe since the external program command
     2279line is subject to shell expansion).
     2280<P>
     2281The
     2282<B>--script-security</B>
     2283
     2284option was introduced in OpenVPN 2.1_rc9.  For configuration file compatibility
     2285with previous OpenVPN versions, use:
     2286<B>--script-security 3 system</B>
     2287
     2288
     2289<DT><B>--disable-occ</B>
     2290
     2291<DD>
     2292Don't output a warning message if option inconsistencies are detected between
     2293peers.  An example of an option inconsistency would be where one peer uses
     2294<B>--dev tun</B>
     2295
     2296while the other peer uses
     2297<B>--dev tap.</B>
     2298
     2299<P>
     2300Use of this option is discouraged, but is provided as
     2301a temporary fix in situations where a recent version of OpenVPN must
     2302connect to an old version.
     2303
     2304<DT><B>--user user</B>
     2305
     2306<DD>
     2307Change the user ID of the OpenVPN process to
     2308<B>user</B>
     2309
     2310after initialization, dropping privileges in the process.
     2311This option is useful to protect the system
     2312in the event that some hostile party was able to gain control of
     2313an OpenVPN session.  Though OpenVPN's security features make
     2314this unlikely, it is provided as a second line of defense.
     2315<P>
     2316By setting
     2317<B>user</B>
     2318
     2319to
     2320<I>nobody</I>
     2321
     2322or somebody similarly unprivileged, the hostile party would be
     2323limited in what damage they could cause.  Of course once
     2324you take away privileges, you cannot return them
     2325to an OpenVPN session.  This means, for example, that if
     2326you want to reset an OpenVPN daemon with a
     2327<B>SIGUSR1</B>
     2328
     2329signal
     2330(for example in response
     2331to a DHCP reset), you should make use of one or more of the
     2332<B>--persist</B>
     2333
     2334options to ensure that OpenVPN doesn't need to execute any privileged
     2335operations in order to restart (such as re-reading key files
     2336or running
     2337<B>ifconfig</B>
     2338
     2339on the TUN device).
     2340
     2341<DT><B>--group group</B>
     2342
     2343<DD>
     2344Similar to the
     2345<B>--user</B>
     2346
     2347option,
     2348this option changes the group ID of the OpenVPN process to
     2349<B>group</B>
     2350
     2351after initialization.
     2352
     2353<DT><B>--cd dir</B>
     2354
     2355<DD>
     2356Change directory to
     2357<B>dir</B>
     2358
     2359prior to reading any files such as
     2360configuration files, key files, scripts, etc.
     2361<B>dir</B>
     2362
     2363should be an absolute path, with a leading &quot;/&quot;,
     2364and without any references
     2365to the current directory such as &quot;.&quot; or &quot;..&quot;.
     2366<P>
     2367This option is useful when you are running
     2368OpenVPN in
     2369<B>--daemon</B>
     2370
     2371mode, and you want to consolidate all of
     2372your OpenVPN control files in one location.
     2373
     2374<DT><B>--chroot dir</B>
     2375
     2376<DD>
     2377Chroot to
     2378<B>dir</B>
     2379
     2380after initialization. 
     2381<B>--chroot</B>
     2382
     2383essentially redefines
     2384<B>dir</B>
     2385
     2386as being the top
     2387level directory tree (/).  OpenVPN will therefore
     2388be unable to access any files outside this tree.
     2389This can be desirable from a security standpoint.
     2390<P>
     2391Since the chroot operation is delayed until after
     2392initialization, most OpenVPN options that reference
     2393files will operate in a pre-chroot context.
     2394<P>
     2395In many cases, the
     2396<B>dir</B>
     2397
     2398parameter can point to an empty directory, however
     2399complications can result when scripts or restarts
     2400are executed after the chroot operation.
     2401
     2402<DT><B>--setcon context</B>
     2403
     2404<DD>
     2405Apply SELinux
     2406<B>context</B>
     2407
     2408after initialization. This
     2409essentially provides the ability to restrict OpenVPN's
     2410rights to only network I/O operations, thanks to
     2411SELinux. This goes further than
     2412<B>--user</B>
     2413
     2414and
     2415<B>--chroot</B>
     2416
     2417in that those two, while being great security features,
     2418unfortunately do not protect against privilege escalation
     2419by exploitation of a vulnerable system call. You can of
     2420course combine all three, but please note that since
     2421setcon requires access to /proc you will have to provide
     2422it inside the chroot directory (e.g. with mount --bind).
     2423<P>
     2424Since the setcon operation is delayed until after
     2425initialization, OpenVPN can be restricted to just
     2426network-related system calls, whereas by applying the
     2427context before startup (such as the OpenVPN one provided
     2428in the SELinux Reference Policies) you will have to
     2429allow many things required only during initialization.
     2430<P>
     2431Like with chroot, complications can result when scripts
     2432or restarts are executed after the setcon operation,
     2433which is why you should really consider using the
     2434<B>--persist-key</B>
     2435
     2436and
     2437<B>--persist-tun</B>
     2438
     2439options.
     2440
     2441<DT><B>--daemon [progname]</B>
     2442
     2443<DD>
     2444Become a daemon after all initialization functions are completed.
     2445This option will cause all message and error output to
     2446be sent to the syslog file (such as /var/log/messages),
     2447except for the output of shell scripts and
     2448ifconfig commands,
     2449which will go to /dev/null unless otherwise redirected.
     2450The syslog redirection occurs immediately at the point
     2451that
     2452<B>--daemon</B>
     2453
     2454is parsed on the command line even though
     2455the daemonization point occurs later.  If one of the
     2456<B>--log</B>
     2457
     2458options is present, it will supercede syslog
     2459redirection.
     2460<P>
     2461The optional
     2462<B>progname</B>
     2463
     2464parameter will cause OpenVPN to report its program name
     2465to the system logger as
     2466<B>progname.</B>
     2467
     2468This can be useful in linking OpenVPN messages
     2469in the syslog file with specific tunnels.
     2470When unspecified,
     2471<B>progname</B>
     2472
     2473defaults to &quot;openvpn&quot;.
     2474<P>
     2475When OpenVPN is run with the
     2476<B>--daemon</B>
     2477
     2478option, it will try to delay daemonization until the majority of initialization
     2479functions which are capable of generating fatal errors are complete.  This means
     2480that initialization scripts can test the return status of the
     2481openvpn command for a fairly reliable indication of whether the command
     2482has correctly initialized and entered the packet forwarding event loop.
     2483<P>
     2484In OpenVPN, the vast majority of errors which occur after initialization are non-fatal.
     2485
     2486<DT><B>--syslog [progname]</B>
     2487
     2488<DD>
     2489Direct log output to system logger, but do not become a daemon.
     2490See
     2491<B>--daemon</B>
     2492
     2493directive above for description of
     2494<B>progname</B>
     2495
     2496parameter.
     2497
     2498<DT><B>--passtos</B>
     2499
     2500<DD>
     2501Set the TOS field of the tunnel packet to what the payload's TOS is.
     2502
     2503<DT><B>--inetd [wait|nowait] [progname]</B>
     2504
     2505<DD>
     2506Use this option when OpenVPN is being run from the inetd or
     2507<B><A HREF="/man/man2html?8+xinetd">xinetd</A>(8)</B>
     2508
     2509server.
     2510<P>
     2511The
     2512<B>wait/nowait</B>
     2513
     2514option must match what is specified in the inetd/xinetd
     2515config file.  The
     2516<B>nowait</B>
     2517
     2518mode can only be used with
     2519<B>--proto tcp-server.</B>
     2520
     2521The default is
     2522<B>wait.</B>
     2523
     2524The
     2525<B>nowait</B>
     2526
     2527mode can be used to instantiate the OpenVPN daemon as a classic TCP server,
     2528where client connection requests are serviced on a single
     2529port number.  For additional information on this kind of configuration,
     2530see the OpenVPN FAQ:
     2531<I><A HREF="http://openvpn.net/faq.html#oneport">http://openvpn.net/faq.html#oneport</A></I>
     2532
     2533<P>
     2534This option precludes the use of
     2535<B>--daemon, --local,</B>
     2536
     2537or
     2538<B>--remote.</B>
     2539
     2540Note that this option causes message and error output to be handled in the same
     2541way as the
     2542<B>--daemon</B>
     2543
     2544option.  The optional
     2545<B>progname</B>
     2546
     2547parameter is also handled exactly as in
     2548<B>--daemon.</B>
     2549
     2550<P>
     2551Also note that in
     2552<B>wait</B>
     2553
     2554mode, each OpenVPN tunnel requires a separate TCP/UDP port and
     2555a separate inetd or xinetd entry.  See the OpenVPN 1.x HOWTO for an example
     2556on using OpenVPN with xinetd:
     2557<I><A HREF="http://openvpn.net/1xhowto.html">http://openvpn.net/1xhowto.html</A></I>
     2558
     2559
     2560<DT><B>--log file</B>
     2561
     2562<DD>
     2563Output logging messages to
     2564<B>file,</B>
     2565
     2566including output to stdout/stderr which
     2567is generated by called scripts.
     2568If
     2569<B>file</B>
     2570
     2571already exists it will be truncated.
     2572This option takes effect
     2573immediately when it is parsed in the command line
     2574and will supercede syslog output if
     2575<B>--daemon</B>
     2576
     2577or
     2578<B>--inetd</B>
     2579
     2580is also specified.
     2581This option is persistent over the entire course of
     2582an OpenVPN instantiation and will not be reset by SIGHUP,
     2583SIGUSR1, or
     2584<B>--ping-restart.</B>
     2585
     2586<P>
     2587Note that on Windows, when OpenVPN is started as a service,
     2588logging occurs by default without the need to specify
     2589this option.
     2590
     2591<DT><B>--log-append file</B>
     2592
     2593<