Changes between Version 4 and Version 5 of Openvpn23ManPage


Ignore:
Timestamp:
10/31/12 14:39:42 (8 years ago)
Author:
Samuli Seppänen
Comment:

Updated man-page for openvpn-2.3_rc1

Legend:

Unmodified
Added
Removed
Modified
  • Openvpn23ManPage

    v4 v5  
    22#!div style="font-size: 80%"
    33{{{
    4 openvpn(8)                                                                                           openvpn(8)
     4openvpn(8)                                                          openvpn(8)
    55
    66
     
    1313
    1414INTRODUCTION
    15        OpenVPN  is  an open source VPN daemon by James Yonan.  Because OpenVPN tries to be a universal VPN tool
    16        offering a great deal of flexibility, there are a lot of options on this manual page.  If you're new  to
    17        OpenVPN, you might want to skip ahead to the examples section where you will see how to construct simple
    18        VPNs on the command line without even needing a configuration file.
    19 
    20        Also note that there's more documentation and examples on the OpenVPN web site: http://openvpn.net/
    21 
    22        And if you would like to see a shorter version of this manual, see the openvpn usage message  which  can
    23        be obtained by running openvpn without any parameters.
     15       OpenVPN  is  an open source VPN daemon by James Yonan.  Because OpenVPN
     16       tries to be a universal VPN tool offering a great deal of  flexibility,
     17       there are a lot of options on this manual page.  If you're new to Open‐
     18       VPN, you might want to skip ahead to the  examples  section  where  you
     19       will  see how to construct simple VPNs on the command line without even
     20       needing a configuration file.
     21
     22       Also note that there's more documentation and examples on  the  OpenVPN
     23       web site: http://openvpn.net/
     24
     25       And  if you would like to see a shorter version of this manual, see the
     26       openvpn usage message which can be obtained by running openvpn  without
     27       any parameters.
    2428
    2529DESCRIPTION
    26        OpenVPN  is a robust and highly flexible VPN daemon.  OpenVPN supports SSL/TLS security, ethernet bridg‐
    27        ing, TCP or UDP tunnel transport through proxies or NAT, support for  dynamic  IP  addresses  and  DHCP,
    28        scalability to hundreds or thousands of users, and portability to most major OS platforms.
    29 
    30        OpenVPN is tightly bound to the OpenSSL library, and derives much of its crypto capabilities from it.
    31 
    32        OpenVPN  supports  conventional encryption using a pre-shared secret key (Static Key mode) or public key
    33        security (SSL/TLS mode) using client & server certificates.  OpenVPN also supports non-encrypted TCP/UDP
    34        tunnels.
    35 
    36        OpenVPN is designed to work with the TUN/TAP virtual networking interface that exists on most platforms.
    37 
    38        Overall, OpenVPN aims to offer many of the key features of IPSec but with a relatively lightweight foot‐
    39        print.
     30       OpenVPN  is  a robust and highly flexible VPN daemon.  OpenVPN supports
     31       SSL/TLS security,  ethernet  bridging,  TCP  or  UDP  tunnel  transport
     32       through  proxies  or  NAT,  support  for dynamic IP addresses and DHCP,
     33       scalability to hundreds or thousands of users, and portability to  most
     34       major OS platforms.
     35
     36       OpenVPN  is  tightly  bound to the OpenSSL library, and derives much of
     37       its crypto capabilities from it.
     38
     39       OpenVPN supports conventional encryption using a pre-shared secret  key
     40       (Static  Key mode) or public key security (SSL/TLS mode) using client &
     41       server certificates.  OpenVPN also supports non-encrypted TCP/UDP  tun‐
     42       nels.
     43
     44       OpenVPN  is designed to work with the TUN/TAP virtual networking inter‐
     45       face that exists on most platforms.
     46
     47       Overall, OpenVPN aims to offer many of the key features  of  IPSec  but
     48       with a relatively lightweight footprint.
    4049
    4150OPTIONS
    42        OpenVPN allows any option to be placed either on the command line or in a  configuration  file.   Though
    43        all  command  line options are preceded by a double-leading-dash ("--"), this prefix can be removed when
    44        an option is placed in a configuration file.
     51       OpenVPN allows any option to be placed either on the command line or in
     52       a configuration file.  Though all command line options are preceded  by
     53       a double-leading-dash ("--"), this prefix can be removed when an option
     54       is placed in a configuration file.
    4555
    4656       --help Show options.
    4757
    4858       --config file
    49               Load additional config options from file where each line corresponds to one command line  option,
    50               but with the leading '--' removed.
    51 
    52               If  --config file is the only option to the openvpn command, the --config can be removed, and the
    53               command can be given as openvpn file
    54 
    55               Note that configuration files can be nested to a reasonable depth.
    56 
    57               Double quotation or single quotation characters ("", '') can be used to enclose single parameters
    58               containing  whitespace,  and "#" or ";" characters in the first column can be used to denote com‐
     59              Load additional config options from file where each line  corre‐
     60              sponds  to  one  command  line option, but with the leading '--'
     61              removed.
     62
     63              If --config file is the only option to the openvpn command,  the
     64              --config can be removed, and the command can be given as openvpn
     65              file
     66
     67              Note that configuration files can  be  nested  to  a  reasonable
     68              depth.
     69
     70              Double  quotation or single quotation characters ("", '') can be
     71              used to enclose single parameters containing whitespace, and "#"
     72              or ";" characters in the first column can be used to denote com‐
    5973              ments.
    6074
    61               Note that OpenVPN 2.0 and higher performs backslash-based shell escaping for  characters  not  in
    62               single quotations, so the following mappings should be observed:
     75              Note that OpenVPN 2.0 and higher performs backslash-based  shell
     76              escaping for characters not in single quotations, so the follow‐
     77              ing mappings should be observed:
    6378
    6479                  \\       Maps to a single backslash character (\).
     
    6883                           interpret it as a parameter delimiter.
    6984
    70               For example on Windows, use double backslashes to represent pathnames:
     85              For example on Windows,  use  double  backslashes  to  represent
     86              pathnames:
    7187
    7288                  secret "c:\\OpenVPN\\secret.key"
    7389
    74               For examples of configuration files, see http://openvpn.net/examples.html
     90              For   examples   of   configuration   files,   see  http://open‐
     91              vpn.net/examples.html
    7592
    7693              Here is an example configuration file:
     
    97114   Tunnel Options:
    98115       --mode m
    99               Set  OpenVPN  major  mode.  By default, OpenVPN runs in point-to-point mode ("p2p").  OpenVPN 2.0
    100               introduces a new mode ("server") which implements a multi-client server capability.
     116              Set OpenVPN major mode.  By default, OpenVPN runs  in  point-to-
     117              point   mode   ("p2p").   OpenVPN  2.0  introduces  a  new  mode
     118              ("server") which implements a multi-client server capability.
    101119
    102120       --local host
    103               Local host name or IP address for bind.  If specified, OpenVPN will bind to  this  address  only.
    104               If unspecified, OpenVPN will bind to all interfaces.
     121              Local host name or IP address for bind.  If  specified,  OpenVPN
     122              will  bind  to  this address only.  If unspecified, OpenVPN will
     123              bind to all interfaces.
    105124
    106125       --remote host [port] [proto]
    107               Remote  host  name  or IP address.  On the client, multiple --remote options may be specified for
    108               redundancy, each referring to a different OpenVPN server.  Specifying multiple  --remote  options
    109               for this purpose is a special case of the more general connection-profile feature.  See the <con‐
    110               nection> documentation below.
    111 
    112               The OpenVPN client will try to connect to a server at host:port in the  order  specified  by  the
    113               list of --remote options.
    114 
    115               proto indicates the protocol to use when connecting with the remote, and may be "tcp" or "udp".
    116 
    117               The  client  will move on to the next host in the list, in the event of connection failure.  Note
    118               that at any given time, the OpenVPN client will at most be connected to one server.
    119 
    120               Note that since UDP is connectionless, connection failure is defined by the  --ping  and  --ping-
    121               restart options.
    122 
    123               Note  the following corner case:  If you use multiple --remote options, AND you are dropping root
    124               privileges on the client with --user and/or --group, AND the client is running a non-Windows  OS,
    125               if  the  client  needs  to  switch  to  a different server, and that server pushes back different
    126               TUN/TAP or route settings, the client may lack the necessary privileges to close and  reopen  the
    127               TUN/TAP interface.  This could cause the client to exit with a fatal error.
    128 
    129               If --remote is unspecified, OpenVPN will listen for packets from any IP address, but will not act
    130               on those packets unless they pass all authentication tests.  This requirement for  authentication
    131               is  binding on all potential peers, even those from known and supposedly trusted IP addresses (it
    132               is very easy to forge a source IP address on a UDP packet).
    133 
    134               When used in TCP mode, --remote will act as a filter, rejecting connections from any  host  which
    135               does not match host.
    136 
    137               If  host is a DNS name which resolves to multiple IP addresses, one will be randomly chosen, pro‐
    138               viding a sort of basic load-balancing and failover capability.
     126              Remote host  name  or  IP  address.   On  the  client,  multiple
     127              --remote options may be specified for redundancy, each referring
     128              to a different OpenVPN  server.   Specifying  multiple  --remote
     129              options  for  this purpose is a special case of the more general
     130              connection-profile feature.  See the <connection>  documentation
     131              below.
     132
     133              The  OpenVPN client will try to connect to a server at host:port
     134              in the order specified by the list of --remote options.
     135
     136              proto indicates the protocol to use  when  connecting  with  the
     137              remote, and may be "tcp" or "udp".
     138
     139              The  client  will  move  on to the next host in the list, in the
     140              event of connection failure.  Note that at any given  time,  the
     141              OpenVPN client will at most be connected to one server.
     142
     143              Note  that  since  UDP  is connectionless, connection failure is
     144              defined by the --ping and --ping-restart options.
     145
     146              Note the following corner case:  If you  use  multiple  --remote
     147              options, AND you are dropping root privileges on the client with
     148              --user and/or --group, AND the client is running  a  non-Windows
     149              OS,  if  the  client  needs to switch to a different server, and
     150              that server pushes back different TUN/TAP or route settings, the
     151              client may lack the necessary privileges to close and reopen the
     152              TUN/TAP interface.  This could cause the client to exit  with  a
     153              fatal error.
     154
     155              If --remote is unspecified, OpenVPN will listen for packets from
     156              any IP address, but will not act on those  packets  unless  they
     157              pass all authentication tests.  This requirement for authentica‐
     158              tion is binding on all potential peers, even  those  from  known
     159              and  supposedly trusted IP addresses (it is very easy to forge a
     160              source IP address on a UDP packet).
     161
     162              When used in TCP mode, --remote will act as a filter,  rejecting
     163              connections from any host which does not match host.
     164
     165              If  host  is a DNS name which resolves to multiple IP addresses,
     166              one will be randomly chosen, providing a sort of basic load-bal‐
     167              ancing and failover capability.
    139168
    140169       --remote-random-hostname
    141               Add a random string (6 characters) to first DNS label of hostname to prevent  DNS  caching.   For
    142               example, "foo.bar.gov" would be modified to "<random-chars>.foo.bar.gov".
     170              Add  a  random string (6 characters) to first DNS label of host‐
     171              name to prevent DNS caching.  For example,  "foo.bar.gov"  would
     172              be modified to "<random-chars>.foo.bar.gov".
    143173
    144174       <connection>
    145               Define  a  client  connection  profile.  Client connection profiles are groups of OpenVPN options
    146               that describe how to connect to a given OpenVPN server.  Client connection profiles are specified
    147               within an OpenVPN configuration file, and each profile is bracketed by <connection> and </connec‐
    148               tion>.
    149 
    150               An OpenVPN client will try each connection profile sequentially until it  achieves  a  successful
    151               connection.
    152 
    153               --remote-random can be used to initially "scramble" the connection list.
     175              Define  a client connection profile.  Client connection profiles
     176              are groups of OpenVPN options that describe how to connect to  a
     177              given  OpenVPN server.  Client connection profiles are specified
     178              within an OpenVPN configuration file, and each profile is brack‐
     179              eted by <connection> and </connection>.
     180
     181              An  OpenVPN client will try each connection profile sequentially
     182              until it achieves a successful connection.
     183
     184              --remote-random can be used to initially "scramble" the  connec‐
     185              tion list.
    154186
    155187              Here is an example of connection profile usage:
     
    184216                  verb 3
    185217
    186               First  we  try to connect to a server at 198.19.34.56:1194 using UDP.  If that fails, we then try
    187               to connect to 198.19.34.56:443 using TCP.  If that also fails, then  try  connecting  through  an
    188               HTTP  proxy  at  192.168.0.8:8080 to 198.19.34.56:443 using TCP.  Finally, try to connect through
    189               the same proxy to a server at 198.19.36.99:443 using TCP.
    190 
    191               The following OpenVPN options may be used inside of a <connection> block:
    192 
    193               bind, connect-retry, connect-retry-max, connect-timeout,  float,  http-proxy,  http-proxy-option,
    194               http-proxy-retry,  http-proxy-timeout,  local,  lport, nobind, port, proto, remote, rport, socks-
    195               proxy, and socks-proxy-retry.
    196 
    197               A defaulting mechanism exists for specifying options to apply to all <connection>  profiles.   If
    198               any  of the above options (with the exception of remote ) appear outside of a <connection> block,
    199               but in a configuration file which has one or more <connection> blocks, the option setting will be
    200               used as a default for <connection> blocks which follow it in the configuration file.
    201 
    202               For  example,  suppose the nobind option were placed in the sample configuration file above, near
    203               the top of the file, before the first <connection> block.  The effect would be as if nobind  were
     218              First  we  try to connect to a server at 198.19.34.56:1194 using
     219              UDP.  If that fails, we then try to connect to  198.19.34.56:443
     220              using  TCP.   If that also fails, then try connecting through an
     221              HTTP proxy at 192.168.0.8:8080 to  198.19.34.56:443  using  TCP.
     222              Finally,  try  to  connect through the same proxy to a server at
     223              198.19.36.99:443 using TCP.
     224
     225              The following OpenVPN options may be used inside of  a  <connec‐
     226              tion> block:
     227
     228              bind,  connect-retry, connect-retry-max, connect-timeout, float,
     229              http-proxy,  http-proxy-option,  http-proxy-retry,   http-proxy-
     230              timeout,  local,  lport,  nobind,  port,  proto,  remote, rport,
     231              socks-proxy, and socks-proxy-retry.
     232
     233              A defaulting mechanism exists for specifying options to apply to
     234              all  <connection>  profiles.   If any of the above options (with
     235              the exception of remote  )  appear  outside  of  a  <connection>
     236              block,  but  in a configuration file which has one or more <con‐
     237              nection> blocks, the option setting will be used  as  a  default
     238              for  <connection>  blocks  which  follow it in the configuration
     239              file.
     240
     241              For example, suppose the nobind option were placed in the sample
     242              configuration  file  above, near the top of the file, before the
     243              first <connection> block.  The effect would be as if nobind were
    204244              declared in all <connection> blocks below it.
    205245
    206246       --proto-force p
    207               When   iterating   through   connection   profiles,  only  consider  profiles  using  protocol  p
    208               ('tcp'|'udp').
     247              When  iterating  through connection profiles, only consider pro‐
     248              files using protocol p ('tcp'|'udp').
    209249
    210250       --remote-random
    211               When multiple --remote address/ports are specified, or if connection  profiles  are  being  used,
    212               initially randomize the order of the list as a kind of basic load-balancing measure.
     251              When multiple --remote address/ports are specified, or  if  con‐
     252              nection  profiles  are being used, initially randomize the order
     253              of the list as a kind of basic load-balancing measure.
    213254
    214255       --proto p
    215               Use protocol p for communicating with remote host.  p can be udp, tcp-client, or tcp-server.
     256              Use protocol p for communicating with remote  host.   p  can  be
     257              udp, tcp-client, or tcp-server.
    216258
    217259              The default protocol is udp when --proto is not specified.
    218260
    219               For UDP operation, --proto udp should be specified on both peers.
    220 
    221               For  TCP  operation,  one  peer  must  use --proto tcp-server and the other must use --proto tcp-
    222               client.  A peer started with tcp-server will wait indefinitely for  an  incoming  connection.   A
    223               peer started with tcp-client will attempt to connect, and if that fails, will sleep for 5 seconds
    224               (adjustable via the --connect-retry option) and try again infinite or up to N retries (adjustable
    225               via  the --connect-retry-max option).  Both TCP client and server will simulate a SIGUSR1 restart
    226               signal if either side resets the connection.
    227 
    228               OpenVPN is designed to operate optimally over UDP, but TCP capability is provided for  situations
    229               where  UDP  cannot  be used.  In comparison with UDP, TCP will usually be somewhat less efficient
     261              For  UDP  operation,  --proto  udp  should  be specified on both
     262              peers.
     263
     264              For TCP operation, one peer must use --proto tcp-server and  the
     265              other  must  use  --proto  tcp-client.  A peer started with tcp-
     266              server will wait indefinitely for  an  incoming  connection.   A
     267              peer  started  with  tcp-client  will attempt to connect, and if
     268              that fails, will sleep for 5 seconds (adjustable via the  --con‐
     269              nect-retry  option)  and  try  again infinite or up to N retries
     270              (adjustable  via  the  --connect-retry-max  option).   Both  TCP
     271              client  and  server  will  simulate  a SIGUSR1 restart signal if
     272              either side resets the connection.
     273
     274              OpenVPN is designed to operate optimally over UDP, but TCP capa‐
     275              bility  is provided for situations where UDP cannot be used.  In
     276              comparison with UDP, TCP will usually be somewhat less efficient
    230277              and less robust when used over unreliable or congested networks.
    231278
    232               This article outlines some of problems with tunneling IP over TCP:
     279              This  article  outlines  some of problems with tunneling IP over
     280              TCP:
    233281
    234282              http://sites.inka.de/sites/bigred/devel/tcp-tcp.html
    235283
    236               There are certain cases, however, where using TCP may be advantageous from a security and robust‐
    237               ness  perspective, such as tunneling non-IP or application-level UDP protocols, or tunneling pro‐
    238               tocols which don't possess a built-in reliability layer.
     284              There are certain cases, however, where using TCP may be  advan‐
     285              tageous from a security and robustness perspective, such as tun‐
     286              neling non-IP or application-level UDP protocols,  or  tunneling
     287              protocols which don't possess a built-in reliability layer.
    239288
    240289       --connect-retry n
    241               For --proto tcp-client, take n as the number  of  seconds  to  wait  between  connection  retries
    242               (default=5).
     290              For  --proto tcp-client, take n as the number of seconds to wait
     291              between connection retries (default=5).
    243292
    244293       --connect-timeout n
    245               For --proto tcp-client, set connection timeout to n seconds (default=10).
     294              For --proto tcp-client, set  connection  timeout  to  n  seconds
     295              (default=10).
    246296
    247297       --connect-retry-max n
    248               For --proto tcp-client, take n as the number of retries of connection attempt (default=infinite).
     298              For  --proto tcp-client, take n as the number of retries of con‐
     299              nection attempt (default=infinite).
    249300
    250301       --show-proxy-settings
    251               Show sensed HTTP or SOCKS proxy settings. Currently, only Windows clients support this option.
     302              Show sensed HTTP or SOCKS proxy settings. Currently,  only  Win‐
     303              dows clients support this option.
    252304
    253305       --http-proxy server port [authfile|'auto'|'auto-nct'] [auth-method]
    254               Connect  to  remote  host  through an HTTP proxy at address server and port port.  If HTTP Proxy-
    255               Authenticate is required, authfile is a file containing a username and password on  2  lines,  or
     306              Connect  to  remote host through an HTTP proxy at address server
     307              and port port.  If HTTP Proxy-Authenticate is required, authfile
     308              is  a  file  containing  a  username and password on 2 lines, or
    256309              "stdin" to prompt from console.
    257310
    258311              auth-method should be one of "none", "basic", or "ntlm".
    259312
    260               HTTP Digest authentication is supported as well, but only via the auto or auto-nct flags (below).
    261 
    262               The  auto  flag  causes OpenVPN to automatically determine the auth-method and query stdin or the
    263               management interface for username/password credentials, if required.  This flag exists on OpenVPN
    264               2.1 or higher.
    265 
    266               The auto-nct flag (no clear-text auth) instructs OpenVPN to automatically determine the authenti‐
    267               cation method, but to reject weak authentication protocols such as HTTP Basic Authentication.
     313              HTTP Digest authentication is supported as well,  but  only  via
     314              the auto or auto-nct flags (below).
     315
     316              The  auto  flag  causes  OpenVPN  to automatically determine the
     317              auth-method and query stdin  or  the  management  interface  for
     318              username/password credentials, if required.  This flag exists on
     319              OpenVPN 2.1 or higher.
     320
     321              The auto-nct flag (no  clear-text  auth)  instructs  OpenVPN  to
     322              automatically determine the authentication method, but to reject
     323              weak authentication protocols such as HTTP Basic Authentication.
    268324
    269325       --http-proxy-retry
    270               Retry indefinitely on HTTP proxy errors.  If an HTTP  proxy  error  occurs,  simulate  a  SIGUSR1
    271               reset.
     326              Retry indefinitely on HTTP proxy errors.  If an HTTP proxy error
     327              occurs, simulate a SIGUSR1 reset.
    272328
    273329       --http-proxy-timeout n
     
    275331
    276332       --http-proxy-option type [parm]
    277               Set extended HTTP proxy options.  Repeat to set multiple options.
    278 
    279               VERSION version -- Set HTTP version number to version (default=1.0).
     333              Set  extended  HTTP  proxy  options.   Repeat  to  set  multiple
     334              options.
     335
     336              VERSION  version  --  Set  HTTP  version   number   to   version
     337              (default=1.0).
    280338
    281339              AGENT user-agent -- Set HTTP "User-Agent" string to user-agent.
    282340
    283341       --socks-proxy server [port]
    284               Connect to remote host through a Socks5 proxy at address server and port port (default=1080).
     342              Connect  to remote host through a Socks5 proxy at address server
     343              and port port (default=1080).
    285344
    286345       --socks-proxy-retry
    287               Retry  indefinitely  on  Socks  proxy  errors.  If a Socks proxy error occurs, simulate a SIGUSR1
    288               reset.
     346              Retry indefinitely on Socks proxy  errors.   If  a  Socks  proxy
     347              error occurs, simulate a SIGUSR1 reset.
    289348
    290349       --resolv-retry n
    291               If hostname resolve fails for --remote, retry resolve for n seconds before failing.
     350              If hostname resolve fails for --remote, retry resolve for n sec‐
     351              onds before failing.
    292352
    293353              Set n to "infinite" to retry indefinitely.
    294354
    295               By default, --resolv-retry infinite is enabled.  You can disable by setting n=0.
     355              By default, --resolv-retry infinite is enabled.  You can disable
     356              by setting n=0.
    296357
    297358       --float
    298               Allow remote peer to change its IP address and/or port number, such as due to DHCP (this  is  the
    299               default if --remote is not used).  --float when specified with --remote allows an OpenVPN session
    300               to initially connect to a peer at a known address, however if packets arrive from a  new  address
    301               and  pass  all  authentication  tests, the new address will take control of the session.  This is
    302               useful when you are connecting to a peer which holds a dynamic address such as a dial-in user  or
    303               DHCP client.
    304 
    305               Essentially, --float tells OpenVPN to accept authenticated packets from any address, not only the
    306               address which was specified in the --remote option.
     359              Allow  remote  peer to change its IP address and/or port number,
     360              such as due to DHCP (this is the  default  if  --remote  is  not
     361              used).   --float  when specified with --remote allows an OpenVPN
     362              session to initially connect to a peer at a known address,  how‐
     363              ever if packets arrive from a new address and pass all authenti‐
     364              cation tests, the new address will take control of the  session.
     365              This  is  useful when you are connecting to a peer which holds a
     366              dynamic address such as a dial-in user or DHCP client.
     367
     368              Essentially, --float tells OpenVPN to accept authenticated pack‐
     369              ets  from  any address, not only the address which was specified
     370              in the --remote option.
    307371
    308372       --ipchange cmd
    309               Run command cmd when our remote ip-address is initially authenticated or changes.
    310 
    311               cmd consists of a path to script (or executable program), optionally followed by  arguments.  The
    312               path  and  arguments may be single- or double-quoted and/or escaped using a backslash, and should
    313               be separated by one or more spaces.
    314 
    315               When cmd is executed two arguments are appended after any arguments specified in cmd  ,  as  fol‐
    316               lows:
     373              Run command cmd when our remote ip-address is initially  authen‐
     374              ticated or changes.
     375
     376              cmd  consists  of  a  path  to  script  (or executable program),
     377              optionally followed by arguments. The path and arguments may  be
     378              single-  or  double-quoted and/or escaped using a backslash, and
     379              should be separated by one or more spaces.
     380
     381              When cmd is executed two arguments are appended after any  argu‐
     382              ments specified in cmd , as follows:
    317383
    318384              cmd ip_address port_number
    319385
    320               Don't use --ipchange in --mode server mode.  Use a --client-connect script instead.
    321 
    322               See the "Environmental Variables" section below for additional parameters passed as environmental
    323               variables.
    324 
    325               If you are running in a dynamic IP address environment where the  IP  addresses  of  either  peer
    326               could  change  without  notice, you can use this script, for example, to edit the /etc/hosts file
    327               with the current address of the peer.  The script will be run every time the remote peer  changes
    328               its IP address.
    329 
    330               Similarly if our IP address changes due to DHCP, we should configure our IP address change script
    331               (see man page for dhcpcd(8) ) to deliver a SIGHUP or SIGUSR1 signal  to  OpenVPN.   OpenVPN  will
    332               then reestablish a connection with its most recently authenticated peer on its new IP address.
     386              Don't use --ipchange in --mode server mode.  Use a --client-con‐
     387              nect script instead.
     388
     389              See the "Environmental Variables" section below  for  additional
     390              parameters passed as environmental variables.
     391
     392              If you are running in a dynamic IP address environment where the
     393              IP addresses of either peer could change without notice, you can
     394              use  this  script, for example, to edit the /etc/hosts file with
     395              the current address of the peer.  The script will be  run  every
     396              time the remote peer changes its IP address.
     397
     398              Similarly  if our IP address changes due to DHCP, we should con‐
     399              figure our IP address change script (see man page for  dhcpcd(8)
     400              )  to  deliver  a  SIGHUP or SIGUSR1 signal to OpenVPN.  OpenVPN
     401              will then  reestablish  a  connection  with  its  most  recently
     402              authenticated peer on its new IP address.
    333403
    334404       --port port
    335               TCP/UDP  port number for both local and remote.  The current default of 1194 represents the offi‐
    336               cial IANA port number assignment for OpenVPN and has been used since version 2.0-beta17.   Previ‐
    337               ous versions used port 5000 as the default.
     405              TCP/UDP  port  number  for  both  local and remote.  The current
     406              default of 1194 represents the official IANA port number assign‐
     407              ment  for  OpenVPN  and  has been used since version 2.0-beta17.
     408              Previous versions used port 5000 as the default.
    338409
    339410       --lport port
     
    343414              TCP/UDP port number for remote.
    344415
    345        --bind Bind  to  local  address and port. This is the default unless any of --proto tcp-client , --http-
    346               proxy or --socks-proxy are used.
     416       --bind Bind to local address and port. This is the default  unless  any
     417              of --proto tcp-client , --http-proxy or --socks-proxy are used.
    347418
    348419       --nobind
    349               Do not bind to local address and port.  The IP stack will allocate a dynamic port  for  returning
    350               packets.   Since  the  value  of  the  dynamic port could not be known in advance by a peer, this
    351               option is only suitable for peers which will be initiating  connections  by  using  the  --remote
    352               option.
     420              Do  not bind to local address and port.  The IP stack will allo‐
     421              cate a dynamic port for returning packets.  Since the  value  of
     422              the  dynamic  port could not be known in advance by a peer, this
     423              option is only suitable for peers which will be initiating  con‐
     424              nections by using the --remote option.
    353425
    354426       --dev tunX | tapX | null
    355               TUN/TAP virtual network device ( X can be omitted for a dynamic device.)
    356 
    357               See examples section below for an example on setting up a TUN device.
    358 
    359               You  must use either tun devices on both ends of the connection or tap devices on both ends.  You
    360               cannot mix them, as they represent different underlying network layers.
    361 
    362               tun devices encapsulate IPv4 or IPv6 (OSI Layer 3) while tap devices encapsulate  Ethernet  802.3
    363               (OSI Layer 2).
     427              TUN/TAP  virtual network device ( X can be omitted for a dynamic
     428              device.)
     429
     430              See examples section below for an example on setting  up  a  TUN
     431              device.
     432
     433              You  must  use either tun devices on both ends of the connection
     434              or tap devices on both ends.  You cannot mix them, as they  rep‐
     435              resent different underlying network layers.
     436
     437              tun  devices  encapsulate  IPv4  or IPv6 (OSI Layer 3) while tap
     438              devices encapsulate Ethernet 802.3 (OSI Layer 2).
    364439
    365440       --dev-type device-type
    366               Which  device  type  are we using?  device-type should be tun (OSI Layer 3) or tap (OSI Layer 2).
    367               Use this option only if the TUN/TAP device used with --dev does not begin with tun or tap.
     441              Which device type are we using?  device-type should be tun  (OSI
     442              Layer  3)  or  tap  (OSI  Layer 2).  Use this option only if the
     443              TUN/TAP device used with --dev does not begin with tun or tap.
    368444
    369445       --topology mode
    370               Configure virtual addressing topology when running in --dev tun  mode.   This  directive  has  no
    371               meaning in --dev tap mode, which always uses a subnet topology.
    372 
    373               If  you  set this directive on the server, the --server and --server-bridge directives will auto‐
    374               matically push your chosen topology setting to clients as well.  This directive can also be manu‐
    375               ally  pushed  to  clients.   Like  the  --dev directive, this directive must always be compatible
    376               between client and server.
     446              Configure virtual addressing topology when running in --dev  tun
     447              mode.   This  directive  has no meaning in --dev tap mode, which
     448              always uses a subnet topology.
     449
     450              If you set this  directive  on  the  server,  the  --server  and
     451              --server-bridge  directives  will automatically push your chosen
     452              topology setting to clients as well.  This directive can also be
     453              manually  pushed  to  clients.   Like  the --dev directive, this
     454              directive must always be compatible between client and server.
    377455
    378456              mode can be one of:
    379457
    380               net30 -- Use a point-to-point topology, by  allocating  one  /30  subnet  per  client.   This  is
    381               designed  to  allow  point-to-point semantics when some or all of the connecting clients might be
     458              net30 -- Use a point-to-point topology, by  allocating  one  /30
     459              subnet  per  client.   This  is designed to allow point-to-point
     460              semantics when some or all of the connecting  clients  might  be
    382461              Windows systems.  This is the default on OpenVPN 2.0.
    383462
    384               p2p -- Use a point-to-point topology where the remote endpoint  of  the  client's  tun  interface
    385               always  points to the local endpoint of the server's tun interface.  This mode allocates a single
    386               IP address per connecting client.  Only use when none of the connecting clients are Windows  sys‐
    387               tems.   This  mode  is  functionally  equivalent to the --ifconfig-pool-linear directive which is
     463              p2p  --  Use a point-to-point topology where the remote endpoint
     464              of the client's tun interface always points to  the  local  end‐
     465              point of the server's tun interface.  This mode allocates a sin‐
     466              gle IP address per connecting client.  Only use when none of the
     467              connecting  clients are Windows systems.  This mode is function‐
     468              ally equivalent to the --ifconfig-pool-linear directive which is
    388469              available in OpenVPN 2.0 and is now deprecated.
    389470
    390               subnet -- Use a subnet rather than a point-to-point topology by  configuring  the  tun  interface
    391               with  a  local IP address and subnet mask, similar to the topology used in --dev tap and ethernet
    392               bridging mode.  This mode allocates a single IP address per connecting client and works  on  Win‐
    393               dows as well.  Only available when server and clients are OpenVPN 2.1 or higher, or OpenVPN 2.0.x
    394               which has been manually patched with the  --topology  directive  code.   When  used  on  Windows,
    395               requires version 8.2 or higher of the TAP-Win32 driver.  When used on *nix, requires that the tun
    396               driver supports an ifconfig(8) command which sets a  subnet  instead  of  a  remote  endpoint  IP
    397               address.
     471              subnet  -- Use a subnet rather than a point-to-point topology by
     472              configuring the tun interface with a local IP address and subnet
     473              mask,  similar  to  the  topology used in --dev tap and ethernet
     474              bridging mode.  This mode allocates a single IP address per con‐
     475              necting  client  and  works  on Windows as well.  Only available
     476              when server and clients are OpenVPN 2.1 or  higher,  or  OpenVPN
     477              2.0.x which has been manually patched with the --topology direc‐
     478              tive code.  When used on Windows, requires version 8.2 or higher
     479              of  the  TAP-Win32 driver.  When used on *nix, requires that the
     480              tun driver supports an ifconfig(8) command which sets  a  subnet
     481              instead of a remote endpoint IP address.
    398482
    399483              This option exists in OpenVPN 2.1 or higher.
    400484
    401485       --tun-ipv6
    402               Build  a  tun  link capable of forwarding IPv6 traffic.  Should be used in conjunction with --dev
    403               tun or --dev tunX.  A warning will be displayed if no specific IPv6 TUN support for your  OS  has
    404               been compiled into OpenVPN.
     486              Build  a tun link capable of forwarding IPv6 traffic.  Should be
     487              used in conjunction with --dev tun or  --dev  tunX.   A  warning
     488              will  be  displayed  if no specific IPv6 TUN support for your OS
     489              has been compiled into OpenVPN.
    405490
    406491              See below for further IPv6-related configuration options.
    407492
    408493       --dev-node node
    409               Explicitly set the device node rather than using /dev/net/tun, /dev/tun, /dev/tap, etc.  If Open‐
    410               VPN cannot figure out whether node is a TUN or TAP device based on  the  name,  you  should  also
     494              Explicitly set the device node rather than  using  /dev/net/tun,
     495              /dev/tun,  /dev/tap,  etc.  If OpenVPN cannot figure out whether
     496              node is a TUN or TAP device based on the name, you  should  also
    411497              specify --dev-type tun or --dev-type tap.
    412498
    413               On  Windows  systems, select the TAP-Win32 adapter which is named node in the Network Connections
    414               Control Panel or the raw GUID of the adapter enclosed  by  braces.   The  --show-adapters  option
    415               under  Windows  can also be used to enumerate all available TAP-Win32 adapters and will show both
    416               the network connections control panel name and the GUID for each TAP-Win32 adapter.
     499              On  Windows systems, select the TAP-Win32 adapter which is named
     500              node in the Network Connections Control Panel or the raw GUID of
     501              the  adapter  enclosed  by  braces.   The --show-adapters option
     502              under Windows can also be used to enumerate all  available  TAP-
     503              Win32  adapters  and will show both the network connections con‐
     504              trol panel name and the GUID for each TAP-Win32 adapter.
    417505
    418506       --lladdr address
    419               Specify the link layer address, more commonly known as the MAC  address.   Only  applied  to  TAP
    420               devices.
     507              Specify the link layer address, more commonly known as  the  MAC
     508              address.  Only applied to TAP devices.
    421509
    422510       --iproute cmd
    423               Set  alternate  command  to execute instead of default iproute2 command.  May be used in order to
    424               execute OpenVPN in unprivileged environment.
     511              Set  alternate  command  to  execute instead of default iproute2
     512              command.  May be used in order to execute  OpenVPN  in  unprivi‐
     513              leged environment.
    425514
    426515       --ifconfig l rn
    427               Set TUN/TAP adapter parameters.  l is the IP address of the local VPN endpoint.  For TUN devices,
    428               rn  is  the IP address of the remote VPN endpoint.  For TAP devices, rn is the subnet mask of the
    429               virtual ethernet segment which is being created or connected to.
    430 
    431               For TUN devices, which facilitate virtual point-to-point IP  connections,  the  proper  usage  of
    432               --ifconfig is to use two private IP addresses which are not a member of any existing subnet which
    433               is in use.  The IP addresses may be consecutive and should  have  their  order  reversed  on  the
    434               remote peer.  After the VPN is established, by pinging rn, you will be pinging across the VPN.
    435 
    436               For  TAP  devices,  which  provide the ability to create virtual ethernet segments, --ifconfig is
    437               used to set an IP address and subnet mask just as a physical ethernet adapter would be  similarly
    438               configured.   If  you  are  attempting to connect to a remote ethernet bridge, the IP address and
    439               subnet should be set to values which would be valid on the the  bridged  ethernet  segment  (note
    440               also that DHCP can be used for the same purpose).
    441 
    442               This option, while primarily a proxy for the ifconfig(8) command, is designed to simplify TUN/TAP
    443               tunnel configuration by providing a standard interface to the different ifconfig  implementations
    444               on different platforms.
    445 
    446               --ifconfig  parameters  which  are IP addresses can also be specified as a DNS or /etc/hosts file
    447               resolvable name.
    448 
    449               For TAP devices, --ifconfig should not be used if the TAP interface will be getting an IP address
    450               lease from a DHCP server.
     516              Set  TUN/TAP  adapter  parameters.   l  is the IP address of the
     517              local VPN endpoint.  For TUN devices, rn is the  IP  address  of
     518              the remote VPN endpoint.  For TAP devices, rn is the subnet mask
     519              of the virtual ethernet segment which is being created  or  con‐
     520              nected to.
     521
     522              For TUN devices, which facilitate virtual point-to-point IP con‐
     523              nections, the proper usage of --ifconfig is to use  two  private
     524              IP addresses which are not a member of any existing subnet which
     525              is in use.  The IP addresses may be consecutive and should  have
     526              their  order  reversed  on  the  remote  peer.  After the VPN is
     527              established, by pinging rn, you will be pinging across the VPN.
     528
     529              For TAP devices, which provide the  ability  to  create  virtual
     530              ethernet  segments,  --ifconfig is used to set an IP address and
     531              subnet mask just as a physical ethernet adapter would  be  simi‐
     532              larly  configured.  If you are attempting to connect to a remote
     533              ethernet bridge, the IP address and subnet should be set to val‐
     534              ues  which  would  be  valid on the the bridged ethernet segment
     535              (note also that DHCP can be used for the same purpose).
     536
     537              This option, while primarily a proxy for  the  ifconfig(8)  com‐
     538              mand,  is  designed  to simplify TUN/TAP tunnel configuration by
     539              providing a standard interface to the different ifconfig  imple‐
     540              mentations on different platforms.
     541
     542              --ifconfig  parameters which are IP addresses can also be speci‐
     543              fied as a DNS or /etc/hosts file resolvable name.
     544
     545              For TAP devices, --ifconfig should not be used if the TAP inter‐
     546              face will be getting an IP address lease from a DHCP server.
    451547
    452548       --ifconfig-noexec
    453               Don't  actually  execute  ifconfig/netsh  commands, instead pass --ifconfig parameters to scripts
    454               using environmental variables.
     549              Don't  actually  execute  ifconfig/netsh  commands, instead pass
     550              --ifconfig parameters to scripts using environmental variables.
    455551
    456552       --ifconfig-nowarn
    457               Don't output an options consistency check warning if the --ifconfig option on this  side  of  the
    458               connection  doesn't  match  the  remote side.  This is useful when you want to retain the overall
    459               benefits of the options consistency check (also see --disable-occ option)  while  only  disabling
    460               the ifconfig component of the check.
    461 
    462               For example, if you have a configuration where the local host uses --ifconfig but the remote host
    463               does not, use --ifconfig-nowarn on the local host.
    464 
    465               This option will also silence warnings about potential address conflicts which occasionally annoy
    466               more experienced users by triggering "false positive" warnings.
     553              Don't  output  an  options  consistency  check  warning  if  the
     554              --ifconfig  option  on this side of the connection doesn't match
     555              the remote side.  This is useful when you  want  to  retain  the
     556              overall  benefits  of  the  options  consistency check (also see
     557              --disable-occ option) while only disabling the  ifconfig  compo‐
     558              nent of the check.
     559
     560              For  example,  if  you have a configuration where the local host
     561              uses --ifconfig but the remote host does  not,  use  --ifconfig-
     562              nowarn on the local host.
     563
     564              This  option  will also silence warnings about potential address
     565              conflicts which occasionally annoy  more  experienced  users  by
     566              triggering "false positive" warnings.
    467567
    468568       --route network/IP [netmask] [gateway] [metric]
    469               Add  route  to  routing table after connection is established.  Multiple routes can be specified.
    470               Routes will be automatically torn down in reverse order prior to TUN/TAP device close.
    471 
    472               This option is intended as a convenience proxy for the route(8) shell command, while at the  same
    473               time providing portable semantics across OpenVPN's platform space.
     569              Add  route  to  routing  table  after connection is established.
     570              Multiple routes can be specified.  Routes will be  automatically
     571              torn down in reverse order prior to TUN/TAP device close.
     572
     573              This  option is intended as a convenience proxy for the route(8)
     574              shell command, while at the same time providing portable  seman‐
     575              tics across OpenVPN's platform space.
    474576
    475577              netmask default -- 255.255.255.255
    476578
    477               gateway  default  --  taken from --route-gateway or the second parameter to --ifconfig when --dev
    478               tun is specified.
     579              gateway  default  --  taken  from  --route-gateway or the second
     580              parameter to --ifconfig when --dev tun is specified.
    479581
    480582              metric default -- taken from --route-metric otherwise 0.
    481583
    482               The default can be specified by leaving an option blank or setting it to "default".
    483 
    484               The network and gateway parameters can also be specified as a DNS or /etc/hosts  file  resolvable
    485               name, or as one of three special keywords:
    486 
    487               vpn_gateway -- The remote VPN endpoint address (derived either from --route-gateway or the second
    488               parameter to --ifconfig when --dev tun is specified).
    489 
    490               net_gateway -- The pre-existing IP default gateway, read from the routing table (not supported on
    491               all OSes).
    492 
    493               remote_host  --  The --remote address if OpenVPN is being run in client mode, and is undefined in
    494               server mode.
     584              The default can be specified by leaving an option blank or  set‐
     585              ting it to "default".
     586
     587              The  network  and  gateway parameters can also be specified as a
     588              DNS or /etc/hosts file resolvable name, or as one of three  spe‐
     589              cial keywords:
     590
     591              vpn_gateway  --  The remote VPN endpoint address (derived either
     592              from --route-gateway or the second parameter to --ifconfig  when
     593              --dev tun is specified).
     594
     595              net_gateway  --  The  pre-existing IP default gateway, read from
     596              the routing table (not supported on all OSes).
     597
     598              remote_host -- The --remote address if OpenVPN is being  run  in
     599              client mode, and is undefined in server mode.
    495600
    496601       --max-routes n
    497               Allow a maximum number of n --route options to be specified, either in  the  local  configuration
    498               file, or pulled from an OpenVPN server.  By default, n=100.
     602              Allow  a  maximum  number  of n --route options to be specified,
     603              either in the local configuration file, or pulled from an  Open‐
     604              VPN server.  By default, n=100.
    499605
    500606       --route-gateway gw|'dhcp'
    501607              Specify a default gateway gw for use with --route.
    502608
    503               If dhcp is specified as the parameter, the gateway address will be extracted from a DHCP negotia‐
    504               tion with the OpenVPN server-side LAN.
     609              If  dhcp is specified as the parameter, the gateway address will
     610              be extracted from a DHCP negotiation with  the  OpenVPN  server-
     611              side LAN.
    505612
    506613       --route-metric m
     
    508615
    509616       --route-delay [n] [w]
    510               Delay n seconds (default=0) after connection establishment, before adding  routes.  If  n  is  0,
    511               routes  will  be  added  immediately upon connection establishment.  If --route-delay is omitted,
    512               routes will be added immediately after TUN/TAP device open and --up script execution, before  any
    513               --user or --group privilege downgrade (or --chroot execution.)
    514 
    515               This  option  is  designed  to  be  useful  in  scenarios  where  DHCP is used to set tap adapter
    516               addresses.  The delay will give the DHCP handshake time to complete before routes are added.
    517 
    518               On Windows, --route-delay tries to be more intelligent by waiting w seconds (w=30 by default) for
    519               the TAP-Win32 adapter to come up before adding routes.
     617              Delay  n  seconds  (default=0)  after  connection establishment,
     618              before adding routes. If n is 0, routes will  be  added  immedi‐
     619              ately  upon connection establishment.  If --route-delay is omit‐
     620              ted, routes will be added immediately after TUN/TAP device  open
     621              and  --up  script execution, before any --user or --group privi‐
     622              lege downgrade (or --chroot execution.)
     623
     624              This option is designed to be useful in scenarios where DHCP  is
     625              used to set tap adapter addresses.  The delay will give the DHCP
     626              handshake time to complete before routes are added.
     627
     628              On Windows, --route-delay tries to be more intelligent by  wait‐
     629              ing  w  seconds  (w=30  by default) for the TAP-Win32 adapter to
     630              come up before adding routes.
    520631
    521632       --route-up cmd
    522               Run command cmd after routes are added, subject to --route-delay.
    523 
    524               cmd  consists  of a path to script (or executable program), optionally followed by arguments. The
    525               path and arguments may be single- or double-quoted and/or escaped using a backslash,  and  should
    526               be separated by one or more spaces.
    527 
    528               See the "Environmental Variables" section below for additional parameters passed as environmental
    529               variables.
     633              Run command cmd after routes  are  added,  subject  to  --route-
     634              delay.
     635
     636              cmd  consists  of  a  path  to  script  (or executable program),
     637              optionally followed by arguments. The path and arguments may  be
     638              single-  or  double-quoted and/or escaped using a backslash, and
     639              should be separated by one or more spaces.
     640
     641              See the "Environmental Variables" section below  for  additional
     642              parameters passed as environmental variables.
    530643
    531644       --route-pre-down cmd
    532645              Run command cmd before routes are removed upon disconnection.
    533646
    534               cmd consists of a path to script (or executable program), optionally followed by  arguments.  The
    535               path  and  arguments may be single- or double-quoted and/or escaped using a backslash, and should
    536               be separated by one or more spaces.
    537 
    538               See the "Environmental Variables" section below for additional parameters passed as environmental
    539               variables.
     647              cmd  consists  of  a  path  to  script  (or executable program),
     648              optionally followed by arguments. The path and arguments may  be
     649              single-  or  double-quoted and/or escaped using a backslash, and
     650              should be separated by one or more spaces.
     651
     652              See the "Environmental Variables" section below  for  additional
     653              parameters passed as environmental variables.
    540654
    541655       --route-noexec
    542               Don't  add  or remove routes automatically.  Instead pass routes to --route-up script using envi‐
    543               ronmental variables.
     656              Don't  add  or remove routes automatically.  Instead pass routes
     657              to --route-up script using environmental variables.
    544658
    545659       --route-nopull
    546               When used with --client or --pull, accept options pushed by server EXCEPT  for  routes  and  dhcp
    547               options like DNS servers.
    548 
    549               When  used  on  the  client,  this  option  effectively bars the server from adding routes to the
    550               client's routing table, however note that this option still allows the server to set  the  TCP/IP
    551               properties of the client's TUN/TAP interface.
     660              When used with --client or  --pull,  accept  options  pushed  by
     661              server EXCEPT for routes and dhcp options like DNS servers.
     662
     663              When used on the client, this option effectively bars the server
     664              from adding routes to the client's routing table,  however  note
     665              that this option still allows the server to set the TCP/IP prop‐
     666              erties of the client's TUN/TAP interface.
    552667
    553668       --allow-pull-fqdn
    554               Allow client to pull DNS names from server (rather than being limited to IP address) for --ifcon‐
    555               fig, --route, and --route-gateway.
     669              Allow client to pull DNS names from server  (rather  than  being
     670              limited  to  IP  address)  for --ifconfig, --route, and --route-
     671              gateway.
    556672
    557673       --client-nat snat|dnat network netmask alias
    558               This pushable client option sets up a stateless one-to-one NAT  rule  on  packet  addresses  (not
    559               ports),  and is useful in cases where routes or ifconfig settings pushed to the client would cre‐
    560               ate an IP numbering conflict.
    561 
    562               network/netmask (for example 192.168.0.0/255.255.0.0) defines the local view of a  resource  from
    563               the  client  perspective,  while  alias/netmask  (for  example 10.64.0.0/255.255.0.0) defines the
     674              This pushable client option sets up a stateless  one-to-one  NAT
     675              rule  on  packet  addresses  (not ports), and is useful in cases
     676              where routes or ifconfig settings pushed  to  the  client  would
     677              create an IP numbering conflict.
     678
     679              network/netmask  (for  example  192.168.0.0/255.255.0.0) defines
     680              the local view of a resource from the client perspective,  while
     681              alias/netmask  (for  example  10.64.0.0/255.255.0.0) defines the
    564682              remote view from the server perspective.
    565683
    566               Use snat (source NAT) for resources owned by the client and dnat  (destination  NAT)  for  remote
    567               resources.
    568 
    569               Set --verb 6 for debugging info showing the transformation of src/dest addresses in packets.
     684              Use snat (source NAT) for resources owned by the client and dnat
     685              (destination NAT) for remote resources.
     686
     687              Set  --verb  6  for debugging info showing the transformation of
     688              src/dest addresses in packets.
    570689
    571690       --redirect-gateway flags...
    572               Automatically execute routing commands to cause all outgoing IP traffic to be redirected over the
    573               VPN.  This is a client-side option.
     691              Automatically execute routing commands to cause all outgoing  IP
     692              traffic  to  be  redirected over the VPN.  This is a client-side
     693              option.
    574694
    575695              This option performs three steps:
    576696
    577               (1) Create a static route for the --remote address which forwards  to  the  pre-existing  default
    578               gateway.  This is done so that (3) will not create a routing loop.
     697              (1) Create a static route for the --remote  address  which  for‐
     698              wards to the pre-existing default gateway.  This is done so that
     699              (3) will not create a routing loop.
    579700
    580701              (2) Delete the default gateway route.
    581702
    582               (3) Set the new default gateway to be the VPN endpoint address (derived either from --route-gate‐
    583               way or the second parameter to --ifconfig when --dev tun is specified).
    584 
    585               When the tunnel is torn down, all of the above steps are reversed so that  the  original  default
    586               route is restored.
     703              (3) Set the new default gateway to be the VPN  endpoint  address
     704              (derived  either from --route-gateway or the second parameter to
     705              --ifconfig when --dev tun is specified).
     706
     707              When the tunnel is  torn  down,  all  of  the  above  steps  are
     708              reversed so that the original default route is restored.
    587709
    588710              Option flags:
    589711
    590               local  --  Add the local flag if both OpenVPN servers are directly connected via a common subnet,
    591               such as with wireless.  The local flag will cause step 1 above to be omitted.
    592 
    593               autolocal -- Try to automatically determine whether to enable local flag above.
    594 
    595               def1 -- Use this flag to override the default gateway by using 0.0.0.0/1 and  128.0.0.0/1  rather
    596               than 0.0.0.0/0.  This has the benefit of overriding but not wiping out the original default gate‐
    597               way.
    598 
    599               bypass-dhcp -- Add a direct route to the DHCP server (if it is non-local) which bypasses the tun‐
    600               nel (Available on Windows clients, may not be available on non-Windows clients).
    601 
    602               bypass-dns  -- Add a direct route to the DNS server(s) (if they are non-local) which bypasses the
    603               tunnel (Available on Windows clients, may not be available on non-Windows clients).
    604 
    605               block-local -- Block access to local LAN when the tunnel is active, except for  the  LAN  gateway
    606               itself.   This is accomplished by routing the local LAN (except for the LAN gateway address) into
    607               the tunnel.
     712              local -- Add the local flag if both OpenVPN servers are directly
     713              connected via a common subnet, such as with wireless.  The local
     714              flag will cause step 1 above to be omitted.
     715
     716              autolocal  --  Try  to automatically determine whether to enable
     717              local flag above.
     718
     719              def1 -- Use this flag to override the default gateway  by  using
     720              0.0.0.0/1  and  128.0.0.0/1 rather than 0.0.0.0/0.  This has the
     721              benefit of overriding but not wiping out  the  original  default
     722              gateway.
     723
     724              bypass-dhcp  --  Add a direct route to the DHCP server (if it is
     725              non-local) which  bypasses  the  tunnel  (Available  on  Windows
     726              clients, may not be available on non-Windows clients).
     727
     728              bypass-dns  --  Add a direct route to the DNS server(s) (if they
     729              are non-local) which bypasses the tunnel (Available  on  Windows
     730              clients, may not be available on non-Windows clients).
     731
     732              block-local  --  Block  access  to  local LAN when the tunnel is
     733              active, except for the LAN gateway itself.  This is accomplished
     734              by  routing  the  local LAN (except for the LAN gateway address)
     735              into the tunnel.
    608736
    609737       --link-mtu n
    610               Sets an upper bound on the size of UDP packets which are sent between OpenVPN peers.   It's  best
    611               not to set this parameter unless you know what you're doing.
     738              Sets an upper bound on the size of UDP packets  which  are  sent
     739              between  OpenVPN  peers.   It's  best  not to set this parameter
     740              unless you know what you're doing.
    612741
    613742       --redirect-private [flags]
    614               Like  --redirect-gateway,  but  omit  actually changing the default gateway.  Useful when pushing
    615               private subnets.
     743              Like --redirect-gateway, but omit actually changing the  default
     744              gateway.  Useful when pushing private subnets.
    616745
    617746       --tun-mtu n
    618               Take the TUN device MTU to be n and derive the link MTU from it (default=1500).  In  most  cases,
    619               you will probably want to leave this parameter set to its default value.
    620 
    621               The  MTU  (Maximum  Transmission  Units)  is  the maximum datagram size in bytes that can be sent
    622               unfragmented over a particular network path.  OpenVPN requires that packets  on  the  control  or
     747              Take  the TUN device MTU to be n and derive the link MTU from it
     748              (default=1500).  In most cases, you will probably want to  leave
     749              this parameter set to its default value.
     750
     751              The  MTU  (Maximum  Transmission  Units) is the maximum datagram
     752              size in bytes that can be sent unfragmented  over  a  particular
     753              network  path.   OpenVPN requires that packets on the control or
    623754              data channels be sent unfragmented.
    624755
    625               MTU problems often manifest themselves as connections which hang during periods of active usage.
    626 
    627               It's best to use the --fragment and/or --mssfix options to deal with MTU sizing issues.
     756              MTU problems often manifest themselves as connections which hang
     757              during periods of active usage.
     758
     759              It's  best to use the --fragment and/or --mssfix options to deal
     760              with MTU sizing issues.
    628761
    629762       --tun-mtu-extra n
    630               Assume  that  the  TUN/TAP device might return as many as n bytes more than the --tun-mtu size on
    631               read.  This parameter defaults to 0, which is sufficient for most TUN devices.  TAP  devices  may
    632               introduce  additional overhead in excess of the MTU size, and a setting of 32 is the default when
    633               TAP devices are used.  This parameter only controls internal OpenVPN buffer sizing, so  there  is
    634               no transmission overhead associated with using a larger value.
     763              Assume that the TUN/TAP device might return as many as  n  bytes
     764              more  than  the --tun-mtu size on read.  This parameter defaults
     765              to 0, which is sufficient for most TUN devices.  TAP devices may
     766              introduce  additional  overhead in excess of the MTU size, and a
     767              setting of 32 is the default when TAP devices  are  used.   This
     768              parameter only controls internal OpenVPN buffer sizing, so there
     769              is no transmission  overhead  associated  with  using  a  larger
     770              value.
    635771
    636772       --mtu-disc type
    637               Should  we  do  Path MTU discovery on TCP/UDP channel?  Only supported on OSes such as Linux that
    638               supports the necessary system call to set.
     773              Should  we  do Path MTU discovery on TCP/UDP channel?  Only sup‐
     774              ported on OSes such as Linux that supports the necessary  system
     775              call to set.
    639776
    640777              'no' -- Never send DF (Don't Fragment) frames
     
    643780
    644781       --mtu-test
    645               To empirically measure MTU on connection startup, add the --mtu-test option  to  your  configura‐
    646               tion.  OpenVPN will send ping packets of various sizes to the remote peer and measure the largest
    647               packets which were successfully received.  The --mtu-test process normally takes about 3  minutes
    648               to complete.
     782              To empirically measure MTU on connection startup, add the --mtu-
     783              test option to your configuration.  OpenVPN will send ping pack‐
     784              ets  of various sizes to the remote peer and measure the largest
     785              packets  which  were  successfully  received.   The   --mtu-test
     786              process normally takes about 3 minutes to complete.
    649787
    650788       --fragment max
    651               Enable  internal  datagram  fragmentation so that no UDP datagrams are sent which are larger than
    652               max bytes.
    653 
    654               The max parameter is interpreted in the same way as the --link-mtu parameter, i.e. the UDP packet
    655               size after encapsulation overhead has been added in, but not including the UDP header itself.
    656 
    657               The --fragment option only makes sense when you are using the UDP protocol ( --proto udp ).
     789              Enable  internal datagram fragmentation so that no UDP datagrams
     790              are sent which are larger than max bytes.
     791
     792              The max parameter is interpreted in the same way as the  --link-
     793              mtu  parameter,  i.e.  the  UDP  packet size after encapsulation
     794              overhead has been added in, but not  including  the  UDP  header
     795              itself.
     796
     797              The  --fragment  option  only makes sense when you are using the
     798              UDP protocol ( --proto udp ).
    658799
    659800              --fragment adds 4 bytes of overhead per datagram.
    660801
    661               See the --mssfix option below for an important related option to --fragment.
    662 
    663               It  should  also  be  noted  that this option is not meant to replace UDP fragmentation at the IP
    664               stack level.  It is only meant as a last resort when path MTU discovery is  broken.   Using  this
    665               option  is  less  efficient  than  fixing path MTU discovery for your IP link and using native IP
    666               fragmentation instead.
    667 
    668               Having said that, there are circumstances where using OpenVPN's internal fragmentation capability
    669               may be your only option, such as tunneling a UDP multicast stream which requires fragmentation.
     802              See the --mssfix option below for an important related option to
     803              --fragment.
     804
     805              It should also be noted that this option is not meant to replace
     806              UDP fragmentation at the IP stack level.  It is only meant as  a
     807              last  resort  when  path  MTU  discovery  is broken.  Using this
     808              option is less efficient than fixing path MTU discovery for your
     809              IP link and using native IP fragmentation instead.
     810
     811              Having  said that, there are circumstances where using OpenVPN's
     812              internal fragmentation capability may be your only option,  such
     813              as  tunneling  a  UDP multicast stream which requires fragmenta‐
     814              tion.
    670815
    671816       --mssfix max
    672               Announce  to  TCP sessions running over the tunnel that they should limit their send packet sizes
    673               such that after OpenVPN has encapsulated them, the resulting UDP packet size that  OpenVPN  sends
    674               to its peer will not exceed max bytes. The default value is 1450.
    675 
    676               The max parameter is interpreted in the same way as the --link-mtu parameter, i.e. the UDP packet
    677               size after encapsulation overhead has been added in, but not including the UDP header itself.
    678 
    679               The --mssfix option only makes sense when you are using the UDP protocol for OpenVPN peer-to-peer
    680               communication, i.e.  --proto udp.
    681 
    682               --mssfix  and  --fragment  can be ideally used together, where --mssfix will try to keep TCP from
    683               needing packet fragmentation in the first place, and if big packets  come  through  anyhow  (from
    684               protocols other than TCP), --fragment will internally fragment them.
    685 
    686               Both --fragment and --mssfix are designed to work around cases where Path MTU discovery is broken
    687               on the network path between OpenVPN peers.
    688 
    689               The usual symptom of such a breakdown is an OpenVPN connection  which  successfully  starts,  but
    690               then stalls during active usage.
    691 
    692               If  --fragment  and --mssfix are used together, --mssfix will take its default max parameter from
    693               the --fragment max option.
    694 
    695               Therefore, one could lower the maximum UDP packet size to 1300 (a good first try for solving MTU-
    696               related connection problems) with the following options:
     817              Announce to TCP sessions  running  over  the  tunnel  that  they
     818              should limit their send packet sizes such that after OpenVPN has
     819              encapsulated them, the resulting UDP packet  size  that  OpenVPN
     820              sends  to  its peer will not exceed max bytes. The default value
     821              is 1450.
     822
     823              The max parameter is interpreted in the same way as the  --link-
     824              mtu  parameter,  i.e.  the  UDP  packet size after encapsulation
     825              overhead has been added in, but not  including  the  UDP  header
     826              itself.
     827
     828              The  --mssfix option only makes sense when you are using the UDP
     829              protocol for OpenVPN peer-to-peer communication,  i.e.   --proto
     830              udp.
     831
     832              --mssfix  and  --fragment  can  be  ideally used together, where
     833              --mssfix will try to keep TCP from needing packet  fragmentation
     834              in the first place, and if big packets come through anyhow (from
     835              protocols other than TCP), --fragment will  internally  fragment
     836              them.
     837
     838              Both  --fragment  and --mssfix are designed to work around cases
     839              where Path MTU discovery is broken on the network  path  between
     840              OpenVPN peers.
     841
     842              The  usual  symptom of such a breakdown is an OpenVPN connection
     843              which successfully starts, but then stalls during active usage.
     844
     845              If --fragment and --mssfix are used together, --mssfix will take
     846              its default max parameter from the --fragment max option.
     847
     848              Therefore,  one  could lower the maximum UDP packet size to 1300
     849              (a good first try for solving MTU-related  connection  problems)
     850              with the following options:
    697851
    698852              --tun-mtu 1500 --fragment 1300 --mssfix
    699853
    700854       --sndbuf size
    701               Set the TCP/UDP socket send buffer size.  Currently defaults to 65536 bytes.
     855              Set  the TCP/UDP socket send buffer size.  Currently defaults to
     856              65536 bytes.
    702857
    703858       --rcvbuf size
    704               Set the TCP/UDP socket receive buffer size.  Currently defaults to 65536 bytes.
     859              Set the TCP/UDP socket receive buffer size.  Currently  defaults
     860              to 65536 bytes.
    705861
    706862       --mark value
    707               Mark encrypted packets being sent with value. The mark value can be matched in policy routing and
    708               packetfilter rules. This option is only supported in Linux and does nothing  on  other  operating
     863              Mark encrypted packets being sent with value. The mark value can
     864              be matched in policy routing and packetfilter rules. This option
     865              is  only  supported in Linux and does nothing on other operating
    709866              systems.
    710867
    711868       --socket-flags flags...
    712               Apply the given flags to the OpenVPN transport socket.  Currently, only TCP_NODELAY is supported.
    713 
    714               The  TCP_NODELAY  socket flag is useful in TCP mode, and causes the kernel to send tunnel packets
    715               immediately over the TCP connection without trying to group several smaller packets into a larger
    716               packet.  This can result in a considerably improvement in latency.
    717 
    718               This  option  is pushable from server to client, and should be used on both client and server for
    719               maximum effect.
     869              Apply the given flags to the  OpenVPN  transport  socket.   Cur‐
     870              rently, only TCP_NODELAY is supported.
     871
     872              The  TCP_NODELAY  socket  flag is useful in TCP mode, and causes
     873              the kernel to send tunnel packets immediately over the TCP  con‐
     874              nection  without  trying to group several smaller packets into a
     875              larger packet.  This can result in a considerably improvement in
     876              latency.
     877
     878              This  option  is  pushable  from server to client, and should be
     879              used on both client and server for maximum effect.
    720880
    721881       --txqueuelen n
    722               (Linux only) Set the TX queue length on the TUN/TAP interface.  Currently defaults to 100.
     882              (Linux only) Set the TX queue length on the  TUN/TAP  interface.
     883              Currently defaults to 100.
    723884
    724885       --shaper n
    725               Limit bandwidth of outgoing tunnel data to n bytes per second on the TCP/UDP port.  If  you  want
    726               to limit the bandwidth in both directions, use this option on both peers.
    727 
    728               OpenVPN uses the following algorithm to implement traffic shaping: Given a shaper rate of n bytes
    729               per second, after a datagram write of b bytes is queued on the TCP/UDP port, wait a minimum of (b
    730               / n) seconds before queuing the next write.
    731 
    732               It  should  be  noted that OpenVPN supports multiple tunnels between the same two peers, allowing
    733               you to construct full-speed and reduced bandwidth tunnels at the same time, routing  low-priority
    734               data  such  as  off-site backups over the reduced bandwidth tunnel, and other data over the full-
    735               speed tunnel.
    736 
    737               Also note that for low bandwidth tunnels (under 1000 bytes per second), you should  probably  use
    738               lower MTU values as well (see above), otherwise the packet latency will grow so large as to trig‐
    739               ger timeouts in the TLS layer and TCP connections running over the tunnel.
     886              Limit bandwidth of outgoing tunnel data to n bytes per second on
     887              the TCP/UDP port.  If you want to limit the  bandwidth  in  both
     888              directions, use this option on both peers.
     889
     890              OpenVPN  uses the following algorithm to implement traffic shap‐
     891              ing: Given a shaper rate of n bytes per second, after a datagram
     892              write  of  b bytes is queued on the TCP/UDP port, wait a minimum
     893              of (b / n) seconds before queuing the next write.
     894
     895              It should  be  noted  that  OpenVPN  supports  multiple  tunnels
     896              between the same two peers, allowing you to construct full-speed
     897              and reduced bandwidth tunnels at the same time, routing low-pri‐
     898              ority  data  such as off-site backups over the reduced bandwidth
     899              tunnel, and other data over the full-speed tunnel.
     900
     901              Also note that for low bandwidth tunnels (under 1000  bytes  per
     902              second),  you  should probably use lower MTU values as well (see
     903              above), otherwise the packet latency will grow so  large  as  to
     904              trigger  timeouts  in  the TLS layer and TCP connections running
     905              over the tunnel.
    740906
    741907              OpenVPN allows n to be between 100 bytes/sec and 100 Mbytes/sec.
    742908
    743909       --inactive n [bytes]
    744               Causes OpenVPN to exit after n seconds of inactivity on the TUN/TAP device. The  time  length  of
    745               inactivity is measured since the last incoming or outgoing tunnel packet.  The default value is 0
    746               seconds, which disables this feature.
    747 
    748               If the optional bytes parameter is included, exit if less than bytes of combined  in/out  traffic
    749               are produced on the tun/tap device in n seconds.
    750 
    751               In  any case, OpenVPN's internal ping packets (which are just keepalives) and TLS control packets
    752               are not considered "activity", nor are they counted as traffic, as they are  used  internally  by
    753               OpenVPN and are not an indication of actual user activity.
     910              Causes OpenVPN to exit after n  seconds  of  inactivity  on  the
     911              TUN/TAP  device. The time length of inactivity is measured since
     912              the last incoming or outgoing tunnel packet.  The default  value
     913              is 0 seconds, which disables this feature.
     914
     915              If  the  optional bytes parameter is included, exit if less than
     916              bytes of combined in/out traffic are  produced  on  the  tun/tap
     917              device in n seconds.
     918
     919              In  any  case,  OpenVPN's  internal ping packets (which are just
     920              keepalives) and TLS control packets are not  considered  "activ‐
     921              ity",  nor  are they counted as traffic, as they are used inter‐
     922              nally by OpenVPN and are not an indication of actual user activ‐
     923              ity.
    754924
    755925       --ping n
    756               Ping  remote over the TCP/UDP control channel if no packets have been sent for at least n seconds
    757               (specify --ping on both peers to cause ping packets to be sent in both directions  since  OpenVPN
    758               ping  packets  are  not echoed like IP ping packets).  When used in one of OpenVPN's secure modes
    759               (where --secret, --tls-server, or --tls-client is specified), the ping  packet  will  be  crypto‐
    760               graphically secure.
     926              Ping  remote over the TCP/UDP control channel if no packets have
     927              been sent for at least n seconds (specify --ping on  both  peers
     928              to  cause ping packets to be sent in both directions since Open‐
     929              VPN ping packets are not echoed like  IP  ping  packets).   When
     930              used  in  one  of OpenVPN's secure modes (where --secret, --tls-
     931              server, or --tls-client is specified), the ping packet  will  be
     932              cryptographically secure.
    761933
    762934              This option has two intended uses:
    763935
    764               (1)  Compatibility  with stateful firewalls.  The periodic ping will ensure that a stateful fire‐
    765               wall rule which allows OpenVPN UDP packets to pass will not time out.
    766 
    767               (2) To provide a basis for the remote to test the existence of its  peer  using  the  --ping-exit
    768               option.
     936              (1)  Compatibility  with  stateful firewalls.  The periodic ping
     937              will ensure that a stateful firewall rule which  allows  OpenVPN
     938              UDP packets to pass will not time out.
     939
     940              (2)  To  provide a basis for the remote to test the existence of
     941              its peer using the --ping-exit option.
    769942
    770943       --ping-exit n
    771               Causes  OpenVPN  to  exit  after  n seconds pass without reception of a ping or other packet from
    772               remote.  This option can be combined with --inactive, --ping, and --ping-exit to  create  a  two-
    773               tiered inactivity disconnect.
     944              Causes OpenVPN to exit after n seconds pass without reception of
     945              a ping or other packet from remote.  This option can be combined
     946              with --inactive, --ping, and --ping-exit to create a  two-tiered
     947              inactivity disconnect.
    774948
    775949              For example,
     
    777951              openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60
    778952
    779               when used on both peers will cause OpenVPN to exit within 60 seconds if its peer disconnects, but
    780               will exit after one hour if no actual tunnel data is exchanged.
     953              when  used  on  both  peers will cause OpenVPN to exit within 60
     954              seconds if its peer disconnects, but will exit after one hour if
     955              no actual tunnel data is exchanged.
    781956
    782957       --ping-restart n
    783               Similar to --ping-exit, but trigger a SIGUSR1 restart after n seconds pass without reception of a
    784               ping or other packet from remote.
    785 
    786               This  option  is useful in cases where the remote peer has a dynamic IP address and a low-TTL DNS
    787               name is used to track the IP address using a service such as http://dyndns.org/ + a  dynamic  DNS
    788               client such as ddclient.
    789 
    790               If  the  peer  cannot  be  reached,  a  restart will be triggered, causing the hostname used with
    791               --remote to be re-resolved (if --resolv-retry is also specified).
    792 
    793               In server mode, --ping-restart, --inactive, or any other type of internally generated signal will
    794               always be applied to individual client instance objects, never to whole server itself.  Note also
    795               in server mode that any internally generated signal which would normally cause  a  restart,  will
    796               cause the deletion of the client instance object instead.
    797 
    798               In client mode, the --ping-restart parameter is set to 120 seconds by default.  This default will
    799               hold until the client pulls a replacement value from the server, based on the --keepalive setting
    800               in  the  server  configuration.   To  disable the 120 second default, set --ping-restart 0 on the
    801               client.
     958              Similar  to  --ping-exit,  but trigger a SIGUSR1 restart after n
     959              seconds pass without reception of a ping or  other  packet  from
     960              remote.
     961
     962              This  option  is  useful  in  cases  where the remote peer has a
     963              dynamic IP address and a low-TTL DNS name is used to  track  the
     964              IP  address  using  a  service  such  as  http://dyndns.org/ + a
     965              dynamic DNS client such as ddclient.
     966
     967              If the peer cannot be reached,  a  restart  will  be  triggered,
     968              causing  the  hostname  used with --remote to be re-resolved (if
     969              --resolv-retry is also specified).
     970
     971              In server mode, --ping-restart, --inactive, or any other type of
     972              internally generated signal will always be applied to individual
     973              client instance objects, never to  whole  server  itself.   Note
     974              also  in  server mode that any internally generated signal which
     975              would normally cause a restart, will cause the deletion  of  the
     976              client instance object instead.
     977
     978              In  client mode, the --ping-restart parameter is set to 120 sec‐
     979              onds by default.  This default will hold until the client  pulls
     980              a  replacement  value  from the server, based on the --keepalive
     981              setting in the server configuration.  To disable the 120  second
     982              default, set --ping-restart 0 on the client.
    802983
    803984              See the signals section below for more information on SIGUSR1.
    804985
    805               Note that the behavior of SIGUSR1 can be modified by the --persist-tun, --persist-key, --persist-
    806               local-ip, and --persist-remote-ip options.
    807 
    808               Also note that --ping-exit and --ping-restart are mutually exclusive and cannot be used together.
     986              Note  that the behavior of SIGUSR1 can be modified by the --per‐
     987              sist-tun,  --persist-key,  --persist-local-ip,  and   --persist-
     988              remote-ip options.
     989
     990              Also  note  that  --ping-exit  and  --ping-restart  are mutually
     991              exclusive and cannot be used together.
    809992
    810993       --keepalive n m
    811               A  helper  directive  designed  to simplify the expression of --ping and --ping-restart in server
    812               mode configurations.
    813 
    814               The server timeout is set twice the value of the second argument.  This ensures that a timeout is
    815               dectected on client side before the server side drops the connection.
     994              A helper directive designed to simplify the expression of --ping
     995              and --ping-restart in server mode configurations.
     996
     997              The  server  timeout  is set twice the value of the second argu‐
     998              ment.  This ensures that a timeout is dectected on  client  side
     999              before the server side drops the connection.
    8161000
    8171001              For example, --keepalive 10 60 expands as follows:
     
    8271011
    8281012       --ping-timer-rem
    829               Run  the --ping-exit / --ping-restart timer only if we have a remote address.  Use this option if
    830               you are starting the daemon in listen mode (i.e. without an  explicit  --remote  peer),  and  you
    831               don't want to start clocking timeouts until a remote peer connects.
     1013              Run  the  --ping-exit  /  --ping-restart timer only if we have a
     1014              remote address.  Use this option if you are starting the  daemon
     1015              in listen mode (i.e. without an explicit --remote peer), and you
     1016              don't want to start clocking timeouts until a remote  peer  con‐
     1017              nects.
    8321018
    8331019       --persist-tun
    834               Don't  close  and  reopen  TUN/TAP device or run up/down scripts across SIGUSR1 or --ping-restart
    835               restarts.
    836 
    837               SIGUSR1 is a restart signal similar to SIGHUP, but which offers finer-grained control over  reset
    838               options.
     1020              Don't  close  and  reopen  TUN/TAP device or run up/down scripts
     1021              across SIGUSR1 or --ping-restart restarts.
     1022
     1023              SIGUSR1 is a restart signal similar to SIGHUP, but which  offers
     1024              finer-grained control over reset options.
    8391025
    8401026       --persist-key
    8411027              Don't re-read key files across SIGUSR1 or --ping-restart.
    8421028
    843               This option can be combined with --user nobody to allow restarts triggered by the SIGUSR1 signal.
    844               Normally if you drop root privileges in OpenVPN, the daemon cannot be restarted since it will now
    845               be unable to re-read protected key files.
    846 
    847               This option solves the problem by persisting keys across SIGUSR1 resets, so they don't need to be
    848               re-read.
     1029              This option can be combined with --user nobody to allow restarts
     1030              triggered by the SIGUSR1 signal.   Normally  if  you  drop  root
     1031              privileges  in  OpenVPN, the daemon cannot be restarted since it
     1032              will now be unable to re-read protected key files.
     1033
     1034              This option solves the problem by persisting keys across SIGUSR1
     1035              resets, so they don't need to be re-read.
    8491036
    8501037       --persist-local-ip
    851               Preserve initially resolved local IP address and port number  across  SIGUSR1  or  --ping-restart
    852               restarts.
     1038              Preserve  initially  resolved  local  IP address and port number
     1039              across SIGUSR1 or --ping-restart restarts.
    8531040
    8541041       --persist-remote-ip
    855               Preserve  most recently authenticated remote IP address and port number across SIGUSR1 or --ping-
    856               restart restarts.
     1042              Preserve most recently authenticated remote IP address and  port
     1043              number across SIGUSR1 or --ping-restart restarts.
    8571044
    8581045       --mlock
    859               Disable paging by calling the POSIX mlockall function.  Requires that OpenVPN be initially run as
    860               root (though OpenVPN can subsequently downgrade its UID using the --user option).
    861 
    862               Using this option ensures that key material and tunnel data are never written to disk due to vir‐
    863               tual memory paging operations which occur under most modern operating systems.  It  ensures  that
    864               even  if  an attacker was able to crack the box running OpenVPN, he would not be able to scan the
    865               system swap file to recover previously used ephemeral keys, which are used for a period  of  time
    866               governed by the --reneg options (see below), then are discarded.
    867 
    868               The  downside  of using --mlock is that it will reduce the amount of physical memory available to
    869               other applications.
     1046              Disable paging by calling the POSIX mlockall function.  Requires
     1047              that OpenVPN be initially run as root (though OpenVPN can subse‐
     1048              quently downgrade its UID using the --user option).
     1049
     1050              Using  this option ensures that key material and tunnel data are
     1051              never written to disk due to virtual  memory  paging  operations
     1052              which  occur  under  most  modern operating systems.  It ensures
     1053              that even if an attacker was able to crack the box running Open‐
     1054              VPN,  he  would  not  be  able  to  scan the system swap file to
     1055              recover previously used ephemeral keys, which  are  used  for  a
     1056              period of time governed by the --reneg options (see below), then
     1057              are discarded.
     1058
     1059              The downside of using --mlock is that it will reduce the  amount
     1060              of physical memory available to other applications.
    8701061
    8711062       --up cmd
    872               Run command cmd after successful TUN/TAP device open (pre --user UID change).
    873 
    874               cmd consists of a path to script (or executable program), optionally followed by  arguments.  The
    875               path  and  arguments may be single- or double-quoted and/or escaped using a backslash, and should
    876               be separated by one or more spaces.
    877 
    878               The up command is useful for specifying route commands which route IP traffic destined  for  pri‐
    879               vate subnets which exist at the other end of the VPN connection into the tunnel.
     1063              Run command cmd after successful TUN/TAP device open (pre --user
     1064              UID change).
     1065
     1066              cmd consists of  a  path  to  script  (or  executable  program),
     1067              optionally  followed by arguments. The path and arguments may be
     1068              single- or double-quoted and/or escaped using a  backslash,  and
     1069              should be separated by one or more spaces.
     1070
     1071              The  up  command  is  useful for specifying route commands which
     1072              route IP traffic destined for private subnets which exist at the
     1073              other end of the VPN connection into the tunnel.
    8801074
    8811075              For --dev tun execute as:
    8821076
    883               cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [ init | restart ]
     1077              cmd    tun_dev   tun_mtu   link_mtu   ifconfig_local_ip   ifcon‐
     1078              fig_remote_ip [ init | restart ]
    8841079
    8851080              For --dev tap execute as:
    8861081
    887               cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [ init | restart ]
    888 
    889               See the "Environmental Variables" section below for additional parameters passed as environmental
    890               variables.
    891 
    892               Note that if cmd includes arguments, all OpenVPN-generated arguments will be appended to them  to
    893               build an argument list with which the executable will be called.
     1082              cmd tap_dev tap_mtu link_mtu ifconfig_local_ip  ifconfig_netmask
     1083              [ init | restart ]
     1084
     1085              See  the  "Environmental Variables" section below for additional
     1086              parameters passed as environmental variables.
     1087
     1088              Note that if cmd includes arguments, all OpenVPN-generated argu‐
     1089              ments  will  be  appended to them to build an argument list with
     1090              which the executable will be called.
    8941091
    8951092              Typically, cmd will run a script to add routes to the tunnel.
    8961093
    897               Normally  the  up script is called after the TUN/TAP device is opened.  In this context, the last
    898               command line parameter passed to the script will be init.  If the  --up-restart  option  is  also
    899               used, the up script will be called for restarts as well.  A restart is considered to be a partial
    900               reinitialization of OpenVPN where the TUN/TAP instance is  preserved  (the  --persist-tun  option
    901               will enable such preservation).  A restart can be generated by a SIGUSR1 signal, a --ping-restart
    902               timeout, or a connection reset when the TCP protocol is enabled with the --proto  option.   If  a
    903               restart occurs, and --up-restart has been specified, the up script will be called with restart as
    904               the last parameter.
    905 
    906               The following standalone example shows how the --up script can be called in both  an  initializa‐
    907               tion  and  restart  context.  (NOTE: for security reasons, don't run the following example unless
    908               UDP port 9999 is blocked by your firewall.  Also, the  example  will  run  indefinitely,  so  you
    909               should abort with control-c).
    910 
    911               openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 --up 'echo up' --down 'echo down' --per‐
    912               sist-tun --up-restart
    913 
    914               Note that OpenVPN also provides the --ifconfig option to automatically ifconfig the  TUN  device,
    915               eliminating  the  need  to define an --up script, unless you also want to configure routes in the
    916               --up script.
    917 
    918               If --ifconfig is also specified, OpenVPN will pass the ifconfig local and remote endpoints on the
    919               command line to the --up script so that they can be used to configure routes such as:
     1094              Normally the up script is called after  the  TUN/TAP  device  is
     1095              opened.  In this context, the last command line parameter passed
     1096              to the script will be init.  If the --up-restart option is  also
     1097              used,  the  up  script  will  be called for restarts as well.  A
     1098              restart is considered to be a partial reinitialization of  Open‐
     1099              VPN  where  the TUN/TAP instance is preserved (the --persist-tun
     1100              option will enable such preservation).  A restart can be  gener‐
     1101              ated by a SIGUSR1 signal, a --ping-restart timeout, or a connec‐
     1102              tion reset when the TCP protocol is  enabled  with  the  --proto
     1103              option.   If  a restart occurs, and --up-restart has been speci‐
     1104              fied, the up script will be called  with  restart  as  the  last
     1105              parameter.
     1106
     1107              The  following  standalone example shows how the --up script can
     1108              be called in both an initialization and restart context.  (NOTE:
     1109              for security reasons, don't run the following example unless UDP
     1110              port 9999 is blocked by your firewall.  Also, the  example  will
     1111              run indefinitely, so you should abort with control-c).
     1112
     1113              openvpn  --dev  tun  --port 9999 --verb 4 --ping-restart 10 --up
     1114              'echo up' --down 'echo down' --persist-tun --up-restart
     1115
     1116              Note that OpenVPN also provides the --ifconfig option  to  auto‐
     1117              matically  ifconfig  the  TUN  device,  eliminating  the need to
     1118              define an --up script, unless you also want to configure  routes
     1119              in the --up script.
     1120
     1121              If  --ifconfig is also specified, OpenVPN will pass the ifconfig
     1122              local and remote endpoints on  the  command  line  to  the  --up
     1123              script so that they can be used to configure routes such as:
    9201124
    9211125              route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
    9221126
    9231127       --up-delay
    924               Delay  TUN/TAP  open and possible --up script execution until after TCP/UDP connection establish‐
    925               ment with peer.
    926 
    927               In --proto udp mode, this option normally requires the use of --ping to allow connection  initia‐
    928               tion to be sensed in the absence of tunnel data, since UDP is a "connectionless" protocol.
    929 
    930               On  Windows,  this option will delay the TAP-Win32 media state transitioning to "connected" until
    931               connection establishment, i.e. the receipt of the first authenticated packet from the peer.
     1128              Delay  TUN/TAP  open  and  possible  --up script execution until
     1129              after TCP/UDP connection establishment with peer.
     1130
     1131              In --proto udp mode, this option normally requires  the  use  of
     1132              --ping  to  allow  connection  initiation  to  be  sensed in the
     1133              absence of tunnel data, since UDP is a  "connectionless"  proto‐
     1134              col.
     1135
     1136              On  Windows,  this  option  will delay the TAP-Win32 media state
     1137              transitioning to  "connected"  until  connection  establishment,
     1138              i.e.  the  receipt  of  the  first authenticated packet from the
     1139              peer.
    9321140
    9331141       --down cmd
    934               Run command cmd after TUN/TAP device close (post --user UID change and/or --chroot ).   cmd  con‐
    935               sists of a path to script (or executable program), optionally followed by arguments. The path and
    936               arguments may be single- or double-quoted and/or escaped using a backslash, and should  be  sepa‐
    937               rated by one or more spaces.
    938 
    939               Called with the same parameters and environmental variables as the --up option above.
    940 
    941               Note  that  if you reduce privileges by using --user and/or --group, your --down script will also
    942               run at reduced privilege.
     1142              Run command cmd after TUN/TAP  device  close  (post  --user  UID
     1143              change  and/or --chroot ).  cmd consists of a path to script (or
     1144              executable program), optionally followed by arguments. The  path
     1145              and  arguments  may  be  single- or double-quoted and/or escaped
     1146              using a backslash, and should be separated by one or  more  spa‐
     1147              ces.
     1148
     1149              Called  with  the same parameters and environmental variables as
     1150              the --up option above.
     1151
     1152              Note that if  you  reduce  privileges  by  using  --user  and/or
     1153              --group, your --down script will also run at reduced privilege.
    9431154
    9441155       --down-pre
     
    9461157
    9471158       --up-restart
    948               Enable the --up and --down scripts to be called for restarts as well as  initial  program  start.
    949               This option is described more fully above in the --up option documentation.
     1159              Enable  the --up and --down scripts to be called for restarts as
     1160              well as initial program start.  This option  is  described  more
     1161              fully above in the --up option documentation.
    9501162
    9511163       --setenv name value
    952               Set a custom environmental variable name=value to pass to script.
     1164              Set  a  custom  environmental  variable  name=value  to  pass to
     1165              script.
    9531166
    9541167       --setenv FORWARD_COMPATIBLE 1
    955               Relax  config  file  syntax  checking so that unknown directives will trigger a warning but not a
    956               fatal error, on the assumption that a given unknown directive might be valid  in  future  OpenVPN
     1168              Relax config file syntax checking  so  that  unknown  directives
     1169              will  trigger a warning but not a fatal error, on the assumption
     1170              that a given unknown directive might be valid in future  OpenVPN
    9571171              versions.
    9581172
    959               This  option  should  be used with caution, as there are good security reasons for having OpenVPN
    960               fail if it detects problems in a config file.  Having said that,  there  are  valid  reasons  for
    961               wanting new software features to gracefully degrade when encountered by older software versions.
     1173              This option should be used with caution, as there are good secu‐
     1174              rity reasons for having OpenVPN fail if it detects problems in a
     1175              config  file.   Having  said  that,  there are valid reasons for
     1176              wanting new software features to gracefully degrade when encoun‐
     1177              tered by older software versions.
    9621178
    9631179       --setenv-safe name value
    964               Set a custom environmental variable OPENVPN_name=value to pass to script.
    965 
    966               This  directive  is  designed to be pushed by the server to clients, and the prepending of "OPEN‐
    967               VPN_" to the environmental variable is a safety precaution to prevent a LD_PRELOAD  style  attack
    968               from a malicious or compromised server.
    969 
    970        --script-security level [method]
    971               This directive offers policy-level control over OpenVPN's usage of external programs and scripts.
    972               Lower level values are more restrictive, higher values are more permissive.  Settings for level:
     1180              Set  a  custom environmental variable OPENVPN_name=value to pass
     1181              to script.
     1182
     1183              This directive is  designed  to  be  pushed  by  the  server  to
     1184              clients,  and  the prepending of "OPENVPN_" to the environmental
     1185              variable is a safety precaution to prevent  a  LD_PRELOAD  style
     1186              attack from a malicious or compromised server.
     1187
     1188       --script-security level
     1189              This  directive offers policy-level control over OpenVPN's usage
     1190              of external programs and scripts.  Lower level values  are  more
     1191              restrictive,  higher  values  are more permissive.  Settings for
     1192              level:
    9731193
    9741194              0 -- Strictly no calling of external programs.
    975               1 -- (Default) Only call built-in executables such as ifconfig, ip, route, or netsh.
    976               2 -- Allow calling of built-in executables and user-defined scripts.
    977               3 -- Allow passwords to be passed to scripts via environmental variables (potentially unsafe).
    978 
    979               The method parameter indicates how OpenVPN should call external commands and  scripts.   Settings
    980               for method:
    981 
    982               execve -- (default) Use execve() function on Unix family OSes and CreateProcess() on Windows.
    983               system -- Use system() function (deprecated and less safe since the external program command line
    984               is subject to shell expansion).
    985 
    986               The --script-security option was introduced in OpenVPN 2.1_rc9.  For configuration file  compati‐
    987               bility with previous OpenVPN versions, use: --script-security 3 system
     1195              1 -- (Default) Only call built-in executables such as  ifconfig,
     1196              ip, route, or netsh.
     1197              2  --  Allow  calling  of  built-in executables and user-defined
     1198              scripts.
     1199              3 -- Allow passwords to be passed to scripts  via  environmental
     1200              variables (potentially unsafe).
     1201
     1202              OpenVPN  releases before v2.3 also supported a method flag which
     1203              indicated how OpenVPN should call external commands and scripts.
     1204              This could be either execve or system.  As of OpenVPN v2.3, this
     1205              flag is no longer  accepted.   In  most  *nix  environments  the
     1206              execve() approach has been used without any issues.
     1207
     1208              To run scripts in Windows in earlier OpenVPN versions you needed
     1209              to either add a full path to the script  interpreter  which  can
     1210              parse  the  script  or use the system flag to run these scripts.
     1211              As of OpenVPN v2.3 it is now a strict requirement to  have  full
     1212              path  to  the  script  interpreter  when running non-executables
     1213              files.  This is not needed for executable files, such  as  .exe,
     1214              .com,  .bat  or  .cmd  files.  For example, if you have a Visual
     1215              Basic script, you must use this syntax now:
     1216
     1217                  --up 'C:\\Windows\\System32\\wscript.exe C:\\Program\ Files\\OpenVPN\\config\\my-up-script.vbs'
     1218
     1219              Please note the single quote marks and the escaping of the back‐
     1220              slashes (\) and the space character.
     1221
     1222              The reason the support for the system flag was removed is due to
     1223              the security implications with shell expansions  when  executing
     1224              scripts via the system() call.
    9881225
    9891226       --disable-occ
    990               Don't  output a warning message if option inconsistencies are detected between peers.  An example
    991               of an option inconsistency would be where one peer uses --dev tun while the other peer uses --dev
    992               tap.
    993 
    994               Use  of  this  option  is  discouraged,  but is provided as a temporary fix in situations where a
    995               recent version of OpenVPN must connect to an old version.
     1227              Don't  output  a  warning  message if option inconsistencies are
     1228              detected between peers.  An example of an  option  inconsistency
     1229              would be where one peer uses --dev tun while the other peer uses
     1230              --dev tap.
     1231
     1232              Use of this option is discouraged, but is provided as  a  tempo‐
     1233              rary  fix  in  situations where a recent version of OpenVPN must
     1234              connect to an old version.
    9961235
    9971236       --user user
    998               Change the user ID of the OpenVPN process to user after initialization,  dropping  privileges  in
    999               the  process.   This  option is useful to protect the system in the event that some hostile party
    1000               was able to gain control of an OpenVPN session.  Though OpenVPN's  security  features  make  this
    1001               unlikely, it is provided as a second line of defense.
    1002 
    1003               By  setting user to nobody or somebody similarly unprivileged, the hostile party would be limited
    1004               in what damage they could cause.  Of course once you take away privileges, you cannot return them
    1005               to an OpenVPN session.  This means, for example, that if you want to reset an OpenVPN daemon with
    1006               a SIGUSR1 signal (for example in response to a DHCP reset), you should make use of one or more of
    1007               the --persist options to ensure that OpenVPN doesn't need to execute any privileged operations in
    1008               order to restart (such as re-reading key files or running ifconfig on the TUN device).
     1237              Change the user ID of the OpenVPN process to user after initial‐
     1238              ization,  dropping  privileges  in  the process.  This option is
     1239              useful to protect the system in  the  event  that  some  hostile
     1240              party  was  able  to gain control of an OpenVPN session.  Though
     1241              OpenVPN's security features make this unlikely, it  is  provided
     1242              as a second line of defense.
     1243
     1244              By  setting  user  to nobody or somebody similarly unprivileged,
     1245              the hostile party would be limited in  what  damage  they  could
     1246              cause.   Of  course  once  you  take away privileges, you cannot
     1247              return them to an OpenVPN session.   This  means,  for  example,
     1248              that  if you want to reset an OpenVPN daemon with a SIGUSR1 sig‐
     1249              nal (for example in response to a DHCP reset), you  should  make
     1250              use of one or more of the --persist options to ensure that Open‐
     1251              VPN doesn't need to execute any privileged operations  in  order
     1252              to  restart (such as re-reading key files or running ifconfig on
     1253              the TUN device).
    10091254
    10101255       --group group
    1011               Similar to the --user option, this option changes the group ID of the OpenVPN  process  to  group
    1012               after initialization.
     1256              Similar to the --user option, this option changes the  group  ID
     1257              of the OpenVPN process to group after initialization.
    10131258
    10141259       --cd dir
    1015               Change  directory  to  dir  prior  to  reading  any files such as configuration files, key files,
    1016               scripts, etc.  dir should be an absolute path, with a leading "/", and without any references  to
     1260              Change  directory to dir prior to reading any files such as con‐
     1261              figuration files, key files, scripts, etc.   dir  should  be  an
     1262              absolute path, with a leading "/", and without any references to
    10171263              the current directory such as "." or "..".
    10181264
    1019               This  option is useful when you are running OpenVPN in --daemon mode, and you want to consolidate
    1020               all of your OpenVPN control files in one location.
     1265              This option is useful when you are running OpenVPN  in  --daemon
     1266              mode,  and  you  want to consolidate all of your OpenVPN control
     1267              files in one location.
    10211268
    10221269       --chroot dir
    1023               Chroot to dir after initialization.  --chroot essentially redefines dir as being  the  top  level
    1024               directory  tree  (/).   OpenVPN  will  therefore be unable to access any files outside this tree.
     1270              Chroot to dir after initialization.  --chroot essentially  rede‐
     1271              fines  dir  as  being the top level directory tree (/).  OpenVPN
     1272              will therefore be unable to access any files outside this  tree.
    10251273              This can be desirable from a security standpoint.
    10261274
    1027               Since the chroot operation is delayed until after initialization, most OpenVPN options that  ref‐
    1028               erence files will operate in a pre-chroot context.
    1029 
    1030               In  many  cases,  the  dir  parameter  can point to an empty directory, however complications can
    1031               result when scripts or restarts are executed after the chroot operation.
     1275              Since  the  chroot  operation is delayed until after initializa‐
     1276              tion, most OpenVPN options that reference files will operate  in
     1277              a pre-chroot context.
     1278
     1279              In  many  cases,  the dir parameter can point to an empty direc‐
     1280              tory, however complications can result when scripts or  restarts
     1281              are executed after the chroot operation.
    10321282
    10331283       --setcon context
    1034               Apply SELinux context after initialization. This essentially provides  the  ability  to  restrict
    1035               OpenVPN's rights to only network I/O operations, thanks to SELinux. This goes further than --user
    1036               and --chroot in that those two, while being great security features, unfortunately do not protect
    1037               against  privilege escalation by exploitation of a vulnerable system call. You can of course com‐
    1038               bine all three, but please note that since setcon requires access to /proc you will have to  pro‐
    1039               vide it inside the chroot directory (e.g. with mount --bind).
    1040 
    1041               Since  the  setcon  operation is delayed until after initialization, OpenVPN can be restricted to
    1042               just network-related system calls, whereas by applying the context before startup  (such  as  the
    1043               OpenVPN  one  provided  in  the  SELinux  Reference  Policies) you will have to allow many things
    1044               required only during initialization.
    1045 
    1046               Like with chroot, complications can result when scripts or restarts are executed after the setcon
    1047               operation,  which  is  why  you  should really consider using the --persist-key and --persist-tun
    1048               options.
     1284              Apply  SELinux  context  after  initialization. This essentially
     1285              provides the ability to restrict OpenVPN's rights to  only  net‐
     1286              work  I/O  operations, thanks to SELinux. This goes further than
     1287              --user and --chroot in that those two, while being  great  secu‐
     1288              rity  features,  unfortunately  do not protect against privilege
     1289              escalation by exploitation of a vulnerable system call. You  can
     1290              of  course  combine all three, but please note that since setcon
     1291              requires access to /proc you will have to provide it inside  the
     1292              chroot directory (e.g. with mount --bind).
     1293
     1294              Since  the  setcon  operation is delayed until after initializa‐
     1295              tion, OpenVPN can be restricted to just  network-related  system
     1296              calls,  whereas  by applying the context before startup (such as
     1297              the OpenVPN one provided in the SELinux Reference Policies)  you
     1298              will  have to allow many things required only during initializa‐
     1299              tion.
     1300
     1301              Like with chroot,  complications  can  result  when  scripts  or
     1302              restarts  are  executed after the setcon operation, which is why
     1303              you should really consider using the  --persist-key  and  --per‐
     1304              sist-tun options.
    10491305
    10501306       --daemon [progname]
    1051               Become a daemon after all initialization functions are completed.  This  option  will  cause  all
    1052               message  and  error  output to be sent to the syslog file (such as /var/log/messages), except for
    1053               the output of scripts and ifconfig commands, which will go to /dev/null  unless  otherwise  redi‐
    1054               rected.   The  syslog  redirection occurs immediately at the point that --daemon is parsed on the
    1055               command line even though the daemonization point occurs later.  If one of the  --log  options  is
    1056               present, it will supercede syslog redirection.
    1057 
    1058               The  optional progname parameter will cause OpenVPN to report its program name to the system log‐
    1059               ger as progname.  This can be useful in linking OpenVPN messages in the syslog file with specific
     1307              Become  a  daemon  after  all  initialization functions are com‐
     1308              pleted.  This option will cause all message and error output  to
     1309              be  sent  to the syslog file (such as /var/log/messages), except
     1310              for the output of scripts and ifconfig commands, which  will  go
     1311              to  /dev/null unless otherwise redirected.  The syslog redirect‐
     1312              ion occurs immediately at the point that --daemon is  parsed  on
     1313              the  command  line  even  though  the daemonization point occurs
     1314              later.  If  one  of  the  --log  options  is  present,  it  will
     1315              supercede syslog redirection.
     1316
     1317              The optional progname parameter will cause OpenVPN to report its
     1318              program name to the system logger as progname.  This can be use‐
     1319              ful in linking OpenVPN messages in the syslog file with specific
    10601320              tunnels.  When unspecified, progname defaults to "openvpn".
    10611321
    1062               When OpenVPN is run with the --daemon option, it will try to delay daemonization until the major‐
    1063               ity of initialization functions which are capable of generating fatal errors are complete.   This
    1064               means  that initialization scripts can test the return status of the openvpn command for a fairly
    1065               reliable indication of whether the command has correctly initialized and entered the packet  for‐
    1066               warding event loop.
    1067 
    1068               In OpenVPN, the vast majority of errors which occur after initialization are non-fatal.
     1322              When OpenVPN is run with the --daemon option,  it  will  try  to
     1323              delay  daemonization  until the majority of initialization func‐
     1324              tions which are capable of generating fatal errors are complete.
     1325              This  means that initialization scripts can test the return sta‐
     1326              tus of the openvpn command for a fairly reliable  indication  of
     1327              whether  the  command  has correctly initialized and entered the
     1328              packet forwarding event loop.
     1329
     1330              In OpenVPN, the vast majority of errors which occur  after  ini‐
     1331              tialization are non-fatal.
    10691332
    10701333       --syslog [progname]
    1071               Direct log output to system logger, but do not become a daemon.  See --daemon directive above for
    1072               description of progname parameter.
     1334              Direct  log output to system logger, but do not become a daemon.
     1335              See --daemon directive above for description of progname parame‐
     1336              ter.
    10731337
    10741338       --errors-to-stderr
    1075               Output errors to stderr instead of stdout unless log output is redirected by  one  of  the  --log
    1076               options.
     1339              Output  errors  to stderr instead of stdout unless log output is
     1340              redirected by one of the --log options.
    10771341
    10781342       --passtos
    1079               Set the TOS field of the tunnel packet to what the payload's TOS is.
     1343              Set the TOS field of the tunnel packet to what the payload's TOS
     1344              is.
    10801345
    10811346       --inetd [wait|nowait] [progname]
    1082               Use this option when OpenVPN is being run from the inetd or xinetd(8) server.
    1083 
    1084               The  wait/nowait option must match what is specified in the inetd/xinetd config file.  The nowait
    1085               mode can only be used with --proto tcp-server.  The default is wait.  The nowait mode can be used
    1086               to  instantiate  the OpenVPN daemon as a classic TCP server, where client connection requests are
    1087               serviced on a single port number.  For additional information on this kind of configuration,  see
    1088               the OpenVPN FAQ: http://openvpn.net/faq.html#oneport
    1089 
    1090               This  option  precludes  the use of --daemon, --local, or --remote.  Note that this option causes
    1091               message and error output to be handled in the same way as  the  --daemon  option.   The  optional
    1092               progname parameter is also handled exactly as in --daemon.
    1093 
    1094               Also  note that in wait mode, each OpenVPN tunnel requires a separate TCP/UDP port and a separate
    1095               inetd or xinetd entry.  See the OpenVPN 1.x HOWTO for an example on using  OpenVPN  with  xinetd:
    1096               http://openvpn.net/1xhowto.html
     1347              Use  this  option  when  OpenVPN  is being run from the inetd or
     1348              xinetd(8) server.
     1349
     1350              The wait/nowait option must  match  what  is  specified  in  the
     1351              inetd/xinetd config file.  The nowait mode can only be used with
     1352              --proto tcp-server.  The default is wait.  The nowait  mode  can
     1353              be  used  to  instantiate  the  OpenVPN  daemon as a classic TCP
     1354              server, where client connection requests are serviced on a  sin‐
     1355              gle  port  number.   For  additional information on this kind of
     1356              configuration,    see    the    OpenVPN    FAQ:     http://open‐
     1357              vpn.net/faq.html#oneport
     1358
     1359              This option precludes the use of --daemon, --local, or --remote.
     1360              Note that this option causes message and error output to be han‐
     1361              dled in the same way as the --daemon option.  The optional prog‐
     1362              name parameter is also handled exactly as in --daemon.
     1363
     1364              Also note that in wait mode, each OpenVPN tunnel requires a sep‐
     1365              arate  TCP/UDP  port  and a separate inetd or xinetd entry.  See
     1366              the OpenVPN 1.x HOWTO for  an  example  on  using  OpenVPN  with
     1367              xinetd: http://openvpn.net/1xhowto.html
    10971368
    10981369       --log file
    1099               Output  logging  messages to file, including output to stdout/stderr which is generated by called
    1100               scripts.  If file already exists it will be truncated.  This option takes effect immediately when
    1101               it  is parsed in the command line and will supercede syslog output if --daemon or --inetd is also
    1102               specified.  This option is persistent over the entire course of an OpenVPN instantiation and will
    1103               not be reset by SIGHUP, SIGUSR1, or --ping-restart.
    1104 
    1105               Note that on Windows, when OpenVPN is started as a service, logging occurs by default without the
    1106               need to specify this option.
     1370              Output  logging  messages  to  file,  including  output  to std‐
     1371              out/stderr which  is  generated  by  called  scripts.   If  file
     1372              already  exists  it will be truncated.  This option takes effect
     1373              immediately when it is parsed  in  the  command  line  and  will
     1374              supercede  syslog  output  if --daemon or --inetd is also speci‐
     1375              fied.  This option is persistent over the entire  course  of  an
     1376              OpenVPN  instantiation and will not be reset by SIGHUP, SIGUSR1,
     1377              or --ping-restart.
     1378
     1379              Note that on Windows, when OpenVPN is started as a service, log‐
     1380              ging occurs by default without the need to specify this option.
    11071381
    11081382       --log-append file
    1109               Append logging messages to file.  If file does not  exist,  it  will  be  created.   This  option
    1110               behaves exactly like --log except that it appends to rather than truncating the log file.
     1383              Append  logging  messages  to  file.  If file does not exist, it
     1384              will be created.  This option behaves exactly like --log  except
     1385              that it appends to rather than truncating the log file.
    11111386
    11121387       --suppress-timestamps
    1113               Avoid writing timestamps to log messages, even when they otherwise would be prepended. In partic‐
    1114               ular, this applies to log messages sent to stdout.
     1388              Avoid  writing timestamps to log messages, even when they other‐
     1389              wise would be prepended. In particular, this applies to log mes‐
     1390              sages sent to stdout.
    11151391
    11161392       --writepid file
     
    11181394
    11191395       --nice n
    1120               Change process priority after initialization ( n greater than 0 is lower priority,  n  less  than
    1121               zero is higher priority).
     1396              Change  process priority after initialization ( n greater than 0
     1397              is lower priority, n less than zero is higher priority).
    11221398
    11231399       --fast-io
    1124               (Experimental)  Optimize  TUN/TAP/UDP I/O writes by avoiding a call to poll/epoll/select prior to
    1125               the write operation.  The purpose of such a call would normally be to block until the  device  or
    1126               socket  is ready to accept the write.  Such blocking is unnecessary on some platforms which don't
    1127               support write blocking on UDP sockets or TUN/TAP devices.  In such cases, one  can  optimize  the
    1128               event loop by avoiding the poll/epoll/select call, improving CPU efficiency by 5% to 10%.
    1129 
    1130               This  option  can  only  be  used on non-Windows systems, when --proto udp is specified, and when
    1131               --shaper is NOT specified.
     1400              (Experimental) Optimize TUN/TAP/UDP I/O  writes  by  avoiding  a
     1401              call  to  poll/epoll/select  prior  to the write operation.  The
     1402              purpose of such a call would normally  be  to  block  until  the
     1403              device or socket is ready to accept the write.  Such blocking is
     1404              unnecessary on some platforms which don't support write blocking
     1405              on UDP sockets or TUN/TAP devices.  In such cases, one can opti‐
     1406              mize the event loop  by  avoiding  the  poll/epoll/select  call,
     1407              improving CPU efficiency by 5% to 10%.
     1408
     1409              This  option  can  only  be  used  on  non-Windows systems, when
     1410              --proto udp is specified, and when --shaper is NOT specified.
    11321411
    11331412       --multihome
    1134               Configure a multi-homed UDP server.  This option can be used when OpenVPN has been configured  to
    1135               listen  on  all  interfaces,  and  will attempt to bind client sessions to the interface on which
    1136               packets are being received, so that outgoing packets will be sent  out  of  the  same  interface.
    1137               Note  that  this  option  is  only  relevant for UDP servers and currently is only implemented on
    1138               Linux.
    1139 
    1140               Note: clients connecting to a --multihome server should always use the --nobind option.
     1413              Configure a multi-homed UDP server.  This  option  can  be  used
     1414              when  OpenVPN  has  been configured to listen on all interfaces,
     1415              and will attempt to bind client sessions  to  the  interface  on
     1416              which  packets are being received, so that outgoing packets will
     1417              be sent out of the same interface.  Note  that  this  option  is
     1418              only  relevant for UDP servers and currently is only implemented
     1419              on Linux.
     1420
     1421              Note: clients connecting to a --multihome server  should  always
     1422              use the --nobind option.
    11411423
    11421424       --echo [parms...]
    11431425              Echo parms to log output.
    11441426
    1145               Designed to be used to send messages to a controlling application which is receiving the  OpenVPN
    1146               log output.
     1427              Designed  to  be used to send messages to a controlling applica‐
     1428              tion which is receiving the OpenVPN log output.
    11471429
    11481430       --remap-usr1 signal
    1149               Control  whether  internally  or  externally  generated  SIGUSR1  signals  are remapped to SIGHUP
    1150               (restart without persisting state) or SIGTERM (exit).
    1151 
    1152               signal can be set to "SIGHUP" or "SIGTERM".  By default, no remapping occurs.
     1431              Control whether internally or externally generated SIGUSR1  sig‐
     1432              nals  are  remapped to SIGHUP (restart without persisting state)
     1433              or SIGTERM (exit).
     1434
     1435              signal can be set to "SIGHUP"  or  "SIGTERM".   By  default,  no
     1436              remapping occurs.
    11531437
    11541438       --verb n
    1155               Set output verbosity to n (default=1).  Each level shows  all  info  from  the  previous  levels.
    1156               Level  3  is  recommended if you want a good summary of what's happening without being swamped by
     1439              Set  output  verbosity  to  n (default=1).  Each level shows all
     1440              info from the previous levels.  Level 3 is  recommended  if  you
     1441              want a good summary of what's happening without being swamped by
    11571442              output.
    11581443
    11591444              0 -- No output except fatal errors.
    11601445              1 to 4 -- Normal usage range.
    1161               5 -- Output R and W characters to the console for each packet read and write, uppercase  is  used
    1162               for TCP/UDP packets and lowercase is used for TUN/TAP packets.
    1163               6 to 11 -- Debug info range (see errlevel.h for additional information on debug levels).
     1446              5 -- Output R and W characters to the console  for  each  packet
     1447              read and write, uppercase is used for TCP/UDP packets and lower‐
     1448              case is used for TUN/TAP packets.
     1449              6 to 11 -- Debug  info  range  (see  errlevel.h  for  additional
     1450              information on debug levels).
    11641451
    11651452       --status file [n]
    11661453              Write operational status to file every n seconds.
    11671454
    1168               Status can also be written to the syslog by sending a SIGUSR2 signal.
     1455              Status  can  also  be written to the syslog by sending a SIGUSR2
     1456              signal.
    11691457
    11701458       --status-version [n]
    1171               Choose the status file format version number.  Currently n can be 1, 2, or 3 and defaults to 1.
     1459              Choose the status file format version number.  Currently  n  can
     1460              be 1, 2, or 3 and defaults to 1.
    11721461
    11731462       --mute n
    1174               Log at most n consecutive messages in the same category.  This is useful to limit repetitive log‐
    1175               ging of similar message types.
     1463              Log  at  most n consecutive messages in the same category.  This
     1464              is useful to limit repetitive logging of similar message types.
    11761465
    11771466       --comp-lzo [mode]
    1178               Use fast LZO compression -- may add up to 1 byte per packet for incompressible data.  mode may be
    1179               "yes", "no", or "adaptive" (default).
    1180 
    1181               In  a  server mode setup, it is possible to selectively turn compression on or off for individual
    1182               clients.
    1183 
    1184               First, make sure the client-side config file enables selective compression by having at least one
    1185               --comp-lzo  directive,  such  as  --comp-lzo  no.  This will turn off compression by default, but
    1186               allow a future directive push from the server to dynamically change the on/off/adaptive setting.
    1187 
    1188               Next in a --client-config-dir file, specify the compression setting for the client, for example:
     1467              Use fast LZO compression -- may add up to 1 byte per packet  for
     1468              incompressible  data.   mode  may  be "yes", "no", or "adaptive"
     1469              (default).
     1470
     1471              In a server mode setup, it is possible to selectively turn  com‐
     1472              pression on or off for individual clients.
     1473
     1474              First,  make  sure the client-side config file enables selective
     1475              compression by having at least one --comp-lzo directive, such as
     1476              --comp-lzo  no.   This will turn off compression by default, but
     1477              allow a future directive push from  the  server  to  dynamically
     1478              change the on/off/adaptive setting.
     1479
     1480              Next in a --client-config-dir file, specify the compression set‐
     1481              ting for the client, for example:
    11891482
    11901483                  comp-lzo yes
    11911484                  push "comp-lzo yes"
    11921485
    1193               The first line sets the comp-lzo setting for the server side of the link,  the  second  sets  the
    1194               client side.
     1486              The first line sets the comp-lzo setting for the server side  of
     1487              the link, the second sets the client side.
    11951488
    11961489       --comp-noadapt
    1197               When used in conjunction with --comp-lzo, this option will disable OpenVPN's adaptive compression
    1198               algorithm.  Normally, adaptive compression is enabled with --comp-lzo.
    1199 
    1200               Adaptive compression tries to optimize the case where you have compression enabled, but  you  are
    1201               sending  predominantly uncompressible (or pre-compressed) packets over the tunnel, such as an FTP
    1202               or rsync transfer of a large, compressed file.  With adaptive compression, OpenVPN will  periodi‐
    1203               cally  sample the compression process to measure its efficiency.  If the data being sent over the
    1204               tunnel is already compressed, the compression efficiency will be very low, triggering openvpn  to
    1205               disable compression for a period of time until the next re-sample test.
     1490              When  used in conjunction with --comp-lzo, this option will dis‐
     1491              able OpenVPN's adaptive compression algorithm.  Normally,  adap‐
     1492              tive compression is enabled with --comp-lzo.
     1493
     1494              Adaptive  compression  tries to optimize the case where you have
     1495              compression enabled, but you are  sending  predominantly  uncom‐
     1496              pressible  (or  pre-compressed) packets over the tunnel, such as
     1497              an FTP or rsync transfer of  a  large,  compressed  file.   With
     1498              adaptive  compression, OpenVPN will periodically sample the com‐
     1499              pression process to measure its efficiency.  If the  data  being
     1500              sent  over  the  tunnel  is  already compressed, the compression
     1501              efficiency will be very low, triggering openvpn to disable  com‐
     1502              pression for a period of time until the next re-sample test.
    12061503
    12071504       --management IP port [pw-file]
    1208               Enable  a TCP server on IP:port to handle daemon management functions.  pw-file, if specified, is
    1209               a password file (password on first line) or "stdin" to prompt from standard input.  The  password
    1210               provided  will set the password which TCP clients will need to provide in order to access manage‐
    1211               ment functions.
    1212 
    1213               The management interface can also listen on a unix domain socket, for those platforms  that  sup‐
    1214               port  it.   To  use a unix domain socket, specify the unix socket pathname in place of IP and set
    1215               port to 'unix'.  While the default behavior is to create a unix domain socket that  may  be  con‐
    1216               nected  to  by any process, the --management-client-user and --management-client-group directives
    1217               can be used to restrict access.
    1218 
    1219               The management interface provides a special mode where the TCP management link can  operate  over
    1220               the  tunnel  itself.  To enable this mode, set IP = "tunnel".  Tunnel mode will cause the manage‐
    1221               ment interface to listen for a TCP connection on the local VPN address of the TUN/TAP interface.
    1222 
    1223               While the management port is designed for programmatic control of OpenVPN by other  applications,
    1224               it  is possible to telnet to the port, using a telnet client in "raw" mode.  Once connected, type
    1225               "help" for a list of commands.
    1226 
    1227               For detailed documentation on the management interface, see the management-notes.txt file in  the
    1228               management folder of the OpenVPN source distribution.
    1229 
    1230               It  is  strongly recommended that IP be set to 127.0.0.1 (localhost) to restrict accessibility of
    1231               the management server to local clients.
     1505              Enable a TCP server on IP:port to handle daemon management func‐
     1506              tions.  pw-file, if specified, is a password file  (password  on
     1507              first line) or "stdin" to prompt from standard input.  The pass‐
     1508              word provided will set the password which TCP clients will  need
     1509              to provide in order to access management functions.
     1510
     1511              The  management  interface  can  also  listen  on  a unix domain
     1512              socket, for those platforms that support  it.   To  use  a  unix
     1513              domain  socket,  specify the unix socket pathname in place of IP
     1514              and set port to 'unix'.  While the default behavior is to create
     1515              a  unix  domain  socket that may be connected to by any process,
     1516              the   --management-client-user   and   --management-client-group
     1517              directives can be used to restrict access.
     1518
     1519              The  management  interface provides a special mode where the TCP
     1520              management link can operate over the tunnel itself.   To  enable
     1521              this  mode,  set IP = "tunnel".  Tunnel mode will cause the man‐
     1522              agement interface to listen for a TCP connection  on  the  local
     1523              VPN address of the TUN/TAP interface.
     1524
     1525              While  the  management port is designed for programmatic control
     1526              of OpenVPN by other applications, it is possible  to  telnet  to
     1527              the  port, using a telnet client in "raw" mode.  Once connected,
     1528              type "help" for a list of commands.
     1529
     1530              For detailed documentation on the management interface, see  the
     1531              management-notes.txt  file in the management folder of the Open‐
     1532              VPN source distribution.
     1533
     1534              It is strongly recommended that IP be set to  127.0.0.1  (local‐
     1535              host)  to  restrict  accessibility  of  the management server to
     1536              local clients.
    12321537
    12331538       --management-client
    1234               Management interface will connect as a TCP/unix domain client to IP:port specified  by  --manage‐
    1235               ment rather than listen as a TCP server or on a unix domain socket.
    1236 
    1237               If  the client connection fails to connect or is disconnected, a SIGTERM signal will be generated
    1238               causing OpenVPN to quit.
     1539              Management interface will connect as a TCP/unix domain client to
     1540              IP:port  specified  by  --management rather than listen as a TCP
     1541              server or on a unix domain socket.
     1542
     1543              If the client connection fails to connect or is disconnected,  a
     1544              SIGTERM signal will be generated causing OpenVPN to quit.
    12391545
    12401546       --management-query-passwords
    1241               Query management channel for private key password and --auth-user-pass  username/password.   Only
    1242               query  the  management  channel for inputs which ordinarily would have been queried from the con‐
    1243               sole.
     1547              Query  management  channel  for private key password and --auth-
     1548              user-pass username/password.  Only query the management  channel
     1549              for  inputs  which  ordinarily  would have been queried from the
     1550              console.
    12441551
    12451552       --management-query-proxy
    1246               Query management channel for proxy server information for a specific --remote (client-only).
     1553              Query management channel for proxy server information for a spe‐
     1554              cific --remote (client-only).
    12471555
    12481556       --management-query-remote
    1249               Allow management interface to override --remote directives (client-only).
     1557              Allow  management  interface  to  override  --remote  directives
     1558              (client-only).   --management-external-key  Allows   usage   for
     1559              external private key file instead of --key option (client-only).
    12501560
    12511561       --management-forget-disconnect
    1252               Make OpenVPN forget passwords when management session disconnects.
    1253 
    1254               This directive does not affect the --http-proxy username/password.  It is always cached.
     1562              Make  OpenVPN  forget  passwords when management session discon‐
     1563              nects.
     1564
     1565              This directive does not affect the  --http-proxy  username/pass‐
     1566              word.  It is always cached.
    12551567
    12561568       --management-hold
    1257               Start OpenVPN in a hibernating state, until a  client  of  the  management  interface  explicitly
    1258               starts it with the hold release command.
     1569              Start OpenVPN in a hibernating state, until a client of the man‐
     1570              agement interface explicitly starts it  with  the  hold  release
     1571              command.
    12591572
    12601573       --management-signal
    1261               Send  SIGUSR1  signal to OpenVPN if management session disconnects.  This is useful when you wish
    1262               to disconnect an OpenVPN session on user logoff.  For  --management-client  this  option  is  not
    1263               needed since a disconnect will always generate a SIGTERM.
     1574              Send  SIGUSR1  signal  to  OpenVPN if management session discon‐
     1575              nects.  This is useful when you wish to  disconnect  an  OpenVPN
     1576              session  on  user logoff. For --management-client this option is
     1577              not needed since a disconnect will always generate a SIGTERM.
    12641578
    12651579       --management-log-cache n
    1266               Cache the most recent n lines of log file history for usage by the management channel.
     1580              Cache the most recent n lines of log file history for  usage  by
     1581              the management channel.
    12671582
    12681583       --management-up-down
     
    12701585
    12711586       --management-client-auth
    1272               Gives  management  interface client the responsibility to authenticate clients after their client
    1273               certificate has been verified.  See management-notes.txt in  OpenVPN  distribution  for  detailed
     1587              Gives  management interface client the responsibility to authen‐
     1588              ticate clients after their client certificate has been verified.
     1589              See  management-notes.txt  in  OpenVPN distribution for detailed
    12741590              notes.
    12751591
    12761592       --management-client-pf
    1277               Management  interface  clients must specify a packet filter file for each connecting client.  See
    1278               management-notes.txt in OpenVPN distribution for detailed notes.
     1593              Management interface clients must specify a packet  filter  file
     1594              for each connecting client.  See management-notes.txt in OpenVPN
     1595              distribution for detailed notes.
    12791596
    12801597       --management-client-user u
    1281               When the management interface is listening on a unix domain socket, only allow  connections  from
    1282               user u.
     1598              When the management interface is  listening  on  a  unix  domain
     1599              socket, only allow connections from user u.
    12831600
    12841601       --management-client-group g
    1285               When  the  management interface is listening on a unix domain socket, only allow connections from
    1286               group g.
     1602              When  the  management  interface  is  listening on a unix domain
     1603              socket, only allow connections from group g.
    12871604
    12881605       --plugin module-pathname [init-string]
    1289               Load plug-in module from the file module-pathname, passing init-string as an argument to the mod‐
    1290               ule initialization function.  Multiple plugin modules may be loaded into one OpenVPN process.
    1291 
    1292               For more information and examples on how to build OpenVPN plug-in modules, see the README file in
    1293               the plugin folder of the OpenVPN source distribution.
    1294 
    1295               If you are using an RPM install of OpenVPN, see /usr/share/openvpn/plugin.  The documentation  is
    1296               in doc and the actual plugin modules are in lib.
    1297 
    1298               Multiple  plugin  modules  can  be cascaded, and modules can be used in tandem with scripts.  The
    1299               modules will be called by OpenVPN in the order that they are declared in  the  config  file.   If
    1300               both  a  plugin  and script are configured for the same callback, the script will be called last.
    1301               If the return code of the module/script controls an authentication function (such as  tls-verify,
    1302               auth-user-pass-verify,  or  client-connect), then every module and script must return success (0)
    1303               in order for the connection to be authenticated.
     1606              Load plug-in module from the file module-pathname, passing init-
     1607              string  as  an  argument  to the module initialization function.
     1608              Multiple plugin modules may be loaded into one OpenVPN process.
     1609
     1610              For more information and examples on how to build OpenVPN  plug-
     1611              in  modules,  see  the  README  file in the plugin folder of the
     1612              OpenVPN source distribution.
     1613
     1614              If you are using an RPM install of OpenVPN, see /usr/share/open‐
     1615              vpn/plugin.   The  documentation is in doc and the actual plugin
     1616              modules are in lib.
     1617
     1618              Multiple plugin modules can be cascaded, and modules can be used
     1619              in  tandem  with scripts.  The modules will be called by OpenVPN
     1620              in the order that they are declared in the config file.  If both
     1621              a  plugin  and  script are configured for the same callback, the
     1622              script will be called last.  If the  return  code  of  the  mod‐
     1623              ule/script controls an authentication function (such as tls-ver‐
     1624              ify, auth-user-pass-verify, or client-connect), then every  mod‐
     1625              ule  and script must return success (0) in order for the connec‐
     1626              tion to be authenticated.
    13041627
    13051628   Server Mode
    1306        Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is supported, and can be enabled with  the
    1307        --mode  server option.  In server mode, OpenVPN will listen on a single port for incoming client connec‐
    1308        tions.  All client connections will be routed through a single tun  or  tap  interface.   This  mode  is
    1309        designed  for  scalability and should be able to support hundreds or even thousands of clients on suffi‐
    1310        ciently fast hardware.  SSL/TLS authentication must be used in this mode.
     1629       Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode  is  sup‐
     1630       ported,  and  can  be enabled with the --mode server option.  In server
     1631       mode, OpenVPN will listen on a single port for incoming client  connec‐
     1632       tions.   All  client connections will be routed through a single tun or
     1633       tap interface.  This mode is designed for  scalability  and  should  be
     1634       able  to  support hundreds or even thousands of clients on sufficiently
     1635       fast hardware.  SSL/TLS authentication must be used in this mode.
    13111636
    13121637       --server network netmask
    1313               A helper directive designed to simplify the configuration of OpenVPN's server mode.  This  direc‐
    1314               tive will set up an OpenVPN server which will allocate addresses to clients out of the given net‐
    1315               work/netmask.  The server itself will take the ".1" address of the given network for use  as  the
    1316               server-side endpoint of the local TUN/TAP interface.
     1638              A helper directive designed to  simplify  the  configuration  of
     1639              OpenVPN's  server  mode.   This directive will set up an OpenVPN
     1640              server which will allocate addresses to clients out of the given
     1641              network/netmask.   The  server itself will take the ".1" address
     1642              of the given network for use as the server-side endpoint of  the
     1643              local TUN/TAP interface.
    13171644
    13181645              For example, --server 10.8.0.0 255.255.255.0 expands as follows:
     
    13381665                     push "route-gateway 10.8.0.1"
    13391666
    1340               Don't use --server if you are ethernet bridging.  Use --server-bridge instead.
     1667              Don't  use --server if you are ethernet bridging.  Use --server-
     1668              bridge instead.
    13411669
    13421670       --server-bridge gateway netmask pool-start-IP pool-end-IP
     
    13441672       --server-bridge ['nogw']
    13451673
    1346               A  helper  directive similar to --server which is designed to simplify the configuration of Open‐
    1347               VPN's server mode in ethernet bridging configurations.
    1348 
    1349               If --server-bridge is used without any parameters, it will enable a DHCP-proxy mode,  where  con‐
    1350               necting  OpenVPN  clients  will  receive an IP address for their TAP adapter from the DHCP server
    1351               running on the OpenVPN server-side LAN.  Note that only clients that support  the  binding  of  a
    1352               DHCP client with the TAP adapter (such as Windows) can support this mode.  The optional nogw flag
    1353               (advanced) indicates that gateway information should not be pushed to the client.
    1354 
    1355               To configure ethernet bridging, you must first use your OS's bridging capability  to  bridge  the
    1356               TAP interface with the ethernet NIC interface.  For example, on Linux this is done with the brctl
    1357               tool, and with Windows XP it is done in the Network Connections Panel by selecting  the  ethernet
    1358               and TAP adapters and right-clicking on "Bridge Connections".
    1359 
    1360               Next  you  you must manually set the IP/netmask on the bridge interface.  The gateway and netmask
    1361               parameters to --server-bridge can be set to either the IP/netmask of the bridge interface, or the
    1362               IP/netmask of the default gateway/router on the bridged subnet.
    1363 
    1364               Finally,  set  aside  a IP range in the bridged subnet, denoted by pool-start-IP and pool-end-IP,
    1365               for OpenVPN to allocate to connecting clients.
    1366 
    1367               For example, server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 10.8.0.254 expands as follows:
     1674              A helper directive similar to --server which is designed to sim‐
     1675              plify  the  configuration  of  OpenVPN's server mode in ethernet
     1676              bridging configurations.
     1677
     1678              If --server-bridge is  used  without  any  parameters,  it  will
     1679              enable  a DHCP-proxy mode, where connecting OpenVPN clients will
     1680              receive an IP address for their TAP adapter from the DHCP server
     1681              running  on the OpenVPN server-side LAN.  Note that only clients
     1682              that support the binding of a DHCP client with the  TAP  adapter
     1683              (such as Windows) can support this mode.  The optional nogw flag
     1684              (advanced) indicates that  gateway  information  should  not  be
     1685              pushed to the client.
     1686
     1687              To  configure  ethernet  bridging,  you must first use your OS's
     1688              bridging capability to bridge the TAP interface with the  ether‐
     1689              net  NIC interface.  For example, on Linux this is done with the
     1690              brctl tool, and with Windows XP it is done in the  Network  Con‐
     1691              nections  Panel  by  selecting the ethernet and TAP adapters and
     1692              right-clicking on "Bridge Connections".
     1693
     1694              Next you you must manually set  the  IP/netmask  on  the  bridge
     1695              interface.   The  gateway  and  netmask  parameters to --server-
     1696              bridge can be set to either the IP/netmask of the bridge  inter‐
     1697              face,  or  the  IP/netmask  of the default gateway/router on the
     1698              bridged subnet.
     1699
     1700              Finally, set aside a IP range in the bridged subnet, denoted  by
     1701              pool-start-IP  and  pool-end-IP, for OpenVPN to allocate to con‐
     1702              necting clients.
     1703
     1704              For example,  server-bridge  10.8.0.4  255.255.255.0  10.8.0.128
     1705              10.8.0.254 expands as follows:
    13681706
    13691707                  mode server
     
    13731711                  push "route-gateway 10.8.0.4"
    13741712
    1375               In another example, --server-bridge (without parameters) expands as follows:
     1713              In another example, --server-bridge (without parameters) expands
     1714              as follows:
    13761715
    13771716                  mode server
     
    13861725
    13871726       --push option
    1388               Push a config file option back to the client for remote execution.   Note  that  option  must  be
    1389               enclosed  in  double quotes ("").  The client must specify --pull in its config file.  The set of
    1390               options which can be pushed is limited by both feasibility and security.  Some  options  such  as
    1391               those  which  would  execute scripts are banned, since they would effectively allow a compromised
    1392               server to execute arbitrary code on the client.  Other options such as TLS or MTU parameters can‐
    1393               not  be  pushed  because the client needs to know them before the connection to the server can be
    1394               initiated.
    1395 
    1396               This is a partial list of options  which  can  currently  be  pushed:  --route,  --route-gateway,
    1397               --route-delay,  --redirect-gateway,  --ip-win32,  --dhcp-option, --inactive, --ping, --ping-exit,
    1398               --ping-restart,  --setenv,  --persist-key,  --persist-tun,  --echo,  --comp-lzo,  --socket-flags,
    1399               --sndbuf, --rcvbuf
     1727              Push a config file option back to the client for  remote  execu‐
     1728              tion.   Note that option must be enclosed in double quotes ("").
     1729              The client must specify --pull in its config file.  The  set  of
     1730              options  which  can be pushed is limited by both feasibility and
     1731              security.  Some  options  such  as  those  which  would  execute
     1732              scripts are banned, since they would effectively allow a compro‐
     1733              mised server to execute arbitrary code  on  the  client.   Other
     1734              options  such  as TLS or MTU parameters cannot be pushed because
     1735              the client needs to know  them  before  the  connection  to  the
     1736              server can be initiated.
     1737
     1738              This is a partial list of options which can currently be pushed:
     1739              --route,  --route-gateway,  --route-delay,   --redirect-gateway,
     1740              --ip-win32,   --dhcp-option,  --inactive,  --ping,  --ping-exit,
     1741              --ping-restart, --setenv, --persist-key, --persist-tun,  --echo,
     1742              --comp-lzo, --socket-flags, --sndbuf, --rcvbuf
    14001743
    14011744       --push-reset
    1402               Don't  inherit  the  global  push  list for a specific client instance.  Specify this option in a
    1403               client-specific context such as with a --client-config-dir configuration file.  This option  will
    1404               ignore --push options at the global config file level.
     1745              Don't  inherit  the  global  push  list  for  a  specific client
     1746              instance.  Specify this option in a client-specific context such
     1747              as  with  a --client-config-dir configuration file.  This option
     1748              will ignore --push options at the global config file level.
    14051749
    14061750       --push-peer-info
    1407               Push  additional  information about the client to server.  The additional information consists of
    1408               the following data:
     1751              Push additional information about the  client  to  server.   The
     1752              additional information consists of the following data:
    14091753
    14101754              IV_VER=<version> -- the client OpenVPN version
    14111755
    1412               IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win] -- the client OS platform
    1413 
    1414               IV_HWADDR=<mac address> -- the MAC address of clients default gateway
     1756              IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]   --  the
     1757              client OS platform
     1758
     1759              IV_HWADDR=<mac address> -- the MAC address  of  clients  default
     1760              gateway
    14151761
    14161762              IV_LZO_STUB=1 -- if client was built with LZO stub capability
    14171763
    1418               UV_<name>=<value> -- client environment variables whose names start with "UV_"
     1764              UV_<name>=<value>  --  client  environment variables whose names
     1765              start with "UV_"
    14191766
    14201767       --disable
    1421               Disable a particular client (based on the common name) from connecting.  Don't use this option to
    1422               disable  a  client  due  to  key or password compromise.  Use a CRL (certificate revocation list)
     1768              Disable a particular client (based on the common name) from con‐
     1769              necting.   Don't  use this option to disable a client due to key
     1770              or password compromise.  Use a CRL (certificate revocation list)
    14231771              instead (see the --crl-verify option).
    14241772
    1425               This option must be associated with a specific client instance, which means that it must be spec‐
    1426               ified  either in a client instance config file using --client-config-dir or dynamically generated
    1427               using a --client-connect script.
     1773              This  option must be associated with a specific client instance,
     1774              which means that  it  must  be  specified  either  in  a  client
     1775              instance  config  file  using --client-config-dir or dynamically
     1776              generated using a --client-connect script.
    14281777
    14291778       --ifconfig-pool start-IP end-IP [netmask]
    1430               Set aside a pool of subnets to be dynamically allocated to connecting clients, similar to a  DHCP
    1431               server.  For tun-style tunnels, each client will be given a /30 subnet (for interoperability with
    1432               Windows clients).  For tap-style  tunnels,  individual  addresses  will  be  allocated,  and  the
    1433               optional netmask parameter will also be pushed to clients.
     1779              Set aside a pool of subnets to be dynamically allocated to  con‐
     1780              necting  clients,  similar to a DHCP server.  For tun-style tun‐
     1781              nels, each client will be given a /30 subnet (for interoperabil‐
     1782              ity  with  Windows  clients).  For tap-style tunnels, individual
     1783              addresses will be allocated, and the optional netmask  parameter
     1784              will also be pushed to clients.
    14341785
    14351786
    14361787       --ifconfig-pool-persist file [seconds]
    1437               Persist/unpersist  ifconfig-pool  data to file, at seconds intervals (default=600), as well as on
    1438               program startup and shutdown.
    1439 
    1440               The goal of this option is to provide a long-term association between clients (denoted  by  their
    1441               common  name)  and the virtual IP address assigned to them from the ifconfig-pool.  Maintaining a
    1442               long-term association is good for clients because it allows them to effectively  use  the  --per‐
    1443               sist-tun option.
    1444 
    1445               file is a comma-delimited ASCII file, formatted as <Common-Name>,<IP-address>.
    1446 
    1447               If  seconds  =  0,  file will be treated as read-only.  This is useful if you would like to treat
    1448               file as a configuration file.
    1449 
    1450               Note that the entries in this file are treated by OpenVPN as  suggestions  only,  based  on  past
    1451               associations  between  a common name and IP address.  They do not guarantee that the given common
    1452               name will always receive the given IP address.  If you want guaranteed assignment,  use  --ifcon‐
    1453               fig-push
     1788              Persist/unpersist  ifconfig-pool data to file, at seconds inter‐
     1789              vals (default=600), as well as on program startup and shutdown.
     1790
     1791              The goal of this option is to provide  a  long-term  association
     1792              between  clients  (denoted by their common name) and the virtual
     1793              IP address assigned to them from the ifconfig-pool.  Maintaining
     1794              a  long-term  association  is good for clients because it allows
     1795              them to effectively use the --persist-tun option.
     1796
     1797              file is a comma-delimited  ASCII  file,  formatted  as  <Common-
     1798              Name>,<IP-address>.
     1799
     1800              If seconds = 0, file will be treated as read-only.  This is use‐
     1801              ful if you would like to treat file as a configuration file.
     1802
     1803              Note that the entries in this file are  treated  by  OpenVPN  as
     1804              suggestions  only,  based  on past associations between a common
     1805              name and IP address.  They do not guarantee that the given  com‐
     1806              mon  name will always receive the given IP address.  If you want
     1807              guaranteed assignment, use --ifconfig-push
    14541808
    14551809       --ifconfig-pool-linear
    1456               Modifies the --ifconfig-pool directive to allocate individual TUN interface addresses for clients
    1457               rather than /30 subnets.  NOTE:  This option is incompatible with Windows clients.
    1458 
    1459               This option is deprecated, and should be replaced  with  --topology  p2p  which  is  functionally
    1460               equivalent.
     1810              Modifies the --ifconfig-pool directive  to  allocate  individual
     1811              TUN  interface  addresses  for  clients rather than /30 subnets.
     1812              NOTE:  This option is incompatible with Windows clients.
     1813
     1814              This option is deprecated, and should be replaced with  --topol‐
     1815              ogy p2p which is functionally equivalent.
    14611816
    14621817       --ifconfig-push local remote-netmask [alias]
    1463               Push virtual IP endpoints for client tunnel, overriding the --ifconfig-pool dynamic allocation.
    1464 
    1465               The  parameters  local and remote-netmask are set according to the --ifconfig directive which you
    1466               want to execute on the client machine to configure the remote end of the tunnel.  Note  that  the
    1467               parameters local and remote-netmask are from the perspective of the client, not the server.  They
    1468               may be DNS names rather than IP addresses, in which case they will be resolved on the  server  at
    1469               the time of client connection.
    1470 
    1471               The  optional  alias parameter may be used in cases where NAT causes the client view of its local
    1472               endpoint to differ from the server view.  In this case local/remote-netmask  will  refer  to  the
    1473               server view while alias/remote-netmask will refer to the client view.
    1474 
    1475               This option must be associated with a specific client instance, which means that it must be spec‐
    1476               ified either in a client instance config file using --client-config-dir or dynamically  generated
    1477               using a --client-connect script.
    1478 
    1479               Remember  also  to  include  a  --route  directive in the main OpenVPN config file which encloses
    1480               local, so that the kernel will know to route it to the server's TUN/TAP interface.
    1481 
    1482               OpenVPN's internal client IP address selection algorithm works as follows:
    1483 
    1484               1 -- Use --client-connect script generated file for static IP (first choice).
     1818              Push  virtual  IP  endpoints  for  client tunnel, overriding the
     1819              --ifconfig-pool dynamic allocation.
     1820
     1821              The parameters local and remote-netmask are set according to the
     1822              --ifconfig  directive  which  you  want to execute on the client
     1823              machine to configure the remote end of the  tunnel.   Note  that
     1824              the parameters local and remote-netmask are from the perspective
     1825              of the client, not the server.  They may  be  DNS  names  rather
     1826              than  IP  addresses,  in which case they will be resolved on the
     1827              server at the time of client connection.
     1828
     1829              The optional alias parameter may be  used  in  cases  where  NAT
     1830              causes  the client view of its local endpoint to differ from the
     1831              server view.  In this case local/remote-netmask  will  refer  to
     1832              the  server  view  while  alias/remote-netmask will refer to the
     1833              client view.
     1834
     1835              This option must be associated with a specific client  instance,
     1836              which  means  that  it  must  be  specified  either  in a client
     1837              instance config file using  --client-config-dir  or  dynamically
     1838              generated using a --client-connect script.
     1839
     1840              Remember also to include a --route directive in the main OpenVPN
     1841              config file which encloses local, so that the kernel  will  know
     1842              to route it to the server's TUN/TAP interface.
     1843
     1844              OpenVPN's  internal  client IP address selection algorithm works
     1845              as follows:
     1846
     1847              1 -- Use --client-connect script generated file  for  static  IP
     1848              (first choice).
    14851849              2 -- Use --client-config-dir file for static IP (next choice).
    1486               3 -- Use --ifconfig-pool allocation for dynamic IP (last choice).
     1850              3  --  Use  --ifconfig-pool  allocation  for  dynamic  IP  (last
     1851              choice).
    14871852
    14881853       --iroute network [netmask]
    1489               Generate an internal route to a specific client. The netmask parameter, if omitted,  defaults  to
    1490               255.255.255.255.
    1491 
    1492               This  directive  can  be  used  to  route  a fixed subnet from the server to a particular client,
    1493               regardless of where the client is connecting from.  Remember that you must also add the route  to
    1494               the  system  routing  table as well (such as by using the --route directive).  The reason why two
    1495               routes are needed is that the --route directive routes the packet from  the  kernel  to  OpenVPN.
    1496               Once in OpenVPN, the --iroute directive routes to the specific client.
    1497 
    1498               This  option  must be specified either in a client instance config file using --client-config-dir
    1499               or dynamically generated using a --client-connect script.
    1500 
    1501               The --iroute directive also has an important  interaction  with  --push  "route  ...".   --iroute
    1502               essentially  defines a subnet which is owned by a particular client (we will call this client A).
    1503               If you would like other clients to be able to reach A's subnet, you can use  --push  "route  ..."
    1504               together  with  --client-to-client  to  effect this.  In order for all clients to see A's subnet,
    1505               OpenVPN must push this route to all clients EXCEPT for A, since the subnet is already owned by A.
    1506               OpenVPN  accomplishes  this  by  not  not  pushing  a  route to a client if it matches one of the
     1854              Generate an internal route to a  specific  client.  The  netmask
     1855              parameter, if omitted, defaults to 255.255.255.255.
     1856
     1857              This  directive  can  be  used  to route a fixed subnet from the
     1858              server to a particular client, regardless of where the client is
     1859              connecting  from.   Remember that you must also add the route to
     1860              the system routing table as well (such as by using  the  --route
     1861              directive).   The  reason  why two routes are needed is that the
     1862              --route directive routes the packet from the kernel to  OpenVPN.
     1863              Once  in  OpenVPN, the --iroute directive routes to the specific
     1864              client.
     1865
     1866              This option must be specified either in a client instance config
     1867              file  using --client-config-dir or dynamically generated using a
     1868              --client-connect script.
     1869
     1870              The --iroute directive also has an  important  interaction  with
     1871              --push "route ...".  --iroute essentially defines a subnet which
     1872              is owned by a particular client (we will call  this  client  A).
     1873              If  you would like other clients to be able to reach A's subnet,
     1874              you can use --push "route ..."  together with --client-to-client
     1875              to  effect  this.   In  order for all clients to see A's subnet,
     1876              OpenVPN must push this route to all clients EXCEPT for A,  since
     1877              the  subnet is already owned by A.  OpenVPN accomplishes this by
     1878              not not pushing a route to a client if it  matches  one  of  the
    15071879              client's iroutes.
    15081880
    15091881       --client-to-client
    1510               Because the OpenVPN server mode handles multiple clients through a single tun or  tap  interface,
    1511               it  is  effectively  a  router.   The  --client-to-client  flag tells OpenVPN to internally route
    1512               client-to-client traffic rather than pushing all client-originating traffic to the TUN/TAP inter‐
    1513               face.
    1514 
    1515               When this option is used, each client will "see" the other clients which are currently connected.
    1516               Otherwise, each client will only see the server.  Don't use this option if you want  to  firewall
    1517               tunnel traffic using custom, per-client rules.
     1882              Because the OpenVPN server mode handles multiple clients through
     1883              a single tun or tap interface, it is effectively a router.   The
     1884              --client-to-client   flag  tells  OpenVPN  to  internally  route
     1885              client-to-client traffic rather than pushing  all  client-origi‐
     1886              nating traffic to the TUN/TAP interface.
     1887
     1888              When  this  option  is  used,  each  client will "see" the other
     1889              clients which are currently connected.  Otherwise,  each  client
     1890              will  only see the server.  Don't use this option if you want to
     1891              firewall tunnel traffic using custom, per-client rules.
    15181892
    15191893       --duplicate-cn
    1520               Allow multiple clients with the same common name to concurrently connect.  In the absence of this
    1521               option, OpenVPN will disconnect a client instance upon connection of a new client having the same
    1522               common name.
     1894              Allow multiple clients with the same common name to concurrently
     1895              connect.  In the absence of this option, OpenVPN will disconnect
     1896              a client instance upon connection of a  new  client  having  the
     1897              same common name.
    15231898
    15241899       --client-connect cmd
    15251900              Run command cmd on client connection.
    15261901
    1527               cmd  consists  of a path to script (or executable program), optionally followed by arguments. The
    1528               path and arguments may be single- or double-quoted and/or escaped using a backslash,  and  should
    1529               be separated by one or more spaces.
    1530 
    1531               The command is passed the common name and IP address of the just-authenticated client as environ‐
    1532               mental variables (see environmental variable section below).  The  command  is  also  passed  the
    1533               pathname  of a freshly created temporary file as the last argument (after any arguments specified
    1534               in cmd ), to be used by the command to pass dynamically generated config file directives back  to
    1535               OpenVPN.
    1536 
    1537               If the script wants to generate a dynamic config file to be applied on the server when the client
    1538               connects, it should write it to the file named by the last argument.
    1539 
    1540               See the --client-config-dir option below for options which can be legally used in  a  dynamically
    1541               generated config file.
    1542 
    1543               Note  that the return value of script is significant.  If script returns a non-zero error status,
    1544               it will cause the client to be disconnected.
     1902              cmd  consists  of  a  path  to  script  (or executable program),
     1903              optionally followed by arguments. The path and arguments may  be
     1904              single-  or  double-quoted and/or escaped using a backslash, and
     1905              should be separated by one or more spaces.
     1906
     1907              The command is passed the common name  and  IP  address  of  the
     1908              just-authenticated  client as environmental variables (see envi‐
     1909              ronmental variable section below).  The command is  also  passed
     1910              the  pathname  of  a  freshly created temporary file as the last
     1911              argument (after any arguments specified in cmd ), to be used  by
     1912              the command to pass dynamically generated config file directives
     1913              back to OpenVPN.
     1914
     1915              If the script wants to generate a  dynamic  config  file  to  be
     1916              applied  on the server when the client connects, it should write
     1917              it to the file named by the last argument.
     1918
     1919              See the --client-config-dir option below for options  which  can
     1920              be legally used in a dynamically generated config file.
     1921
     1922              Note  that the return value of script is significant.  If script
     1923              returns a non-zero error status, it will cause the client to  be
     1924              disconnected.
    15451925
    15461926       --client-disconnect cmd
    1547               Like --client-connect but called on client instance shutdown.  Will  not  be  called  unless  the
    1548               --client-connect  script  and  plugins  (if defined) were previously called on this instance with
     1927              Like  --client-connect  but  called on client instance shutdown.
     1928              Will not be called unless the --client-connect script and  plug‐
     1929              ins  (if  defined)  were previously called on this instance with
    15491930              successful (0) status returns.
    15501931
    1551               The exception to this rule is if the --client-disconnect command or plugins are cascaded, and  at
    1552               least  one  client-connect  function  succeeded,  then ALL of the client-disconnect functions for
    1553               scripts and plugins will be called on client instance object deletion, even in cases  where  some
    1554               of the related client-connect functions returned an error status.
    1555 
    1556               The --client-disconnect command is passed the same pathname as the corresponding --client-connect
    1557               command as its last argument. (after any arguments specified in cmd ).
     1932              The exception to this rule is if the --client-disconnect command
     1933              or  plugins  are cascaded, and at least one client-connect func‐
     1934              tion succeeded, then ALL of the client-disconnect functions  for
     1935              scripts  and  plugins  will  be called on client instance object
     1936              deletion, even in cases where some of the related client-connect
     1937              functions returned an error status.
     1938
     1939              The  --client-disconnect  command is passed the same pathname as
     1940              the corresponding --client-connect command as its last argument.
     1941              (after any arguments specified in cmd ).
    15581942
    15591943       --client-config-dir dir
    1560               Specify a directory dir for custom client config files.   After  a  connecting  client  has  been
    1561               authenticated,  OpenVPN  will  look  in  this  directory  for  a file having the same name as the
    1562               client's X509 common name.  If a matching file exists, it will be opened and parsed  for  client-
    1563               specific  configuration  options.  If no matching file is found, OpenVPN will instead try to open
    1564               and parse a default file called "DEFAULT", which may be provided but is not required.  Note  that
    1565               the  configuration  files  must be readable by the OpenVPN process after it has dropped it's root
    1566               privileges.
    1567 
    1568               This file can specify a fixed IP address for a given client using  --ifconfig-push,  as  well  as
    1569               fixed subnets owned by the client using --iroute.
    1570 
    1571               One  of  the  useful properties of this option is that it allows client configuration files to be
    1572               conveniently created, edited, or removed while the server is live, without needing to restart the
    1573               server.
    1574 
    1575               The  following  options  are  legal in a client-specific context: --push, --push-reset, --iroute,
    1576               --ifconfig-push, and --config.
     1944              Specify a directory dir for custom client config files.  After a
     1945              connecting client has been authenticated, OpenVPN will  look  in
     1946              this  directory  for a file having the same name as the client's
     1947              X509 common name.  If a matching file exists, it will be  opened
     1948              and  parsed  for  client-specific  configuration options.  If no
     1949              matching file is found, OpenVPN will instead  try  to  open  and
     1950              parse a default file called "DEFAULT", which may be provided but
     1951              is not required. Note that the configuration files must be read‐
     1952              able by the OpenVPN process after it has dropped it's root priv‐
     1953              ileges.
     1954
     1955              This file can specify a fixed IP  address  for  a  given  client
     1956              using  --ifconfig-push,  as  well  as fixed subnets owned by the
     1957              client using --iroute.
     1958
     1959              One of the useful properties of this option is  that  it  allows
     1960              client  configuration  files to be conveniently created, edited,
     1961              or removed while the server is live, without needing to  restart
     1962              the server.
     1963
     1964              The  following  options  are legal in a client-specific context:
     1965              --push, --push-reset, --iroute, --ifconfig-push, and --config.
    15771966
    15781967       --ccd-exclusive
    1579               Require, as a condition of authentication, that a connecting  client  has  a  --client-config-dir
    1580               file.
     1968              Require, as a condition of  authentication,  that  a  connecting
     1969              client has a --client-config-dir file.
    15811970
    15821971       --tmp-dir dir
    1583               Specify  a  directory  dir for temporary files.  This directory will be used by openvpn processes
    1584               and script to communicate temporary data with openvpn main process. Note that the directory  must
    1585               be writable by the OpenVPN process after it has dropped it's root privileges.
     1972              Specify  a  directory  dir  for temporary files.  This directory
     1973              will be used by openvpn processes and script to communicate tem‐
     1974              porary  data  with openvpn main process. Note that the directory
     1975              must be writable by the OpenVPN process  after  it  has  dropped
     1976              it's root privileges.
    15861977
    15871978              This directory will be used by in the following cases:
    15881979
    1589               * --client-connect scripts to dynamically generate client-specific configuration files.
    1590 
    1591               *  OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY  plugin  hook  to  return  success/failure  via auth_con‐
    1592               trol_file when using deferred auth method
    1593 
    1594               * OPENVPN_PLUGIN_ENABLE_PF plugin hook to pass filtering rules via pf_file
     1980              *  --client-connect  scripts to dynamically generate client-spe‐
     1981              cific configuration files.
     1982
     1983              * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY  plugin  hook  to  return
     1984              success/failure  via  auth_control_file when using deferred auth
     1985              method
     1986
     1987              * OPENVPN_PLUGIN_ENABLE_PF plugin hook to pass  filtering  rules
     1988              via pf_file
    15951989
    15961990       --hash-size r v
    1597               Set the size of the real address hash table to r and the virtual address table to v.  By default,
    1598               both tables are sized at 256 buckets.
     1991              Set the size of the real address hash table to r and the virtual
     1992              address table to v.  By default, both tables are  sized  at  256
     1993              buckets.
    15991994
    16001995       --bcast-buffers n
     
    16041999              Maximum number of output packets queued before TCP (default=64).
    16052000
    1606               When OpenVPN is tunneling data from a TUN/TAP device to a remote client over a TCP connection, it
    1607               is possible that the TUN/TAP device might produce data at a faster rate than the  TCP  connection
    1608               can  support.   When the number of output packets queued before sending to the TCP socket reaches
    1609               this limit for a given client connection, OpenVPN will start to drop outgoing packets directed at
    1610               this client.
     2001              When OpenVPN is tunneling data from a TUN/TAP device to a remote
     2002              client over a TCP connection, it is possible  that  the  TUN/TAP
     2003              device  might produce data at a faster rate than the TCP connec‐
     2004              tion can support.  When the  number  of  output  packets  queued
     2005              before  sending to the TCP socket reaches this limit for a given
     2006              client connection, OpenVPN will start to drop  outgoing  packets
     2007              directed at this client.
    16112008
    16122009       --tcp-nodelay
    1613               This  macro  sets  the  TCP_NODELAY  socket flag on the server as well as pushes it to connecting
    1614               clients.  The TCP_NODELAY flag disables the Nagle algorithm on TCP sockets causing packets to  be
    1615               transmitted  immediately with low latency, rather than waiting a short period of time in order to
    1616               aggregate several packets into a  larger  containing  packet.   In  VPN  applications  over  TCP,
     2010              This  macro  sets  the  TCP_NODELAY socket flag on the server as
     2011              well as pushes it to connecting clients.  The  TCP_NODELAY  flag
     2012              disables  the  Nagle algorithm on TCP sockets causing packets to
     2013              be transmitted immediately with low latency, rather than waiting
     2014              a  short  period  of  time in order to aggregate several packets
     2015              into a larger containing packet.  In VPN applications over  TCP,
    16172016              TCP_NODELAY is generally a good latency optimization.
    16182017
     
    16272026
    16282027       --max-routes-per-client n
    1629               Allow  a maximum of n internal routes per client (default=256).  This is designed to help contain
    1630               DoS attacks where an authenticated client floods the server with packets appearing to  come  from
    1631               many  unique  MAC addresses, forcing the server to deplete virtual memory as its internal routing
    1632               table expands.  This directive can be used in a --client-config-dir file or auto-generated  by  a
    1633               --client-connect script to override the global value for a particular client.
    1634 
    1635               Note that this directive affects OpenVPN's internal routing table, not the kernel routing table.
     2028              Allow  a  maximum of n internal routes per client (default=256).
     2029              This is designed to help contain DoS attacks where an  authenti‐
     2030              cated  client  floods  the server with packets appearing to come
     2031              from many unique MAC addresses, forcing the  server  to  deplete
     2032              virtual  memory  as  its  internal  routing table expands.  This
     2033              directive can be used in a --client-config-dir file or auto-gen‐
     2034              erated by a --client-connect script to override the global value
     2035              for a particular client.
     2036
     2037              Note that this directive affects OpenVPN's internal routing  ta‐
     2038              ble, not the kernel routing table.
    16362039
    16372040       --stale-routes-check n [t]
    1638               Remove routes haven't had activity for n seconds (i.e. the ageing time).
     2041              Remove  routes haven't had activity for n seconds (i.e. the age‐
     2042              ing time).
    16392043
    16402044              This check is ran every t seconds (i.e. check interval).
     
    16422046              If t is not present it defaults to n
    16432047
    1644               This option helps to keep the dynamic routing table small.  See also --max-routes-per-client
     2048              This option helps to keep the dynamic routing table small.   See
     2049              also --max-routes-per-client
    16452050
    16462051       --connect-freq n sec
    1647               Allow  a  maximum of n new connections per sec seconds from clients.  This is designed to contain
    1648               DoS attacks which flood the server with connection requests using certificates which  will  ulti‐
    1649               mately fail to authenticate.
    1650 
    1651               This  is  an  imperfect  solution however, because in a real DoS scenario, legitimate connections
    1652               might also be refused.
    1653 
    1654               For the best protection against DoS attacks in server mode, use --proto udp and --tls-auth.
     2052              Allow  a  maximum  of  n  new  connections  per sec seconds from
     2053              clients.  This is designed to contain DoS  attacks  which  flood
     2054              the  server  with  connection  requests using certificates which
     2055              will ultimately fail to authenticate.
     2056
     2057              This is an imperfect solution however, because  in  a  real  DoS
     2058              scenario, legitimate connections might also be refused.
     2059
     2060              For  the best protection against DoS attacks in server mode, use
     2061              --proto udp and --tls-auth.
    16552062
    16562063       --learn-address cmd
    16572064              Run command cmd to validate client virtual addresses or routes.
    16582065
    1659               cmd consists of a path to script (or executable program), optionally followed by  arguments.  The
    1660               path  and  arguments may be single- or double-quoted and/or escaped using a backslash, and should
    1661               be separated by one or more spaces.
    1662 
    1663               Three arguments will be appended to any arguments in cmd as follows:
    1664 
    1665               [1] operation -- "add", "update", or "delete" based on whether or not the address is being  added
    1666               to, modified, or deleted from OpenVPN's internal routing table.
    1667               [2]  address  --  The  address  being  learned or unlearned.  This can be an IPv4 address such as
    1668               "198.162.10.14", an IPv4 subnet such as "198.162.10.0/24", or an ethernet MAC address (when --dev
    1669               tap is being used) such as "00:FF:01:02:03:04".
    1670               [3]  common  name -- The common name on the certificate associated with the client linked to this
    1671               address.  Only present for "add" or "update" operations, not "delete".
    1672 
    1673               On "add" or "update" methods, if the script returns  a  failure  code  (non-zero),  OpenVPN  will
    1674               reject the address and will not modify its internal routing table.
    1675 
    1676               Normally,  the  cmd  script  will  use the information provided above to set appropriate firewall
    1677               entries on the VPN TUN/TAP interface.  Since OpenVPN provides the association between virtual  IP
    1678               or  MAC  address  and  the client's authenticated common name, it allows a user-defined script to
    1679               configure firewall access policies with regard to the client's  high-level  common  name,  rather
     2066              cmd consists of  a  path  to  script  (or  executable  program),
     2067              optionally  followed by arguments. The path and arguments may be
     2068              single- or double-quoted and/or escaped using a  backslash,  and
     2069              should be separated by one or more spaces.
     2070
     2071              Three arguments will be appended to any arguments in cmd as fol‐
     2072              lows:
     2073
     2074              [1] operation -- "add", "update", or "delete" based  on  whether
     2075              or  not the address is being added to, modified, or deleted from
     2076              OpenVPN's internal routing table.
     2077              [2] address -- The address being learned or unlearned.  This can
     2078              be  an IPv4 address such as "198.162.10.14", an IPv4 subnet such
     2079              as "198.162.10.0/24", or an ethernet MAC address (when --dev tap
     2080              is being used) such as "00:FF:01:02:03:04".
     2081              [3] common name -- The common name on the certificate associated
     2082              with the client linked to this address.  Only present for  "add"
     2083              or "update" operations, not "delete".
     2084
     2085              On  "add"  or  "update" methods, if the script returns a failure
     2086              code (non-zero), OpenVPN will reject the address  and  will  not
     2087              modify its internal routing table.
     2088
     2089              Normally, the cmd script will use the information provided above
     2090              to set appropriate firewall entries on the  VPN  TUN/TAP  inter‐
     2091              face.  Since OpenVPN provides the association between virtual IP
     2092              or MAC address and the client's authenticated  common  name,  it
     2093              allows  a user-defined script to configure firewall access poli‐
     2094              cies with regard to the client's high-level common name,  rather
    16802095              than the low level client virtual addresses.
    16812096
    16822097       --auth-user-pass-verify cmd method
    1683               Require  the client to provide a username/password (possibly in addition to a client certificate)
    1684               for authentication.
    1685 
    1686               OpenVPN will run command cmd to validate the username/password provided by the client.
    1687 
    1688               cmd consists of a path to script (or executable program), optionally followed by  arguments.  The
    1689               path  and  arguments may be single- or double-quoted and/or escaped using a backslash, and should
    1690               be separated by one or more spaces.
    1691 
    1692               If method is set to "via-env", OpenVPN will call script with the environmental variables username
    1693               and  password  set  to  the username/password strings provided by the client.  Be aware that this
    1694               method is insecure on some platforms which make the environment of a process publicly visible  to
    1695               other unprivileged processes.
    1696 
    1697               If  method  is  set  to "via-file", OpenVPN will write the username and password to the first two
    1698               lines of a temporary file.  The filename will be passed as an argument to script,  and  the  file
    1699               will be automatically deleted by OpenVPN after the script returns.  The location of the temporary
    1700               file is controlled by the --tmp-dir option, and will default to the current directory if unspeci‐
    1701               fied.  For security, consider setting --tmp-dir to a volatile storage medium such as /dev/shm (if
    1702               available) to prevent the username/password file from touching the hard drive.
    1703 
    1704               The script should examine the username and password, returning a success exit  code  (0)  if  the
    1705               client's authentication request is to be accepted, or a failure code (1) to reject the client.
    1706 
    1707               This directive is designed to enable a plugin-style interface for extending OpenVPN's authentica‐
    1708               tion capabilities.
    1709 
    1710               To protect against a client passing a maliciously formed username or password string,  the  user‐
    1711               name  string must consist only of these characters: alphanumeric, underbar ('_'), dash ('-'), dot
    1712               ('.'), or at ('@').  The password string can consist of any printable characters except for CR or
    1713               LF.  Any illegal characters in either the username or password string will be converted to under‐
    1714               bar ('_').
    1715 
    1716               Care must be taken by any user-defined scripts to avoid creating a security vulnerability in  the
    1717               way  that  these  strings  are handled.  Never use these strings in such a way that they might be
     2098              Require  the  client to provide a username/password (possibly in
     2099              addition to a client certificate) for authentication.
     2100
     2101              OpenVPN will run command cmd to validate  the  username/password
     2102              provided by the client.
     2103
     2104              cmd  consists  of  a  path  to  script  (or executable program),
     2105              optionally followed by arguments. The path and arguments may  be
     2106              single-  or  double-quoted and/or escaped using a backslash, and
     2107              should be separated by one or more spaces.
     2108
     2109              If method is set to "via-env", OpenVPN will call script with the
     2110              environmental  variables  username and password set to the user‐
     2111              name/password strings provided by the  client.   Be  aware  that
     2112              this  method  is insecure on some platforms which make the envi‐
     2113              ronment of a process publicly visible to other unprivileged pro‐
     2114              cesses.
     2115
     2116              If  method is set to "via-file", OpenVPN will write the username
     2117              and password to the first two lines of a  temporary  file.   The
     2118              filename  will  be passed as an argument to script, and the file
     2119              will be  automatically  deleted  by  OpenVPN  after  the  script
     2120              returns.   The  location  of the temporary file is controlled by
     2121              the --tmp-dir option, and will default to the current  directory
     2122              if  unspecified.   For security, consider setting --tmp-dir to a
     2123              volatile storage medium such as /dev/shm (if available) to  pre‐
     2124              vent the username/password file from touching the hard drive.
     2125
     2126              The script should examine the username and password, returning a
     2127              success exit code (0) if the client's authentication request  is
     2128              to be accepted, or a failure code (1) to reject the client.
     2129
     2130              This  directive  is  designed to enable a plugin-style interface
     2131              for extending OpenVPN's authentication capabilities.
     2132
     2133              To protect against a client passing a maliciously  formed  user‐
     2134              name  or  password string, the username string must consist only
     2135              of these characters: alphanumeric, underbar ('_'),  dash  ('-'),
     2136              dot  ('.'), or at ('@').  The password string can consist of any
     2137              printable characters except for CR or LF.  Any  illegal  charac‐
     2138              ters in either the username or password string will be converted
     2139              to underbar ('_').
     2140
     2141              Care must be taken by any user-defined scripts to avoid creating
     2142              a  security vulnerability in the way that these strings are han‐
     2143              dled.  Never use these strings in such a way that they might  be
    17182144              escaped or evaluated by a shell interpreter.
    17192145
    1720               For a sample script that performs PAM authentication, see sample-scripts/auth-pam.pl in the Open
    1721               VPN source distribution.
     2146              For  a  sample script that performs PAM authentication, see sam
     2147              ple-scripts/auth-pam.pl in the OpenVPN source distribution.
    17222148
    17232149       --opt-verify
    1724               Clients  that connect with options that are incompatible with those of the server will be discon‐
    1725               nected.
    1726 
    1727               Options that will be compared for compatibility include dev-type, link-mtu, tun-mtu, proto,  tun-
    1728               ipv6, ifconfig, comp-lzo, fragment, keydir, cipher, auth, keysize, secret, no-replay, no-iv, tls-
    1729               auth, key-method, tls-server, and tls-client.
     2150              Clients that connect with options  that  are  incompatible  with
     2151              those of the server will be disconnected.
     2152
     2153              Options  that  will  be  compared for compatibility include dev-
     2154              type, link-mtu, tun-mtu, proto,  tun-ipv6,  ifconfig,  comp-lzo,
     2155              fragment,  keydir, cipher, auth, keysize, secret, no-replay, no-
     2156              iv, tls-auth, key-method, tls-server, and tls-client.
    17302157
    17312158              This option requires that --disable-occ NOT be used.
    17322159
    17332160       --auth-user-pass-optional
    1734               Allow connections by clients that do not specify a  username/password.   Normally,  when  --auth-
    1735               user-pass-verify  or  --management-client-auth is specified (or an authentication plugin module),
    1736               the OpenVPN server daemon will require connecting clients to specify  a  username  and  password.
    1737               This  option makes the submission of a username/password by clients optional, passing the respon‐
    1738               sibility to the user-defined authentication module/script to accept or deny the client  based  on
    1739               other  factors (such as the setting of X509 certificate fields).  When this option is used, and a
    1740               connecting client does not submit  a  username/password,  the  user-defined  authentication  mod‐
    1741               ule/script  will see the username and password as being set to empty strings ("").  The authenti‐
    1742               cation module/script MUST have logic to detect this condition and respond accordingly.
     2161              Allow connections  by  clients  that  do  not  specify  a  user‐
     2162              name/password.  Normally, when --auth-user-pass-verify or --man‐
     2163              agement-client-auth is specified (or  an  authentication  plugin
     2164              module),  the  OpenVPN  server  daemon  will  require connecting
     2165              clients to specify a username and password.  This  option  makes
     2166              the submission of a username/password by clients optional, pass‐
     2167              ing the responsibility to the user-defined  authentication  mod‐
     2168              ule/script  to  accept or deny the client based on other factors
     2169              (such as the setting of X509  certificate  fields).   When  this
     2170              option  is used, and a connecting client does not submit a user‐
     2171              name/password,  the  user-defined  authentication  module/script
     2172              will see the username and password as being set to empty strings
     2173              ("").  The  authentication  module/script  MUST  have  logic  to
     2174              detect this condition and respond accordingly.
    17432175
    17442176       --client-cert-not-required
    1745               Don't require client certificate, client will  authenticate  using  username/password  only.   Be
    1746               aware that using this directive is less secure than requiring certificates from all clients.
    1747 
    1748               If  you use this directive, the entire responsibility of authentication will rest on your --auth-
    1749               user-pass-verify script, so keep in mind that bugs in your script  could  potentially  compromise
    1750               the security of your VPN.
    1751 
    1752               If  you  don't  use  this directive, but you also specify an --auth-user-pass-verify script, then
    1753               OpenVPN will perform double authentication.  The client certificate verification AND the  --auth-
    1754               user-pass-verify  script  will  need  to  succeed  in  order for a client to be authenticated and
    1755               accepted onto the VPN.
     2177              Don't require client certificate, client will authenticate using
     2178              username/password only.  Be aware that using this  directive  is
     2179              less secure than requiring certificates from all clients.
     2180
     2181              If  you use this directive, the entire responsibility of authen‐
     2182              tication will rest on your  --auth-user-pass-verify  script,  so
     2183              keep  in mind that bugs in your script could potentially compro‐
     2184              mise the security of your VPN.
     2185
     2186              If you don't use this directive, but you also specify an --auth-
     2187              user-pass-verify   script,  then  OpenVPN  will  perform  double
     2188              authentication.  The client  certificate  verification  AND  the
     2189              --auth-user-pass-verify script will need to succeed in order for
     2190              a client to be authenticated and accepted onto the VPN.
    17562191
    17572192       --username-as-common-name
    1758               For --auth-user-pass-verify authentication, use the authenticated username as  the  common  name,
    1759               rather than the common name from the client cert.
     2193              For --auth-user-pass-verify authentication,  use  the  authenti‐
     2194              cated  username  as the common name, rather than the common name
     2195              from the client cert.
    17602196
    17612197       --compat-names [no-remapping]
    1762               Until OpenVPN v2.3 the format of the X.509 Subject fields was formatted like this:
     2198              Until OpenVPN v2.3 the format of the X.509  Subject  fields  was
     2199              formatted like this:
    17632200
    17642201              /C=US/L=Somewhere/CN=John Doe/emailAddress=john@example.com
    17652202
    1766               In  addition  the  old  behavivour was to remap any character other than alphanumeric, underscore
    1767               ('_'), dash ('-'), dot ('.'), and slash ('/') to underscore ('_').  The X.509 Subject  string  as
    1768               returned  by  the  tls_id environmental variable, could additionally contain colon (':') or equal
    1769               ('=').
    1770 
    1771               When using the --compat-names option, this old formatting and remapping will be re-enabled again.
    1772               This  is  purely implemented for compatibility reasons when using older plug-ins or scripts which
    1773               does not handle the new formatting or UTF-8 characters.
    1774 
    1775               In OpenVPN v2.3 the formatting of these fields changed into a more standardised format.   It  now
    1776               looks like:
     2203              In  addition the old behavivour was to remap any character other
     2204              than alphanumeric, underscore ('_'), dash ('-'), dot ('.'),  and
     2205              slash  ('/')  to  underscore ('_').  The X.509 Subject string as
     2206              returned by the tls_id environmental variable,  could  addition‐
     2207              ally contain colon (':') or equal ('=').
     2208
     2209              When  using  the  --compat-names option, this old formatting and
     2210              remapping will be re-enabled again.  This is purely  implemented
     2211              for  compatibility  reasons when using older plug-ins or scripts
     2212              which does not handle the new formatting or UTF-8 characters.
     2213
     2214              In OpenVPN v2.3 the formatting of these fields  changed  into  a
     2215              more standardised format.  It now looks like:
    17772216
    17782217              C=US, L=Somewhere, CN=John Doe, emailAddress=john@example.com
    17792218
    1780               The  new  default  format in OpenVPN v2.3 also does not do the character remapping which happened
    1781               earlier.  This new format enables proper support for UTF-8 characters  in  the  usernames,  X.509
    1782               Subject  fields and Common Name variables and it complies to the RFC 2253, UTF-8 String Represen‐
    1783               tation of Distinguished Names.
    1784 
    1785               As a backwards compatibility for the removed --no-name-remapping feature in  older  OpenVPN  ver‐
    1786               sions,  the  no-remapping  mode  flag can be used with the --compat-names option.  When this mode
    1787               flag is used, the Common Name, Subject, and username strings are allowed to include any printable
    1788               character  including  space, but excluding control characters such as tab, newline, and carriage-
    1789               return. It ensures compatibility with the --no-name-remapping option of OpenVPN  versions  before
    1790               v2.3.
    1791 
    1792               Please  note: This option will not be around for a long time.  It is only implemented to make the
    1793               transition to the new formatting less intrusive.  It will be removed either in  OpenVPN  v2.4  or
    1794               v2.5.   So please make sure you start the process to support the new formatting as soon as possi‐
    1795               ble.
     2219              The  new  default  format  in  OpenVPN v2.3 also does not do the
     2220              character remapping which happened  earlier.   This  new  format
     2221              enables  proper  support  for UTF-8 characters in the usernames,
     2222              X.509 Subject fields and Common Name variables and  it  complies
     2223              to  the  RFC  2253, UTF-8 String Representation of Distinguished
     2224              Names.
     2225
     2226              As a backwards compatibility for the removed --no-name-remapping
     2227              feature  in  older  OpenVPN versions, the no-remapping mode flag
     2228              can be used with the --compat-names option.  When this mode flag
     2229              is  used,  the  Common  Name,  Subject, and username strings are
     2230              allowed to include any printable character including space,  but
     2231              excluding control characters such as tab, newline, and carriage-
     2232              return. It ensures compatibility  with  the  --no-name-remapping
     2233              option of OpenVPN versions before v2.3.
     2234
     2235              Please note: This option will not be around for a long time.  It
     2236              is only implemented to make the transition to the new formatting
     2237              less  intrusive.   It  will be removed either in OpenVPN v2.4 or
     2238              v2.5.  So please make sure you start the process to support  the
     2239              new formatting as soon as possible.
    17962240
    17972241       --port-share host port [dir]
    1798               When run in TCP server mode, share the OpenVPN port with another application, such  as  an  HTTPS
    1799               server.   If  OpenVPN  senses  a connection to its port which is using a non-OpenVPN protocol, it
    1800               will proxy the connection to the server at host:port.   Currently  only  designed  to  work  with
    1801               HTTP/HTTPS, though it would be theoretically possible to extend to other protocols such as ssh.
    1802 
    1803               dir  specifies an optional directory where a temporary file with name N containing content C will
    1804               be dynamically generated for each proxy connection, where N is the source IP:port of  the  client
    1805               connection  and  C is the source IP:port of the connection to the proxy receiver.  This directory
    1806               can be used as a dictionary by the proxy receiver to determine  the  origin  of  the  connection.
    1807               Each generated file will be automatically deleted when the proxied connection is torn down.
     2242              When run in TCP server mode, share the OpenVPN port with another
     2243              application, such as an HTTPS server.  If OpenVPN senses a  con‐
     2244              nection  to  its  port which is using a non-OpenVPN protocol, it
     2245              will proxy the connection to the server at host:port.  Currently
     2246              only  designed to work with HTTP/HTTPS, though it would be theo‐
     2247              retically possible to extend to other protocols such as ssh.
     2248
     2249              dir specifies an optional directory where a temporary file  with
     2250              name  N  containing  content C will be dynamically generated for
     2251              each proxy connection, where N is  the  source  IP:port  of  the
     2252              client  connection and C is the source IP:port of the connection
     2253              to the proxy receiver.  This directory can be used as a  dictio‐
     2254              nary  by  the proxy receiver to determine the origin of the con‐
     2255              nection.  Each generated file will be automatically deleted when
     2256              the proxied connection is torn down.
    18082257
    18092258              Not implemented on Windows.
    18102259
    18112260   Client Mode
    1812        Use  client  mode  when  connecting  to an OpenVPN server which has --server, --server-bridge, or --mode
    1813        server in it's configuration.
     2261       Use  client  mode  when  connecting  to  an  OpenVPN  server  which has
     2262       --server, --server-bridge, or --mode server in it's configuration.
    18142263
    18152264       --client
    1816               A helper directive designed to simplify the configuration of OpenVPN's client mode.  This  direc‐
    1817               tive is equivalent to:
     2265              A helper directive designed to  simplify  the  configuration  of
     2266              OpenVPN's client mode.  This directive is equivalent to:
    18182267
    18192268                   pull
    18202269                   tls-client
    18212270
    1822        --pull This  option must be used on a client which is connecting to a multi-client server.  It indicates
    1823               to OpenVPN that it should accept options pushed by the server, provided  they  are  part  of  the
    1824               legal set of pushable options (note that the --pull option is implied by --client ).
    1825 
    1826               In  particular,  --pull  allows  the  server  to push routes to the client, so you should not use
    1827               --pull or --client in situations where you don't trust  the  server  to  have  control  over  the
     2271       --pull This  option  must  be used on a client which is connecting to a
     2272              multi-client server.  It indicates to  OpenVPN  that  it  should
     2273              accept  options  pushed by the server, provided they are part of
     2274              the legal set of pushable options (note that the  --pull  option
     2275              is implied by --client ).
     2276
     2277              In  particular,  --pull  allows the server to push routes to the
     2278              client, so you should not use --pull or --client  in  situations
     2279              where  you  don't  trust  the  server  to  have control over the
    18282280              client's routing table.
    18292281
    18302282       --auth-user-pass [up]
    1831               Authenticate with server using username/password.  up is a file containing username/password on 2
    1832               lines (Note: OpenVPN will only read passwords from a file if it has been built with the --enable-
    1833               password-save  configure  option,  or  on  Windows  by  defining ENABLE_PASSWORD_SAVE in win/set‐
    1834               tings.in).
    1835 
    1836               If up is omitted, username/password will be prompted from the console.
    1837 
    1838               The server configuration must specify an  --auth-user-pass-verify  script  to  verify  the  user‐
    1839               name/password provided by the client.
     2283              Authenticate with server using username/password.  up is a  file
     2284              containing username/password on 2 lines (Note: OpenVPN will only
     2285              read passwords from a  file  if  it  has  been  built  with  the
     2286              --enable-password-save configure option, or on Windows by defin‐
     2287              ing ENABLE_PASSWORD_SAVE in win/settings.in).
     2288
     2289              If up is omitted, username/password will be  prompted  from  the
     2290              console.
     2291
     2292              The server configuration must specify an --auth-user-pass-verify
     2293              script to verify the username/password provided by the client.
    18402294
    18412295       --auth-retry type
    1842               Controls  how  OpenVPN  responds to username/password verification errors such as the client-side
    1843               response to an AUTH_FAILED message from the server or verification failure  of  the  private  key
     2296              Controls how OpenVPN responds to username/password  verification
     2297              errors  such  as the client-side response to an AUTH_FAILED mes‐
     2298              sage from the server or verification failure of the private  key
    18442299              password.
    18452300
    1846               Normally  used  to  prevent  auth errors from being fatal on the client side, and to permit user‐
    1847               name/password requeries in case of error.
    1848 
    1849               An AUTH_FAILED message is generated by the server if the client fails --auth-user-pass  authenti‐
    1850               cation,  or  if  the  server-side --client-connect script returns an error status when the client
     2301              Normally  used  to  prevent  auth errors from being fatal on the
     2302              client side, and to permit username/password requeries  in  case
     2303              of error.
     2304
     2305              An  AUTH_FAILED message is generated by the server if the client
     2306              fails --auth-user-pass authentication,  or  if  the  server-side
     2307              --client-connect  script returns an error status when the client
    18512308              tries to connect.
    18522309
    18532310              type can be one of:
    18542311
    1855               none -- Client will exit with a fatal error (this is the default).
    1856               nointeract -- Client will retry the connection without requerying for an  --auth-user-pass  user‐
    1857               name/password.  Use this option for unattended clients.
    1858               interact  --  Client  will  requery  for an --auth-user-pass username/password and/or private key
    1859               password before attempting a reconnection.
    1860 
    1861               Note that while this option cannot be pushed, it can be controlled from the management interface.
     2312              none -- Client will  exit  with  a  fatal  error  (this  is  the
     2313              default).
     2314              nointeract  -- Client will retry the connection without requery‐
     2315              ing for an --auth-user-pass username/password.  Use this  option
     2316              for unattended clients.
     2317              interact  --  Client  will requery for an --auth-user-pass user‐
     2318              name/password and/or private key password  before  attempting  a
     2319              reconnection.
     2320
     2321              Note  that  while  this  option cannot be pushed, it can be con‐
     2322              trolled from the management interface.
    18622323
    18632324       --static-challenge t e
    1864               Enable static challenge/response protocol using challenge text t,  with  echo  flag  given  by  e
    1865               (0|1).
    1866 
    1867               The echo flag indicates whether or not the user's response to the challenge should be echoed.
    1868 
    1869               See  management-notes.txt  in  the  OpenVPN  distribution  for a description of the OpenVPN chal‐
    1870               lenge/response protocol.
     2325              Enable static challenge/response protocol using  challenge  text
     2326              t, with echo flag given by e (0|1).
     2327
     2328              The  echo  flag  indicates whether or not the user's response to
     2329              the challenge should be echoed.
     2330
     2331              See management-notes.txt  in  the  OpenVPN  distribution  for  a
     2332              description of the OpenVPN challenge/response protocol.
    18712333
    18722334       --server-poll-timeout n
    1873               when polling possible remote servers to connect to in a round-robin fashion, spend no more than n
    1874               seconds waiting for a response before trying the next server.
     2335              when  polling  possible remote servers to connect to in a round-
     2336              robin fashion, spend no  more  than  n  seconds  waiting  for  a
     2337              response before trying the next server.
    18752338
    18762339       --explicit-exit-notify [n]
    1877               In  UDP  client  mode  or point-to-point mode, send server/peer an exit notification if tunnel is
    1878               restarted or OpenVPN process is exited.  In client mode, on exit/restart, this option  will  tell
    1879               the  server  to  immediately  close its client instance object rather than waiting for a timeout.
    1880               The n parameter (default=1) controls the maximum number of attempts that the client will  try  to
    1881               resend  the  exit notification message.  OpenVPN will not send any exit notifications unless this
    1882               option is enabled.
     2340              In  UDP  client mode or point-to-point mode, send server/peer an
     2341              exit notification if tunnel is restarted or OpenVPN  process  is
     2342              exited.   In client mode, on exit/restart, this option will tell
     2343              the server to  immediately  close  its  client  instance  object
     2344              rather  than waiting for a timeout.  The n parameter (default=1)
     2345              controls the maximum number of attempts that the client will try
     2346              to  resend the exit notification message.  OpenVPN will not send
     2347              any exit notifications unless this option is enabled.
    18832348
    18842349   Data Channel Encryption Options:
    1885        These options are meaningful for both Static & TLS-negotiated key  modes  (must  be  compatible  between
    1886        peers).
     2350       These options are meaningful for both Static & TLS-negotiated key modes
     2351       (must be compatible between peers).
    18872352
    18882353       --secret file [direction]
    1889               Enable Static Key encryption mode (non-TLS).  Use pre-shared secret file which was generated with
    1890               --genkey.
    1891 
    1892               The optional direction parameter enables the use of 4 distinct keys  (HMAC-send,  cipher-encrypt,
    1893               HMAC-receive,  cipher-decrypt),  so that each data flow direction has a different set of HMAC and
    1894               cipher keys.  This has a number of desirable security properties  including  eliminating  certain
    1895               kinds of DoS and message replay attacks.
    1896 
    1897               When  the  direction  parameter is omitted, 2 keys are used bidirectionally, one for HMAC and the
    1898               other for encryption/decryption.
    1899 
    1900               The direction parameter should always be complementary on either side of the connection, i.e. one
    1901               side should use "0" and the other should use "1", or both sides should omit it altogether.
    1902 
    1903               The  direction  parameter  requires that file contains a 2048 bit key.  While pre-1.5 versions of
    1904               OpenVPN generate 1024 bit key files, any version of OpenVPN which supports the direction  parame‐
    1905               ter, will also support 2048 bit key file generation using the --genkey option.
    1906 
    1907               Static key encryption mode has certain advantages, the primary being ease of configuration.
    1908 
    1909               There  are  no  certificates or certificate authorities or complicated negotiation handshakes and
    1910               protocols.  The only requirement is that you have a pre-existing secure channel  with  your  peer
    1911               (such  as  ssh  ) to initially copy the key.  This requirement, along with the fact that your key
    1912               never changes unless you manually generate a new one, makes it somewhat less secure than TLS mode
    1913               (see  below).   If an attacker manages to steal your key, everything that was ever encrypted with
    1914               it is compromised.  Contrast that to the perfect forward secrecy  features  of  TLS  mode  (using
    1915               Diffie  Hellman  key  exchange), where even if an attacker was able to steal your private key, he
    1916               would gain no information to help him decrypt past sessions.
    1917 
    1918               Another advantageous aspect of Static Key encryption mode is that it is a handshake-free protocol
    1919               without any distinguishing signature or feature (such as a header or protocol handshake sequence)
    1920               that would mark the ciphertext packets as being generated by OpenVPN.   Anyone  eavesdropping  on
    1921               the wire would see nothing but random-looking data.
     2354              Enable  Static  Key  encryption  mode (non-TLS).  Use pre-shared
     2355              secret file which was generated with --genkey.
     2356
     2357              The optional direction parameter enables the use of  4  distinct
     2358              keys  (HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt),
     2359              so that each data flow direction has a different set of HMAC and
     2360              cipher keys.  This has a number of desirable security properties
     2361              including eliminating certain kinds of DoS  and  message  replay
     2362              attacks.
     2363
     2364              When  the  direction parameter is omitted, 2 keys are used bidi‐
     2365              rectionally, one for HMAC and the other  for  encryption/decryp‐
     2366              tion.
     2367
     2368              The direction parameter should always be complementary on either
     2369              side of the connection, i.e. one side should  use  "0"  and  the
     2370              other should use "1", or both sides should omit it altogether.
     2371
     2372              The  direction  parameter requires that file contains a 2048 bit
     2373              key.  While pre-1.5 versions of OpenVPN generate  1024  bit  key
     2374              files,  any  version  of  OpenVPN  which  supports the direction
     2375              parameter, will also support 2048 bit key file generation  using
     2376              the --genkey option.
     2377
     2378              Static  key  encryption mode has certain advantages, the primary
     2379              being ease of configuration.
     2380
     2381              There are no certificates or certificate authorities or  compli‐
     2382              cated  negotiation  handshakes and protocols.  The only require‐
     2383              ment is that you have a pre-existing secure  channel  with  your
     2384              peer  (such  as  ssh ) to initially copy the key.  This require‐
     2385              ment, along with the fact that your key never changes unless you
     2386              manually  generate a new one, makes it somewhat less secure than
     2387              TLS mode (see below).  If an attacker manages to steal your key,
     2388              everything that was ever encrypted with it is compromised.  Con‐
     2389              trast that to the perfect forward secrecy features of  TLS  mode
     2390              (using  Diffie  Hellman key exchange), where even if an attacker
     2391              was able to steal your private key, he would gain no information
     2392              to help him decrypt past sessions.
     2393
     2394              Another  advantageous  aspect  of  Static Key encryption mode is
     2395              that it is a handshake-free protocol without any  distinguishing
     2396              signature  or  feature  (such  as a header or protocol handshake
     2397              sequence) that would mark the ciphertext packets as being gener‐
     2398              ated  by  OpenVPN.   Anyone  eavesdropping on the wire would see
     2399              nothing but random-looking data.
    19222400
    19232401       --key-direction
    1924               Alternative  way  of  specifying the optional direction parameter for the --tls-auth and --secret
    1925               options. Useful when using inline files (See section on inline files).
     2402              Alternative way of specifying the optional  direction  parameter
     2403              for  the  --tls-auth  and  --secret  options.  Useful when using
     2404              inline files (See section on inline files).
    19262405
    19272406       --auth alg
    1928               Authenticate packets with HMAC using message digest algorithm alg.  (The default is SHA1 ).  HMAC
    1929               is  a commonly used message authentication algorithm (MAC) that uses a data string, a secure hash
    1930               algorithm, and a key, to produce a digital signature.
    1931 
    1932               OpenVPN's usage of HMAC is to first encrypt a packet, then HMAC the resulting ciphertext.
    1933 
    1934               In static-key encryption mode, the HMAC key is included in the key file  generated  by  --genkey.
    1935               In  TLS  mode, the HMAC key is dynamically generated and shared between peers via the TLS control
    1936               channel.  If OpenVPN receives a packet with a bad HMAC it will drop  the  packet.   HMAC  usually
    1937               adds 16 or 20 bytes per packet.  Set alg=none to disable authentication.
    1938 
    1939               For more information on HMAC see http://www.cs.ucsd.edu/users/mihir/papers/hmac.html
     2407              Authenticate packets with HMAC using  message  digest  algorithm
     2408              alg.   (The  default is SHA1 ).  HMAC is a commonly used message
     2409              authentication algorithm (MAC) that uses a data string, a secure
     2410              hash algorithm, and a key, to produce a digital signature.
     2411
     2412              OpenVPN's  usage of HMAC is to first encrypt a packet, then HMAC
     2413              the resulting ciphertext.
     2414
     2415              In static-key encryption mode, the HMAC key is included  in  the
     2416              key  file  generated  by --genkey.  In TLS mode, the HMAC key is
     2417              dynamically generated and shared between peers via the TLS  con‐
     2418              trol  channel.   If OpenVPN receives a packet with a bad HMAC it
     2419              will drop the packet.  HMAC usually adds  16  or  20  bytes  per
     2420              packet.  Set alg=none to disable authentication.
     2421
     2422              For        more        information       on       HMAC       see
     2423              http://www.cs.ucsd.edu/users/mihir/papers/hmac.html
    19402424
    19412425       --cipher alg
    1942               Encrypt  packets  with cipher algorithm alg.  The default is BF-CBC, an abbreviation for Blowfish
    1943               in Cipher Block Chaining mode.  Blowfish has the advantages  of  being  fast,  very  secure,  and
    1944               allowing  key  sizes of up to 448 bits.  Blowfish is designed to be used in situations where keys
    1945               are changed infrequently.
    1946 
    1947               For more information on blowfish, see http://www.counterpane.com/blowfish.html
    1948 
    1949               To see other ciphers that are available with OpenVPN, use the --show-ciphers option.
    1950 
    1951               OpenVPN supports the CBC, CFB, and OFB cipher modes, however CBC is recommended and CFB  and  OFB
    1952               should be considered advanced modes.
     2426              Encrypt packets with cipher algorithm alg.  The default  is  BF-
     2427              CBC, an abbreviation for Blowfish in Cipher Block Chaining mode.
     2428              Blowfish has the advantages of  being  fast,  very  secure,  and
     2429              allowing  key  sizes of up to 448 bits.  Blowfish is designed to
     2430              be used in situations where keys are changed infrequently.
     2431
     2432              For  more  information  on  blowfish,  see   http://www.counter‐
     2433              pane.com/blowfish.html
     2434
     2435              To  see  other  ciphers that are available with OpenVPN, use the
     2436              --show-ciphers option.
     2437
     2438              OpenVPN supports the CBC, CFB, and OFB cipher modes, however CBC
     2439              is  recommended  and  CFB  and OFB should be considered advanced
     2440              modes.
    19532441
    19542442              Set alg=none to disable encryption.
    19552443
    19562444       --keysize n
    1957               Size of cipher key in bits (optional).  If unspecified, defaults to cipher-specific default.  The
    1958               --show-ciphers option (see below) shows all available OpenSSL ciphers, their default  key  sizes,
    1959               and whether the key size can be changed.  Use care in changing a cipher's default key size.  Many
    1960               ciphers have not been extensively cryptanalyzed with non-standard key lengths, and a  larger  key
    1961               may offer no real guarantee of greater security, or may even reduce security.
     2445              Size of cipher key in bits (optional).  If unspecified, defaults
     2446              to  cipher-specific  default.   The  --show-ciphers  option (see
     2447              below) shows all available OpenSSL ciphers,  their  default  key
     2448              sizes,  and  whether  the  key size can be changed.  Use care in
     2449              changing a cipher's default key size.   Many  ciphers  have  not
     2450              been  extensively  cryptanalyzed  with non-standard key lengths,
     2451              and a larger key may offer no real guarantee  of  greater  secu‐
     2452              rity, or may even reduce security.
    19622453
    19632454       --prng alg [nsl]
    1964               (Advanced)  For  PRNG  (Pseudo-random number generator), use digest algorithm alg (default=sha1),
    1965               and set nsl (default=16) to the size in bytes of the nonce secret length (between 16 and 64).
    1966 
    1967               Set alg=none to disable the PRNG and use the OpenSSL RAND_bytes function instead for all of Open‐
    1968               VPN's pseudo-random number needs.
     2455              (Advanced) For PRNG (Pseudo-random number generator), use digest
     2456              algorithm alg (default=sha1), and set nsl  (default=16)  to  the
     2457              size in bytes of the nonce secret length (between 16 and 64).
     2458
     2459              Set  alg=none to disable the PRNG and use the OpenSSL RAND_bytes
     2460              function instead  for  all  of  OpenVPN's  pseudo-random  number
     2461              needs.
    19692462
    19702463       --engine [engine-name]
    19712464              Enable OpenSSL hardware-based crypto engine functionality.
    19722465
    1973               If  engine-name  is  specified,  use a specific crypto engine.  Use the --show-engines standalone
    1974               option to list the crypto engines which are supported by OpenSSL.
     2466              If  engine-name is specified, use a specific crypto engine.  Use
     2467              the --show-engines standalone option to list the crypto  engines
     2468              which are supported by OpenSSL.
    19752469
    19762470       --no-replay
    1977               (Advanced) Disable OpenVPN's protection against replay attacks.  Don't use this option unless you
    1978               are prepared to make a tradeoff of greater efficiency in exchange for less security.
     2471              (Advanced)  Disable OpenVPN's protection against replay attacks.
     2472              Don't use this option unless you are prepared to make a tradeoff
     2473              of greater efficiency in exchange for less security.
    19792474
    19802475              OpenVPN provides datagram replay protection by default.
    19812476
    1982               Replay  protection  is  accomplished by tagging each outgoing datagram with an identifier that is
    1983               guaranteed to be unique for the key being used.  The peer that receives the datagram  will  check
    1984               for the uniqueness of the identifier.  If the identifier was already received in a previous data‐
    1985               gram, OpenVPN will drop the packet.  Replay protection is important to defeat attacks such  as  a
    1986               SYN  flood attack, where the attacker listens in the wire, intercepts a TCP SYN packet (identify‐
    1987               ing it by the context in which it occurs in relation to other packets), then floods the receiving
    1988               peer with copies of this packet.
    1989 
    1990               OpenVPN's  replay protection is implemented in slightly different ways, depending on the key man‐
    1991               agement mode you have selected.
    1992 
    1993               In Static Key mode or when using an CFB or OFB mode cipher, OpenVPN uses a 64 bit unique  identi‐
    1994               fier that combines a time stamp with an incrementing sequence number.
    1995 
    1996               When  using  TLS mode for key exchange and a CBC cipher mode, OpenVPN uses only a 32 bit sequence
    1997               number without a time stamp, since OpenVPN can guarantee the uniqueness of this  value  for  each
    1998               key.  As in IPSec, if the sequence number is close to wrapping back to zero, OpenVPN will trigger
    1999               a new key exchange.
    2000 
    2001               To check for replays, OpenVPN uses the sliding window algorithm used by IPSec.
     2477              Replay protection is accomplished by tagging each outgoing data‐
     2478              gram with an identifier that is guaranteed to be unique for  the
     2479              key  being used.  The peer that receives the datagram will check
     2480              for the uniqueness of the identifier.   If  the  identifier  was
     2481              already  received  in a previous datagram, OpenVPN will drop the
     2482              packet.  Replay protection is important to defeat  attacks  such
     2483              as  a  SYN flood attack, where the attacker listens in the wire,
     2484              intercepts a TCP SYN packet (identifying it by  the  context  in
     2485              which  it  occurs in relation to other packets), then floods the
     2486              receiving peer with copies of this packet.
     2487
     2488              OpenVPN's replay protection is implemented in slightly different
     2489              ways, depending on the key management mode you have selected.
     2490
     2491              In  Static  Key  mode  or  when using an CFB or OFB mode cipher,
     2492              OpenVPN uses a 64 bit unique identifier  that  combines  a  time
     2493              stamp with an incrementing sequence number.
     2494
     2495              When  using  TLS  mode  for  key exchange and a CBC cipher mode,
     2496              OpenVPN uses only a 32 bit sequence number without a time stamp,
     2497              since  OpenVPN  can  guarantee  the uniqueness of this value for
     2498              each key.  As in IPSec, if the sequence number is close to wrap‐
     2499              ping back to zero, OpenVPN will trigger a new key exchange.
     2500
     2501              To  check for replays, OpenVPN uses the sliding window algorithm
     2502              used by IPSec.
    20022503
    20032504       --replay-window n [t]
    2004               Use a replay protection sliding-window of size n and a time window of t seconds.
     2505              Use a replay protection sliding-window of size n and a time win‐
     2506              dow of t seconds.
    20052507
    20062508              By default n is 64 (the IPSec default) and t is 15 seconds.
    20072509
    2008               This option is only relevant in UDP mode, i.e.  when  either  --proto  udp  is  specifed,  or  no
    2009               --proto option is specified.
    2010 
    2011               When  OpenVPN tunnels IP packets over UDP, there is the possibility that packets might be dropped
    2012               or delivered out of order.  Because OpenVPN, like IPSec, is emulating the physical network layer,
    2013               it  will  accept an out-of-order packet sequence, and will deliver such packets in the same order
    2014               they were received to the TCP/IP protocol stack, provided they satisfy several constraints.
    2015 
    2016               (a) The packet cannot be a replay (unless --no-replay is specified, which disables replay protec‐
    2017               tion altogether).
    2018 
    2019               (b)  If  a  packet  arrives  out of order, it will only be accepted if the difference between its
    2020               sequence number and the highest sequence number received so far is less than n.
    2021 
    2022               (c) If a packet arrives out of order, it will only be accepted if it arrives no later than t sec‐
    2023               onds after any packet containing a higher sequence number.
    2024 
    2025               If  you are using a network link with a large pipeline (meaning that the product of bandwidth and
    2026               latency is high), you may want to use a larger value for n.  Satellite links in particular  often
    2027               require this.
    2028 
    2029               If  you  run OpenVPN at --verb 4, you will see the message "Replay-window backtrack occurred [x]"
    2030               every time the maximum sequence number backtrack seen thus far increases.  This can  be  used  to
    2031               calibrate n.
    2032 
    2033               There is some controversy on the appropriate method of handling packet reordering at the security
    2034               layer.
    2035 
    2036               Namely, to what extent should the security layer protect the encapsulated protocol  from  attacks
    2037               which masquerade as the kinds of normal packet loss and reordering that occur over IP networks?
    2038 
    2039               The IPSec and OpenVPN approach is to allow packet reordering within a certain fixed sequence num‐
    2040               ber window.
    2041 
    2042               OpenVPN adds to the IPSec model by limiting the window size in time as well as sequence space.
    2043 
    2044               OpenVPN also adds TCP transport as an option (not offered by IPSec) in  which  case  OpenVPN  can
    2045               adopt a very strict attitude towards message deletion and reordering:  Don't allow it.  Since TCP
    2046               guarantees reliability, any packet loss or reordering event can be assumed to be an attack.
    2047 
    2048               In this sense, it could be argued that TCP tunnel transport is preferred when tunneling non-IP or
    2049               UDP  application  protocols  which might be vulnerable to a message deletion or reordering attack
    2050               which falls within the normal operational parameters of IP networks.
    2051 
    2052               So I would make the statement that one should never tunnel a non-IP protocol or  UDP  application
    2053               protocol over UDP, if the protocol might be vulnerable to a message deletion or reordering attack
    2054               that falls within the normal operating parameters of what is to be expected from the physical  IP
    2055               layer.  The problem is easily fixed by simply using TCP as the VPN transport layer.
     2510              This  option  is  only  relevant  in UDP mode, i.e.  when either
     2511              --proto udp is specifed, or no --proto option is specified.
     2512
     2513              When OpenVPN tunnels IP packets over UDP, there is the possibil‐
     2514              ity  that  packets  might  be dropped or delivered out of order.
     2515              Because OpenVPN, like IPSec, is emulating the  physical  network
     2516              layer,  it will accept an out-of-order packet sequence, and will
     2517              deliver such packets in the same order they were received to the
     2518              TCP/IP  protocol  stack,  provided  they  satisfy  several  con‐
     2519              straints.
     2520
     2521              (a) The packet cannot be a replay (unless --no-replay is  speci‐
     2522              fied, which disables replay protection altogether).
     2523
     2524              (b)  If  a packet arrives out of order, it will only be accepted
     2525              if the difference between its sequence number  and  the  highest
     2526              sequence number received so far is less than n.
     2527
     2528              (c)  If  a packet arrives out of order, it will only be accepted
     2529              if it arrives no later than t seconds after any packet  contain‐
     2530              ing a higher sequence number.
     2531
     2532              If  you  are using a network link with a large pipeline (meaning
     2533              that the product of bandwidth and latency is high), you may want
     2534              to  use  a  larger  value  for n.  Satellite links in particular
     2535              often require this.
     2536
     2537              If you run OpenVPN  at  --verb  4,  you  will  see  the  message
     2538              "Replay-window  backtrack  occurred  [x]" every time the maximum
     2539              sequence number backtrack seen thus far increases.  This can  be
     2540              used to calibrate n.
     2541
     2542              There  is some controversy on the appropriate method of handling
     2543              packet reordering at the security layer.
     2544
     2545              Namely, to what extent should the  security  layer  protect  the
     2546              encapsulated protocol from attacks which masquerade as the kinds
     2547              of normal packet loss and reordering that  occur  over  IP  net‐
     2548              works?
     2549
     2550              The  IPSec  and  OpenVPN  approach is to allow packet reordering
     2551              within a certain fixed sequence number window.
     2552
     2553              OpenVPN adds to the IPSec model by limiting the window  size  in
     2554              time as well as sequence space.
     2555
     2556              OpenVPN  also  adds  TCP  transport as an option (not offered by
     2557              IPSec) in which case OpenVPN can adopt a  very  strict  attitude
     2558              towards message deletion and reordering:  Don't allow it.  Since
     2559              TCP guarantees reliability, any packet loss or reordering  event
     2560              can be assumed to be an attack.
     2561
     2562              In  this  sense, it could be argued that TCP tunnel transport is
     2563              preferred when tunneling non-IP  or  UDP  application  protocols
     2564              which  might  be  vulnerable to a message deletion or reordering
     2565              attack which falls within the normal operational  parameters  of
     2566              IP networks.
     2567
     2568              So  I  would  make  the statement that one should never tunnel a
     2569              non-IP protocol or UDP application protocol  over  UDP,  if  the
     2570              protocol might be vulnerable to a message deletion or reordering
     2571              attack that falls within the normal operating parameters of what
     2572              is  to  be  expected from the physical IP layer.  The problem is
     2573              easily fixed by simply using TCP as the VPN transport layer.
    20562574
    20572575       --mute-replay-warnings
    2058               Silence  the  output  of  replay warnings, which are a common false alarm on WiFi networks.  This
    2059               option preserves the security of the replay protection code without the verbosity associated with
     2576              Silence the output of replay warnings, which are a common  false
     2577              alarm  on  WiFi networks.  This option preserves the security of
     2578              the replay protection code without the verbosity associated with
    20602579              warnings about duplicate packets.
    20612580
    20622581       --replay-persist file
    2063               Persist replay-protection state across sessions using file to save and reload the state.
    2064 
    2065               This  option  will  strengthen  protection  against replay attacks, especially when you are using
    2066               OpenVPN in a dynamic context (such as with --inetd) when OpenVPN sessions are frequently  started
     2582              Persist  replay-protection  state  across sessions using file to
     2583              save and reload the state.
     2584
     2585              This option will strengthen protection against  replay  attacks,
     2586              especially when you are using OpenVPN in a dynamic context (such
     2587              as with --inetd) when OpenVPN sessions  are  frequently  started
    20672588              and stopped.
    20682589
    2069               This  option  will  keep a disk copy of the current replay protection state (i.e. the most recent
    2070               packet timestamp and sequence number received from the remote peer), so that if an  OpenVPN  ses‐
    2071               sion  is stopped and restarted, it will reject any replays of packets which were already received
    2072               by the prior session.
    2073 
    2074               This option only makes sense when replay protection is enabled (the default) and  you  are  using
    2075               either --secret (shared-secret key mode) or TLS mode with --tls-auth.
     2590              This  option will keep a disk copy of the current replay protec‐
     2591              tion state (i.e. the most recent packet timestamp  and  sequence
     2592              number  received  from  the  remote peer), so that if an OpenVPN
     2593              session is stopped and restarted, it will reject any replays  of
     2594              packets which were already received by the prior session.
     2595
     2596              This  option  only makes sense when replay protection is enabled
     2597              (the default) and you are using either  --secret  (shared-secret
     2598              key mode) or TLS mode with --tls-auth.
    20762599
    20772600       --no-iv
    2078               (Advanced)  Disable  OpenVPN's  use  of IV (cipher initialization vector).  Don't use this option
    2079               unless you are prepared to make a tradeoff of greater efficiency in exchange for less security.
    2080 
    2081               OpenVPN uses an IV by default, and requires it for CFB and OFB cipher modes  (which  are  totally
    2082               insecure  without  it).   Using  an IV is important for security when multiple messages are being
     2601              (Advanced)  Disable  OpenVPN's  use of IV (cipher initialization
     2602              vector).  Don't use this option unless you are prepared to  make
     2603              a tradeoff of greater efficiency in exchange for less security.
     2604
     2605              OpenVPN  uses  an IV by default, and requires it for CFB and OFB
     2606              cipher modes (which are totally insecure without it).  Using  an
     2607              IV  is  important  for security when multiple messages are being
    20832608              encrypted/decrypted with the same key.
    20842609
     
    20872612              In CBC mode, OpenVPN uses a pseudo-random IV for each packet.
    20882613
    2089               In CFB/OFB mode, OpenVPN uses a unique sequence number and time stamp as the  IV.   In  fact,  in
    2090               CFB/OFB  mode,  OpenVPN uses a datagram space-saving optimization that uses the unique identifier
     2614              In CFB/OFB mode, OpenVPN uses a unique sequence number and  time
     2615              stamp as the IV.  In fact, in CFB/OFB mode, OpenVPN uses a data‐
     2616              gram space-saving optimization that uses the  unique  identifier
    20912617              for datagram replay protection as the IV.
    20922618
     
    20942620              Enable prediction resistance on PolarSSL's RNG.
    20952621
    2096               Enabling prediction resistance causes the RNG to reseed in each call for random.  Reseeding  this
    2097               often can quickly deplete the kernel entropy pool.
    2098 
    2099               If you need this option, please consider running a daemon that adds entropy to the kernel pool.
    2100 
    2101               Note that this option only works with PolarSSL versions greater than 1.1.
     2622              Enabling  prediction resistance causes the RNG to reseed in each
     2623              call for random. Reseeding this often can  quickly  deplete  the
     2624              kernel entropy pool.
     2625
     2626              If  you  need this option, please consider running a daemon that
     2627              adds entropy to the kernel pool.
     2628
     2629              Note that this option only works with PolarSSL versions  greater
     2630              than 1.1.
    21022631
    21032632       --test-crypto
    2104               Do  a  self-test  of OpenVPN's crypto options by encrypting and decrypting test packets using the
    2105               data channel encryption options specified above.  This option does not require a  peer  to  func‐
    2106               tion, and therefore can be specified without --dev or --remote.
     2633              Do  a  self-test  of  OpenVPN's crypto options by encrypting and
     2634              decrypting  test  packets  using  the  data  channel  encryption
     2635              options specified above.  This option does not require a peer to
     2636              function, and  therefore  can  be  specified  without  --dev  or
     2637              --remote.
    21072638
    21082639              The typical usage of --test-crypto would be something like this:
     
    21142645              openvpn --test-crypto --secret key --verb 9
    21152646
    2116               This option is very useful to test OpenVPN after it has been ported to a new platform, or to iso‐
    2117               late problems in the compiler, OpenSSL crypto library, or OpenVPN's crypto code.  Since it  is  a
    2118               self-test mode, problems with encryption and authentication can be debugged independently of net‐
    2119               work and tunnel issues.
     2647              This  option  is  very  useful to test OpenVPN after it has been
     2648              ported to a new platform, or to isolate  problems  in  the  com‐
     2649              piler,  OpenSSL crypto library, or OpenVPN's crypto code.  Since
     2650              it is a self-test mode, problems with encryption and authentica‐
     2651              tion can be debugged independently of network and tunnel issues.
    21202652
    21212653   TLS Mode Options:
    2122        TLS mode is the most powerful crypto mode of OpenVPN in both security and flexibility.  TLS  mode  works
    2123        by  establishing  control  and  data channels which are multiplexed over a single TCP/UDP port.  OpenVPN
    2124        initiates a TLS session over the control channel and uses it to exchange cipher and HMAC keys to protect
    2125        the  data  channel.   TLS  mode  uses a robust reliability layer over the UDP connection for all control
    2126        channel communication, while the data channel, over which encrypted tunnel  data  passes,  is  forwarded
    2127        without  any  mediation.   The result is the best of both worlds: a fast data channel that forwards over
    2128        UDP with only the overhead of encrypt, decrypt, and HMAC functions, and a control channel that  provides
    2129        all  of the security features of TLS, including certificate-based authentication and Diffie Hellman for‐
    2130        ward secrecy.
    2131 
    2132        To use TLS mode, each peer that runs OpenVPN should have its own local certificate/key pair ( --cert and
    2133        --key ), signed by the root certificate which is specified in --ca.
    2134 
    2135        When  two  OpenVPN peers connect, each presents its local certificate to the other.  Each peer will then
    2136        check that its partner peer presented a certificate which was signed by the master root  certificate  as
    2137        specified in --ca.
    2138 
    2139        If  that  check  on  both peers succeeds, then the TLS negotiation will succeed, both OpenVPN peers will
    2140        exchange temporary session keys, and the tunnel will begin passing data.
    2141 
    2142        The OpenVPN distribution contains a set of scripts for managing RSA certificates & keys, located in  the
    2143        easy-rsa subdirectory.
    2144 
    2145        The easy-rsa package is also rendered in web form here: http://openvpn.net/easyrsa.html
     2654       TLS  mode  is the most powerful crypto mode of OpenVPN in both security
     2655       and flexibility.  TLS mode works by establishing control and data chan‐
     2656       nels  which are multiplexed over a single TCP/UDP port.  OpenVPN initi‐
     2657       ates a TLS session over the control channel and  uses  it  to  exchange
     2658       cipher  and  HMAC  keys  to  protect the data channel.  TLS mode uses a
     2659       robust reliability layer over the UDP connection for all control  chan‐
     2660       nel  communication, while the data channel, over which encrypted tunnel
     2661       data passes, is forwarded without any mediation.   The  result  is  the
     2662       best  of  both  worlds: a fast data channel that forwards over UDP with
     2663       only the overhead of encrypt, decrypt, and HMAC functions, and  a  con‐
     2664       trol channel that provides all of the security features of TLS, includ‐
     2665       ing  certificate-based  authentication  and  Diffie   Hellman   forward
     2666       secrecy.
     2667
     2668       To  use TLS mode, each peer that runs OpenVPN should have its own local
     2669       certificate/key pair ( --cert and --key ), signed by the root  certifi‐
     2670       cate which is specified in --ca.
     2671
     2672       When  two OpenVPN peers connect, each presents its local certificate to
     2673       the other.  Each peer will then check that its partner peer presented a
     2674       certificate  which  was signed by the master root certificate as speci‐
     2675       fied in --ca.
     2676
     2677       If that check on both peers succeeds, then  the  TLS  negotiation  will
     2678       succeed,  both  OpenVPN peers will exchange temporary session keys, and
     2679       the tunnel will begin passing data.
     2680
     2681       The OpenVPN distribution contains a set of  scripts  for  managing  RSA
     2682       certificates & keys, located in the easy-rsa subdirectory.
     2683
     2684       The  easy-rsa  package  is also rendered in web form here: http://open‐
     2685       vpn.net/easyrsa.html
    21462686
    21472687       --tls-server
    2148               Enable TLS and assume server role during TLS handshake.  Note that OpenVPN is designed as a peer-
    2149               to-peer application.  The designation of client or server is only for the purpose of  negotiating
    2150               the TLS control channel.
     2688              Enable TLS and assume server role during  TLS  handshake.   Note
     2689              that  OpenVPN  is  designed  as a peer-to-peer application.  The
     2690              designation of client or server is only for the purpose of nego‐
     2691              tiating the TLS control channel.
    21512692
    21522693       --tls-client
     
    21542695
    21552696       --ca file
    2156               Certificate  authority  (CA) file in .pem format, also referred to as the root certificate.  This
    2157               file can have multiple certificates in .pem format, concatenated  together.   You  can  construct
    2158               your own certificate authority certificate and private key by using a command such as:
     2697              Certificate authority (CA) file in .pem format, also referred to
     2698              as the root certificate.  This file can have  multiple  certifi‐
     2699              cates  in .pem format, concatenated together.  You can construct
     2700              your own certificate authority certificate and  private  key  by
     2701              using a command such as:
    21592702
    21602703              openssl req -nodes -new -x509 -keyout ca.key -out ca.crt
    21612704
    2162               Then  edit your openssl.cnf file and edit the certificate variable to point to your new root cer‐
    2163               tificate ca.crt.
    2164 
    2165               For testing purposes only, the OpenVPN distribution includes a sample  CA  certificate  (ca.crt).
    2166               Of  course you should never use the test certificates and test keys distributed with OpenVPN in a
    2167               production environment, since by virtue of the fact that they are distributed with OpenVPN,  they
    2168               are totally insecure.
     2705              Then  edit  your openssl.cnf file and edit the certificate vari‐
     2706              able to point to your new root certificate ca.crt.
     2707
     2708              For testing purposes only, the OpenVPN distribution  includes  a
     2709              sample  CA certificate (ca.crt).  Of course you should never use
     2710              the test certificates and test keys distributed with OpenVPN  in
     2711              a  production environment, since by virtue of the fact that they
     2712              are distributed with OpenVPN, they are totally insecure.
    21692713
    21702714       --capath dir
    2171               Directory  containing  trusted  certificates  (CAs  and CRLs).  Available with OpenSSL version >=
    2172               0.9.7 dev.  Not available with PolarSSL.
     2715              Directory  containing  trusted  certificates  (CAs  and   CRLs).
     2716              Available with OpenSSL version >= 0.9.7 dev.  Not available with
     2717              PolarSSL.
    21732718
    21742719       --dh file
    2175               File containing Diffie Hellman parameters in .pem format (required for --tls-server only). Use
     2720              File  containing  Diffie  Hellman  parameters  in  .pem   format
     2721              (required for --tls-server only). Use
    21762722
    21772723              openssl dhparam -out dh1024.pem 1024
    21782724
    2179               to generate your own, or use the existing dh1024.pem file included with the OpenVPN distribution.
    2180               Diffie Hellman parameters may be considered public.
     2725              to  generate  your  own,  or  use  the  existing dh1024.pem file
     2726              included with the OpenVPN distribution.  Diffie Hellman  parame‐
     2727              ters may be considered public.
    21812728
    21822729       --cert file
    2183               Local peer's signed certificate in .pem format -- must be signed by a certificate authority whose
    2184               certificate is in --ca file.  Each peer in an OpenVPN link running in TLS mode  should  have  its
    2185               own  certificate  and private key file.  In addition, each certificate should have been signed by
    2186               the key of a certificate authority whose public key resides in  the  --ca  certificate  authority
    2187               file.   You can easily make your own certificate authority (see above) or pay money to use a com‐
    2188               mercial service such as thawte.com (in which case you will be helping to finance the world's sec‐
    2189               ond space tourist :).  To generate a certificate, you can use a command such as:
     2730              Local peer's signed certificate in .pem format -- must be signed
     2731              by a certificate authority whose certificate is  in  --ca  file.
     2732              Each peer in an OpenVPN link running in TLS mode should have its
     2733              own certificate and private key file.  In  addition,  each  cer‐
     2734              tificate  should  have  been  signed by the key of a certificate
     2735              authority whose public  key  resides  in  the  --ca  certificate
     2736              authority  file.   You  can  easily  make  your  own certificate
     2737              authority (see above) or pay money to use a  commercial  service
     2738              such as thawte.com (in which case you will be helping to finance
     2739              the world's second space tourist :).  To generate a certificate,
     2740              you can use a command such as:
    21902741
    21912742              openssl req -nodes -new -keyout mycert.key -out mycert.csr
    21922743
    2193               If  your certificate authority private key lives on another machine, copy the certificate signing
    2194               request (mycert.csr) to this other machine (this can be done over an  insecure  channel  such  as
    2195               email).  Now sign the certificate with a command such as:
     2744              If  your  certificate  authority  private  key  lives on another
     2745              machine, copy the certificate signing  request  (mycert.csr)  to
     2746              this  other  machine  (this can be done over an insecure channel
     2747              such as email).  Now sign the certificate with  a  command  such
     2748              as:
    21962749
    21972750              openssl ca -out mycert.crt -in mycert.csr
    21982751
    2199               Now  copy  the  certificate (mycert.crt) back to the peer which initially generated the .csr file
    2200               (this can be over a public medium).  Note that the openssl ca command reads the location  of  the
    2201               certificate  authority key from its configuration file such as /usr/share/ssl/openssl.cnf -- note
    2202               also that for certificate authority functions, you must set up the files index.txt (may be empty)
    2203               and serial (initialize to 01 ).
     2752              Now  copy  the  certificate  (mycert.crt) back to the peer which
     2753              initially generated the .csr file (this can  be  over  a  public
     2754              medium).  Note that the openssl ca command reads the location of
     2755              the certificate authority key from its configuration  file  such
     2756              as  /usr/share/ssl/openssl.cnf -- note also that for certificate
     2757              authority functions, you must set up the files index.txt (may be
     2758              empty) and serial (initialize to 01 ).
    22042759
    22052760       --extra-certs file
    2206               Specify  a  file containing one or more PEM certs (concatenated together) that complete the local
    2207               certificate chain.
    2208 
    2209               This option is useful for "split" CAs, where the CA for server certs is different than the CA for
    2210               client  certs.   Putting certs in this file allows them to be used to complete the local certifi‐
    2211               cate chain without trusting them to verify the peer-submitted certificate, as would be  the  case
    2212               if the certs were placed in the ca file.
     2761              Specify  a  file  containing one or more PEM certs (concatenated
     2762              together) that complete the local certificate chain.
     2763
     2764              This option is useful for "split" CAs, where the CA  for  server
     2765              certs  is different than the CA for client certs.  Putting certs
     2766              in this file allows them to be used to complete the  local  cer‐
     2767              tificate  chain without trusting them to verify the peer-submit‐
     2768              ted certificate, as would be the case if the certs  were  placed
     2769              in the ca file.
    22132770
    22142771       --key file
    2215               Local  peer's private key in .pem format.  Use the private key which was generated when you built
    2216               your peer's certificate (see -cert file above).
     2772              Local  peer's  private  key in .pem format.  Use the private key
     2773              which was generated when you built your peer's certificate  (see
     2774              -cert file above).
    22172775
    22182776       --pkcs12 file
    2219               Specify a PKCS #12 file containing local private key, local certificate, and root CA certificate.
    2220               This option can be used instead of --ca, --cert, and --key.  Not available with PolarSSL.
     2777              Specify a PKCS #12 file containing local private key, local cer‐
     2778              tificate, and root CA certificate.   This  option  can  be  used
     2779              instead   of  --ca,  --cert,  and  --key.   Not  available  with
     2780              PolarSSL.
    22212781
    22222782       --verify-hash hash
    2223               Specify  SHA1  fingerprint  for  level-1 cert.  The level-1 cert is the CA (or intermediate cert)
    2224               that signs the leaf certificate, and is one removed from the leaf certificate in the direction of
    2225               the  root.  When accepting a connection from a peer, the level-1 cert fingerprint must match hash
    2226               or  certificate  verification  will  fail.   Hash  is  specified  as  XX:XX:...    For   example:
     2783              Specify SHA1 fingerprint for level-1 cert.  The level-1 cert  is
     2784              the  CA  (or intermediate cert) that signs the leaf certificate,
     2785              and is one removed from the leaf certificate in the direction of
     2786              the  root.  When accepting a connection from a peer, the level-1
     2787              cert fingerprint must match  hash  or  certificate  verification
     2788              will  fail.   Hash  is  specified  as  XX:XX:...   For  example:
    22272789              AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16
    22282790
    22292791       --pkcs11-cert-private [0|1]...
    2230               Set  if access to certificate object should be performed after login.  Every provider has its own
    2231               setting.
     2792              Set if access to certificate object should  be  performed  after
     2793              login.  Every provider has its own setting.
    22322794
    22332795       --pkcs11-id name
    2234               Specify the serialized certificate id to be used. The id can be gotten by the standalone  --show-
    2235               pkcs11-ids option.
     2796              Specify  the serialized certificate id to be used. The id can be
     2797              gotten by the standalone --show-pkcs11-ids option.
    22362798
    22372799       --pkcs11-id-management
    2238               Acquire  PKCS#11  id from management interface. In this case a NEED-STR 'pkcs11-id-request' real-
    2239               time message will be triggered, application may use pkcs11-id-count command to retrieve available
    2240               number  of  certificates,  and  pkcs11-id-get  command to retrieve certificate id and certificate
    2241               body.
     2800              Acquire PKCS#11 id from management interface.  In  this  case  a
     2801              NEED-STR  'pkcs11-id-request'  real-time  message  will be trig‐
     2802              gered, application may use pkcs11-id-count command  to  retrieve
     2803              available  number  of certificates, and pkcs11-id-get command to
     2804              retrieve certificate id and certificate body.
    22422805
    22432806       --pkcs11-pin-cache seconds
    2244               Specify how many seconds the PIN can be cached, the default is until the token is removed.
     2807              Specify how many seconds the PIN can be cached, the  default  is
     2808              until the token is removed.
    22452809
    22462810       --pkcs11-protected-authentication [0|1]...
    2247               Use PKCS#11 protected authentication path, useful for  biometric  and  external  keypad  devices.
    2248               Every provider has its own setting.
     2811              Use  PKCS#11 protected authentication path, useful for biometric
     2812              and external keypad devices.  Every provider has  its  own  set‐
     2813              ting.
    22492814
    22502815       --pkcs11-providers provider...
    2251               Specify  a RSA Security Inc. PKCS #11 Cryptographic Token Interface (Cryptoki) providers to load.
    2252               This option can be used instead of --cert, --key, and --pkcs12.
     2816              Specify  a RSA Security Inc. PKCS #11 Cryptographic Token Inter‐
     2817              face (Cryptoki) providers to load.   This  option  can  be  used
     2818              instead of --cert, --key, and --pkcs12.
    22532819
    22542820       --pkcs11-private-mode mode...
    2255               Specify which method to use in order to perform private key operations.  A different mode can  be
    2256               specified for each provider.  Mode is encoded as hex number, and can be a mask one of the follow‐
    2257               ing:
     2821              Specify  which  method  to  use  in order to perform private key
     2822              operations.   A  different  mode  can  be  specified  for   each
     2823              provider.   Mode is encoded as hex number, and can be a mask one
     2824              of the following:
    22582825
    22592826              0 (default) -- Try to determind automatically.
     
    22642831
    22652832       --cryptoapicert select-string
    2266               Load the certificate and private key from the Windows Certificate System  Store  (Windows/OpenSSL
    2267               Only).
     2833              Load the certificate and private key from the  Windows  Certifi‐
     2834              cate System Store (Windows/OpenSSL Only).
    22682835
    22692836              Use this option instead of --cert and --key.
    22702837
    2271               This makes it possible to use any smart card, supported by Windows, but also any kind of certifi‐
    2272               cate, residing in the Cert Store, where you have access to the private key.  This option has been
    2273               tested  with a couple of different smart cards (GemSAFE, Cryptoflex, and Swedish Post Office eID)
    2274               on the client side, and also an imported PKCS12 software certificate on the server side.
    2275 
    2276               To select a certificate, based on a substring search in the certificate's subject:
     2838              This  makes it possible to use any smart card, supported by Win‐
     2839              dows, but also any kind of certificate,  residing  in  the  Cert
     2840              Store,  where  you  have access to the private key.  This option
     2841              has been tested with a couple of different smart cards (GemSAFE,
     2842              Cryptoflex, and Swedish Post Office eID) on the client side, and
     2843              also an imported PKCS12 software certificate on the server side.
     2844
     2845              To select a certificate, based on a substring search in the cer‐
     2846              tificate's subject:
    22772847
    22782848              cryptoapicert "SUBJ:Peter Runestig"
     
    22822852              cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."
    22832853
    2284               The thumbprint hex string can easily be copy-and-pasted from the Windows Certificate Store GUI.
     2854              The thumbprint hex string can easily be copy-and-pasted from the
     2855              Windows Certificate Store GUI.
    22852856
    22862857
    22872858       --key-method m
    2288               Use data channel key negotiation method m.  The key method must match on both sides of  the  con‐
    2289               nection.
    2290 
    2291               After  OpenVPN negotiates a TLS session, a new set of keys for protecting the tunnel data channel
    2292               is generated and exchanged over the TLS session.
    2293 
    2294               In method 1 (the default for OpenVPN 1.x), both sides generate random encrypt and HMAC-send  keys
    2295               which are forwarded to the other host over the TLS channel.
    2296 
    2297               In  method  2,  (the default for OpenVPN 2.0) the client generates a random key.  Both client and
    2298               server also generate some random seed material.  All key source material is  exchanged  over  the
    2299               TLS channel. The actual keys are generated using the TLS PRF function, taking source entropy from
    2300               both client and server.  Method 2 is designed to closely parallel the key generation process used
    2301               by TLS 1.0.
     2859              Use data channel key negotiation method m.  The key method  must
     2860              match on both sides of the connection.
     2861
     2862              After  OpenVPN  negotiates  a TLS session, a new set of keys for
     2863              protecting the tunnel data channel is  generated  and  exchanged
     2864              over the TLS session.
     2865
     2866              In  method  1 (the default for OpenVPN 1.x), both sides generate
     2867              random encrypt and HMAC-send keys which  are  forwarded  to  the
     2868              other host over the TLS channel.
     2869
     2870              In  method 2, (the default for OpenVPN 2.0) the client generates
     2871              a random key.  Both client and server also generate some  random
     2872              seed  material.   All  key source material is exchanged over the
     2873              TLS channel. The actual keys are generated  using  the  TLS  PRF
     2874              function,  taking  source  entropy  from both client and server.
     2875              Method 2 is designed to  closely  parallel  the  key  generation
     2876              process used by TLS 1.0.
    23022877
    23032878              Note that in TLS mode, two separate levels of keying occur:
    23042879
    2305               (1)  The TLS connection is initially negotiated, with both sides of the connection producing cer‐
    2306               tificates and verifying the certificate (or other authentication  info  provided)  of  the  other
     2880              (1)  The TLS connection is initially negotiated, with both sides
     2881              of the connection producing certificates and verifying the  cer‐
     2882              tificate  (or  other  authentication info provided) of the other
    23072883              side.  The --key-method parameter has no effect on this process.
    23082884
    2309               (2)  After  the  TLS connection is established, the tunnel session keys are separately negotiated
    2310               over the existing secure TLS channel.  Here, --key-method determines the derivation of the tunnel
    2311               session keys.
     2885              (2) After the TLS connection is established, the tunnel  session
     2886              keys  are  separately  negotiated  over  the existing secure TLS
     2887              channel.  Here, --key-method determines the  derivation  of  the
     2888              tunnel session keys.
    23122889
    23132890       --tls-cipher l
    2314               A  list  l  of  allowable TLS ciphers delimited by a colon (":").  If you require a high level of
    2315               security, you may want to set this parameter manually, to prevent a version rollback attack where
    2316               a  man-in-the-middle  attacker tries to force two peers to negotiate to the lowest level of secu‐
    2317               rity they both support.  Use --show-tls to see a list of supported TLS ciphers.
     2891              A  list  l  of allowable TLS ciphers delimited by a colon (":").
     2892              If you require a high level of security, you  may  want  to  set
     2893              this  parameter  manually,  to prevent a version rollback attack
     2894              where a man-in-the-middle attacker tries to force two  peers  to
     2895              negotiate  to  the  lowest  level of security they both support.
     2896              Use --show-tls to see a list of supported TLS ciphers.
    23182897
    23192898       --tls-timeout n
    2320               Packet retransmit timeout on TLS control channel if no acknowledgment from remote within  n  sec‐
    2321               onds  (default=2).  When OpenVPN sends a control packet to its peer, it will expect to receive an
    2322               acknowledgement within n seconds or it will retransmit the packet, subject to a TCP-like exponen‐
    2323               tial  backoff  algorithm.   This parameter only applies to control channel packets.  Data channel
    2324               packets (which carry encrypted tunnel data) are never acknowledged, sequenced,  or  retransmitted
    2325               by  OpenVPN  because  the higher level network protocols running on top of the tunnel such as TCP
    2326               expect this role to be left to them.
     2899              Packet retransmit timeout on TLS control channel if no  acknowl‐
     2900              edgment  from remote within n seconds (default=2).  When OpenVPN
     2901              sends a control packet to its peer, it will expect to receive an
     2902              acknowledgement  within  n  seconds  or  it  will retransmit the
     2903              packet, subject to a  TCP-like  exponential  backoff  algorithm.
     2904              This  parameter  only  applies to control channel packets.  Data
     2905              channel packets (which carry encrypted tunnel  data)  are  never
     2906              acknowledged, sequenced, or retransmitted by OpenVPN because the
     2907              higher level network protocols running on top of the tunnel such
     2908              as TCP expect this role to be left to them.
    23272909
    23282910       --reneg-bytes n
    2329               Renegotiate data channel key after n bytes sent  or  received  (disabled  by  default).   OpenVPN
    2330               allows  the  lifetime of a key to be expressed as a number of bytes encrypted/decrypted, a number
    2331               of packets, or a number of seconds.  A key renegotiation will be forced if  any  of  these  three
    2332               criteria are met by either peer.
     2911              Renegotiate  data  channel  key  after  n bytes sent or received
     2912              (disabled by default).  OpenVPN allows the lifetime of a key  to
     2913              be  expressed as a number of bytes encrypted/decrypted, a number
     2914              of packets, or a number of seconds.  A key renegotiation will be
     2915              forced if any of these three criteria are met by either peer.
    23332916
    23342917       --reneg-pkts n
    2335               Renegotiate data channel key after n packets sent and received (disabled by default).
     2918              Renegotiate  data  channel key after n packets sent and received
     2919              (disabled by default).
    23362920
    23372921       --reneg-sec n
    23382922              Renegotiate data channel key after n seconds (default=3600).
    23392923
    2340               When  using dual-factor authentication, note that this default value may cause the end user to be
    2341               challenged to reauthorize once per hour.
    2342 
    2343               Also, keep in mind that this option can be used on both the client and server, and whichever uses
    2344               the  lower  value  will  be  the  one  to  trigger the renegotiation.  A common mistake is to set
    2345               --reneg-sec to a higher value on either the client or server, while the other side of the connec‐
    2346               tion  is still using the default value of 3600 seconds, meaning that the renegotiation will still
    2347               occur once per 3600 seconds.  The solution is to increase --reneg-sec  on  both  the  client  and
    2348               server,  or  set  it to 0 on one side of the connection (to disable), and to your chosen value on
    2349               the other side.
     2924              When using dual-factor authentication, note  that  this  default
     2925              value  may  cause  the  end user to be challenged to reauthorize
     2926              once per hour.
     2927
     2928              Also, keep in mind that this option can  be  used  on  both  the
     2929              client  and  server,  and whichever uses the lower value will be
     2930              the one to trigger the renegotiation.  A common  mistake  is  to
     2931              set  --reneg-sec  to  a  higher  value  on  either the client or
     2932              server, while the other side of the connection  is  still  using
     2933              the  default  value of 3600 seconds, meaning that the renegotia‐
     2934              tion will still occur once per 3600 seconds.  The solution is to
     2935              increase --reneg-sec on both the client and server, or set it to
     2936              0 on one side of the connection (to disable), and to your chosen
     2937              value on the other side.
    23502938
    23512939       --hand-window n
    2352               Handshake Window -- the TLS-based key exchange must finalize within n seconds of handshake initi‐
    2353               ation  by  any  peer (default = 60 seconds).  If the handshake fails we will attempt to reset our
    2354               connection with our peer and try again.  Even in the event of handshake failure we will still use
    2355               our expiring key for up to --tran-window seconds to maintain continuity of transmission of tunnel
    2356               data.
     2940              Handshake  Window  --  the  TLS-based key exchange must finalize
     2941              within n seconds of handshake initiation by any peer (default  =
     2942              60  seconds).   If  the handshake fails we will attempt to reset
     2943              our connection with our peer and try again.  Even in  the  event
     2944              of  handshake  failure we will still use our expiring key for up
     2945              to --tran-window seconds to maintain continuity of  transmission
     2946              of tunnel data.
    23572947
    23582948       --tran-window n
    2359               Transition window -- our old key can live this many seconds  after  a  new  a  key  renegotiation
    2360               begins  (default  = 3600 seconds).  This feature allows for a graceful transition from old to new
    2361               key, and removes the key renegotiation sequence from the critical path of tunnel data forwarding.
     2949              Transition  window  --  our  old  key can live this many seconds
     2950              after a new a key renegotiation begins (default = 3600 seconds).
     2951              This  feature  allows  for a graceful transition from old to new
     2952              key, and removes the key renegotiation sequence from the  criti‐
     2953              cal path of tunnel data forwarding.
    23622954
    23632955       --single-session
    2364               After initially connecting to a remote peer, disallow any new  connections.   Using  this  option
    2365               means that a remote peer cannot connect, disconnect, and then reconnect.
    2366 
    2367               If the daemon is reset by a signal or --ping-restart, it will allow one new connection.
    2368 
    2369               --single-session  can  be  used with --ping-exit or --inactive to create a single dynamic session
    2370               that will exit when finished.
     2956              After  initially  connecting  to a remote peer, disallow any new
     2957              connections.  Using this option means that a remote peer  cannot
     2958              connect, disconnect, and then reconnect.
     2959
     2960              If  the  daemon  is reset by a signal or --ping-restart, it will
     2961              allow one new connection.
     2962
     2963              --single-session can be used with --ping-exit or  --inactive  to
     2964              create a single dynamic session that will exit when finished.
    23712965
    23722966       --tls-exit
     
    23742968
    23752969       --tls-auth file [direction]
    2376               Add an additional layer of HMAC authentication on top of  the  TLS  control  channel  to  protect
    2377               against DoS attacks.
    2378 
    2379               In  a nutshell, --tls-auth enables a kind of "HMAC firewall" on OpenVPN's TCP/UDP port, where TLS
    2380               control channel packets bearing an incorrect HMAC signature can be  dropped  immediately  without
    2381               response.
    2382 
    2383               file (required) is a key file which can be in one of two formats:
    2384 
    2385               (1) An OpenVPN static key file generated by --genkey (required if direction parameter is used).
    2386 
    2387               (2)  A  freeform  passphrase  file.  In this case the HMAC key will be derived by taking a secure
    2388               hash of this file, similar to the md5sum(1) or sha1sum(1) commands.
    2389 
    2390               OpenVPN will first try format (1), and if the file fails to parse as a static  key  file,  format
    2391               (2) will be used.
    2392 
    2393               See the --secret option for more information on the optional direction parameter.
    2394 
    2395               --tls-auth  is recommended when you are running OpenVPN in a mode where it is listening for pack‐
    2396               ets from any IP address, such as when --remote is not specified, or --remote  is  specified  with
     2970              Add an additional layer of HMAC authentication on top of the TLS
     2971              control channel to protect against DoS attacks.
     2972
     2973              In a nutshell, --tls-auth enables a kind of "HMAC  firewall"  on
     2974              OpenVPN's  TCP/UDP port, where TLS control channel packets bear‐
     2975              ing an incorrect HMAC signature can be dropped immediately with‐
     2976              out response.
     2977
     2978              file  (required)  is  a key file which can be in one of two for‐
     2979              mats:
     2980
     2981              (1) An OpenVPN static key file generated by  --genkey  (required
     2982              if direction parameter is used).
     2983
     2984              (2)  A freeform passphrase file.  In this case the HMAC key will
     2985              be derived by taking a secure hash of this file, similar to  the
     2986              md5sum(1) or sha1sum(1) commands.
     2987
     2988              OpenVPN  will  first  try  format  (1), and if the file fails to
     2989              parse as a static key file, format (2) will be used.
     2990
     2991              See the --secret option for more  information  on  the  optional
     2992              direction parameter.
     2993
     2994              --tls-auth is recommended when you are running OpenVPN in a mode
     2995              where it is listening for packets from any IP address,  such  as
     2996              when  --remote  is  not specified, or --remote is specified with
    23972997              --float.
    23982998
    2399               The  rationale for this feature is as follows.  TLS requires a multi-packet exchange before it is
    2400               able to authenticate a peer.  During this  time  before  authentication,  OpenVPN  is  allocating
    2401               resources  (memory  and  CPU)  to  this potential peer.  The potential peer is also exposing many
    2402               parts of OpenVPN and the OpenSSL library to the packets it is sending.  Most  successful  network
    2403               attacks  today seek to either exploit bugs in programs (such as buffer overflow attacks) or force
    2404               a program to consume so many resources that it becomes unusable.  Of course  the  first  line  of
    2405               defense  is  always  to  produce  clean, well-audited code.  OpenVPN has been written with buffer
    2406               overflow attack prevention as a top priority.  But as history has shown, many of the most  widely
    2407               used network applications have, from time to time, fallen to buffer overflow attacks.
    2408 
    2409               So as a second line of defense, OpenVPN offers this special layer of authentication on top of the
    2410               TLS control channel so that every packet on the control channel is authenticated by an HMAC  sig‐
    2411               nature  and a unique ID for replay protection.  This signature will also help protect against DoS
    2412               (Denial of Service) attacks.  An important rule of thumb in reducing vulnerability to DoS attacks
    2413               is to minimize the amount of resources a potential, but as yet unauthenticated, client is able to
    2414               consume.
    2415 
    2416               --tls-auth does this by signing every TLS control channel packet with an HMAC signature,  includ‐
    2417               ing  packets  which are sent before the TLS level has had a chance to authenticate the peer.  The
    2418               result is that packets without the correct signature can be dropped immediately  upon  reception,
    2419               before  they  have  a  chance  to consume additional system resources such as by initiating a TLS
    2420               handshake.  --tls-auth can be strengthened by adding the --replay-persist option which will  keep
    2421               OpenVPN's replay protection state in a file so that it is not lost across restarts.
    2422 
    2423               It  should be emphasized that this feature is optional and that the passphrase/key file used with
    2424               --tls-auth gives a peer nothing more than the power to initiate a TLS handshake.  It is not  used
    2425               to encrypt or authenticate any tunnel data.
     2999              The rationale for this feature is as follows.   TLS  requires  a
     3000              multi-packet  exchange before it is able to authenticate a peer.
     3001              During this time before authentication,  OpenVPN  is  allocating
     3002              resources  (memory  and CPU) to this potential peer.  The poten‐
     3003              tial peer is also exposing many parts of OpenVPN and the OpenSSL
     3004              library  to  the packets it is sending.  Most successful network
     3005              attacks today seek to either exploit bugs in programs  (such  as
     3006              buffer  overflow  attacks) or force a program to consume so many
     3007              resources that it becomes unusable.  Of course the first line of
     3008              defense  is always to produce clean, well-audited code.  OpenVPN
     3009              has been written with buffer overflow attack prevention as a top
     3010              priority.   But  as  history  has shown, many of the most widely
     3011              used network applications have, from time  to  time,  fallen  to
     3012              buffer overflow attacks.
     3013
     3014              So  as  a  second  line  of defense, OpenVPN offers this special
     3015              layer of authentication on top of the  TLS  control  channel  so
     3016              that  every packet on the control channel is authenticated by an
     3017              HMAC signature and a unique ID for replay protection.  This sig‐
     3018              nature  will  also  help protect against DoS (Denial of Service)
     3019              attacks.  An important rule of thumb in  reducing  vulnerability
     3020              to  DoS  attacks is to minimize the amount of resources a poten‐
     3021              tial, but as yet unauthenticated, client is able to consume.
     3022
     3023              --tls-auth does this by signing every TLS control channel packet
     3024              with  an HMAC signature, including packets which are sent before
     3025              the TLS level has had a chance to authenticate  the  peer.   The
     3026              result  is  that  packets  without  the correct signature can be
     3027              dropped immediately upon reception, before they have a chance to
     3028              consume  additional system resources such as by initiating a TLS
     3029              handshake.   --tls-auth  can  be  strengthened  by  adding   the
     3030              --replay-persist option which will keep OpenVPN's replay protec‐
     3031              tion state in a file so that it is not lost across restarts.
     3032
     3033              It should be emphasized that this feature is optional  and  that
     3034              the  passphrase/key file used with --tls-auth gives a peer noth‐
     3035              ing more than the power to initiate a TLS handshake.  It is  not
     3036              used to encrypt or authenticate any tunnel data.
    24263037
    24273038       --askpass [file]
    2428               Get certificate password from console or file before we daemonize.
    2429 
    2430               For the extremely security conscious, it is possible to protect your private key with a password.
    2431               Of course this means that every time the OpenVPN daemon is started you must be there to type  the
    2432               password.  The --askpass option allows you to start OpenVPN from the command line.  It will query
    2433               you for a password before it daemonizes.  To protect a private key with  a  password  you  should
    2434               omit the -nodes option when you use the openssl command line tool to manage certificates and pri‐
    2435               vate keys.
    2436 
    2437               If file is specified, read the password from the first line of file.  Keep in mind  that  storing
    2438               your  password  in a file to a certain extent invalidates the extra security provided by using an
    2439               encrypted key (Note: OpenVPN will only read passwords from a file if it has been built  with  the
    2440               --enable-password-save  configure  option,  or  on  Windows  by  defining ENABLE_PASSWORD_SAVE in
     3039              Get  certificate  password from console or file before we daemo‐
     3040              nize.
     3041
     3042              For the extremely security conscious, it is possible to  protect
     3043              your  private  key  with  a password.  Of course this means that
     3044              every time the OpenVPN daemon is started you must  be  there  to
     3045              type  the  password.   The  --askpass option allows you to start
     3046              OpenVPN from the command line.  It will query you for a password
     3047              before  it daemonizes.  To protect a private key with a password
     3048              you should omit the -nodes option when you use the openssl  com‐
     3049              mand line tool to manage certificates and private keys.
     3050
     3051              If  file  is specified, read the password from the first line of
     3052              file.  Keep in mind that storing your password in a  file  to  a
     3053              certain  extent invalidates the extra security provided by using
     3054              an encrypted key (Note: OpenVPN will only read passwords from  a
     3055              file  if  it has been built with the --enable-password-save con‐
     3056              figure option, or on Windows by defining ENABLE_PASSWORD_SAVE in
    24413057              win/settings.in).
    24423058
    24433059       --auth-nocache
    2444               Don't cache --askpass or --auth-user-pass username/passwords in virtual memory.
    2445 
    2446               If specified, this directive will cause OpenVPN to immediately  forget  username/password  inputs
    2447               after  they  are  used.   As a result, when OpenVPN needs a username/password, it will prompt for
    2448               input from stdin, which may be multiple times during the duration of an OpenVPN session.
    2449 
    2450               This directive does not affect the --http-proxy username/password.  It is always cached.
     3060              Don't  cache --askpass or --auth-user-pass username/passwords in
     3061              virtual memory.
     3062
     3063              If specified, this directive will cause OpenVPN  to  immediately
     3064              forget  username/password  inputs  after  they  are  used.  As a
     3065              result, when OpenVPN needs a username/password, it  will  prompt
     3066              for  input  from  stdin,  which may be multiple times during the
     3067              duration of an OpenVPN session.
     3068
     3069              This directive does not affect the  --http-proxy  username/pass‐
     3070              word.  It is always cached.
    24513071
    24523072       --tls-verify cmd
    2453               Run command cmd to verify the X509 name of a pending TLS connection that has otherwise passed all
    2454               other  tests  of  certification (except for revocation via --crl-verify directive; the revocation
    2455               test occurs after the --tls-verify test).
    2456 
    2457               cmd should return 0 to allow the TLS handshake to proceed, or 1 to fail.
    2458 
    2459               cmd consists of a path to script (or executable program), optionally followed by  arguments.  The
    2460               path  and  arguments may be single- or double-quoted and/or escaped using a backslash, and should
    2461               be separated by one or more spaces.
    2462 
    2463               When cmd is executed two arguments are appended after any arguments specified in cmd  ,  as  fol‐
    2464               lows:
     3073              Run command cmd to verify the X509 name of a pending TLS connec‐
     3074              tion that has otherwise passed all other tests of  certification
     3075              (except  for  revocation via --crl-verify directive; the revoca‐
     3076              tion test occurs after the --tls-verify test).
     3077
     3078              cmd should return 0 to allow the TLS handshake to proceed, or  1
     3079              to fail.
     3080
     3081              cmd  consists  of  a  path  to  script  (or executable program),
     3082              optionally followed by arguments. The path and arguments may  be
     3083              single-  or  double-quoted and/or escaped using a backslash, and
     3084              should be separated by one or more spaces.
     3085
     3086              When cmd is executed two arguments are appended after any  argu‐
     3087              ments specified in cmd , as follows:
    24653088
    24663089              cmd certificate_depth subject
    24673090
    2468               These arguments are, respectively, the current certificate depth and the X509 common name (cn) of
    2469               the peer.
    2470 
    2471               This feature is useful if the peer you want to trust has a certificate which was signed by a cer‐
    2472               tificate  authority  who also signed many other certificates, where you don't necessarily want to
    2473               trust all of them, but rather be selective about which peer certificate you  will  accept.   This
    2474               feature  allows  you  to write a script which will test the X509 name on a certificate and decide
    2475               whether or not it should be accepted.  For a simple perl script which will test the  common  name
    2476               field on the certificate, see the file verify-cn in the OpenVPN distribution.
    2477 
    2478               See the "Environmental Variables" section below for additional parameters passed as environmental
    2479               variables.
     3091              These arguments are, respectively, the current certificate depth
     3092              and the X509 common name (cn) of the peer.
     3093
     3094              This feature is useful if the peer you want to trust has a  cer‐
     3095              tificate  which  was  signed by a certificate authority who also
     3096              signed many other certificates, where you don't necessarily want
     3097              to  trust  all of them, but rather be selective about which peer
     3098              certificate you will accept.  This feature allows you to write a
     3099              script which will test the X509 name on a certificate and decide
     3100              whether or not it should be accepted.  For a simple perl  script
     3101              which  will  test  the common name field on the certificate, see
     3102              the file verify-cn in the OpenVPN distribution.
     3103
     3104              See the "Environmental Variables" section below  for  additional
     3105              parameters passed as environmental variables.
    24803106
    24813107       --tls-export-cert directory
    2482               Store the certificates the clients uses upon connection to this  directory.  This  will  be  done
    2483               before  --tls-verify  is  called.  The certificates will use a temporary name and will be deleted
    2484               when the tls-verify script returns.  The file name used for the certificate is available via  the
    2485               peer_cert environment variable.
     3108              Store  the certificates the clients uses upon connection to this
     3109              directory. This will be done before --tls-verify is called.  The
     3110              certificates  will use a temporary name and will be deleted when
     3111              the tls-verify script returns.  The file name used for the  cer‐
     3112              tificate is available via the peer_cert environment variable.
    24863113
    24873114       --x509-username-field fieldname
    2488               Field  in x509 certificate subject to be used as username (default=CN).  Fieldname will be upper‐
    2489               cased before matching. When this option is used, the --tls-remote option will match  against  the
    2490               chosen fieldname instead of the CN.
     3115              Field  in  x509  certificate  subject  to  be  used  as username
     3116              (default=CN).  Fieldname will  be  uppercased  before  matching.
     3117              When  this  option  is  used, the --tls-remote option will match
     3118              against the chosen fieldname instead of the CN.
    24913119
    24923120       --tls-remote name
    2493               Accept connections only from a host with X509 name or common name equal to name.  The remote host
    2494               must also pass all other tests of verification.
    2495 
    2496               NOTE: Because tls-remote may test against a common name prefix, only use this option when you are
    2497               using  OpenVPN  with  a  custom CA certificate that is under your control.  Never use this option
    2498               when your client certificates are signed by a third party, such as a commercial web CA.
    2499 
    2500               Name can also be a common name prefix, for example if you want a client to  only  accept  connec‐
    2501               tions to "Server-1", "Server-2", etc., you can simply use --tls-remote Server
    2502 
    2503               Using  a  common  name  prefix  is a useful alternative to managing a CRL (Certificate Revocation
    2504               List) on the client, since it allows the client to refuse all certificates except for those asso‐
    2505               ciated with designated servers.
    2506 
    2507               --tls-remote  is  a  useful  replacement  for  the --tls-verify option to verify the remote host,
    2508               because --tls-remote works in a --chroot environment too.
     3121              Accept connections only from a host with  X509  name  or  common
     3122              name  equal  to  name.  The remote host must also pass all other
     3123              tests of verification.
     3124
     3125              NOTE: Because tls-remote may test against a common name  prefix,
     3126              only use this option when you are using OpenVPN with a custom CA
     3127              certificate that is under your control.  Never use  this  option
     3128              when  your client certificates are signed by a third party, such
     3129              as a commercial web CA.
     3130
     3131              Name can also be a common name prefix, for example if you want a
     3132              client  to  only  accept  connections to "Server-1", "Server-2",
     3133              etc., you can simply use --tls-remote Server
     3134
     3135              Using a common name prefix is a useful alternative to managing a
     3136              CRL (Certificate Revocation List) on the client, since it allows
     3137              the client to refuse all certificates except for  those  associ‐
     3138              ated with designated servers.
     3139
     3140              --tls-remote is a useful replacement for the --tls-verify option
     3141              to verify the remote  host,  because  --tls-remote  works  in  a
     3142              --chroot environment too.
    25093143
    25103144       --x509-track attribute
    2511               Save peer X509 attribute value in environment  for  use  by  plugins  and  management  interface.
    2512               Prepend  a  '+'  to  attribute  to  save  values from full cert chain.  Values will be encoded as
    2513               X509_<depth>_<attribute>=<value>.  Multiple --x509-track options can be defined to track multiple
    2514               attributes.  Not available with PolarSSL.
     3145              Save peer X509 attribute value in environment for use by plugins
     3146              and management interface.  Prepend a '+' to  attribute  to  save
     3147              values  from  full  cert  chain.   Values  will  be  encoded  as
     3148              X509_<depth>_<attribute>=<value>.  Multiple --x509-track options
     3149              can be defined to track multiple attributes.  Not available with
     3150              PolarSSL.
    25153151
    25163152       --ns-cert-type client|server
    2517               Require  that  peer certificate was signed with an explicit nsCertType designation of "client" or
     3153              Require that  peer  certificate  was  signed  with  an  explicit
     3154              nsCertType designation of "client" or "server".
     3155
     3156              This is a useful security option for clients, to ensure that the
     3157              host they connect with is a designated server.
     3158
     3159              See the easy-rsa/build-key-server script for an example  of  how
     3160              to  generate  a  certificate  with  the  nsCertType field set to
    25183161              "server".
    25193162
    2520               This is a useful security option for clients, to ensure that the host they connect with is a des‐
    2521               ignated server.
    2522 
    2523               See the easy-rsa/build-key-server script for an example of how to generate a certificate with the
    2524               nsCertType field set to "server".
    2525 
    2526               If the server certificate's nsCertType field is set to "server", then the clients can verify this
    2527