Changes between Version 5 and Version 6 of Openvpn23ManPage


Ignore:
Timestamp:
03/28/13 10:02:11 (8 years ago)
Author:
Samuli Seppänen
Comment:

Updated to man-page from OpenVPN 2.3.1

Legend:

Unmodified
Added
Removed
Modified
  • Openvpn23ManPage

    v5 v6  
    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
    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.
     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 OpenVPN,
     18       you might want to skip ahead to the examples section where  you  will  see
     19       how  to  construct  simple VPNs on the command line without even needing a
     20       configuration file.
     21
     22       Also note that there's more documentation and examples on the OpenVPN  web
     23       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 any
     27       parameters.
    2828
    2929DESCRIPTION
    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.
     30       OpenVPN  is  a  robust  and  highly flexible VPN daemon.  OpenVPN supports
     31       SSL/TLS security, ethernet bridging, TCP or UDP tunnel  transport  through
     32       proxies  or NAT, support for dynamic IP addresses and DHCP, scalability to
     33       hundreds or thousands of users, and portability to  most  major  OS  plat‐
     34       forms.
     35
     36       OpenVPN  is  tightly bound to the OpenSSL library, and derives much of its
     37       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 tunnels.
     42
     43       OpenVPN is designed to work with the TUN/TAP virtual networking  interface
     44       that exists on most platforms.
     45
     46       Overall,  OpenVPN aims to offer many of the key features of IPSec but with
     47       a relatively lightweight footprint.
    4948
    5049OPTIONS
    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.
     50       OpenVPN allows any option to be placed either on the command line or in  a
     51       configuration  file.   Though  all  command line options are preceded by a
     52       double-leading-dash ("--"), this prefix can be removed when an  option  is
     53       placed in a configuration file.
    5554
    5655       --help Show options.
    5756
    5857       --config file
    59               Load additional config options from file where each line corre‐
    60               sponds  to  one  command  line option, but with the leading '--'
     58              Load  additional  config  options  from file where each line corre‐
     59              sponds to one command  line  option,  but  with  the  leading '--'
    6160              removed.
    6261
    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
     62              If  --config  file  is  the only option to the openvpn command, the
     63              --config can be removed, and the command can be  given  as openvpn
    6564              file
    6665
    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‐
    73               ments.
    74 
    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:
     66              Note that configuration files can be nested to a reasonable depth.
     67
     68              Double  quotation  or  single  quotation characters ("", '') can be
     69              used to enclose single parameters containing whitespace, and "#" or
     70              ";" characters in the first column can be used to denote comments.
     71
     72              Note  that  OpenVPN  2.0  and higher performs backslash-based shell
     73              escaping for characters not in single quotations, so the  following
     74              mappings should be observed:
    7875
    7976                  \\       Maps to a single backslash character (\).
     
    8380                           interpret it as a parameter delimiter.
    8481
    85               For example on Windows,  use  double  backslashes  to  represent
    86               pathnames:
     82              For  example  on Windows, use double backslashes to represent path‐
     83              names:
    8784
    8885                  secret "c:\\OpenVPN\\secret.key"
    8986
    90               For   examples   of   configuration   files,   see  http://open
    91               vpn.net/examples.html
     87              For examples of configuration files,  see  http://openvpn.net/exam
     88              ples.html
    9289
    9390              Here is an example configuration file:
     
    114111   Tunnel Options:
    115112       --mode m
    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.
     113              Set OpenVPN major mode.  By default, OpenVPN runs in point-to-point
     114              mode ("p2p").  OpenVPN 2.0 introduces a new mode  ("server")  which
     115              implements a multi-client server capability.
    119116
    120117       --local host
    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.
     118              Local host name or IP address for bind.  If specified, OpenVPN will
     119              bind to this address only.  If unspecified, OpenVPN  will  bind  to
     120              all interfaces.
    124121
    125122       --remote host [port] [proto]
    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
     123              Remote  host  name or IP address.  On the client, multiple --remote
     124              options may be specified for redundancy, each referring to  a  dif‐
     125              ferent  OpenVPN  server.   Specifying multiple --remote options for
     126              this purpose is a special case of the more general  connection-pro‐
     127              file feature.  See the <connection> documentation below.
     128
     129              The  OpenVPN client will try to connect to a server at host:port in
     130              the order specified by the list of --remote options.
     131
     132              proto indicates the  protocol  to  use  when  connecting  with  the
    137133              remote, and may be "tcp" or "udp".
    138134
    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
     135              The  client will move on to the next host in the list, in the event
     136              of connection failure.  Note that at any given  time,  the  OpenVPN
     137              client will at most be connected to one server.
     138
     139              Note  that  since  UDP  is  connectionless,  connection failure is
    144140              defined by the --ping and --ping-restart options.
    145141
    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
     142              Note the following corner  case:   If  you  use  multiple  --remote
     143              options,  AND  you  are dropping root privileges on the client with
     144              --user and/or --group, AND the client is running a non-Windows  OS,
     145              if  the  client  needs  to  switch  to a different server, and that
     146              server pushes back different TUN/TAP or route settings, the  client
     147              may  lack  the necessary privileges to close and reopen the TUN/TAP
     148              interface.  This could cause the client to exit with a fatal error.
     149
     150              If --remote is unspecified, OpenVPN will listen  for  packets  from
     151              any  IP address, but will not act on those packets unless they pass
     152              all authentication tests.  This requirement for  authentication  is
     153              binding  on  all potential peers, even those from known and suppos‐
     154              edly trusted IP addresses (it is very easy to  forge  a  source  IP
     155              address on a UDP packet).
     156
     157              When  used  in  TCP  mode, --remote will act as a filter, rejecting
    163158              connections from any host which does not match host.
    164159
    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.
     160              If host is a DNS name which resolves to multiple IP addresses,  one
     161              will  be  randomly chosen, providing a sort of basic load-balancing
     162              and failover capability.
    168163
    169164       --remote-random-hostname
    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".
     165              Add a random string (6 characters) to first DNS label  of  hostname
     166              to  prevent DNS caching.  For example, "foo.bar.gov" would be modi‐
     167              fied to "<random-chars>.foo.bar.gov".
    173168
    174169       <connection>
    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
     170              Define a client connection profile.  Client connection profiles are
     171              groups  of  OpenVPN options that describe how to connect to a given
     172              OpenVPN server.  Client connection profiles are specified within an
     173              OpenVPN  configuration file, and each profile is bracketed by <con
     174              nection> and </connection>.
     175
     176              An OpenVPN client will try  each  connection  profile sequentially
    182177              until it achieves a successful connection.
    183178
    184               --remote-random can be used to initially "scramble" the  connec‐
    185               tion list.
     179              --remote-random  can be used to initially "scramble" the connection
     180              list.
    186181
    187182              Here is an example of connection profile usage:
     
    216211                  verb 3
    217212
    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
     213              First we try to connect to a server at 198.19.34.56:1194 using UDP.
     214              If  that  fails,  we  then try to connect to 198.19.34.56:443 using
     215              TCP.  If that also fails, then try connecting through an HTTP proxy
     216              at 192.168.0.8:8080 to 198.19.34.56:443 using TCP.  Finally, try to
     217              connect through the same proxy  to  a  server  at  198.19.36.99:443
     218              using TCP.
     219
     220              The  following OpenVPN options may be used inside of a <connection>
     221              block:
     222
     223              bind, connect-retry, connect-retry-max, connect-timeout,  explicit-
     224              exit-notify,  float, fragment, http-proxy, http-proxy-option, http-
     225              proxy-retry, http-proxy-timeout, link-mtu,  local,  lport,  mssfix,
     226              mtu-disc,  nobind,  port, proto, remote, rport, socks-proxy, socks-
     227              proxy-retry, tun-mtu and tun-mtu-extra.
     228
     229              A defaulting mechanism exists for specifying options  to  apply  to
     230              all  <connection>  profiles.  If any of the above options (with the
     231              exception of remote ) appear outside of a <connection>  block,  but
     232              in  a configuration file which has one or more <connection> blocks,
     233              the option setting will be  used  as  a  default  for  <connection>
     234              blocks which follow it in the configuration file.
     235
     236              For  example,  suppose the nobind option were placed in the sample
     237              configuration file above, near the top  of  the  file,  before the
     238              first  <connection>  block.   The effect would be as if nobind were
    244239              declared in all <connection> blocks below it.
    245240
    246241       --proto-force p
    247               When  iterating  through connection profiles, only consider pro‐
    248               files using protocol p ('tcp'|'udp').
     242              When iterating through connection profiles, only consider  profiles
     243              using protocol p ('tcp'|'udp').
    249244
    250245       --remote-random
    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.
     246              When  multiple  --remote address/ports are specified, or if connec
     247              tion profiles are being used, initially randomize the order of  the
     248              list as a kind of basic load-balancing measure.
    254249
    255250       --proto p
    256               Use protocol p for communicating with remote  host.   p  can  be
    257               udp, tcp-client, or tcp-server.
     251              Use  protocol  p for communicating with remote host.  p can be udp,
     252              tcp-client, or tcp-server.
    258253
    259254              The default protocol is udp when --proto is not specified.
    260255
    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
    277               and less robust when used over unreliable or congested networks.
    278 
    279               This  article  outlines  some of problems with tunneling IP over
    280               TCP:
     256              For UDP operation, --proto udp should be specified on both peers.
     257
     258              For TCP operation, one peer must use  --proto  tcp-server  and  the
     259              other  must use --proto tcp-client.  A peer started with tcp-server
     260              will wait indefinitely for an incoming connection.  A peer  started
     261              with  tcp-client  will  attempt to connect, and if that fails, will
     262              sleep for 5 seconds (adjustable via the --connect-retry option) and
     263              try  again  infinite  or up to N retries (adjustable via the --con‐
     264              nect-retry-max option).  Both TCP client and server will simulate a
     265              SIGUSR1 restart signal if either side resets the connection.
     266
     267              OpenVPN is designed to operate optimally over UDP, but TCP capabil‐
     268              ity is provided for situations where UDP cannot be used.   In  com‐
     269              parison  with  UDP, TCP will usually be somewhat less efficient and
     270              less robust when used over unreliable or congested networks.
     271
     272              This article outlines some of problems with tunneling IP over TCP:
    281273
    282274              http://sites.inka.de/sites/bigred/devel/tcp-tcp.html
    283275
    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.
     276              There are certain cases, however, where using TCP may  be  advanta
     277              geous from a security and robustness perspective, such as tunneling
     278              non-IP or application-level UDP protocols, or  tunneling  protocols
     279              which don't possess a built-in reliability layer.
    288280
    289281       --connect-retry n
    290               For  --proto tcp-client, take n as the number of seconds to wait
     282              For  --proto  tcp-client,  take n as the number of seconds to wait
    291283              between connection retries (default=5).
    292284
    293285       --connect-timeout n
    294               For --proto tcp-client, set  connection  timeout  to  n  seconds
     286              For  --proto  tcp-client, set  connection  timeout  to  n  seconds
    295287              (default=10).
    296288
    297289       --connect-retry-max n
    298               For  --proto tcp-client, take n as the number of retries of con
    299               nection attempt (default=infinite).
     290              For  --proto tcp-client, take n as the number of retries of connec
     291              tion attempt (default=infinite).
    300292
    301293       --show-proxy-settings
    302               Show sensed HTTP or SOCKS proxy settings. Currently,  only  Win
    303               dows clients support this option.
     294              Show sensed HTTP or SOCKS proxy settings. Currently,  only  Windows
     295              clients support this option.
    304296
    305297       --http-proxy server port [authfile|'auto'|'auto-nct'] [auth-method]
    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
    309               "stdin" to prompt from console.
     298              Connect  to remote host through an HTTP proxy at address server and
     299              port port.  If HTTP Proxy-Authenticate is required, authfile  is  a
     300              file  containing  a username and password on 2 lines, or "stdin" to
     301              prompt from console.
    310302
    311303              auth-method should be one of "none", "basic", or "ntlm".
    312304
    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.
     305              HTTP Digest authentication is supported as well, but only  via  the
     306              auto or auto-nct flags (below).
     307
     308              The  auto  flag causes OpenVPN to automatically determine the auth-
     309              method and query  stdin  or  the  management  interface  for  user‐
     310              name/password  credentials, if required.  This flag exists on Open‐
     311              VPN 2.1 or higher.
     312
     313              The auto-nct flag (no clear-text auth) instructs OpenVPN  to  auto‐
     314              matically  determine  the authentication method, but to reject weak
     315              authentication protocols such as HTTP Basic Authentication.
    324316
    325317       --http-proxy-retry
    326               Retry indefinitely on HTTP proxy errors.  If an HTTP proxy error
     318              Retry indefinitely on HTTP proxy errors.  If an  HTTP  proxy error
    327319              occurs, simulate a SIGUSR1 reset.
    328320
     
    331323
    332324       --http-proxy-option type [parm]
    333               Set  extended  HTTP  proxy  options.   Repeat  to  set  multiple
    334               options.
    335 
    336               VERSION  version  --  Set  HTTP  version   number   to   version
     325              Set extended HTTP proxy options.  Repeat to set multiple options.
     326
     327              VERSION   version   --   Set   HTTP   version   number  to  version
    337328              (default=1.0).
    338329
     
    340331
    341332       --socks-proxy server [port]
    342               Connect  to remote host through a Socks5 proxy at address server
    343               and port port (default=1080).
     333              Connect to remote host through a Socks5 proxy at address server and
     334              port port (default=1080).
    344335
    345336       --socks-proxy-retry
    346               Retry indefinitely on Socks proxy  errors.   If  a  Socks  proxy
    347               error occurs, simulate a SIGUSR1 reset.
     337              Retry  indefinitely  on Socks proxy errors.  If a Socks proxy error
     338              occurs, simulate a SIGUSR1 reset.
    348339
    349340       --resolv-retry n
    350               If hostname resolve fails for --remote, retry resolve for n sec
    351               onds before failing.
     341              If hostname resolve fails for --remote, retry resolve for n seconds
     342              before failing.
    352343
    353344              Set n to "infinite" to retry indefinitely.
    354345
    355               By default, --resolv-retry infinite is enabled.  You can disable
    356               by setting n=0.
     346              By default, --resolv-retry infinite is enabled.  You can disable by
     347              setting n=0.
    357348
    358349       --float
    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.
     350              Allow remote peer to change its IP address and/or port number, such
     351              as  due  to  DHCP  (this  is  the default if --remote is not used).
     352              --float when specified with --remote allows an OpenVPN  session  to
     353              initially  connect to a peer at a known address, however if packets
     354              arrive from a new address and pass all  authentication  tests,  the
     355              new  address will take control of the session.  This is useful when
     356              you are connecting to a peer which holds a dynamic address such  as
     357              a dial-in user or DHCP client.
     358
     359              Essentially,  --float tells OpenVPN to accept authenticated packets
     360              from any address, not only the address which was specified  in  the
     361              --remote option.
    371362
    372363       --ipchange cmd
    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:
     364              Run  command  cmd when our remote ip-address is initially authenti
     365              cated or changes.
     366
     367              cmd consists of a path to script (or executable  program),  option‐
     368              ally  followed  by arguments. The path and arguments may be single-
     369              or double-quoted and/or escaped using a backslash,  and  should  be
     370              separated by one or more spaces.
     371
     372              When cmd is executed two arguments are appended after any arguments
     373              specified in cmd , as follows:
    383374
    384375              cmd ip_address port_number
    385376
    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
     377              Don't use --ipchange in --mode server mode.  Use a --client-connect
     378              script instead.
     379
     380              See  the  "Environmental  Variables"  section  below for additional
    390381              parameters passed as environmental variables.
    391382
    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.
     383              If you are running in a dynamic IP address environment where the IP
     384              addresses  of  either peer could change without notice, you can use
     385              this script, for example, to edit the /etc/hosts file with the cur‐
     386              rent  address  of  the peer.  The script will be run every time the
     387              remote peer changes its IP address.
     388
     389              Similarly if our IP address changes due to DHCP, we should  config
     390              ure  our  IP address change script (see man page for dhcpcd(8) ) to
     391              deliver a SIGHUP or SIGUSR1 signal to OpenVPN.  OpenVPN  will  then
     392              reestablish  a connection with its most recently authenticated peer
     393              on its new IP address.
    403394
    404395       --port port
    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.
     396              TCP/UDP port number for both local and remote.  The current default
     397              of  1194  represents  the  official IANA port number assignment for
     398              OpenVPN and has been used since version 2.0-beta17.  Previous  ver‐
     399              sions used port 5000 as the default.
    409400
    410401       --lport port
     
    414405              TCP/UDP port number for remote.
    415406
    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.
     407       --bind Bind  to  local address and port. This is the default unless any of
     408              --proto tcp-client , --http-proxy or --socks-proxy are used.
    418409
    419410       --nobind
    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.
     411              Do not bind to local address and port.  The IP stack will  allocate
     412              a  dynamic  port  for  returning  packets.   Since the value of the
     413              dynamic port could not be known in advance by a peer,  this  option
     414              is  only suitable for peers which will be initiating connections by
     415              using the --remote option.
    425416
    426417       --dev tunX | tapX | null
    427               TUN/TAP  virtual network device ( X can be omitted for a dynamic
     418              TUN/TAP virtual network device ( X can be  omitted  for  a dynamic
    428419              device.)
    429420
    430               See examples section below for an example on setting  up  a TUN
     421              See  examples  section  below  for  an  example on setting up a TUN
    431422              device.
    432423
    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
     424              You must use either tun devices on both ends of the  connection  or
     425              tap  devices  on both ends.  You cannot mix them, as they represent
     426              different underlying network layers.
     427
     428              tun devices encapsulate IPv4  or  IPv6  (OSI  Layer  3)  while tap
    438429              devices encapsulate Ethernet 802.3 (OSI Layer 2).
    439430
    440431       --dev-type device-type
    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.
     432              Which  device  type  are  we using?  device-type should be tun (OSI
     433              Layer 3) or tap (OSI Layer 2).  Use this option only if the TUN/TAP
     434              device used with --dev does not begin with tun or tap.
    444435
    445436       --topology mode
    446               Configure virtual addressing topology when running in --dev tun
    447               mode.   This  directive  has no meaning in --dev tap mode, which
     437              Configure  virtual  addressing  topology  when running in --dev tun
     438              mode.  This directive has no  meaning  in  --dev  tap  mode, which
    448439              always uses a subnet topology.
    449440
    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.
     441              If you set this directive on the server, the --server and --server-
     442              bridge directives will automatically push your chosen topology set‐
     443              ting  to  clients  as  well.   This  directive can also be manually
     444              pushed to clients.  Like the --dev directive, this  directive  must
     445              always be compatible between client and server.
    455446
    456447              mode can be one of:
    457448
    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
    461               Windows systems.  This is the default on OpenVPN 2.0.
    462 
    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
    469               available in OpenVPN 2.0 and is now deprecated.
    470 
    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.
     449              net30  -- Use a point-to-point topology, by allocating one /30 sub‐
     450              net per client.  This is designed to allow point-to-point semantics
     451              when  some  or  all of the connecting clients might be Windows sys‐
     452              tems.  This is the default on OpenVPN 2.0.
     453
     454              p2p -- Use a point-to-point topology where the remote  endpoint  of
     455              the  client's  tun interface always points to the local endpoint of
     456              the server's tun  interface.   This  mode  allocates  a  single  IP
     457              address  per connecting client.  Only use when none of the connect‐
     458              ing clients are Windows systems.  This mode is functionally equiva
     459              lent  to the --ifconfig-pool-linear directive which is available in
     460              OpenVPN 2.0 and is now deprecated.
     461
     462              subnet -- Use a subnet rather than  a  point-to-point  topology by
     463              configuring  the  tun interface with a local IP address and subnet
     464              mask, similar to the topology used in --dev tap and ethernet bridg‐
     465              ing  mode.   This mode allocates a single IP address per connecting
     466              client and works on Windows as well.  Only  available  when  server
     467              and  clients  are OpenVPN 2.1 or higher, or OpenVPN 2.0.x which has
     468              been manually patched with the  --topology  directive  code.   When
     469              used  on  Windows,  requires version 8.2 or higher of the TAP-Win32
     470              driver.  When used on *nix, requires that the tun  driver  supports
     471              an ifconfig(8) command which sets a subnet instead of a remote end‐
     472              point IP address.
    482473
    483474              This option exists in OpenVPN 2.1 or higher.
    484475
    485476       --tun-ipv6
    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.
     477              Build a tun link capable of forwarding  IPv6  traffic.   Should be
     478              used  in  conjunction with --dev tun or --dev tunX.  A warning will
     479              be displayed if no specific IPv6 TUN support for your OS  has  been
     480              compiled into OpenVPN.
    490481
    491482              See below for further IPv6-related configuration options.
    492483
    493484       --dev-node node
    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
    497               specify --dev-type tun or --dev-type tap.
    498 
    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.
     485              Explicitly  set  the  device  node  rather than using /dev/net/tun,
     486              /dev/tun, /dev/tap, etc.  If OpenVPN cannot figure out whether node
     487              is  a  TUN or TAP device based on the name, you should also specify
     488              --dev-type tun or --dev-type tap.
     489
     490              On Windows systems, select the TAP-Win32  adapter  which  is named
     491              node  in  the Network Connections Control Panel or the raw GUID of
     492              the adapter enclosed by braces.  The --show-adapters  option  under
     493              Windows  can  also  be  used  to  enumerate all available TAP-Win32
     494              adapters and will show both the network connections  control  panel
     495              name and the GUID for each TAP-Win32 adapter.
    505496
    506497       --lladdr address
    507               Specify the link layer address, more commonly known as  the MAC
     498              Specify  the  link  layer  address,  more commonly known as the MAC
    508499              address.  Only applied to TAP devices.
    509500
    510501       --iproute cmd
    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.
     502              Set alternate command to execute instead of default  iproute2  com‐
     503              mand.   May  be  used  in  order to execute OpenVPN in unprivileged
     504              environment.
    514505
    515506       --ifconfig l rn
    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.
     507              Set TUN/TAP adapter parameters.  l is the IP address of  the  local
     508              VPN  endpoint.  For TUN devices, rn is the IP address of the remote
     509              VPN endpoint.  For TAP devices, rn is the subnet mask of  the  vir‐
     510              tual ethernet segment which is being created or connected to.
     511
     512              For TUN devices, which facilitate virtual point-to-point IP connec‐
     513              tions, the proper usage of --ifconfig is  to  use  two  private  IP
     514              addresses which are not a member of any existing subnet which is in
     515              use.  The IP addresses may be consecutive  and  should  have  their
     516              order  reversed  on the remote peer.  After the VPN is established,
     517              by pinging rn, you will be pinging across the VPN.
     518
     519              For TAP devices, which provide the ability to create virtual ether‐
     520              net  segments,  --ifconfig  is used to set an IP address and subnet
     521              mask just as a physical ethernet adapter would be similarly config‐
     522              ured.   If  you  are  attempting  to  connect  to a remote ethernet
     523              bridge, the IP address and subnet should be  set  to  values  which
     524              would  be valid on the the bridged ethernet segment (note also that
     525              DHCP can be used for the same purpose).
     526
     527              This option, while primarily a proxy for the  ifconfig(8)  command,
     528              is designed to simplify TUN/TAP tunnel configuration by providing a
     529              standard interface to the  different  ifconfig  implementations  on
     530              different platforms.
     531
     532              --ifconfig  parameters which are IP addresses can also be specified
     533              as a DNS or /etc/hosts file resolvable name.
     534
     535              For TAP devices, --ifconfig should not be used if the TAP interface
     536              will be getting an IP address lease from a DHCP server.
    547537
    548538       --ifconfig-noexec
    549               Don't  actually  execute  ifconfig/netsh  commands, instead pass
     539              Don't   actually  execute  ifconfig/netsh  commands,  instead pass
    550540              --ifconfig parameters to scripts using environmental variables.
    551541
    552542       --ifconfig-nowarn
    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.
     543              Don't output an options consistency check warning if the --ifconfig
     544              option  on  this  side  of  the connection doesn't match the remote
     545              side.  This is useful when you want to retain the overall  benefits
     546              of  the  options  consistency check (also see --disable-occ option)
     547              while only disabling the ifconfig component of the check.
     548
     549              For example, if you have a configuration where the local host  uses
     550              --ifconfig  but  the remote host does not, use --ifconfig-nowarn on
     551              the local host.
     552
     553              This option will also silence warnings about potential address con‐
     554              flicts  which occasionally annoy more experienced users by trigger‐
     555              ing "false positive" warnings.
    567556
    568557       --route network/IP [netmask] [gateway] [metric]
    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.
     558              Add route to routing table after connection is established.  Multi‐
     559              ple  routes  can  be  specified.  Routes will be automatically torn
     560              down in reverse order prior to TUN/TAP device close.
     561
     562              This option is intended as a convenience  proxy  for  the route(8)
     563              shell  command, while at the same time providing portable semantics
     564              across OpenVPN's platform space.
    576565
    577566              netmask default -- 255.255.255.255
    578567
    579               gateway  default  --  taken  from  --route-gateway or the second
    580               parameter to --ifconfig when --dev tun is specified.
     568              gateway default -- taken from --route-gateway or the second parame‐
     569              ter to --ifconfig when --dev tun is specified.
    581570
    582571              metric default -- taken from --route-metric otherwise 0.
    583572
    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
     573              The  default can be specified by leaving an option blank or setting
     574              it to "default".
     575
     576              The network and gateway parameters can also be specified as  a  DNS
     577              or /etc/hosts file resolvable name, or as one of three special key
     578              words:
     579
     580              vpn_gateway -- The remote VPN endpoint address (derived either from
     581              --route-gateway  or  the  second parameter to --ifconfig when --dev
     582              tun is specified).
     583
     584              net_gateway -- The pre-existing IP default gateway, read  from  the
     585              routing table (not supported on all OSes).
     586
     587              remote_host  --  The  --remote  address  if OpenVPN is being run in
    599588              client mode, and is undefined in server mode.
    600589
    601590       --max-routes n
    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.
     591              Allow a maximum number of n --route options to be specified, either
     592              in  the local configuration file, or pulled from an OpenVPN server.
     593              By default, n=100.
    605594
    606595       --route-gateway gw|'dhcp'
    607596              Specify a default gateway gw for use with --route.
    608597
    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.
     598              If dhcp is specified as the parameter, the gateway address will  be
     599              extracted from a DHCP negotiation with the OpenVPN server-side LAN.
    612600
    613601       --route-metric m
     
    615603
    616604       --route-delay [n] [w]
    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
     605              Delay  n seconds (default=0) after connection establishment, before
     606              adding routes. If n is 0, routes will  be  added  immediately  upon
     607              connection establishment.  If --route-delay is omitted, routes will
     608              be added immediately after TUN/TAP device open and --up script exe‐
     609              cution,  before  any  --user  or  --group  privilege  downgrade (or
     610              --chroot execution.)
     611
     612              This option is designed to be useful in  scenarios  where DHCP  is
     613              used  to  set tap adapter addresses.  The delay will give the DHCP
    626614              handshake time to complete before routes are added.
    627615
    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.
     616              On Windows, --route-delay tries to be more intelligent by waiting w
     617              seconds  (w=30  by  default)  for  the TAP-Win32 adapter to come up
     618              before adding routes.
    631619
    632620       --route-up cmd
    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
     621              Run command cmd after routes are added, subject to --route-delay.
     622
     623              cmd consists of a path to script (or executable  program),  option‐
     624              ally  followed  by arguments. The path and arguments may be single-
     625              or double-quoted and/or escaped using a backslash,  and  should  be
     626              separated by one or more spaces.
     627
     628              See  the  "Environmental  Variables"  section  below for additional
    642629              parameters passed as environmental variables.
    643630
     
    645632              Run command cmd before routes are removed upon disconnection.
    646633
    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
     634              cmd consists of a path to script (or executable  program),  option‐
     635              ally  followed  by arguments. The path and arguments may be single-
     636              or double-quoted and/or escaped using a backslash,  and  should  be
     637              separated by one or more spaces.
     638
     639              See  the  "Environmental  Variables"  section  below for additional
    653640              parameters passed as environmental variables.
    654641
    655642       --route-noexec
    656               Don't  add  or remove routes automatically.  Instead pass routes
    657               to --route-up script using environmental variables.
     643              Don't add or remove routes automatically.  Instead pass  routes  to
     644              --route-up script using environmental variables.
    658645
    659646       --route-nopull
    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.
     647              When  used with --client or --pull, accept options pushed by server
     648              EXCEPT for routes and dhcp options like DNS servers.
     649
     650              When used on the client, this option effectively  bars  the server
     651              from adding routes to the client's routing table, however note that
     652              this option still allows the server to set the TCP/IP properties of
     653              the client's TUN/TAP interface.
    667654
    668655       --allow-pull-fqdn
    669               Allow client to pull DNS names from server  (rather  than  being
    670               limited  to  IP  address)  for --ifconfig, --route, and --route-
    671               gateway.
     656              Allow  client to pull DNS names from server (rather than being lim‐
     657              ited to IP address) for --ifconfig, --route, and --route-gateway.
    672658
    673659       --client-nat snat|dnat network netmask alias
    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
     660              This pushable client option sets up a stateless one-to-one NAT rule
     661              on  packet  addresses  (not  ports),  and  is useful in cases where
     662              routes or ifconfig settings pushed to the client would create an IP
     663              numbering conflict.
     664
     665              network/netmask  (for  example 192.168.0.0/255.255.0.0) defines the
     666              local view  of  a  resource  from  the  client perspective,  while
     667              alias/netmask   (for  example  10.64.0.0/255.255.0.0)  defines the
    682668              remote view from the server perspective.
    683669
    684               Use snat (source NAT) for resources owned by the client and dnat
     670              Use snat (source NAT) for resources owned by the  client  and dnat
    685671              (destination NAT) for remote resources.
    686672
    687               Set  --verb  6  for debugging info showing the transformation of
     673              Set  --verb  6  for  debugging  info showing the transformation of
    688674              src/dest addresses in packets.
    689675
    690676       --redirect-gateway flags...
    691               Automatically execute routing commands to cause all outgoing  IP
    692               traffic  to  be  redirected over the VPN.  This is a client-side
     677              Automatically execute routing commands to  cause  all outgoing  IP
     678              traffic  to  be  redirected  over  the VPN.  This is a client-side
    693679              option.
    694680
    695681              This option performs three steps:
    696682
    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.
     683              (1) Create a static route for the --remote address  which  forwards
     684              to the pre-existing default gateway.  This is done so that (3) will
     685              not create a routing loop.
    700686
    701687              (2) Delete the default gateway route.
    702688
    703               (3) Set the new default gateway to be the VPN  endpoint  address
    704               (derived  either from --route-gateway or the second parameter to
     689              (3) Set the new default gateway to  be  the VPN  endpoint  address
     690              (derived  either  from  --route-gateway or the second parameter to
    705691              --ifconfig when --dev tun is specified).
    706692
    707               When the tunnel is  torn  down,  all  of  the  above  steps  are
    708               reversed so that the original default route is restored.
     693              When the tunnel is torn down, all of the above steps  are  reversed
     694              so that the original default route is restored.
    709695
    710696              Option flags:
    711697
    712               local -- Add the local flag if both OpenVPN servers are directly
    713               connected via a common subnet, such as with wireless.  The local
     698              local  --  Add the local flag if both OpenVPN servers are directly
     699              connected via a common subnet, such as with  wireless.   The local
    714700              flag will cause step 1 above to be omitted.
    715701
    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.
     702              autolocal -- Try to automatically determine whether to enable local
     703              flag above.
     704
     705              def1 -- Use this flag to override  the  default  gateway  by  using
     706              0.0.0.0/1 and 128.0.0.0/1 rather than 0.0.0.0/0.  This has the ben‐
     707              efit of overriding but not wiping out the original default gateway.
     708
     709              bypass-dhcp -- Add a direct route to the DHCP server (if it is non-
     710              local) which bypasses the tunnel (Available on Windows clients, may
     711              not be available on non-Windows clients).
     712
     713              bypass-dns -- Add a direct route to the DNS server(s) (if they  are
     714              non-local) which bypasses the tunnel (Available on Windows clients,
     715              may not be available on non-Windows clients).
     716
     717              block-local -- Block access to local LAN when the tunnel is active,
     718              except for the LAN gateway itself.  This is accomplished by routing
     719              the local LAN (except for the LAN gateway address) into the tunnel.
    736720
    737721       --link-mtu n
    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.
     722              Sets an upper bound on the size  of  UDP packets  which  are  sent
     723              between  OpenVPN peers.  It's best not to set this parameter unless
     724              you know what you're doing.
    741725
    742726       --redirect-private [flags]
    743               Like --redirect-gateway, but omit actually changing the  default
     727              Like --redirect-gateway, but omit  actually  changing the  default
    744728              gateway.  Useful when pushing private subnets.
    745729
    746730       --tun-mtu n
    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
     731              Take  the  TUN  device MTU to be n and derive the link MTU from it
     732              (default=1500).  In most cases, you will  probably  want to  leave
    749733              this parameter set to its default value.
    750734
    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
    754               data channels be sent unfragmented.
    755 
    756               MTU problems often manifest themselves as connections which hang
     735              The  MTU  (Maximum Transmission Units) is the maximum datagram size
     736              in bytes that can be sent unfragmented over  a  particular  network
     737              path.   OpenVPN  requires that packets on the control or data chan‐
     738              nels be sent unfragmented.
     739
     740              MTU problems often manifest themselves as  connections  which hang
    757741              during periods of active usage.
    758742
    759               It's  best to use the --fragment and/or --mssfix options to deal
     743              It's  best  to  use the --fragment and/or --mssfix options to deal
    760744              with MTU sizing issues.
    761745
    762746       --tun-mtu-extra n
    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.
     747              Assume that the TUN/TAP device might return as many as n bytes more
     748              than  the  --tun-mtu  size  on read.  This parameter defaults to 0,
     749              which is sufficient for most TUN devices.  TAP devices  may  intro‐
     750              duce  additional  overhead in excess of the MTU size, and a setting
     751              of 32 is the default when TAP devices  are  used.   This  parameter
     752              only controls internal OpenVPN buffer sizing, so there is no trans‐
     753              mission overhead associated with using a larger value.
    771754
    772755       --mtu-disc type
    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.
     756              Should we do Path MTU discovery on TCP/UDP channel?  Only supported
     757              on  OSes  such  as Linux that supports the necessary system call to
     758              set.
    776759
    777760              'no' -- Never send DF (Don't Fragment) frames
     
    780763
    781764       --mtu-test
    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.
     765              To empirically measure MTU on connection startup,  add  the --mtu-
     766              test  option to your configuration.  OpenVPN will send ping packets
     767              of various sizes to the remote peer and measure the largest packets
     768              which  were successfully received.  The --mtu-test process normally
     769              takes about 3 minutes to complete.
    787770
    788771       --fragment max
    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 ).
     772              Enable internal datagram fragmentation so that no UDP datagrams are
     773              sent which are larger than max bytes.
     774
     775              The  max parameter is interpreted in the same way as the --link-mtu
     776              parameter, i.e. the UDP packet size  after  encapsulation  overhead
     777              has been added in, but not including the UDP header itself.
     778
     779              The  --fragment  option only makes sense when you are using the UDP
     780              protocol ( --proto udp ).
    799781
    800782              --fragment adds 4 bytes of overhead per datagram.
    801783
    802               See the --mssfix option below for an important related option to
     784              See the --mssfix option below for an important  related  option to
    803785              --fragment.
    804786
    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.
     787              It  should  also  be noted that this option is not meant to replace
     788              UDP fragmentation at the IP stack level.  It is  only  meant  as  a
     789              last  resort  when path MTU discovery is broken.  Using this option
     790              is less efficient than fixing path MTU discovery for your  IP  link
     791              and using native IP fragmentation instead.
     792
     793              Having  said  that,  there  are circumstances where using OpenVPN's
     794              internal fragmentation capability may be your only option, such  as
     795              tunneling a UDP multicast stream which requires fragmentation.
    815796
    816797       --mssfix max
    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
     798              Announce  to  TCP sessions running over the tunnel that they should
     799              limit their send packet sizes such that after OpenVPN has  encapsu‐
     800              lated them, the resulting UDP packet size that OpenVPN sends to its
     801              peer will not exceed max bytes. The default value is 1450.
     802
     803              The max parameter is interpreted in the same way as the  --link-mtu
     804              parameter,  i.e.  the  UDP packet size after encapsulation overhead
     805              has been added in, but not including the UDP header itself.
     806
     807              The --mssfix option only makes sense when you  are  using  the  UDP
     808              protocol for OpenVPN peer-to-peer communication, i.e.  --proto udp.
     809
     810              --mssfix  and --fragment can be ideally used together, where --mss‐
     811              fix will try to keep TCP from needing packet fragmentation  in  the
     812              first place, and if big packets come through anyhow (from protocols
     813              other than TCP), --fragment will internally fragment them.
     814
     815              Both --fragment and --mssfix are  designed  to  work  around  cases
     816              where  Path  MTU  discovery  is  broken on the network path between
    840817              OpenVPN peers.
    841818
    842               The  usual  symptom of such a breakdown is an OpenVPN connection
     819              The usual symptom of such a  breakdown  is  an  OpenVPN connection
    843820              which successfully starts, but then stalls during active usage.
    844821
    845               If --fragment and --mssfix are used together, --mssfix will take
     822              If  --fragment  and --mssfix are used together, --mssfix will take
    846823              its default max parameter from the --fragment max option.
    847824
    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:
     825              Therefore, one could lower the maximum UDP packet size to  1300  (a
     826              good  first  try  for solving MTU-related connection problems) with
     827              the following options:
    851828
    852829              --tun-mtu 1500 --fragment 1300 --mssfix
    853830
    854831       --sndbuf size
    855               Set  the TCP/UDP socket send buffer size.  Currently defaults to
     832              Set the TCP/UDP socket send buffer  size.   Currently  defaults to
    856833              65536 bytes.
    857834
    858835       --rcvbuf size
    859               Set the TCP/UDP socket receive buffer size.  Currently  defaults
    860               to 65536 bytes.
     836              Set  the TCP/UDP socket receive buffer size.  Currently defaults to
     837              65536 bytes.
    861838
    862839       --mark value
    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
    866               systems.
     840              Mark encrypted packets being sent with value. The mark value can be
     841              matched  in  policy  routing and packetfilter rules. This option is
     842              only supported in Linux and does nothing on  other  operating  sys‐
     843              tems.
    867844
    868845       --socket-flags flags...
    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.
     846              Apply  the given flags to the OpenVPN transport socket.  Currently,
     847              only TCP_NODELAY is supported.
     848
     849              The TCP_NODELAY socket flag is useful in TCP mode, and  causes  the
     850              kernel  to  send tunnel packets immediately over the TCP connection
     851              without trying to group  several  smaller  packets  into  a  larger
     852              packet.  This can result in a considerably improvement in latency.
     853
     854              This  option  is pushable from server to client, and should be used
     855              on both client and server for maximum effect.
    880856
    881857       --txqueuelen n
    882               (Linux only) Set the TX queue length on the  TUN/TAP  interface.
     858              (Linux only) Set the TX queue  length  on the  TUN/TAP  interface.
    883859              Currently defaults to 100.
    884860
    885861       --shaper n
    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
     862              Limit  bandwidth  of outgoing tunnel data to n bytes per second on
     863              the TCP/UDP port.  If you want  to  limit the  bandwidth  in  both
    888864              directions, use this option on both peers.
    889865
    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.
     866              OpenVPN  uses the following algorithm to implement traffic shaping:
     867              Given a shaper rate of n bytes per second, after a  datagram  write
     868              of b bytes is queued on the TCP/UDP port, wait a minimum of (b / n)
     869              seconds before queuing the next write.
     870
     871              It should be noted that OpenVPN supports multiple  tunnels  between
     872              the  same  two  peers,  allowing  you  to  construct full-speed and
     873              reduced bandwidth tunnels at the same  time,  routing  low-priority
     874              data  such  as  off-site backups over the reduced bandwidth tunnel,
     875              and other data over the full-speed tunnel.
     876
     877              Also note that for low bandwidth tunnels (under 1000 bytes per sec‐
     878              ond), you should probably use lower MTU values as well (see above),
     879              otherwise the packet latency will grow so large as to trigger time‐
     880              outs in the TLS layer and TCP connections running over the tunnel.
    906881
    907882              OpenVPN allows n to be between 100 bytes/sec and 100 Mbytes/sec.
    908883
    909884       --inactive n [bytes]
    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.
     885              Causes OpenVPN to exit after n seconds of inactivity on the TUN/TAP
     886              device. The time length of inactivity is measured  since  the  last
     887              incoming  or  outgoing  tunnel packet.  The default value is 0 sec‐
     888              onds, which disables this feature.
     889
     890              If the optional bytes parameter is  included,  exit  if  less  than
     891              bytes of combined in/out traffic are produced on the tun/tap device
     892              in n seconds.
     893
     894              In any case,  OpenVPN's  internal  ping  packets  (which  are  just
     895              keepalives)  and TLS control packets are not considered "activity",
     896              nor are they counted as traffic, as they  are  used  internally  by
     897              OpenVPN and are not an indication of actual user activity.
    924898
    925899       --ping n
    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.
     900              Ping  remote  over  the TCP/UDP control channel if no packets have
     901              been sent for at least n seconds (specify --ping on both  peers  to
     902              cause ping packets to be sent in both directions since OpenVPN ping
     903              packets are not echoed like IP ping packets).  When used in one  of
     904              OpenVPN's  secure  modes  (where  --secret, --tls-server, or --tls-
     905              client is specified), the ping  packet  will  be  cryptographically
     906              secure.
    933907
    934908              This option has two intended uses:
    935909
    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.
     910              (1)  Compatibility with stateful firewalls.  The periodic ping will
     911              ensure that a stateful firewall rule which allows OpenVPN UDP pack‐
     912              ets to pass will not time out.
     913
     914              (2)  To provide a basis for the remote to test the existence of its
     915              peer using the --ping-exit option.
    942916
    943917       --ping-exit n
    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.
     918              Causes OpenVPN to exit after n seconds pass without reception of  a
     919              ping or other packet from remote.  This option can be combined with
     920              --inactive, --ping, and --ping-exit to create a two-tiered inactiv‐
     921              ity disconnect.
    948922
    949923              For example,
     
    951925              openvpn [options...] --inactive 3600 --ping 10 --ping-exit 60
    952926
    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.
     927              when  used  on both peers will cause OpenVPN to exit within 60 sec‐
     928              onds if its peer disconnects, but will exit after one  hour  if  no
     929              actual tunnel data is exchanged.
    956930
    957931       --ping-restart n
    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.
     932              Similar  to --ping-exit, but trigger a SIGUSR1 restart after n sec‐
     933              onds pass without reception of a ping or other packet from remote.
     934
     935              This option is useful in cases where the remote peer has a  dynamic
     936              IP  address  and a low-TTL DNS name is used to track the IP address
     937              using a service such as http://dyndns.org/ + a dynamic  DNS  client
     938              such as ddclient.
     939
     940              If the peer cannot be reached, a restart will be triggered, causing
     941              the hostname used with --remote to  be  re-resolved  (if  --resolv-
     942              retry is also specified).
     943
     944              In  server  mode,  --ping-restart, --inactive, or any other type of
     945              internally generated signal will always be  applied  to  individual
     946              client  instance  objects, never to whole server itself.  Note also
     947              in server mode that any internally  generated  signal  which  would
     948              normally  cause  a  restart,  will cause the deletion of the client
     949              instance object instead.
     950
     951              In client mode, the --ping-restart parameter is set to 120  seconds
     952              by  default.   This  default  will  hold  until  the client pulls a
     953              replacement value from the server, based on the --keepalive setting
     954              in  the  server  configuration.  To disable the 120 second default,
     955              set --ping-restart 0 on the client.
    983956
    984957              See the signals section below for more information on SIGUSR1.
    985958
    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.
     959              Note that the behavior of SIGUSR1 can be modified by the --persist-
     960              tun,  --persist-key,  --persist-local-ip,  and  --persist-remote-ip
     961              options.
     962
     963              Also note that --ping-exit and --ping-restart are  mutually  exclu‐
     964              sive and cannot be used together.
    992965
    993966       --keepalive n m
    994               A helper directive designed to simplify the expression of --ping
     967              A  helper  directive designed to simplify the expression of --ping
    995968              and --ping-restart in server mode configurations.
    996969
    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.
     970              The server timeout is set twice the value of the  second  argument.
     971              This  ensures that a timeout is dectected on client side before the
     972              server side drops the connection.
    1000973
    1001974              For example, --keepalive 10 60 expands as follows:
     
    1011984
    1012985       --ping-timer-rem
    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.
     986              Run the --ping-exit / --ping-restart timer only if we have a remote
     987              address.   Use this option if you are starting the daemon in listen
     988              mode (i.e. without an explicit --remote peer), and you  don't  want
     989              to start clocking timeouts until a remote peer connects.
    1018990
    1019991       --persist-tun
    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
     992              Don't close and reopen TUN/TAP device or run up/down scripts across
     993              SIGUSR1 or --ping-restart restarts.
     994
     995              SIGUSR1 is a restart signal similar to  SIGHUP,  but which  offers
    1024996              finer-grained control over reset options.
    1025997
     
    1027999              Don't re-read key files across SIGUSR1 or --ping-restart.
    10281000
    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
     1001              This  option  can be combined with --user nobody to allow restarts
     1002              triggered by the SIGUSR1 signal.  Normally if you drop root  privi‐
     1003              leges  in OpenVPN, the daemon cannot be restarted since it will now
     1004              be unable to re-read protected key files.
     1005
     1006              This option solves the problem by persisting  keys  across SIGUSR1
    10351007              resets, so they don't need to be re-read.
    10361008
    10371009       --persist-local-ip
    1038               Preserve  initially  resolved  local  IP address and port number
    1039               across SIGUSR1 or --ping-restart restarts.
     1010              Preserve initially resolved local IP address and port number across
     1011              SIGUSR1 or --ping-restart restarts.
    10401012
    10411013       --persist-remote-ip
    1042               Preserve most recently authenticated remote IP address and  port
     1014              Preserve most recently authenticated remote  IP  address and  port
    10431015              number across SIGUSR1 or --ping-restart restarts.
    10441016
    10451017       --mlock
    1046               Disable paging by calling the POSIX mlockall function.  Requires
    1047               that OpenVPN be initially run as root (though OpenVPN can subse‐
     1018              Disable  paging  by calling the POSIX mlockall function.  Requires
     1019              that OpenVPN be initially run as root (though  OpenVPN  can subse‐
    10481020              quently downgrade its UID using the --user option).
    10491021
    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.
     1022              Using  this  option  ensures  that key material and tunnel data are
     1023              never written to disk due to virtual memory paging operations which
     1024              occur under most modern operating systems.  It ensures that even if
     1025              an attacker was able to crack the box running OpenVPN, he would not
     1026              be  able  to  scan  the system swap file to recover previously used
     1027              ephemeral keys, which are used for a period of time governed by the
     1028              --reneg options (see below), then are discarded.
     1029
     1030              The  downside of using --mlock is that it will reduce the amount of
     1031              physical memory available to other applications.
    10611032
    10621033       --up cmd
    1063               Run command cmd after successful TUN/TAP device open (pre --user
     1034              Run command cmd after successful TUN/TAP device  open  (pre --user
    10641035              UID change).
    10651036
    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.
     1037              cmd  consists  of a path to script (or executable program), option‐
     1038              ally followed by arguments. The path and arguments may  be  single-
     1039              or  double-quoted  and/or  escaped using a backslash, and should be
     1040              separated by one or more spaces.
     1041
     1042              The up command is useful for specifying route commands which  route
     1043              IP  traffic  destined  for private subnets which exist at the other
     1044              end of the VPN connection into the tunnel.
    10741045
    10751046              For --dev tun execute as:
    10761047
    1077               cmd    tun_dev   tun_mtu   link_mtu   ifconfig_local_ip   ifcon‐
    1078               fig_remote_ip [ init | restart ]
     1048              cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [
     1049              init | restart ]
    10791050
    10801051              For --dev tap execute as:
    10811052
    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
     1053              cmd  tap_dev  tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [
     1054              init | restart ]
     1055
     1056              See the "Environmental  Variables"  section  below  for additional
    10861057              parameters passed as environmental variables.
    10871058
    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.
     1059              Note  that  if cmd includes arguments, all OpenVPN-generated argu‐
     1060              ments will be appended to them to build an argument list with which
     1061              the executable will be called.
    10911062
    10921063              Typically, cmd will run a script to add routes to the tunnel.
    10931064
    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:
     1065              Normally  the  up  script  is  called  after  the TUN/TAP device is
     1066              opened.  In this context, the last command line parameter passed to
     1067              the  script will be init.  If the --up-restart option is also used,
     1068              the up script will be called for restarts as well.   A  restart  is
     1069              considered  to  be  a partial reinitialization of OpenVPN where the
     1070              TUN/TAP instance is preserved (the --persist-tun option will enable
     1071              such  preservation).   A restart can be generated by a SIGUSR1 sig‐
     1072              nal, a --ping-restart timeout, or a connection reset when  the  TCP
     1073              protocol  is enabled with the --proto option.  If a restart occurs,
     1074              and --up-restart has been specified, the up script will  be  called
     1075              with restart as the last parameter.
     1076
     1077              The  following  standalone example shows how the --up script can be
     1078              called in both an initialization and restart context.   (NOTE:  for
     1079              security  reasons,  don't run the following example unless UDP port
     1080              9999 is blocked by your  firewall.   Also,  the  example  will  run
     1081              indefinitely, so you should abort with control-c).
     1082
     1083              openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 --up 'echo
     1084              up' --down 'echo down' --persist-tun --up-restart
     1085
     1086              Note that OpenVPN also provides the --ifconfig option to  automati‐
     1087              cally  ifconfig  the  TUN device, eliminating the need to define an
     1088              --up script, unless you also want to configure routes in  the  --up
     1089              script.
     1090
     1091              If  --ifconfig  is  also  specified, OpenVPN will pass the ifconfig
     1092              local and remote endpoints on the command line to the  --up  script
     1093              so that they can be used to configure routes such as:
    11241094
    11251095              route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
    11261096
    11271097       --up-delay
    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.
     1098              Delay  TUN/TAP  open and possible --up script execution until after
     1099              TCP/UDP connection establishment with peer.
     1100
     1101              In --proto udp mode, this  option  normally  requires  the  use  of
     1102              --ping  to  allow connection initiation to be sensed in the absence
     1103              of tunnel data, since UDP is a "connectionless" protocol.
     1104
     1105              On Windows, this option will delay the TAP-Win32 media state  tran‐
     1106              sitioning  to  "connected" until connection establishment, i.e. the
     1107              receipt of the first authenticated packet from the peer.
    11401108
    11411109       --down cmd
    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.
     1110              Run command cmd after TUN/TAP device close (post --user UID  change
     1111              and/or --chroot ).  cmd consists of a path to script (or executable
     1112              program), optionally followed by arguments. The path and  arguments
     1113              may  be  single- or double-quoted and/or escaped using a backslash,
     1114              and should be separated by one or more spaces.
     1115
     1116              Called with the same parameters and environmental variables as  the
     1117              --up option above.
     1118
     1119              Note  that if you reduce privileges by using --user and/or --group,
     1120              your --down script will also run at reduced privilege.
    11541121
    11551122       --down-pre
     
    11571124
    11581125       --up-restart
    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.
     1126              Enable the --up and --down scripts to be  called  for  restarts as
     1127              well as initial program start.  This option is described more fully
     1128              above in the --up option documentation.
    11621129
    11631130       --setenv name value
    1164               Set  a  custom  environmental  variable  name=value  to  pass to
     1131              Set a custom environmental variable name=value to pass to script.
     1132
     1133       --setenv FORWARD_COMPATIBLE 1
     1134              Relax config file syntax checking so that unknown  directives  will
     1135              trigger  a  warning but not a fatal error, on the assumption that a
     1136              given unknown directive might be valid in future OpenVPN versions.
     1137
     1138              This option should be used with caution, as there are good security
     1139              reasons  for having OpenVPN fail if it detects problems in a config
     1140              file.  Having said that, there are valid reasons  for  wanting  new
     1141              software  features  to gracefully degrade when encountered by older
     1142              software versions.
     1143
     1144       --setenv-safe name value
     1145              Set a custom environmental variable OPENVPN_name=value to  pass  to
    11651146              script.
    11661147
    1167        --setenv FORWARD_COMPATIBLE 1
    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
    1171               versions.
    1172 
    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.
    1178 
    1179        --setenv-safe name value
    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.
     1148              This  directive  is designed to be pushed by the server to clients,
     1149              and the prepending of "OPENVPN_" to the environmental variable is a
     1150              safety precaution to prevent a LD_PRELOAD style attack from a mali‐
     1151              cious or compromised server.
    11871152
    11881153       --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
     1154              This directive offers policy-level control over OpenVPN's usage  of
     1155              external  programs  and  scripts.   Lower  level values  are  more
     1156              restrictive, higher  values  are  more  permissive.   Settings for
    11921157              level:
    11931158
    11941159              0 -- Strictly no calling of external programs.
    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
     1160              1 -- (Default) Only call built-in executables such as ifconfig, ip,
     1161              route, or netsh.
     1162              2  --  Allow  calling  of  built-in  executables  and user-defined
    11981163              scripts.
    1199               3 -- Allow passwords to be passed to scripts  via environmental
     1164              3  --  Allow  passwords  to  be passed to scripts via environmental
    12001165              variables (potentially unsafe).
    12011166
    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:
     1167              OpenVPN releases before v2.3 also supported  a  method  flag which
     1168              indicated  how  OpenVPN should call external commands and scripts.
     1169              This could be either execve or system.  As of  OpenVPN  v2.3, this
     1170              flag is no longer accepted.  In most *nix environments the execve()
     1171              approach has been used without any issues.
     1172
     1173              To run scripts in Windows in earlier OpenVPN versions you needed to
     1174              either  add  a  full path to the script interpreter which can parse
     1175              the script or use the system flag to  run  these  scripts.   As  of
     1176              OpenVPN  v2.3  it  is now a strict requirement to have full path to
     1177              the script interpreter when running non-executables files.  This is
     1178              not  needed  for executable files, such as .exe, .com, .bat or .cmd
     1179              files.  For example, if you have a Visual Basic  script,  you  must
     1180              use this syntax now:
    12161181
    12171182                  --up 'C:\\Windows\\System32\\wscript.exe C:\\Program\ Files\\OpenVPN\\config\\my-up-script.vbs'
    12181183
    1219               Please note the single quote marks and the escaping of the back‐
     1184              Please  note  the single quote marks and the escaping of the back‐
    12201185              slashes (\) and the space character.
    12211186
    1222               The reason the support for the system flag was removed is due to
    1223               the security implications with shell expansions  when executing
     1187              The reason the support for the system flag was removed  is  due to
     1188              the  security  implications  with  shell  expansions when executing
    12241189              scripts via the system() call.
    12251190
    12261191       --disable-occ
    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
     1192              Don't output  a  warning  message  if  option  inconsistencies are
     1193              detected  between  peers.   An  example  of an option inconsistency
     1194              would be where one peer uses --dev tun while the  other  peer uses
    12301195              --dev tap.
    12311196
    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.
     1197              Use  of  this option is discouraged, but is provided as a temporary
     1198              fix in situations where a recent version of OpenVPN must connect to
     1199              an old version.
    12351200
    12361201       --user user
    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).
     1202              Change the user ID of the OpenVPN process to user after initializa‐
     1203              tion, dropping privileges in the process.  This option is useful to
     1204              protect the system in the event that some hostile party was able to
     1205              gain control of an OpenVPN session.  Though OpenVPN's security fea‐
     1206              tures  make  this  unlikely,  it  is  provided  as a second line of
     1207              defense.
     1208
     1209              By setting user to nobody or somebody similarly  unprivileged,  the
     1210              hostile party would be limited in what damage they could cause.  Of
     1211              course once you take away privileges, you cannot return them to  an
     1212              OpenVPN  session.   This  means,  for  example, that if you want to
     1213              reset an OpenVPN daemon with  a  SIGUSR1  signal  (for  example  in
     1214              response  to  a  DHCP reset), you should make use of one or more of
     1215              the --persist options to ensure that OpenVPN doesn't need  to  exe‐
     1216              cute  any  privileged  operations  in order to restart (such as re-
     1217              reading key files or running ifconfig on the TUN device).
    12541218
    12551219       --group group
    1256               Similar to the --user option, this option changes the  group  ID
    1257               of the OpenVPN process to group after initialization.
     1220              Similar to the --user option, this option changes the group  ID  of
     1221              the OpenVPN process to group after initialization.
    12581222
    12591223       --cd dir
    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
    1263               the current directory such as "." or "..".
    1264 
    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.
     1224              Change directory to dir prior to reading any files such as configu
     1225              ration files, key files, scripts, etc.  dir should be  an  absolute
     1226              path, with a leading "/", and without any references to the current
     1227              directory such as "." or "..".
     1228
     1229              This option is useful when you  are  running OpenVPN  in  --daemon
     1230              mode, and you want to consolidate all of your OpenVPN control files
     1231              in one location.
    12681232
    12691233       --chroot dir
    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.
    1273               This can be desirable from a security standpoint.
    1274 
    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.
     1234              Chroot to dir after initialization.  --chroot essentially redefines
     1235              dir as being the top level directory tree (/).  OpenVPN will there‐
     1236              fore be unable to access any files outside this tree.  This can  be
     1237              desirable from a security standpoint.
     1238
     1239              Since  the  chroot operation is delayed until after initialization,
     1240              most OpenVPN options that reference files will operate  in  a  pre-
     1241              chroot context.
     1242
     1243              In  many  cases, the dir parameter can point to an empty directory,
     1244              however complications can result when scripts or restarts are  exe‐
     1245              cuted after the chroot operation.
    12821246
    12831247       --setcon context
    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.
     1248              Apply  SELinux  context after initialization. This essentially pro‐
     1249              vides the ability to restrict OpenVPN's rights to only network  I/O
     1250              operations,  thanks  to  SELinux. This goes further than --user and
     1251              --chroot in that those two, while being  great  security  features,
     1252              unfortunately  do  not  protect  against  privilege  escalation  by
     1253              exploitation of a vulnerable system call. You can of course combine
     1254              all  three,  but  please  note that since setcon requires access to
     1255              /proc you will have to provide it inside the chroot directory (e.g.
     1256              with mount --bind).
     1257
     1258              Since  the  setcon operation is delayed until after initialization,
     1259              OpenVPN can be restricted to  just  network-related  system  calls,
     1260              whereas by applying the context before startup (such as the OpenVPN
     1261              one provided in the SELinux Reference Policies) you  will  have  to
     1262              allow many things required only during initialization.
     1263
     1264              Like with chroot, complications can result when scripts or restarts
     1265              are executed after the setcon operation, which is  why  you  should
     1266              really consider using the --persist-key and --persist-tun options.
    13051267
    13061268       --daemon [progname]
    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
    1320               tunnels.  When unspecified, progname defaults to "openvpn".
    1321 
    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.
     1269              Become  a  daemon after all initialization functions are completed.
     1270              This option will cause all message and error output to be  sent  to
     1271              the  syslog file (such as /var/log/messages), except for the output
     1272              of scripts and ifconfig commands, which will go to /dev/null unless
     1273              otherwise redirected.  The syslog redirection occurs immediately at
     1274              the point that --daemon is parsed on the command line  even  though
     1275              the  daemonization point occurs later.  If one of the --log options
     1276              is present, it will supercede syslog redirection.
     1277
     1278              The optional progname parameter will cause OpenVPN  to  report  its
     1279              program  name to the system logger as progname.  This can be useful
     1280              in linking OpenVPN messages in the syslog file with  specific  tun‐
     1281              nels.  When unspecified, progname defaults to "openvpn".
     1282
     1283              When  OpenVPN is run with the --daemon option, it will try to delay
     1284              daemonization until the majority of initialization functions  which
     1285              are  capable  of  generating fatal errors are complete.  This means
     1286              that initialization scripts can test the return status of the open‐
     1287              vpn command for a fairly reliable indication of whether the command
     1288              has correctly initialized and entered the packet  forwarding  event
     1289              loop.
     1290
     1291              In  OpenVPN, the vast majority of errors which occur after initial‐
     1292              ization are non-fatal.
    13321293
    13331294       --syslog [progname]
    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.
     1295              Direct log output to system logger, but do  not  become  a  daemon.
     1296              See --daemon directive above for description of progname parameter.
    13371297
    13381298       --errors-to-stderr
    1339               Output  errors  to stderr instead of stdout unless log output is
     1299              Output  errors  to  stderr  instead of stdout unless log output is
    13401300              redirected by one of the --log options.
    13411301
    13421302       --passtos
    1343               Set the TOS field of the tunnel packet to what the payload's TOS
     1303              Set the TOS field of the tunnel packet to what  the  payload's TOS
    13441304              is.
    13451305
    13461306       --inetd [wait|nowait] [progname]
    1347               Use  this  option  when  OpenVPN  is being run from the inetd or
     1307              Use  this  option  when  OpenVPN  is  being  run from the inetd or
    13481308              xinetd(8) server.
    13491309
    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
     1310              The  wait/nowait  option  must  match  what  is  specified  in  the
     1311              inetd/xinetd  config  file.   The nowait mode can only be used with
     1312              --proto tcp-server.  The default is wait.  The nowait mode  can  be
     1313              used  to  instantiate  the  OpenVPN daemon as a classic TCP server,
     1314              where client connection requests are serviced on a single port num‐
     1315              ber.  For additional information on this kind of configuration, see
     1316              the OpenVPN FAQ: http://openvpn.net/faq.html#oneport
     1317
     1318              This option precludes the use of --daemon,  --local,  or  --remote.
     1319              Note that this option causes message and error output to be handled
     1320              in the same way as the  --daemon  option.   The  optional  progname
     1321              parameter is also handled exactly as in --daemon.
     1322
     1323              Also  note  that in wait mode, each OpenVPN tunnel requires a sepa‐
     1324              rate TCP/UDP port and a separate inetd or xinetd  entry.   See  the
     1325              OpenVPN  1.x  HOWTO  for  an  example on using OpenVPN with xinetd:
     1326              http://openvpn.net/1xhowto.html
    13681327
    13691328       --log file
    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.
     1329              Output logging messages to file, including output to  stdout/stderr
     1330              which  is  generated  by called scripts.  If file already exists it
     1331              will be truncated.  This option takes effect immediately when it is
     1332              parsed  in  the  command  line  and will supercede syslog output if
     1333              --daemon or --inetd is also specified.  This option  is  persistent
     1334              over  the entire course of an OpenVPN instantiation and will not be
     1335              reset by SIGHUP, SIGUSR1, or --ping-restart.
     1336
     1337              Note that on Windows, when OpenVPN is started as a service, logging
     1338              occurs by default without the need to specify this option.
    13811339
    13821340       --log-append 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.
     1341              Append  logging  messages to file.  If file does not exist, it will
     1342              be created.  This option behaves exactly like --log except that  it
     1343              appends to rather than truncating the log file.
    13861344
    13871345       --suppress-timestamps
    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.
     1346              Avoid  writing timestamps to log messages, even when they otherwise
     1347              would be prepended. In particular, this  applies  to  log  messages
     1348              sent to stdout.
    13911349
    13921350       --writepid file
     
    13941352
    13951353       --nice n
    1396               Change  process priority after initialization ( n greater than 0
    1397               is lower priority, n less than zero is higher priority).
     1354              Change  process priority after initialization ( n greater than 0 is
     1355              lower priority, n less than zero is higher priority).
    13981356
    13991357       --fast-io
    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.
     1358              (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding  a  call
     1359              to  poll/epoll/select prior to the write operation.  The purpose of
     1360              such a call would normally be to block until the device  or  socket
     1361              is ready to accept the write.  Such blocking is unnecessary on some
     1362              platforms which don't support write  blocking  on  UDP  sockets  or
     1363              TUN/TAP devices.  In such cases, one can optimize the event loop by
     1364              avoiding the poll/epoll/select call, improving CPU efficiency by 5%
     1365              to 10%.
     1366
     1367              This  option  can only be used on non-Windows systems, when --proto
     1368              udp is specified, and when --shaper is NOT specified.
    14111369
    14121370       --multihome
    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.
     1371              Configure a multi-homed UDP server.  This option can be  used  when
     1372              OpenVPN  has  been configured to listen on all interfaces, and will
     1373              attempt to bind client sessions to the interface on  which  packets
     1374              are  being  received,  so that outgoing packets will be sent out of
     1375              the same interface.  Note that this option is only relevant for UDP
     1376              servers and currently is only implemented on Linux.
     1377
     1378              Note:  clients connecting to a --multihome server should always use
     1379              the --nobind option.
    14231380
    14241381       --echo [parms...]
    14251382              Echo parms to log output.
    14261383
    1427               Designed  to  be used to send messages to a controlling applica‐
    1428               tion which is receiving the OpenVPN log output.
     1384              Designed to be used to send messages to a  controlling  application
     1385              which is receiving the OpenVPN log output.
    14291386
    14301387       --remap-usr1 signal
    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.
     1388              Control  whether internally or externally generated SIGUSR1 signals
     1389              are remapped  to  SIGHUP  (restart  without  persisting  state)  or
     1390              SIGTERM (exit).
     1391
     1392              signal  can be set to "SIGHUP" or "SIGTERM".  By default, no remap‐
     1393              ping occurs.
    14371394
    14381395       --verb n
    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
    1442               output.
     1396              Set output verbosity to n (default=1).  Each level shows  all  info
     1397              from  the  previous  levels.   Level 3 is recommended if you want a
     1398              good summary of what's happening without being swamped by output.
    14431399
    14441400              0 -- No output except fatal errors.
    14451401              1 to 4 -- Normal usage range.
    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).
     1402              5 -- Output R and W characters to the console for each packet  read
     1403              and  write,  uppercase is used for TCP/UDP packets and lowercase is
     1404              used for TUN/TAP packets.
     1405              6 to 11 -- Debug info range (see errlevel.h for additional informa‐
     1406              tion on debug levels).
    14511407
    14521408       --status file [n]
    14531409              Write operational status to file every n seconds.
    14541410
    1455               Status  can  also  be written to the syslog by sending a SIGUSR2
    1456               signal.
     1411              Status  can also be written to the syslog by sending a SIGUSR2 sig‐
     1412              nal.
    14571413
    14581414       --status-version [n]
    1459               Choose the status file format version number.  Currently  n  can
    1460               be 1, 2, or 3 and defaults to 1.
     1415              Choose the status file format version number.  Currently n  can  be
     1416              1, 2, or 3 and defaults to 1.
    14611417
    14621418       --mute n
    1463               Log  at  most n consecutive messages in the same category.  This
    1464               is useful to limit repetitive logging of similar message types.
     1419              Log  at  most n consecutive messages in the same category.  This is
     1420              useful to limit repetitive logging of similar message types.
    14651421
    14661422       --comp-lzo [mode]
    1467               Use fast LZO compression -- may add up to 1 byte per packet  for
    1468               incompressible  data.   mode  may  be "yes", "no", or "adaptive"
     1423              Use fast LZO compression -- may add up to 1  byte  per packet  for
     1424              incompressible  data.   mode  may  be  "yes",  "no", or "adaptive"
    14691425              (default).
    14701426
    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:
     1427              In a server mode setup, it is possible to selectively turn compres
     1428              sion on or off for individual clients.
     1429
     1430              First, make sure the client-side config file enables selective com‐
     1431              pression by having at  least  one  --comp-lzo  directive,  such as
     1432              --comp-lzo  no.   This  will  turn off compression by default, but
     1433              allow a future directive push from the server to dynamically change
     1434              the on/off/adaptive setting.
     1435
     1436              Next in a --client-config-dir file, specify the compression setting
     1437              for the client, for example:
    14821438
    14831439                  comp-lzo yes
    14841440                  push "comp-lzo yes"
    14851441
    1486               The first line sets the comp-lzo setting for the server side  of
    1487               the link, the second sets the client side.
     1442              The first line sets the comp-lzo setting for the server side of the
     1443              link, the second sets the client side.
    14881444
    14891445       --comp-noadapt
    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.
     1446              When  used in conjunction with --comp-lzo, this option will disable
     1447              OpenVPN's adaptive compression algorithm.  Normally, adaptive  com
     1448              pression is enabled with --comp-lzo.
     1449
     1450              Adaptive compression tries to optimize the case where you have com‐
     1451              pression enabled, but you are sending predominantly  uncompressible
     1452              (or  pre-compressed)  packets  over  the  tunnel, such as an FTP or
     1453              rsync transfer of a large, compressed file.  With adaptive compres‐
     1454              sion,  OpenVPN  will periodically sample the compression process to
     1455              measure its efficiency.  If the data being sent over the tunnel  is
     1456              already  compressed,  the  compression efficiency will be very low,
     1457              triggering openvpn to disable compression  for  a  period  of  time
     1458              until the next re-sample test.
    15031459
    15041460       --management IP port [pw-file]
    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.
     1461              Enable  a  TCP server on IP:port to handle daemon management func‐
     1462              tions.  pw-file, if specified, is  a  password file  (password  on
     1463              first line) or "stdin" to prompt from standard input.  The password
     1464              provided will set the password which TCP clients will need to  pro‐
     1465              vide in order to access management functions.
     1466
     1467              The  management  interface can also listen on a unix domain socket,
     1468              for those platforms that support it.  To use a unix domain  socket,
     1469              specify  the  unix  socket  pathname in place of IP and set port to
     1470              'unix'.  While the default behavior is  to  create  a  unix  domain
     1471              socket  that  may be connected to by any process, the --management-
     1472              client-user and --management-client-group directives can be used to
     1473              restrict access.
     1474
     1475              The management interface provides a special mode where the TCP man‐
     1476              agement link can operate over the tunnel itself.   To  enable  this
     1477              mode,  set  IP  =  "tunnel".  Tunnel mode will cause the management
     1478              interface to listen for a TCP connection on the local  VPN  address
     1479              of the TUN/TAP interface.
     1480
     1481              While  the  management port is designed for programmatic control of
     1482              OpenVPN by other applications, it is  possible  to  telnet  to  the
     1483              port,  using  a  telnet client in "raw" mode.  Once connected, type
     1484              "help" for a list of commands.
     1485
     1486              For detailed documentation on the  management  interface, see  the
     1487              management-notes.txt  file  in the management folder of the OpenVPN
     1488              source distribution.
     1489
     1490              It is strongly recommended that IP be set to 127.0.0.1  (localhost)
     1491              to  restrict  accessibility  of  the  management  server  to  local
     1492              clients.
    15371493
    15381494       --management-client
    1539               Management interface will connect as a TCP/unix domain client to
    1540               IP:port  specified  by  --management rather than listen as a TCP
     1495              Management interface will connect as a TCP/unix  domain  client to
     1496              IP:port  specified  by  --management  rather  than listen as a TCP
    15411497              server or on a unix domain socket.
    15421498
    1543               If the client connection fails to connect or is disconnected,  a
     1499              If the client connection fails to connect  or  is disconnected,  a
    15441500              SIGTERM signal will be generated causing OpenVPN to quit.
    15451501
    15461502       --management-query-passwords
    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.
     1503              Query  management channel for private key password and --auth-user-
     1504              pass username/password.  Only  query  the  management  channel  for
     1505              inputs which ordinarily would have been queried from the console.
    15511506
    15521507       --management-query-proxy
    1553               Query management channel for proxy server information for a spe‐
     1508              Query  management  channel for proxy server information for a spe‐
    15541509              cific --remote (client-only).
    15551510
    15561511       --management-query-remote
    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).
     1512              Allow management interface to override --remote directives (client-
     1513              only).  --management-external-key Allows usage for external private
     1514              key file instead of --key option (client-only).
    15601515
    15611516       --management-forget-disconnect
    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.
     1517              Make OpenVPN forget passwords when management session disconnects.
     1518
     1519              This directive does not affect the --http-proxy  username/password.
     1520              It is always cached.
    15671521
    15681522       --management-hold
    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.
     1523              Start OpenVPN in a hibernating state, until a client of the manage‐
     1524              ment interface explicitly starts it with the hold release command.
    15721525
    15731526       --management-signal
    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.
     1527              Send SIGUSR1 signal to OpenVPN if management  session  disconnects.
     1528              This  is  useful  when you wish to disconnect an OpenVPN session on
     1529              user logoff. For --management-client  this  option  is  not  needed
     1530              since a disconnect will always generate a SIGTERM.
    15781531
    15791532       --management-log-cache n
    1580               Cache the most recent n lines of log file history for  usage  by
    1581               the management channel.
     1533              Cache  the most recent n lines of log file history for usage by the
     1534              management channel.
    15821535
    15831536       --management-up-down
     
    15851538
    15861539       --management-client-auth
    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
    1590               notes.
     1540              Gives management interface client the responsibility  to  authenti‐
     1541              cate clients after their client certificate has been verified.  See
     1542              management-notes.txt in OpenVPN distribution for detailed notes.
    15911543
    15921544       --management-client-pf
    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.
     1545              Management interface clients must specify a packet filter file  for
     1546              each  connecting  client.  See management-notes.txt in OpenVPN dis‐
     1547              tribution for detailed notes.
    15961548
    15971549       --management-client-user u
    1598               When the management interface is  listening  on  a  unix  domain
    1599               socket, only allow connections from user u.
     1550              When the management interface is listening on a unix domain socket,
     1551              only allow connections from user u.
    16001552
    16011553       --management-client-group g
    1602               When  the  management  interface  is  listening on a unix domain
    1603               socket, only allow connections from group g.
     1554              When the management interface is listening on a unix domain socket,
     1555              only allow connections from group g.
    16041556
    16051557       --plugin module-pathname [init-string]
    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.
     1558              Load plug-in module from the file  module-pathname,  passing  init-
     1559              string  as an argument to the module initialization function.  Mul‐
     1560              tiple plugin modules may be loaded into one OpenVPN process.
     1561
     1562              For more information and examples on how to build  OpenVPN  plug-in
     1563              modules,  see  the  README file in the plugin folder of the OpenVPN
     1564              source distribution.
     1565
     1566              If you are using an RPM install of  OpenVPN,  see  /usr/share/open‐
     1567              vpn/plugin.  The documentation is in doc and the actual plugin mod‐
     1568              ules are in lib.
     1569
     1570              Multiple plugin modules can be cascaded, and modules can be used in
     1571              tandem  with scripts.  The modules will be called by OpenVPN in the
     1572              order that they are declared in the config file.  If both a  plugin
     1573              and script are configured for the same callback, the script will be
     1574              called last.  If the return code of the module/script  controls  an
     1575              authentication function (such as tls-verify, auth-user-pass-verify,
     1576              or client-connect), then every module and script must  return  suc‐
     1577              cess (0) in order for the connection to be authenticated.
    16271578
    16281579   Server 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.
     1580       Starting  with  OpenVPN  2.0,  a  multi-client TCP/UDP server mode is sup‐
     1581       ported, and can be enabled with the --mode server option.  In server mode,
     1582       OpenVPN will listen on a single port for incoming client connections.  All
     1583       client connections will be routed through a single tun or  tap  interface.
     1584       This  mode  is designed for scalability and should be able to support hun‐
     1585       dreds or even thousands of clients on sufficiently fast hardware.  SSL/TLS
     1586       authentication must be used in this mode.
    16361587
    16371588       --server network netmask
    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.
     1589              A  helper directive designed to simplify the configuration of Open‐
     1590              VPN's server mode.  This directive will set up  an  OpenVPN  server
     1591              which  will  allocate  addresses  to  clients out of the given net‐
     1592              work/netmask.  The server itself will take the ".1" address of  the
     1593              given  network  for  use  as  the server-side endpoint of the local
     1594              TUN/TAP interface.
    16441595
    16451596              For example, --server 10.8.0.0 255.255.255.0 expands as follows:
     
    16651616                     push "route-gateway 10.8.0.1"
    16661617
    1667               Don't  use --server if you are ethernet bridging.  Use --server-
     1618              Don't use --server if you are  ethernet  bridging.   Use --server-
    16681619              bridge instead.
    16691620
     
    16721623       --server-bridge ['nogw']
    16731624
    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
     1625              A  helper  directive  similar to --server which is designed to sim‐
     1626              plify the configuration of OpenVPN's server mode in ethernet bridg‐
     1627              ing configurations.
     1628
     1629              If --server-bridge is used without any parameters, it will enable a
     1630              DHCP-proxy mode, where connecting OpenVPN clients will  receive  an
     1631              IP  address  for  their TAP adapter from the DHCP server running on
     1632              the OpenVPN server-side LAN.  Note that only clients  that  support
     1633              the binding of a DHCP client with the TAP adapter (such as Windows)
     1634              can support this mode.  The optional nogw flag (advanced) indicates
     1635              that gateway information should not be pushed to the client.
     1636
     1637              To configure ethernet bridging, you must first use your OS's bridg‐
     1638              ing capability to bridge the TAP interface with  the  ethernet  NIC
     1639              interface.  For example, on Linux this is done with the brctl tool,
     1640              and with Windows XP it is done in the Network Connections Panel  by
     1641              selecting  the  ethernet  and  TAP  adapters  and right-clicking on
     1642              "Bridge Connections".
     1643
     1644              Next you you must manually set the IP/netmask on the bridge  inter‐
     1645              face.  The gateway and netmask parameters to --server-bridge can be
     1646              set to either the  IP/netmask  of  the  bridge  interface,  or  the
     1647              IP/netmask of the default gateway/router on the bridged subnet.
     1648
     1649              Finally,  set  aside  a  IP range in the bridged subnet, denoted by
     1650              pool-start-IP and pool-end-IP, for OpenVPN to allocate to  connect‐
     1651              ing clients.
     1652
     1653              For   example,   server-bridge  10.8.0.4  255.255.255.0  10.8.0.128
    17051654              10.8.0.254 expands as follows:
    17061655
     
    17111660                  push "route-gateway 10.8.0.4"
    17121661
    1713               In another example, --server-bridge (without parameters) expands
    1714               as follows:
     1662              In another example, --server-bridge (without parameters) expands as
     1663              follows:
    17151664
    17161665                  mode server
     
    17251674
    17261675       --push option
    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
     1676              Push  a config file option back to the client for remote execution.
     1677              Note that option must be  enclosed  in  double  quotes  ("").   The
     1678              client  must specify --pull in its config file.  The set of options
     1679              which can be pushed is limited by both  feasibility  and  security.
     1680              Some  options such as those which would execute scripts are banned,
     1681              since they would effectively allow a compromised server to  execute
     1682              arbitrary  code  on  the  client.  Other options such as TLS or MTU
     1683              parameters cannot be pushed because the client needs to  know  them
     1684              before the connection to the server can be initiated.
     1685
     1686              This  is  a  partial list of options which can currently be pushed:
     1687              --route, --route-gateway, --route-delay, --redirect-gateway,  --ip-
     1688              win32,  --dhcp-option,  --inactive,  --ping,  --ping-exit,  --ping-
     1689              restart, --setenv, --persist-key,  --persist-tun,  --echo,  --comp-
     1690              lzo, --socket-flags, --sndbuf, --rcvbuf
    17431691
    17441692       --push-reset
    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.
     1693              Don't  inherit the global push list for a specific client instance.
     1694              Specify this option in a client-specific context  such  as  with  a
     1695              --client-config-dir  configuration  file.   This option will ignore
     1696              --push options at the global config file level.
    17491697
    17501698       --push-peer-info
    1751               Push additional information about the  client  to  server.   The
    1752               additional information consists of the following data:
     1699              Push additional information about the client to server.  The  addi‐
     1700              tional information consists of the following data:
    17531701
    17541702              IV_VER=<version> -- the client OpenVPN version
    17551703
    1756               IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]   --  the
     1704              IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]    --    the
    17571705              client OS platform
    17581706
    1759               IV_HWADDR=<mac address> -- the MAC address  of  clients  default
    1760               gateway
     1707              IV_HWADDR=<mac address> -- the MAC address of clients default gate‐
     1708              way
    17611709
    17621710              IV_LZO_STUB=1 -- if client was built with LZO stub capability
    17631711
    1764               UV_<name>=<value>  --  client  environment variables whose names
    1765               start with "UV_"
     1712              UV_<name>=<value> -- client environment variables whose names start
     1713              with "UV_"
    17661714
    17671715       --disable
    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)
     1716              Disable a particular client (based on the common  name)  from con‐
     1717              necting.   Don't  use this option to disable a client due to key or
     1718              password compromise.   Use  a  CRL  (certificate  revocation list)
    17711719              instead (see the --crl-verify option).
    17721720
    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.
     1721              This  option  must  be associated with a specific client instance,
     1722              which means that it must be specified either in a  client  instance
     1723              config  file  using  --client-config-dir  or  dynamically generated
     1724              using a --client-connect script.
    17771725
    17781726       --ifconfig-pool start-IP end-IP [netmask]
    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.
     1727              Set aside a pool of subnets to be dynamically allocated to connect
     1728              ing clients, similar to a DHCP server.  For tun-style tunnels, each
     1729              client will be given a /30 subnet (for interoperability  with  Win
     1730              dows clients).  For tap-style tunnels, individual addresses will be
     1731              allocated, and the optional netmask parameter will also  be  pushed
     1732              to clients.
    17851733
    17861734
    17871735       --ifconfig-pool-persist file [seconds]
    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-
     1736              Persist/unpersist  ifconfig-pool data to file, at seconds intervals
     1737              (default=600), as well as on program startup and shutdown.
     1738
     1739              The goal of this option  is  to provide  a  long-term  association
     1740              between  clients  (denoted by their common name) and the virtual IP
     1741              address assigned to them from  the  ifconfig-pool.   Maintaining  a
     1742              long-term association is good for clients because it allows them to
     1743              effectively use the --persist-tun option.
     1744
     1745              file  is  a comma-delimited  ASCII  file,  formatted  as  <Common-
    17981746              Name>,<IP-address>.
    17991747
    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
     1748              If  seconds = 0, file will be treated as read-only.  This is useful
     1749              if you would like to treat file as a configuration file.
     1750
     1751              Note that the entries in this file are treated by OpenVPN  as  sug‐
     1752              gestions only, based on past associations between a common name and
     1753              IP address.  They do not guarantee that the given common name  will
     1754              always  receive  the  given  IP  address.   If  you want guaranteed
     1755              assignment, use --ifconfig-push
    18081756
    18091757       --ifconfig-pool-linear
    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.
     1758              Modifies the --ifconfig-pool directive to allocate  individual  TUN
     1759              interface  addresses  for  clients  rather than /30 subnets.  NOTE:
     1760              This option is incompatible with Windows clients.
     1761
     1762              This option is deprecated, and should be replaced  with  --topology
     1763              p2p which is functionally equivalent.
    18161764
    18171765       --ifconfig-push local remote-netmask [alias]
    1818               Push  virtual  IP  endpoints  for  client tunnel, overriding the
     1766              Push  virtual  IP  endpoints  for  client  tunnel,  overriding the
    18191767              --ifconfig-pool dynamic allocation.
    18201768
    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
     1769              The parameters local and remote-netmask are set  according  to  the
     1770              --ifconfig  directive  which  you  want  to  execute  on the client
     1771              machine to configure the remote end of the tunnel.  Note  that  the
     1772              parameters local and remote-netmask are from the perspective of the
     1773              client, not the server.  They may  be  DNS  names  rather  than  IP
     1774              addresses, in which case they will be resolved on the server at the
     1775              time of client connection.
     1776
     1777              The optional alias parameter may be used in cases where NAT  causes
     1778              the  client  view  of  its local endpoint to differ from the server
     1779              view.  In this case local/remote-netmask will refer to  the  server
     1780              view while alias/remote-netmask will refer to the client view.
     1781
     1782              This  option  must  be  associated with a specific client instance,
     1783              which means that it must be specified either in a  client  instance
     1784              config  file  using  --client-config-dir  or  dynamically generated
     1785              using a --client-connect script.
     1786
     1787              Remember also to include a --route directive in  the  main  OpenVPN
     1788              config  file  which encloses local, so that the kernel will know to
     1789              route it to the server's TUN/TAP interface.
     1790
     1791              OpenVPN's internal client IP address selection algorithm  works  as
     1792              follows:
     1793
     1794              1  --  Use  --client-connect  script  generated  file for static IP
    18481795              (first choice).
    18491796              2 -- Use --client-config-dir file for static IP (next choice).
    1850               3  --  Use  --ifconfig-pool  allocation  for  dynamic  IP  (last
    1851               choice).
     1797              3 -- Use --ifconfig-pool allocation for dynamic IP (last choice).
    18521798
    18531799       --iroute network [netmask]
    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
     1800              Generate an internal route to a specific client. The netmask param‐
     1801              eter, if omitted, defaults to 255.255.255.255.
     1802
     1803              This  directive can be used to route a fixed subnet from the server
     1804              to a particular client, regardless of where the client is  connect‐
     1805              ing  from.  Remember that you must also add the route to the system
     1806              routing table as well (such as by  using  the  --route  directive).
     1807              The  reason why two routes are needed is that the --route directive
     1808              routes the packet from the kernel to OpenVPN.  Once in OpenVPN, the
     1809              --iroute directive routes to the specific client.
     1810
     1811              This  option  must  be specified either in a client instance config
     1812              file using --client-config-dir or  dynamically  generated  using  a
    18681813              --client-connect script.
    18691814
    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
    1879               client's iroutes.
     1815              The  --iroute  directive  also  has  an  important interaction with
     1816              --push "route ...".  --iroute essentially defines a subnet which is
     1817              owned  by a particular client (we will call this client A).  If you
     1818              would like other clients to be able to reach A's  subnet,  you  can
     1819              use  --push "route ..."  together with --client-to-client to effect
     1820              this.  In order for all clients to see  A's  subnet,  OpenVPN  must
     1821              push  this  route  to all clients EXCEPT for A, since the subnet is
     1822              already owned by A.  OpenVPN accomplishes this by not not pushing a
     1823              route to a client if it matches one of the client's iroutes.
    18801824
    18811825       --client-to-client
    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.
     1826              Because  the OpenVPN server mode handles multiple clients through a
     1827              single tun or tap interface,  it  is  effectively  a router.   The
     1828              --client-to-client  flag  tells OpenVPN to internally route client-
     1829              to-client traffic rather than pushing all client-originating  traf
     1830              fic to the TUN/TAP interface.
     1831
     1832              When  this option is used, each client will "see" the other clients
     1833              which are currently connected.  Otherwise, each  client  will  only
     1834              see the server.  Don't use this option if you want to firewall tun‐
     1835              nel traffic using custom, per-client rules.
    18921836
    18931837       --duplicate-cn
    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.
     1838              Allow multiple clients with the same common  name  to concurrently
     1839              connect.   In the absence of this option, OpenVPN will disconnect a
     1840              client instance upon connection of a new  client  having  the  same
     1841              common name.
    18981842
    18991843       --client-connect cmd
    19001844              Run command cmd on client connection.
    19011845
    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
     1846              cmd  consists  of a path to script (or executable program), option‐
     1847              ally followed by arguments. The path and arguments may  be  single-
     1848              or  double-quoted  and/or  escaped using a backslash, and should be
     1849              separated by one or more spaces.
     1850
     1851              The command is passed the common name and IP address of  the  just-
     1852              authenticated  client as environmental variables (see environmental
     1853              variable section below).  The command is also passed  the  pathname
     1854              of a freshly created temporary file as the last argument (after any
     1855              arguments specified in cmd ), to be used by  the  command  to  pass
     1856              dynamically generated config file directives back to OpenVPN.
     1857
     1858              If the script wants to generate a dynamic config file to be applied
     1859              on the server when the client connects, it should write it  to  the
     1860              file named by the last argument.
     1861
     1862              See  the  --client-config-dir option below for options which can be
     1863              legally used in a dynamically generated config file.
     1864
     1865              Note that the return value of script  is  significant.   If  script
     1866              returns  a  non-zero  error  status, it will cause the client to be
    19241867              disconnected.
    19251868
    19261869       --client-disconnect cmd
    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
    1930               successful (0) status returns.
    1931 
    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 ).
     1870              Like --client-connect but called on client instance shutdown.  Will
     1871              not  be  called  unless the --client-connect script and plugins (if
     1872              defined) were previously called on this  instance  with  successful
     1873              (0) status returns.
     1874
     1875              The exception to this rule is if the --client-disconnect command or
     1876              plugins are cascaded, and at least one client-connect function suc‐
     1877              ceeded, then ALL of the client-disconnect functions for scripts and
     1878              plugins will be called on client instance object deletion, even  in
     1879              cases  where  some of the related client-connect functions returned
     1880              an error status.
     1881
     1882              The --client-disconnect command is passed the same pathname as  the
     1883              corresponding --client-connect command as its last argument. (after
     1884              any arguments specified in cmd ).
    19421885
    19431886       --client-config-dir dir
    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:
     1887              Specify a directory dir for custom client config  files.   After  a
     1888              connecting client has been authenticated, OpenVPN will look in this
     1889              directory for a file having the same name as the client's X509 com‐
     1890              mon  name.  If a matching file exists, it will be opened and parsed
     1891              for client-specific configuration options.  If no matching file  is
     1892              found,  OpenVPN  will  instead try to open and parse a default file
     1893              called "DEFAULT", which may be provided but is not  required.  Note
     1894              that  the  configuration  files  must  be  readable  by the OpenVPN
     1895              process after it has dropped it's root privileges.
     1896
     1897              This file can specify a fixed IP address for a given  client  using
     1898              --ifconfig-push, as well as fixed subnets owned by the client using
     1899              --iroute.
     1900
     1901              One of the useful properties of  this  option  is  that  it  allows
     1902              client  configuration  files to be conveniently created, edited, or
     1903              removed while the server is live, without needing  to  restart  the
     1904              server.
     1905
     1906              The  following  options  are  legal  in  a client-specific context:
    19651907              --push, --push-reset, --iroute, --ifconfig-push, and --config.
    19661908
    19671909       --ccd-exclusive
    1968               Require, as a condition of  authentication,  that  a  connecting
    1969               client has a --client-config-dir file.
     1910              Require, as a condition of authentication, that a connecting client
     1911              has a --client-config-dir file.
    19701912
    19711913       --tmp-dir dir
    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.
     1914              Specify  a  directory dir for temporary files.  This directory will
     1915              be used by openvpn processes and script  to  communicate  temporary
     1916              data  with  openvpn  main  process. Note that the directory must be
     1917              writable by the OpenVPN process after  it  has  dropped  it's  root
     1918              privileges.
    19771919
    19781920              This directory will be used by in the following cases:
    19791921
    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
     1922              *  --client-connect scripts to dynamically generate client-specific
     1923              configuration files.
     1924
     1925              * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY plugin hook to  return  suc‐
     1926              cess/failure via auth_control_file when using deferred auth method
     1927
     1928              *  OPENVPN_PLUGIN_ENABLE_PF plugin hook to pass filtering rules via
     1929              pf_file
    19891930
    19901931       --hash-size r v
    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.
     1932              Set the size of the real address hash table to r  and  the virtual
     1933              address table to v.  By default, both tables are sized at 256 buck‐
     1934              ets.
    19941935
    19951936       --bcast-buffers n
     
    19991940              Maximum number of output packets queued before TCP (default=64).
    20001941
    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.
     1942              When OpenVPN is tunneling data from a TUN/TAP device  to  a remote
     1943              client  over  a  TCP  connection,  it  is possible that the TUN/TAP
     1944              device might produce data at a faster rate than the TCP  connection
     1945              can support.  When the number of output packets queued before send‐
     1946              ing to the TCP socket reaches this limit for a given client connec‐
     1947              tion,  OpenVPN will start to drop outgoing packets directed at this
     1948              client.
    20081949
    20091950       --tcp-nodelay
    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,
    2016               TCP_NODELAY is generally a good latency optimization.
     1951              This macro sets the TCP_NODELAY socket flag on the server  as  well
     1952              as  pushes it to connecting clients.  The TCP_NODELAY flag disables
     1953              the Nagle algorithm on TCP sockets causing packets to be  transmit‐
     1954              ted  immediately  with  low  latency,  rather  than waiting a short
     1955              period of time in order to aggregate several packets into a  larger
     1956              containing  packet.   In  VPN applications over TCP, TCP_NODELAY is
     1957              generally a good latency optimization.
    20171958
    20181959              The macro expands as follows:
     
    20261967
    20271968       --max-routes-per-client n
    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.
     1969              Allow a maximum of n  internal  routes  per  client  (default=256).
     1970              This is designed to help contain DoS attacks where an authenticated
     1971              client floods the server with packets appearing to come  from  many
     1972              unique  MAC addresses, forcing the server to deplete virtual memory
     1973              as its internal routing table expands.  This directive can be  used
     1974              in  a --client-config-dir file or auto-generated by a --client-con‐
     1975              nect script to override the global value for a particular client.
     1976
     1977              Note that this directive affects OpenVPN's internal routing  table,
     1978              not the kernel routing table.
    20391979
    20401980       --stale-routes-check n [t]
    2041               Remove  routes haven't had activity for n seconds (i.e. the age‐
    2042               ing time).
     1981              Remove  routes  haven't had activity for n seconds (i.e. the ageing
     1982              time).
    20431983
    20441984              This check is ran every t seconds (i.e. check interval).
     
    20461986              If t is not present it defaults to n
    20471987
    2048               This option helps to keep the dynamic routing table small.   See
     1988              This option helps to keep the dynamic  routing  table small.   See
    20491989              also --max-routes-per-client
    20501990
    20511991       --connect-freq n sec
    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
     1992              Allow  a maximum of n new connections per sec seconds from clients.
     1993              This is designed to contain DoS attacks which flood the server with
     1994              connection  requests  using certificates which will ultimately fail
     1995              to authenticate.
     1996
     1997              This is an imperfect solution however, because in a real  DoS  sce‐
     1998              nario, legitimate connections might also be refused.
     1999
     2000              For  the  best  protection against DoS attacks in server mode, use
    20612001              --proto udp and --tls-auth.
    20622002
     
    20642004              Run command cmd to validate client virtual addresses or routes.
    20652005
    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‐
     2006              cmd consists of a path to script (or executable  program),  option‐
     2007              ally  followed  by arguments. The path and arguments may be single-
     2008              or double-quoted and/or escaped using a backslash,  and  should  be
     2009              separated by one or more spaces.
     2010
     2011              Three  arguments  will be appended to any arguments in cmd as fol‐
    20722012              lows:
    20732013
    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
    2095               than the low level client virtual addresses.
     2014              [1] operation -- "add", "update", or "delete" based on  whether  or
     2015              not  the address is being added to, modified, or deleted from Open‐
     2016              VPN's internal routing table.
     2017              [2] address -- The address being learned or unlearned.  This can be
     2018              an  IPv4  address  such  as "198.162.10.14", an IPv4 subnet such as
     2019              "198.162.10.0/24", or an ethernet MAC address (when  --dev  tap  is
     2020              being used) such as "00:FF:01:02:03:04".
     2021              [3]  common  name -- The common name on the certificate associated
     2022              with the client linked to this address.  Only present for "add"  or
     2023              "update" operations, not "delete".
     2024
     2025              On  "add" or "update" methods, if the script returns a failure code
     2026              (non-zero), OpenVPN will reject the address and will not modify its
     2027              internal routing table.
     2028
     2029              Normally, the cmd script will use the information provided above to
     2030              set appropriate firewall entries  on  the  VPN  TUN/TAP  interface.
     2031              Since  OpenVPN  provides  the association between virtual IP or MAC
     2032              address and the client's authenticated common  name,  it  allows  a
     2033              user-defined  script  to  configure  firewall  access policies with
     2034              regard to the client's high-level common name, rather than the  low
     2035              level client virtual addresses.
    20962036
    20972037       --auth-user-pass-verify cmd method
    2098               Require  the  client to provide a username/password (possibly in
     2038              Require  the  client  to  provide a username/password (possibly in
    20992039              addition to a client certificate) for authentication.
    21002040
    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
    2144               escaped or evaluated by a shell interpreter.
    2145 
    2146               For  a  sample script that performs PAM authentication, see sam‐
    2147               ple-scripts/auth-pam.pl in the OpenVPN source distribution.
     2041              OpenVPN will run command cmd to validate the username/password pro‐
     2042              vided by the client.
     2043
     2044              cmd  consists  of a path to script (or executable program), option‐
     2045              ally followed by arguments. The path and arguments may  be  single-
     2046              or  double-quoted  and/or  escaped using a backslash, and should be
     2047              separated by one or more spaces.
     2048
     2049              If method is set to "via-env", OpenVPN will call  script  with  the
     2050              environmental  variables  username  and  password  set to the user‐
     2051              name/password strings provided by the client.  Be aware  that  this
     2052              method  is insecure on some platforms which make the environment of
     2053              a process publicly visible to other unprivileged processes.
     2054
     2055              If method is set to "via-file", OpenVPN will write the username and
     2056              password  to the first two lines of a temporary file.  The filename
     2057              will be passed as an argument to script, and the file will be auto‐
     2058              matically  deleted  by OpenVPN after the script returns.  The loca‐
     2059              tion of the temporary file is controlled by the  --tmp-dir  option,
     2060              and  will  default  to  the  current directory if unspecified.  For
     2061              security, consider setting --tmp-dir to a volatile  storage  medium
     2062              such  as  /dev/shm  (if available) to prevent the username/password
     2063              file from touching the hard drive.
     2064
     2065              The script should examine the username and  password,  returning  a
     2066              success  exit code (0) if the client's authentication request is to
     2067              be accepted, or a failure code (1) to reject the client.
     2068
     2069              This directive is designed to enable a plugin-style  interface  for
     2070              extending OpenVPN's authentication capabilities.
     2071
     2072              To  protect  against a client passing a maliciously formed username
     2073              or password string, the username string must consist only of  these
     2074              characters: alphanumeric, underbar ('_'), dash ('-'), dot ('.'), or
     2075              at ('@').  The password string can consist of any printable charac‐
     2076              ters  except  for  CR  or LF.  Any illegal characters in either the
     2077              username or password string will be converted to underbar ('_').
     2078
     2079              Care must be taken by any user-defined scripts to avoid creating  a
     2080              security  vulnerability  in the way that these strings are handled.
     2081              Never use these strings in such a way that they might be escaped or
     2082              evaluated by a shell interpreter.
     2083
     2084              For  a  sample script that performs PAM authentication, see sample-
     2085              scripts/auth-pam.pl in the OpenVPN source distribution.
    21482086
    21492087       --opt-verify
    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.
     2088              Clients that connect with options that are incompatible with  those
     2089              of the server will be disconnected.
     2090
     2091              Options  that  will be compared for compatibility include dev-type,
     2092              link-mtu, tun-mtu, proto, tun-ipv6, ifconfig,  comp-lzo,  fragment,
     2093              keydir,  cipher, auth, keysize, secret, no-replay, no-iv, tls-auth,
     2094              key-method, tls-server, and tls-client.
    21572095
    21582096              This option requires that --disable-occ NOT be used.
    21592097
    21602098       --auth-user-pass-optional
    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.
     2099              Allow connections by clients that do not specify  a  username/pass‐
     2100              word.   Normally,  when  --auth-user-pass-verify  or  --management-
     2101              client-auth is specified (or an authentication plugin module),  the
     2102              OpenVPN  server daemon will require connecting clients to specify a
     2103              username and password.  This option makes the submission of a user‐
     2104              name/password  by  clients  optional, passing the responsibility to
     2105              the user-defined authentication module/script to accept or deny the
     2106              client based on other factors (such as the setting of X509 certifi‐
     2107              cate fields).  When this option is used, and  a  connecting  client
     2108              does  not  submit a username/password, the user-defined authentica‐
     2109              tion module/script will see the username and password as being  set
     2110              to  empty strings ("").  The authentication module/script MUST have
     2111              logic to detect this condition and respond accordingly.
    21752112
    21762113       --client-cert-not-required
    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.
     2114              Don't require client certificate, client  will  authenticate using
     2115              username/password only.  Be aware that using this directive is less
     2116              secure than requiring certificates from all clients.
     2117
     2118              If you use this directive, the entire responsibility of authentica
     2119              tion  will  rest on your --auth-user-pass-verify script, so keep in
     2120              mind that bugs in your  script  could  potentially  compromise  the
     2121              security of your VPN.
     2122
     2123              If  you  don't use this directive, but you also specify an --auth-
     2124              user-pass-verify script, then OpenVPN will perform double authenti‐
     2125              cation.   The  client certificate verification AND the --auth-user-
     2126              pass-verify script will need to succeed in order for a client to be
     2127              authenticated and accepted onto the VPN.
    21912128
    21922129       --username-as-common-name
    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.
    2196 
    2197        --compat-names [no-remapping]
    2198               Until OpenVPN v2.3 the format of the X.509  Subject  fields  was
    2199               formatted like this:
     2130              For  --auth-user-pass-verify  authentication, use the authenticated
     2131              username as the common name, rather than the common name  from  the
     2132              client cert.
     2133
     2134       --compat-names [no-remapping] (DEPRECATED)
     2135              Until  OpenVPN v2.3 the format of the X.509 Subject fields was for‐
     2136              matted like this:
    22002137
    22012138              /C=US/L=Somewhere/CN=John Doe/emailAddress=john@example.com
    22022139
    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:
     2140              In addition the old behavivour was to  remap  any  character other
     2141              than  alphanumeric,  underscore  ('_'),  dash ('-'), dot ('.'), and
     2142              slash ('/') to underscore  ('_').   The  X.509  Subject  string as
     2143              returned  by  the tls_id environmental variable, could additionally
     2144              contain colon (':') or equal ('=').
     2145
     2146              When using the  --compat-names  option,  this  old  formatting and
     2147              remapping will be re-enabled again.  This is purely implemented for
     2148              compatibility reasons when using older plug-ins  or  scripts  which
     2149              does not handle the new formatting or UTF-8 characters.
     2150
     2151              In  OpenVPN v2.3 the formatting of these fields changed into a more
     2152              standardised format.  It now looks like:
    22162153
    22172154              C=US, L=Somewhere, CN=John Doe, emailAddress=john@example.com
    22182155
    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.
     2156              The new default format in OpenVPN v2.3 also does not do the charac‐
     2157              ter  remapping  which  happened  earlier.   This new format enables
     2158              proper support for UTF-8 characters in the usernames, X.509 Subject
     2159              fields  and  Common Name variables and it complies to the RFC 2253,
     2160              UTF-8 String Representation of Distinguished Names.
     2161
     2162              The no-remapping mode flag can  be  used  with  the  --compat-names
     2163              option to be compatible with the now deprecated --no-name-remapping
     2164              option.  It is only available at the server. When this mode flag is
     2165              used, the Common Name, Subject, and username strings are allowed to
     2166              include any printable character including space, but excluding con‐
     2167              trol  characters  such  as  tab,  newline, and carriage-return. no-
     2168              remapping is only available on the server side.
     2169
     2170              Please note: This option is immediately  deprecated.   It  is  only
     2171              implemented  to  make  the  transition  to  the new formatting less
     2172              intrusive.  It will be removed either in OpenVPN v2.4 or v2.5.   So
     2173              please  make  sure you use the --verify-x509-name option instead of
     2174              --tls-remote as soon as possible and update your scripts where nec‐
     2175              essary.
     2176
     2177       --no-name-remapping (DEPRECATED)
     2178              The   --no-name-remapping   option   is   an   alias   for   --com‐
     2179              pat-names no-remapping.  It ensures compatibility with server  con‐
     2180              figurations using the --no-name-remapping option.
     2181
     2182              Please  note:  This  option  is now deprecated.  It will be removed
     2183              either in OpenVPN v2.4 or v2.5.  So please make  sure  you  support
     2184              the  new  X.509  name  formatting described with the --compat-names
     2185              option as soon as possible.
    22402186
    22412187       --port-share host port [dir]
    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.
     2188              When run in TCP server mode, share the OpenVPN  port  with another
     2189              application,  such as an HTTPS server.  If OpenVPN senses a connec
     2190              tion to its port which is using a  non-OpenVPN  protocol,  it  will
     2191              proxy  the  connection  to the server at host:port.  Currently only
     2192              designed to work with HTTP/HTTPS, though it would be  theoretically
     2193              possible to extend to other protocols such as ssh.
     2194
     2195              dir  specifies  an  optional  directory where a temporary file with
     2196              name N containing content C will be dynamically generated for  each
     2197              proxy  connection, where N is the source IP:port of the client con‐
     2198              nection and C is the source IP:port of the connection to the  proxy
     2199              receiver.   This directory can be used as a dictionary by the proxy
     2200              receiver to determine the origin of the connection.  Each generated
     2201              file  will  be automatically deleted when the proxied connection is
     2202              torn down.
    22572203
    22582204              Not implemented on Windows.
    22592205
    22602206   Client Mode
    2261        Use  client  mode  when  connecting  to  an  OpenVPN  server  which has
    2262        --server, --server-bridge, or --mode server in it's configuration.
     2207       Use client mode when connecting to an OpenVPN server which  has  --server,
     2208       --server-bridge, or --mode server in it's configuration.
    22632209
    22642210       --client
    2265               A helper directive designed to  simplify  the  configuration  of
    2266               OpenVPN's client mode.  This directive is equivalent to:
     2211              A  helper directive designed to simplify the configuration of Open‐
     2212              VPN's client mode.  This directive is equivalent to:
    22672213
    22682214                   pull
    22692215                   tls-client
    22702216
    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
    2280               client's routing table.
     2217       --pull This option must be used on a  client  which  is  connecting  to a
     2218              multi-client server.  It indicates to OpenVPN that it should accept
     2219              options pushed by the server, provided they are part of  the  legal
     2220              set  of pushable options (note that the --pull option is implied by
     2221              --client ).
     2222
     2223              In particular, --pull allows the  server  to  push  routes  to the
     2224              client,  so  you  should  not  use --pull or --client in situations
     2225              where you don't trust the server to have control over the  client's
     2226              routing table.
    22812227
    22822228       --auth-user-pass [up]
    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
     2229              Authenticate  with  server  using  username/password.  up is a file
     2230              containing username/password on 2 lines (Note:  OpenVPN  will only
     2231              read  passwords from a file if it has been built with the --enable-
     2232              password-save  configure  option,  or  on   Windows   by   defining
     2233              ENABLE_PASSWORD_SAVE in win/settings.in).
     2234
     2235              If  up is omitted, username/password will be prompted from the con‐
     2236              sole.
     2237
     2238              The server configuration must  specify  an --auth-user-pass-verify
    22932239              script to verify the username/password provided by the client.
    22942240
    22952241       --auth-retry type
    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
    2299               password.
    2300 
    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
     2242              Controls  how  OpenVPN  responds  to username/password verification
     2243              errors such as the client-side response to an  AUTH_FAILED  message
     2244              from  the  server  or verification failure of the private key pass‐
     2245              word.
     2246
     2247              Normally used to prevent auth errors from being fatal on the client
     2248              side, and to permit username/password requeries in case of error.
     2249
     2250              An  AUTH_FAILED  message  is  generated by the server if the client
     2251              fails  --auth-user-pass  authentication,  or  if  the   server-side
     2252              --client-connect  script  returns  an  error status when the client
    23082253              tries to connect.
    23092254
    23102255              type can be one of:
    23112256
    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
     2257              none -- Client will exit with a fatal error (this is the default).
     2258              nointeract -- Client will retry the connection  without  requerying
     2259              for  an  --auth-user-pass  username/password.   Use this option for
     2260              unattended clients.
     2261              interact -- Client  will  requery  for  an  --auth-user-pass  user‐
     2262              name/password  and/or  private  key  password  before  attempting a
    23192263              reconnection.
    23202264
    2321               Note  that  while  this  option cannot be pushed, it can be con‐
    2322               trolled from the management interface.
     2265              Note that while this option cannot be pushed, it can be  controlled
     2266              from the management interface.
    23232267
    23242268       --static-challenge t e
    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.
     2269              Enable  static  challenge/response protocol using challenge text t,
     2270              with echo flag given by e (0|1).
     2271
     2272              The echo flag indicates whether or not the user's response  to  the
     2273              challenge should be echoed.
     2274
     2275              See management-notes.txt in the OpenVPN distribution for a descrip‐
     2276              tion of the OpenVPN challenge/response protocol.
    23332277
    23342278       --server-poll-timeout n
    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.
     2279              when polling possible remote servers to connect to in a round-robin
     2280              fashion, spend no more than n seconds waiting for a response before
     2281              trying the next server.
    23382282
    23392283       --explicit-exit-notify [n]
    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.
     2284              In UDP client mode or point-to-point mode, send server/peer an exit
     2285              notification  if  tunnel is restarted or OpenVPN process is exited.
     2286              In client mode, on exit/restart, this option will tell  the  server
     2287              to immediately close its client instance object rather than waiting
     2288              for a timeout.  The n parameter (default=1)  controls  the  maximum
     2289              number  of  attempts  that  the  client will try to resend the exit
     2290              notification message.  OpenVPN will not send any exit notifications
     2291              unless this option is enabled.
    23482292
    23492293   Data Channel Encryption Options:
    2350        These options are meaningful for both Static & TLS-negotiated key modes
     2294       These  options  are meaningful for both Static & TLS-negotiated key modes
    23512295       (must be compatible between peers).
    23522296
    23532297       --secret file [direction]
    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
     2298              Enable Static Key encryption mode (non-TLS).  Use pre-shared secret
     2299              file which was generated with --genkey.
     2300
     2301              The optional direction parameter enables the use of 4 distinct keys
     2302              (HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so  that
     2303              each  data  flow  direction  has a different set of HMAC and cipher
     2304              keys.  This has a number of desirable security properties including
     2305              eliminating certain kinds of DoS and message replay attacks.
     2306
     2307              When  the  direction parameter is omitted, 2 keys are used bidirec‐
     2308              tionally, one for HMAC and the other for encryption/decryption.
     2309
     2310              The direction parameter should always be  complementary  on  either
     2311              side  of the connection, i.e. one side should use "0" and the other
     2312              should use "1", or both sides should omit it altogether.
     2313
     2314              The direction parameter requires that file contains a 2048 bit key.
     2315              While  pre-1.5 versions of OpenVPN generate 1024 bit key files, any
     2316              version of OpenVPN which supports  the  direction  parameter,  will
     2317              also  support  2048  bit  key  file  generation  using the --genkey
     2318              option.
     2319
     2320              Static key encryption mode  has  certain  advantages,  the  primary
    23792321              being ease of configuration.
    23802322
    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.
     2323              There are no certificates or certificate authorities or complicated
     2324              negotiation handshakes and protocols.  The only requirement is that
     2325              you  have a pre-existing secure channel with your peer (such as ssh
     2326              ) to initially copy the key.  This requirement, along with the fact
     2327              that your key never changes unless you manually generate a new one,
     2328              makes it somewhat less secure than TLS mode  (see  below).   If  an
     2329              attacker  manages  to  steal  your  key,  everything  that was ever
     2330              encrypted with it is compromised.  Contrast  that  to  the  perfect
     2331              forward  secrecy  features  of  TLS  mode (using Diffie Hellman key
     2332              exchange), where even if an attacker was able to steal your private
     2333              key,  he  would  gain  no information to help him decrypt past ses‐
     2334              sions.
     2335
     2336              Another advantageous aspect of Static Key encryption mode  is  that
     2337              it  is  a handshake-free protocol without any distinguishing signa‐
     2338              ture or feature (such as a header or protocol  handshake  sequence)
     2339              that  would mark the ciphertext packets as being generated by Open
     2340              VPN.  Anyone eavesdropping on the wire would see nothing  but  ran‐
     2341              dom-looking data.
    24002342
    24012343       --key-direction
    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).
     2344              Alternative  way of specifying the optional direction parameter for
     2345              the --tls-auth and --secret options. Useful when using inline files
     2346              (See section on inline files).
    24052347
    24062348       --auth alg
    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
     2349              Authenticate  packets with HMAC using message digest algorithm alg.
     2350              (The default is SHA1 ).  HMAC is a commonly used message  authenti‐
     2351              cation algorithm (MAC) that uses a data string, a secure hash algo‐
     2352              rithm, and a key, to produce a digital signature.
     2353
     2354              OpenVPN's usage of HMAC is to first encrypt a packet, then HMAC the
     2355              resulting ciphertext.
     2356
     2357              In  static-key encryption mode, the HMAC key is included in the key
     2358              file generated by --genkey.  In TLS mode, the HMAC key  is  dynami‐
     2359              cally  generated and shared between peers via the TLS control chan‐
     2360              nel.  If OpenVPN receives a packet with a bad HMAC it will drop the
     2361              packet.  HMAC usually adds 16 or 20 bytes per packet.  Set alg=none
     2362              to disable authentication.
     2363
     2364              For        more        information        on        HMAC        see
    24232365              http://www.cs.ucsd.edu/users/mihir/papers/hmac.html
    24242366
    24252367       --cipher alg
    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‐
     2368              Encrypt  packets with cipher algorithm alg.  The default is BF-CBC,
     2369              an abbreviation for Blowfish in Cipher Block Chaining mode.   Blow‐
     2370              fish  has  the  advantages of being fast, very secure, and allowing
     2371              key sizes of up to 448 bits.  Blowfish is designed to  be  used  in
     2372              situations where keys are changed infrequently.
     2373
     2374              For   more   information   on   blowfish,  see  http://www.counter‐
    24332375              pane.com/blowfish.html
    24342376
    2435               To  see  other  ciphers that are available with OpenVPN, use the
     2377              To see other ciphers that  are  available  with  OpenVPN,  use the
    24362378              --show-ciphers option.
    24372379
    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.
     2380              OpenVPN supports the CBC, CFB, and OFB cipher modes, however CBC is
     2381              recommended and CFB and OFB should be considered advanced modes.
    24412382
    24422383              Set alg=none to disable encryption.
    24432384
    24442385       --keysize n
    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.
     2386              Size of cipher key in bits (optional).  If unspecified, defaults to
     2387              cipher-specific  default.   The  --show-ciphers  option (see below)
     2388              shows all available OpenSSL ciphers, their default key  sizes,  and
     2389              whether  the  key  size  can  be  changed.   Use care in changing a
     2390              cipher's default key size.  Many ciphers have not been  extensively
     2391              cryptanalyzed  with  non-standard key lengths, and a larger key may
     2392              offer no real guarantee of greater security,  or  may  even  reduce
     2393              security.
    24532394
    24542395       --prng alg [nsl]
    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.
     2396              (Advanced)  For  PRNG  (Pseudo-random number generator), use digest
     2397              algorithm alg (default=sha1), and set nsl (default=16) to the  size
     2398              in bytes of the nonce secret length (between 16 and 64).
     2399
     2400              Set  alg=none  to  disable  the PRNG and use the OpenSSL RAND_bytes
     2401              function instead for all of OpenVPN's pseudo-random number needs.
    24622402
    24632403       --engine [engine-name]
    24642404              Enable OpenSSL hardware-based crypto engine functionality.
    24652405
    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.
     2406              If engine-name is specified, use a specific crypto engine.  Use the
     2407              --show-engines  standalone  option to list the crypto engines which
     2408              are supported by OpenSSL.
    24692409
    24702410       --no-replay
    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.
     2411              (Advanced) Disable OpenVPN's  protection  against  replay attacks.
     2412              Don't use this option unless you are prepared to make a tradeoff of
     2413              greater efficiency in exchange for less security.
    24742414
    24752415              OpenVPN provides datagram replay protection by default.
    24762416
    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
     2417              Replay protection is accomplished by tagging each outgoing datagram
     2418              with  an  identifier  that  is  guaranteed to be unique for the key
     2419              being used.  The peer that receives the datagram will check for the
     2420              uniqueness  of  the  identifier.   If  the  identifier  was already
     2421              received in a previous datagram,  OpenVPN  will  drop  the  packet.
     2422              Replay  protection  is  important  to  defeat attacks such as a SYN
     2423              flood attack, where the attacker listens in the wire, intercepts  a
     2424              TCP SYN packet (identifying it by the context in which it occurs in
     2425              relation to other packets), then floods  the  receiving  peer  with
     2426              copies of this packet.
     2427
     2428              OpenVPN's  replay  protection is implemented in slightly different
    24892429              ways, depending on the key management mode you have selected.
    24902430
    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
     2431              In Static Key mode or when using an CFB or OFB mode cipher, OpenVPN
     2432              uses  a 64 bit unique identifier that combines a time stamp with an
     2433              incrementing sequence number.
     2434
     2435              When using TLS mode for key exchange and a CBC cipher mode, OpenVPN
     2436              uses  only  a  32  bit  sequence number without a time stamp, since
     2437              OpenVPN can guarantee the uniqueness of this value  for  each  key.
     2438              As  in  IPSec,  if the sequence number is close to wrapping back to
     2439              zero, OpenVPN will trigger a new key exchange.
     2440
     2441              To check for replays, OpenVPN uses  the  sliding  window algorithm
    25022442              used by IPSec.
    25032443
    25042444       --replay-window n [t]
    2505               Use a replay protection sliding-window of size n and a time win‐
    2506               dow of t seconds.
     2445              Use  a replay protection sliding-window of size n and a time window
     2446              of t seconds.
    25072447
    25082448              By default n is 64 (the IPSec default) and t is 15 seconds.
    25092449
    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
     2450              This option is only relevant in UDP mode, i.e.  when either --proto
     2451              udp is specifed, or no --proto option is specified.
     2452
     2453              When  OpenVPN tunnels IP packets over UDP, there is the possibility
     2454              that packets might be dropped or delivered out of  order.   Because
     2455              OpenVPN,  like  IPSec,  is emulating the physical network layer, it
     2456              will accept an out-of-order packet sequence, and will deliver  such
     2457              packets in the same order they were received to the TCP/IP protocol
     2458              stack, provided they satisfy several constraints.
     2459
     2460              (a) The packet cannot be a replay (unless --no-replay is specified,
     2461              which disables replay protection altogether).
     2462
     2463              (b)  If  a packet arrives out of order, it will only be accepted if
     2464              the difference between its sequence number and the highest sequence
     2465              number received so far is less than n.
     2466
     2467              (c)  If  a packet arrives out of order, it will only be accepted if
     2468              it arrives no later than t seconds after any  packet  containing  a
     2469              higher sequence number.
     2470
     2471              If you are using a network link with a large pipeline (meaning that
     2472              the product of bandwidth and latency is high), you may want to  use
     2473              a  larger value for n.  Satellite links in particular often require
     2474              this.
     2475
     2476              If you run OpenVPN at --verb 4, you will see the  message  "Replay-
     2477              window backtrack occurred [x]" every time the maximum sequence num‐
     2478              ber backtrack seen thus far increases.  This can be used  to  cali‐
     2479              brate n.
     2480
     2481              There  is  some  controversy  on the appropriate method of handling
    25432482              packet reordering at the security layer.
    25442483
    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.
     2484              Namely, to what extent should the security layer protect the encap‐
     2485              sulated protocol from attacks which masquerade as the kinds of nor‐
     2486              mal packet loss and reordering that occur over IP networks?
     2487
     2488              The IPSec and OpenVPN approach is to allow packet reordering within
     2489              a certain fixed sequence number window.
     2490
     2491              OpenVPN adds to the IPSec model by limiting the window size in time
     2492              as well as sequence space.
     2493
     2494              OpenVPN also adds TCP transport as an option (not offered by IPSec)
     2495              in which case OpenVPN can adopt a very strict attitude towards mes‐
     2496              sage deletion and reordering:  Don't allow it.  Since  TCP  guaran‐
     2497              tees  reliability,  any  packet  loss  or  reordering  event can be
     2498              assumed to be an attack.
     2499
     2500              In this sense, it could be argued that TCP tunnel transport is pre‐
     2501              ferred  when  tunneling  non-IP  or UDP application protocols which
     2502              might be vulnerable to a  message  deletion  or  reordering  attack
     2503              which  falls  within  the  normal operational parameters of IP net‐
     2504              works.
     2505
     2506              So I would make the statement that one should never tunnel a non-IP
     2507              protocol  or  UDP  application  protocol  over UDP, if the protocol
     2508              might be vulnerable to a message deletion or reordering attack that
     2509              falls  within  the  normal  operating  parameters  of what is to be
     2510              expected from the physical IP layer.  The problem is  easily  fixed
     2511              by simply using TCP as the VPN transport layer.
    25742512
    25752513       --mute-replay-warnings
    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
    2579               warnings about duplicate packets.
     2514              Silence  the  output  of  replay warnings, which are a common false
     2515              alarm on WiFi networks.  This option preserves the security of  the
     2516              replay  protection code without the verbosity associated with warn‐
     2517              ings about duplicate packets.
    25802518
    25812519       --replay-persist file
    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
    2588               and stopped.
    2589 
    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.
     2520              Persist replay-protection state across sessions using file to  save
     2521              and reload the state.
     2522
     2523              This  option  will  strengthen  protection  against replay attacks,
     2524              especially when you are using OpenVPN in a dynamic context (such as
     2525              with  --inetd)  when  OpenVPN  sessions  are frequently started and
     2526              stopped.
     2527
     2528              This option will keep a disk copy of the current replay  protection
     2529              state  (i.e.  the  most recent packet timestamp and sequence number
     2530              received from the remote peer), so that if an  OpenVPN  session  is
     2531              stopped  and restarted, it will reject any replays of packets which
     2532              were already received by the prior session.
     2533
     2534              This option only makes sense when replay protection is enabled (the
     2535              default) and you are using either --secret (shared-secret key mode)
     2536              or TLS mode with --tls-auth.
    25992537
    26002538       --no-iv
    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
     2539              (Advanced) Disable OpenVPN's use of IV (cipher initialization  vec‐
     2540              tor).   Don't  use  this  option  unless you are prepared to make a
     2541              tradeoff of greater efficiency in exchange for less security.
     2542
     2543              OpenVPN uses an IV by default, and requires  it  for  CFB  and OFB
     2544              cipher  modes (which are totally insecure without it).  Using an IV
     2545              is  important  for  security  when  multiple  messages  are  being
    26082546              encrypted/decrypted with the same key.
    26092547
     
    26122550              In CBC mode, OpenVPN uses a pseudo-random IV for each packet.
    26132551
    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
    2617               for datagram replay protection as the IV.
     2552              In  CFB/OFB  mode,  OpenVPN  uses a unique sequence number and time
     2553              stamp as the IV.  In fact, in CFB/OFB mode, OpenVPN uses a datagram
     2554              space-saving optimization that uses the unique identifier for data‐
     2555              gram replay protection as the IV.
    26182556
    26192557       --use-prediction-resistance
    26202558              Enable prediction resistance on PolarSSL's RNG.
    26212559
    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
     2560              Enabling prediction resistance causes the RNG  to  reseed  in each
     2561              call  for random. Reseeding this often can quickly deplete the ker‐
     2562              nel entropy pool.
     2563
     2564              If you need this option, please consider running a daemon that adds
     2565              entropy to the kernel pool.
     2566
     2567              Note  that  this  option  only works with PolarSSL versions greater
    26302568              than 1.1.
    26312569
    26322570       --test-crypto
    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.
     2571              Do a self-test  of  OpenVPN's  crypto  options  by  encrypting  and
     2572              decrypting  test  packets using the data channel encryption options
     2573              specified above.  This option does not require a peer to  function,
     2574              and therefore can be specified without --dev or --remote.
    26382575
    26392576              The typical usage of --test-crypto would be something like this:
     
    26452582              openvpn --test-crypto --secret key --verb 9
    26462583
    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.
     2584              This option is very useful to test OpenVPN after it has been ported
     2585              to a new platform, or to isolate problems in the compiler,  OpenSSL
     2586              crypto  library, or OpenVPN's crypto code.  Since it is a self-test
     2587              mode, problems with encryption and authentication can  be  debugged
     2588              independently of network and tunnel issues.
    26522589
    26532590   TLS Mode Options:
    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‐
     2591       TLS  mode is the most powerful crypto mode of OpenVPN in both security and
     2592       flexibility.  TLS mode works by establishing  control  and  data  channels
     2593       which are multiplexed over a single TCP/UDP port.  OpenVPN initiates a TLS
     2594       session over the control channel and uses it to exchange cipher  and  HMAC
     2595       keys  to  protect  the  data  channel.  TLS mode uses a robust reliability
     2596       layer over the UDP connection for all control channel communication, while
     2597       the  data  channel,  over which encrypted tunnel data passes, is forwarded
     2598       without any mediation.  The result is the best of both worlds: a fast data
     2599       channel that forwards over UDP with only the overhead of encrypt, decrypt,
     2600       and HMAC functions, and a control channel that provides all of  the  secu‐
     2601       rity  features  of  TLS,  including  certificate-based  authentication and
     2602       Diffie Hellman forward secrecy.
     2603
     2604       To use TLS mode, each peer that runs OpenVPN should  have  its  own  local
     2605       certificate/key  pair ( --cert and --key ), signed by the root certificate
     2606       which is specified in --ca.
     2607
     2608       When two OpenVPN peers connect, each presents its local certificate to the
     2609       other.   Each  peer will then check that its partner peer presented a cer‐
     2610       tificate which was signed by the master root certificate as  specified  in
     2611       --ca.
     2612
     2613       If  that  check on both peers succeeds, then the TLS negotiation will suc‐
     2614       ceed, both OpenVPN peers will exchange temporary  session  keys,  and  the
     2615       tunnel will begin passing data.
     2616
     2617       The  OpenVPN  distribution contains a set of scripts for managing RSA cer‐
     2618       tificates & keys, located in the easy-rsa subdirectory.
     2619
     2620       The easy-rsa package is also  rendered  in  web  form  here:  http://open‐
    26852621       vpn.net/easyrsa.html
    26862622
    26872623       --tls-server
    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.
     2624              Enable  TLS and assume server role during TLS handshake.  Note that
     2625              OpenVPN is designed as a peer-to-peer application.  The designation
     2626              of  client or server is only for the purpose of negotiating the TLS
     2627              control channel.
    26922628
    26932629       --tls-client
     
    26952631
    26962632       --ca file
    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:
     2633              Certificate authority (CA) file in .pem format, also referred to as
     2634              the  root certificate.  This file can have multiple certificates in
     2635              .pem format, concatenated together.  You  can  construct  your  own
     2636              certificate  authority  certificate and private key by using a com‐
     2637              mand such as:
    27022638
    27032639              openssl req -nodes -new -x509 -keyout ca.key -out ca.crt
    27042640
    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.
     2641              Then edit your openssl.cnf file and edit the  certificate  variable
     2642              to point to your new root certificate ca.crt.
     2643
     2644              For testing purposes only, the OpenVPN distribution includes a sam‐
     2645              ple CA certificate (ca.crt).  Of course you should  never  use  the
     2646              test  certificates and test keys distributed with OpenVPN in a pro‐
     2647              duction environment, since by virtue of the fact that they are dis‐
     2648              tributed with OpenVPN, they are totally insecure.
    27132649
    27142650       --capath dir
    2715               Directory  containing  trusted  certificates  (CAs  and   CRLs).
    2716               Available with OpenSSL version >= 0.9.7 dev.  Not available with
     2651              Directory  containing  trusted certificates (CAs and CRLs).  Avail‐
     2652              able with  OpenSSL  version  >=  0.9.7  dev.   Not  available with
    27172653              PolarSSL.
    27182654
    27192655       --dh file
    2720               File  containing  Diffie  Hellman  parameters  in  .pem   format
    2721               (required for --tls-server only). Use
     2656              File  containing Diffie Hellman parameters in .pem format (required
     2657              for --tls-server only). Use
    27222658
    27232659              openssl dhparam -out dh1024.pem 1024
    27242660
    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.
     2661              to generate your own, or use the existing dh1024.pem file  included
     2662              with  the  OpenVPN  distribution.  Diffie Hellman parameters may be
     2663              considered public.
    27282664
    27292665       --cert file
    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:
     2666              Local peer's signed certificate in .pem format -- must be signed by
     2667              a  certificate  authority  whose certificate is in --ca file.  Each
     2668              peer in an OpenVPN link running in TLS mode  should  have  its  own
     2669              certificate  and  private  key file.  In addition, each certificate
     2670              should have been signed by the key of a certificate authority whose
     2671              public key resides in the --ca certificate authority file.  You can
     2672              easily make your own certificate authority (see above) or pay money
     2673              to  use  a commercial service such as thawte.com (in which case you
     2674              will be helping to finance the world's second space tourist :).  To
     2675              generate a certificate, you can use a command such as:
    27412676
    27422677              openssl req -nodes -new -keyout mycert.key -out mycert.csr
    27432678
    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:
     2679              If your certificate authority private key lives on another machine,
     2680              copy the certificate signing request  (mycert.csr)  to  this  other
     2681              machine  (this can be done over an insecure channel such as email).
     2682              Now sign the certificate with a command such as:
    27492683
    27502684              openssl ca -out mycert.crt -in mycert.csr
    27512685
    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
     2686              Now copy the certificate (mycert.crt) back to the peer  which  ini‐
     2687              tially  generated the .csr file (this can be over a public medium).
     2688              Note that the openssl ca command reads the location of the certifi‐
     2689              cate   authority   key   from   its   configuration  file  such  as
     2690              /usr/share/ssl/openssl.cnf  --  note  also  that  for  certificate
     2691              authority  functions,  you must set up the files index.txt (may be
    27582692              empty) and serial (initialize to 01 ).
    27592693
    27602694       --extra-certs file
    2761               Specify  a  file  containing one or more PEM certs (concatenated
     2695              Specify a file containing  one  or  more  PEM  certs (concatenated
    27622696              together) that complete the local certificate chain.
    27632697
    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.
     2698              This  option  is  useful  for  "split" CAs, where the CA for server
     2699              certs is different than the CA for client certs.  Putting certs  in
     2700              this  file allows them to be used to complete the local certificate
     2701              chain without trusting them to verify the  peer-submitted  certifi‐
     2702              cate, as would be the case if the certs were placed in the ca file.
    27702703
    27712704       --key file
    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).
     2705              Local peer's private key in .pem format.  Use the private key which
     2706              was generated when you built your  peer's  certificate  (see  -cert
     2707              file above).
    27752708
    27762709       --pkcs12 file
    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.
     2710              Specify  a  PKCS  #12 file containing local private key, local cer‐
     2711              tificate, and root CA certificate.  This option can be used instead
     2712              of --ca, --cert, and --key.  Not available with PolarSSL.
    27812713
    27822714       --verify-hash hash
    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:
     2715              Specify SHA1 fingerprint for level-1 cert.  The level-1 cert is the
     2716              CA (or intermediate cert) that signs the leaf certificate,  and  is
     2717              one removed from the leaf certificate in the direction of the root.
     2718              When accepting a connection from a peer, the level-1  cert  finger‐
     2719              print  must match hash or certificate verification will fail.  Hash
     2720              is      specified      as       XX:XX:...        For       example:
    27892721              AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16
    27902722
    27912723       --pkcs11-cert-private [0|1]...
    2792               Set if access to certificate object should  be  performed after
     2724              Set  if  access  to  certificate  object  should be performed after
    27932725              login.  Every provider has its own setting.
    27942726
    27952727       --pkcs11-id name
    2796               Specify  the serialized certificate id to be used. The id can be
     2728              Specify the serialized certificate id to be used.  The  id  can be
    27972729              gotten by the standalone --show-pkcs11-ids option.
    27982730
    27992731       --pkcs11-id-management
    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.
     2732              Acquire  PKCS#11 id from management interface. In this case a NEED-
     2733              STR 'pkcs11-id-request' real-time message will be triggered, appli
     2734              cation may use pkcs11-id-count command to retrieve available number
     2735              of certificates, and pkcs11-id-get command to retrieve  certificate
     2736              id and certificate body.
    28052737
    28062738       --pkcs11-pin-cache seconds
    2807               Specify how many seconds the PIN can be cached, the  default is
     2739              Specify  how  many  seconds  the  PIN can be cached, the default is
    28082740              until the token is removed.
    28092741
    28102742       --pkcs11-protected-authentication [0|1]...
    2811               Use  PKCS#11 protected authentication path, useful for biometric
    2812               and external keypad devices.  Every provider has  its  own  set‐
    2813               ting.
     2743              Use PKCS#11 protected authentication path, useful for biometric and
     2744              external keypad devices.  Every provider has its own setting.
    28142745
    28152746       --pkcs11-providers provider...
    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.
     2747              Specify  a RSA Security Inc. PKCS #11 Cryptographic Token Interface
     2748              (Cryptoki) providers to load.  This option can be used  instead  of
     2749              --cert, --key, and --pkcs12.
    28192750
    28202751       --pkcs11-private-mode mode...
    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:
     2752              Specify  which method to use in order to perform private key opera‐
     2753              tions.  A different mode can be specified for each provider.   Mode
     2754              is encoded as hex number, and can be a mask one of the following:
    28252755
    28262756              0 (default) -- Try to determind automatically.
     
    28312761
    28322762       --cryptoapicert select-string
    2833               Load the certificate and private key from the  Windows  Certifi‐
    2834               cate System Store (Windows/OpenSSL Only).
     2763              Load  the  certificate and private key from the Windows Certificate
     2764              System Store (Windows/OpenSSL Only).
    28352765
    28362766              Use this option instead of --cert and --key.
    28372767
    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‐
     2768              This makes it possible to use any smart card, supported by Windows,
     2769              but also any kind of certificate, residing in the Cert Store, where
     2770              you have access to the private key.  This option  has  been  tested
     2771              with  a  couple  of different smart cards (GemSAFE, Cryptoflex, and
     2772              Swedish Post Office eID) on the client side, and also  an  imported
     2773              PKCS12 software certificate on the server side.
     2774
     2775              To  select  a certificate, based on a substring search in the cer‐
    28462776              tificate's subject:
    28472777
     
    28522782              cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."
    28532783
    2854               The thumbprint hex string can easily be copy-and-pasted from the
     2784              The thumbprint hex string can easily be  copy-and-pasted  from the
    28552785              Windows Certificate Store GUI.
    28562786
    28572787
    28582788       --key-method m
    2859               Use data channel key negotiation method m.  The key method must
     2789              Use  data  channel  key  negotiation method m.  The key method must
    28602790              match on both sides of the connection.
    28612791
    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.
     2792              After OpenVPN negotiates a TLS session, a new set of keys for  pro‐
     2793              tecting the tunnel data channel is generated and exchanged over the
     2794              TLS session.
     2795
     2796              In method 1 (the default for OpenVPN 1.x), both sides generate ran‐
     2797              dom  encrypt  and  HMAC-send  keys which are forwarded to the other
     2798              host over the TLS channel.
     2799
     2800              In method 2, (the default for OpenVPN 2.0) the client  generates  a
     2801              random  key.  Both client and server also generate some random seed
     2802              material.  All key source material is exchanged over the TLS  chan‐
     2803              nel. The actual keys are generated using the TLS PRF function, tak‐
     2804              ing source entropy from  both  client  and  server.   Method  2  is
     2805              designed to closely parallel the key generation process used by TLS
     2806              1.0.
    28772807
    28782808              Note that in TLS mode, two separate levels of keying occur:
    28792809
    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
    2883               side.  The --key-method parameter has no effect on this process.
    2884 
    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.
     2810              (1) The TLS connection is initially negotiated, with both sides  of
     2811              the connection producing certificates and verifying the certificate
     2812              (or other authentication info provided) of  the  other  side.   The
     2813              --key-method parameter has no effect on this process.
     2814
     2815              (2)  After  the  TLS  connection is established, the tunnel session
     2816              keys are separately negotiated over the existing secure  TLS  chan‐
     2817              nel.   Here,  --key-method  determines the derivation of the tunnel
     2818              session keys.
    28892819