Menu
▾
▴
[Openvpn-devel] [PATCH v2 2/8] doc/man: Replace old man page with generated man page
|
From: David S. <da...@op...> - 2020-07-16 22:55:23
|
The doc/openvpn.8 and doc/openvpn.8.html files are now being removed from the
git tree, as it will be generated from the doc/openvpn.8.rst file using
python-docutils.
An additional dist-hook is added so these files are generated
automatically when source tarballs are generated for releases. This
means users compiling directly from the source tarball will not need
python-docutils installed.
Signed-off-by: David Sommerseth <da...@op...>
---
.gitignore | 1 +
INSTALL | 3 +-
configure.ac | 15 +-
doc/Makefile.am | 34 +-
doc/README.man | 23 +
doc/openvpn.8 | 7659 -----------------------------------------------
6 files changed, 61 insertions(+), 7674 deletions(-)
create mode 100644 doc/README.man
delete mode 100644 doc/openvpn.8
diff --git a/.gitignore b/.gitignore
index 0d68ec4b..25d06235 100644
--- a/.gitignore
+++ b/.gitignore
@@ -49,6 +49,7 @@ version.sh
msvc-env-local.bat
config-msvc-local.h
config-msvc-version.h
+doc/openvpn.8
doc/openvpn.8.html
/doc/doxygen/html/
/doc/doxygen/latex/
diff --git a/INSTALL b/INSTALL
index a6a28630..de0eb518 100644
--- a/INSTALL
+++ b/INSTALL
@@ -227,7 +227,6 @@ ENVIRONMENT for ./configure:
ROUTE full path to route utility
IPROUTE full path to ip utility
NETSTAT path to netstat utility
- MAN2HTML path to man2html utility
GIT path to git utility
SYSTEMD_ASK_PASSWORD
path to systemd-ask-password utility
@@ -235,6 +234,8 @@ ENVIRONMENT for ./configure:
Path of systemd unit directory [default=LIBDIR/systemd/system]
TMPFILES_DIR
Path of tmpfiles directory [default=LIBDIR/tmpfiles.d]
+ RST2MAN Path to rst2man utility
+ RST2HTML Path to rst2html utility
ENVIRONMENT variables adjusting parameters related to dependencies
diff --git a/configure.ac b/configure.ac
index 53b7a967..45148892 100644
--- a/configure.ac
+++ b/configure.ac
@@ -354,7 +354,6 @@ AC_ARG_VAR([IFCONFIG], [full path to ipconfig utility])
AC_ARG_VAR([ROUTE], [full path to route utility])
AC_ARG_VAR([IPROUTE], [full path to ip utility])
AC_ARG_VAR([NETSTAT], [path to netstat utility]) # tests
-AC_ARG_VAR([MAN2HTML], [path to man2html utility])
AC_ARG_VAR([GIT], [path to git utility])
AC_ARG_VAR([SYSTEMD_ASK_PASSWORD], [path to systemd-ask-password utility])
AC_ARG_VAR([SYSTEMD_UNIT_DIR], [Path of systemd unit directory @<:@default=LIBDIR/systemd/system@:>@])
@@ -364,13 +363,21 @@ AC_PATH_PROGS([ROUTE], [route],, [$PATH:/usr/local/sbin:/usr/sbin:/sbin])
AC_PATH_PROGS([IPROUTE], [ip],, [$PATH:/usr/local/sbin:/usr/sbin:/sbin])
AC_PATH_PROGS([SYSTEMD_ASK_PASSWORD], [systemd-ask-password],, [$PATH:/usr/local/bin:/usr/bin:/bin])
AC_CHECK_PROGS([NETSTAT], [netstat], [netstat], [$PATH:/usr/local/sbin:/usr/sbin:/sbin:/etc]) # tests
-AC_CHECK_PROGS([MAN2HTML], [man2html])
AC_CHECK_PROGS([GIT], [git]) # optional
AC_DEFINE_UNQUOTED([IFCONFIG_PATH], ["$IFCONFIG"], [Path to ifconfig tool])
AC_DEFINE_UNQUOTED([IPROUTE_PATH], ["$IPROUTE"], [Path to iproute tool])
AC_DEFINE_UNQUOTED([ROUTE_PATH], ["$ROUTE"], [Path to route tool])
AC_DEFINE_UNQUOTED([SYSTEMD_ASK_PASSWORD_PATH], ["$SYSTEMD_ASK_PASSWORD"], [Path to systemd-ask-password tool])
+#
+# man page generation - based on python-docutils
+#
+AC_ARG_VAR([RST2MAN], [path to rst2man utility])
+AC_ARG_VAR([RST2HTML], [path to rst2html utility])
+AC_CHECK_PROGS([RST2MAN], [rst2man])
+AC_CHECK_PROGS([RST2HTML], [rst2html])
+AM_CONDITIONAL([HAVE_PYDOCUTILS], [test "${RST2MAN}" -a "${RST2HTML}"])
+
# Set -std=c99 unless user already specified a -std=
case "${CFLAGS}" in
*-std=*) ;;
@@ -1315,10 +1322,6 @@ if test "${enable_werror}" = "yes"; then
CFLAGS="${CFLAGS} -Werror"
fi
-if test "${WIN32}" = "yes"; then
- test -z "${MAN2HTML}" && AC_MSG_ERROR([man2html is required for win32])
-fi
-
if test "${enable_plugin_auth_pam}" = "yes"; then
PLUGIN_AUTH_PAM_CFLAGS="${LIBPAM_CFLAGS}"
if test "${enable_pam_dlopen}" = "yes"; then
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 95055dbb..5110ca52 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -5,29 +5,47 @@
# packet encryption, packet authentication, and
# packet compression.
#
-# Copyright (C) 2002-2018 OpenVPN Inc <sa...@op...>
+# Copyright (C) 2002-2020 OpenVPN Inc <sa...@op...>
# Copyright (C) 2006-2012 Alon Bar-Lev <alo...@gm...>
#
MAINTAINERCLEANFILES = \
$(srcdir)/Makefile.in
-CLEANFILES = openvpn.8.html
-
SUBDIRS = doxygen
dist_doc_DATA = \
- management-notes.txt
+ management-notes.txt openvpn.8.rst
dist_noinst_DATA = \
README.plugins interactive-service-notes.rst
-if WIN32
+openvpn.8 :
+if HAVE_PYDOCUTILS
+ $(RST2MAN) $(srcdir)/$@.rst > $@
+else
+ @echo "Missing python-docutils - skipping man page generation"
+endif
+
+openvpn.8.html:
+if HAVE_PYDOCUTILS
+ $(RST2HTML) $(srcdir)/openvpn.8.rst > $@
+else
+ @echo "Missing python-docutils - skipping man/html page generation"
+endif
+
+if HAVE_PYDOCUTILS
dist_noinst_DATA += openvpn.8
-nodist_html_DATA = openvpn.8.html
-openvpn.8.html: $(srcdir)/openvpn.8
- $(MAN2HTML) < $(srcdir)/openvpn.8 > openvpn.8.html
+dist_html_DATA = openvpn.8.html
+
+# Failsafe - do not delete these files unless we can recreate them
+CLEANFILES = \
+ openvpn.8 openvpn.8.html
+
+if WIN32
else
dist_man_MANS = openvpn.8
endif
+endif
+dist-hook : openvpn.8 openvpn.8.html
diff --git a/doc/README.man b/doc/README.man
new file mode 100644
index 00000000..00a9c480
--- /dev/null
+++ b/doc/README.man
@@ -0,0 +1,23 @@
+
+man page documentation
+======================
+
+The man page content maintained in the openvpn.8.rst file and proper man and
+the html version of the man page are generated using python-docutils. Both
+the man page and html file are generated during 'make dist' or 'make distcheck'
+and should be distributed inside the tarball by default.
+
+Users compiling OpenVPN from the tarball should not need to regenerate the
+man/html files unless the source file needs to be modified.
+
+Further information:
+
+* Python docutils project:
+ https://docutils.sourceforge.io/
+
+* Quickstart on .rst
+ https://docutils.sourceforge.io/docs/user/rst/quickstart.html
+
+* reStructuredText Markup Specifictaion (.rst)
+ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
+
diff --git a/doc/openvpn.8 b/doc/openvpn.8
deleted file mode 100644
index 03ae5ac5..00000000
--- a/doc/openvpn.8
+++ /dev/null
@@ -1,7659 +0,0 @@
-.\" OpenVPN -- An application to securely tunnel IP networks
-.\" over a single TCP/UDP port, with support for SSL/TLS-based
-.\" session authentication and key exchange,
-.\" packet encryption, packet authentication, and
-.\" packet compression.
-.\"
-.\" Copyright (C) 2002-2018 OpenVPN Inc <sa...@op...>
-.\"
-.\" This program is free software; you can redistribute it and/or modify
-.\" it under the terms of the GNU General Public License version 2
-.\" as published by the Free Software Foundation.
-.\"
-.\" This program is distributed in the hope that it will be useful,
-.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-.\" GNU General Public License for more details.
-.\"
-.\" You should have received a copy of the GNU General Public License along
-.\" with this program; if not, write to the Free Software Foundation, Inc.,
-.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-.\"
-.\" Manual page for openvpn
-.\"
-.\" SH section heading
-.\" SS subsection heading
-.\" LP paragraph
-.\" IP indented paragraph
-.\" TP hanging label
-.\"
-.\" .nf -- no formatting
-.\" .fi -- resume formatting
-.\" .ft 3 -- boldface
-.\" .ft -- normal face
-.\" .in +|-{n} -- indent
-.\"
-.\" Support macros - this is not present on all platforms
-.\" Continuation line for .TP header.
-.de TQ
-. br
-. ns
-. TP \\$1\" no doublequotes around argument!
-..
-.\" End of TQ macro
-.TH openvpn 8 "28 February 2018"
-.\"*********************************************************
-.SH NAME
-openvpn \- secure IP tunnel daemon.
-.\"*********************************************************
-.SH SYNOPSIS
-.ft 3
-openvpn [ options ... ]
-.ft
-.\"*********************************************************
-.SH INTRODUCTION
-.LP
-OpenVPN is an open source VPN daemon by James Yonan.
-Because OpenVPN tries to
-be a universal VPN tool offering a great deal of flexibility,
-there are a lot of options on this manual page.
-If you're new to OpenVPN, you might want to skip ahead to the
-examples section where you will see how to construct simple
-VPNs on the command line without even needing a configuration file.
-
-Also note that there's more documentation and examples on
-the OpenVPN web site:
-.I http://openvpn.net/
-
-And if you would like to see a shorter version of this manual,
-see the openvpn usage message which can be obtained by
-running
-.B openvpn
-without any parameters.
-.\"*********************************************************
-.SH DESCRIPTION
-.LP
-OpenVPN is a robust and highly flexible VPN daemon.
-OpenVPN supports SSL/TLS security, ethernet bridging,
-TCP or UDP tunnel transport through proxies or NAT,
-support for dynamic IP addresses and DHCP,
-scalability to hundreds or thousands of users,
-and portability to most major OS platforms.
-
-OpenVPN is tightly bound to the OpenSSL library, and derives much
-of its crypto capabilities from it.
-
-OpenVPN supports
-conventional encryption
-using a pre\-shared secret key
-.B (Static Key mode)
-or
-public key security
-.B (SSL/TLS mode)
-using client & server certificates.
-OpenVPN also
-supports non\-encrypted TCP/UDP tunnels.
-
-OpenVPN is designed to work with the
-.B TUN/TAP
-virtual networking interface that exists on most platforms.
-
-Overall, OpenVPN aims to offer many of the key features of IPSec but
-with a relatively lightweight footprint.
-.\"*********************************************************
-.SH OPTIONS
-OpenVPN allows any option to be placed either on the command line
-or in a configuration file. Though all command line options are preceded
-by a double\-leading\-dash ("\-\-"), this prefix can be removed when
-an option is placed in a configuration file.
-.\"*********************************************************
-.TP
-.B \-\-help
-Show options.
-.\"*********************************************************
-.TP
-.B \-\-config file
-Load additional config options from
-.B file
-where each line corresponds to one command line option,
-but with the leading '\-\-' removed.
-
-If
-.B \-\-config file
-is the only option to the openvpn command,
-the
-.B \-\-config
-can be removed, and the command can be given as
-.B openvpn file
-
-Note that
-configuration files can be nested to a reasonable depth.
-
-Double quotation or single quotation characters ("", '')
-can be used to enclose single parameters containing whitespace,
-and "#" or ";" characters in the first column
-can be used to denote comments.
-
-Note that OpenVPN 2.0 and higher performs backslash\-based shell
-escaping for characters not in single quotations,
-so the following mappings should be observed:
-
-.nf
-.ft 3
-.in +4
-\\\\ Maps to a single backslash character (\\).
-\\" Pass a literal doublequote character ("), don't
- interpret it as enclosing a parameter.
-\\[SPACE] Pass a literal space or tab character, don't
- interpret it as a parameter delimiter.
-.in -4
-.ft
-.fi
-
-For example on Windows, use double backslashes to
-represent pathnames:
-
-.nf
-.ft 3
-.in +4
-secret "c:\\\\OpenVPN\\\\secret.key"
-.in -4
-.ft
-.fi
-
-For examples of configuration files,
-see
-.I http://openvpn.net/examples.html
-
-Here is an example configuration file:
-
-.nf
-.ft 3
-.in +4
-#
-# Sample OpenVPN configuration file for
-# using a pre\-shared static key.
-#
-# '#' or ';' may be used to delimit comments.
-
-# Use a dynamic tun device.
-dev tun
-
-# Our remote peer
-remote mypeer.mydomain
-
-# 10.1.0.1 is our local VPN endpoint
-# 10.1.0.2 is our remote VPN endpoint
-ifconfig 10.1.0.1 10.1.0.2
-
-# Our pre\-shared static key
-secret static.key
-.in -4
-.ft
-.fi
-.\"*********************************************************
-.SS Tunnel Options:
-.TP
-.B \-\-mode m
-Set OpenVPN major mode. By default, OpenVPN runs in
-point\-to\-point mode ("p2p"). OpenVPN 2.0 introduces
-a new mode ("server") which implements a multi\-client
-server capability.
-.\"*********************************************************
-.TP
-.B \-\-local host
-Local host name or IP address for bind.
-If specified, OpenVPN will bind to this address only.
-If unspecified, OpenVPN will bind to all interfaces.
-.\"*********************************************************
-.TP
-.B \-\-remote host [port] [proto]
-Remote host name or IP address. On the client, multiple
-.B \-\-remote
-options may be specified for redundancy, each referring
-to a different OpenVPN server. Specifying multiple
-.B \-\-remote
-options for this purpose is a special case of the more
-general connection\-profile feature. See the
-.B <connection>
-documentation below.
-
-The OpenVPN client will try to connect to a server at
-.B host:port
-in the order specified by the list of
-.B \-\-remote
-options.
-
-.B proto
-indicates the protocol to use when connecting with the
-remote, and may be "tcp" or "udp".
-
-For forcing IPv4 or IPv6 connection suffix tcp or udp
-with 4/6 like udp4/udp6/tcp4/tcp6.
-
-The client will move on to the next host in the list,
-in the event of connection failure.
-Note that at any given time, the OpenVPN client
-will at most be connected to
-one server.
-
-Note that since UDP is connectionless, connection failure
-is defined by the
-.B \-\-ping
-and
-.B \-\-ping\-restart
-options.
-
-Note the following corner case: If you use multiple
-.B \-\-remote
-options, AND you are dropping root privileges on
-the client with
-.B \-\-user
-and/or
-.B \-\-group,
-AND the client is running a non\-Windows OS, if the client needs
-to switch to a different server, and that server pushes
-back different TUN/TAP or route settings, the client may lack
-the necessary privileges to close and reopen the TUN/TAP interface.
-This could cause the client to exit with a fatal error.
-
-If
-.B \-\-remote
-is unspecified, OpenVPN will listen
-for packets from any IP address, but will not act on those packets unless
-they pass all authentication tests. This requirement for authentication
-is binding on all potential peers, even those from known and supposedly
-trusted IP addresses (it is very easy to forge a source IP address on
-a UDP packet).
-
-When used in TCP mode,
-.B \-\-remote
-will act as a filter, rejecting connections from any host which does
-not match
-.B host.
-
-If
-.B host
-is a DNS name which resolves to multiple IP addresses,
-OpenVPN will try them in the order that the system getaddrinfo()
-presents them, so priorization and DNS randomization is done
-by the system library. Unless an IP version is forced by the
-protocol specification (4/6 suffix), OpenVPN will try both IPv4
-and IPv6 addresses, in the order getaddrinfo() returns them.
-.\"*********************************************************
-.TP
-.B \-\-remote\-random\-hostname
-Prepend a random string (6 bytes, 12 hex characters) to hostname to prevent
-DNS caching. For example, "foo.bar.gov" would be modified to
-"<random\-chars>.foo.bar.gov".
-.\"*********************************************************
-.TP
-.B <connection>
-Define a client connection
-profile. Client connection profiles are groups of OpenVPN options that
-describe how to connect to a given OpenVPN server. Client connection
-profiles are specified within an OpenVPN configuration file, and
-each profile is bracketed by
-.B <connection>
-and
-.B </connection>.
-
-An OpenVPN client will try each connection profile sequentially
-until it achieves a successful connection.
-
-.B \-\-remote\-random
-can be used to initially "scramble" the connection
-list.
-
-Here is an example of connection profile usage:
-
-.nf
-.ft 3
-.in +4
-client
-dev tun
-
-<connection>
-remote 198.19.34.56 1194 udp
-</connection>
-
-<connection>
-remote 198.19.34.56 443 tcp
-</connection>
-
-<connection>
-remote 198.19.34.56 443 tcp
-http\-proxy 192.168.0.8 8080
-</connection>
-
-<connection>
-remote 198.19.36.99 443 tcp
-http\-proxy 192.168.0.8 8080
-</connection>
-
-persist\-key
-persist\-tun
-pkcs12 client.p12
-remote\-cert\-tls server
-verb 3
-.in -4
-.ft
-.fi
-
-First we try to connect to a server at 198.19.34.56:1194 using UDP.
-If that fails, we then try to connect to 198.19.34.56:443 using TCP.
-If that also fails, then try connecting through an HTTP proxy at
-192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to
-connect through the same proxy to a server at 198.19.36.99:443
-using TCP.
-
-The following OpenVPN options may be used inside of
-a
-.B <connection>
-block:
-
-.B bind,
-.B connect\-retry,
-.B connect\-retry\-max,
-.B connect\-timeout,
-.B explicit\-exit\-notify,
-.B float,
-.B fragment,
-.B http\-proxy,
-.B http\-proxy\-option,
-.B key\-direction,
-.B link\-mtu,
-.B local,
-.B lport,
-.B mssfix,
-.B mtu\-disc,
-.B nobind,
-.B port,
-.B proto,
-.B remote,
-.B rport,
-.B socks\-proxy,
-.B tls\-auth,
-.B tls\-crypt,
-.B tun\-mtu and
-.B tun\-mtu\-extra.
-
-A defaulting mechanism exists for specifying options to apply to
-all
-.B <connection>
-profiles. If any of the above options (with the exception of
-.B remote
-) appear outside of a
-.B <connection>
-block, but in a configuration file which has one or more
-.B <connection>
-blocks, the option setting will be used as a default for
-.B <connection>
-blocks which follow it in the configuration file.
-
-For example, suppose the
-.B nobind
-option were placed in the sample configuration file above, near
-the top of the file, before the first
-.B <connection>
-block. The effect would be as if
-.B nobind
-were declared in all
-.B <connection>
-blocks below it.
-.\"*********************************************************
-.TP
-.B \-\-proto\-force p
-When iterating through connection profiles,
-only consider profiles using protocol
-.B p
-('tcp'|'udp').
-.\"*********************************************************
-.TP
-.B \-\-remote\-random
-When multiple
-.B \-\-remote
-address/ports are specified, or if connection profiles are being
-used, initially randomize the order of the list
-as a kind of basic load\-balancing measure.
-.\"*********************************************************
-.TP
-.B \-\-proto p
-Use protocol
-.B p
-for communicating with remote host.
-.B p
-can be
-.B udp,
-.B tcp\-client,
-or
-.B tcp\-server.
-
-The default protocol is
-.B udp
-when
-.B \-\-proto
-is not specified.
-
-For UDP operation,
-.B \-\-proto udp
-should be specified on both peers.
-
-For TCP operation, one peer must use
-.B \-\-proto tcp\-server
-and the other must use
-.B \-\-proto tcp\-client.
-A peer started with
-.B tcp\-server
-will wait indefinitely for an incoming connection. A peer
-started with
-.B tcp\-client
-will attempt to connect, and if that fails, will sleep for 5
-seconds (adjustable via the
-.B \-\-connect\-retry
-option) and try again infinite or up to N retries (adjustable via the
-.B \-\-connect\-retry\-max
-option). Both TCP client and server will simulate
-a SIGUSR1 restart signal if either side resets the connection.
-
-OpenVPN is designed to operate optimally over UDP, but TCP capability is provided
-for situations where UDP cannot be used.
-In comparison with UDP, TCP will usually be
-somewhat less efficient and less robust when used over unreliable or congested
-networks.
-
-This article outlines some of problems with tunneling IP over TCP:
-
-.I http://sites.inka.de/sites/bigred/devel/tcp\-tcp.html
-
-There are certain cases, however, where using TCP may be advantageous from
-a security and robustness perspective, such as tunneling non\-IP or
-application\-level UDP protocols, or tunneling protocols which don't
-possess a built\-in reliability layer.
-.\"*********************************************************
-.TP
-.B \-\-connect\-retry n [max]
-Wait
-.B n
-seconds between connection attempts (default=5). Repeated reconnection
-attempts are slowed down after 5 retries per remote by doubling the wait
-time after each unsuccessful attempt. The optional argument
-.B max
-specifies the maximum value of wait time in seconds at which it gets
-capped (default=300).
-.\"*********************************************************
-.TP
-.B \-\-connect\-retry\-max n
-.B n
-specifies the number of times each
-.B \-\-remote
-or
-.B <connection>
-entry is tried. Specifying
-.B n
-as one would try each entry exactly once. A successful connection
-resets the counter. (default=unlimited).
-.\"*********************************************************
-.TP
-.B \-\-show\-proxy\-settings
-Show sensed HTTP or SOCKS proxy settings. Currently, only Windows clients
-support this option.
-.\"*********************************************************
-.TP
-.B \-\-http\-proxy server port [authfile|'auto'|'auto\-nct'] [auth\-method]
-Connect to remote host through an HTTP proxy at address
-.B server
-and port
-.B port.
-If HTTP Proxy\-Authenticate is required,
-.B authfile
-is a file containing a username and password on 2 lines, or
-"stdin" to prompt from console. Its content can also be specified
-in the config file with the
-.B \-\-http\-proxy\-user\-pass
-option. (See section on inline files)
-
-.B auth\-method
-should be one of "none", "basic", or "ntlm".
-
-HTTP Digest authentication is supported as well, but only via
-the
-.B auto
-or
-.B auto\-nct
-flags (below).
-
-The
-.B auto
-flag causes OpenVPN to automatically determine the
-.B auth\-method
-and query stdin or the management interface for
-username/password credentials, if required. This flag
-exists on OpenVPN 2.1 or higher.
-
-The
-.B auto\-nct
-flag (no clear\-text auth) instructs OpenVPN to automatically
-determine the authentication method, but to reject weak
-authentication protocols such as HTTP Basic Authentication.
-.\"*********************************************************
-.TP
-.B \-\-http\-proxy\-option type [parm]
-Set extended HTTP proxy options.
-Repeat to set multiple options.
-
-.B VERSION version \-\-
-Set HTTP version number to
-.B version
-(default=1.0).
-
-.B AGENT user\-agent \-\-
-Set HTTP "User\-Agent" string to
-.B user\-agent.
-
-.B CUSTOM\-HEADER name content \-\-
-Adds the custom Header with
-.B name
-as name and
-.B content
-as the content of the custom HTTP header.
-.\"*********************************************************
-.TP
-.B \-\-socks\-proxy server [port] [authfile]
-Connect to remote host through a Socks5 proxy at address
-.B server
-and port
-.B port
-(default=1080).
-.B authfile
-(optional) is a file containing a username and password on 2 lines, or
-"stdin" to prompt from console.
-.\"*********************************************************
-.TP
-.B \-\-resolv\-retry n
-If hostname resolve fails for
-.B \-\-remote,
-retry resolve for
-.B n
-seconds before failing.
-
-Set
-.B n
-to "infinite" to retry indefinitely.
-
-By default,
-.B \-\-resolv\-retry infinite
-is enabled. You can disable by setting n=0.
-.\"*********************************************************
-.TP
-.B \-\-float
-Allow remote peer to change its IP address and/or port number, such as due to
-DHCP (this is the default if
-.B \-\-remote
-is not used).
-.B \-\-float
-when specified with
-.B \-\-remote
-allows an OpenVPN session to initially connect to a peer
-at a known address, however if packets arrive from a new
-address and pass all authentication tests, the new address
-will take control of the session. This is useful when
-you are connecting to a peer which holds a dynamic address
-such as a dial\-in user or DHCP client.
-
-Essentially,
-.B \-\-float
-tells OpenVPN to accept authenticated packets
-from any address, not only the address which was specified in the
-.B \-\-remote
-option.
-.\"*********************************************************
-.TP
-.B \-\-ipchange cmd
-Run command
-.B cmd
-when our remote ip\-address is initially authenticated or
-changes.
-
-.B cmd
-consists of a path to script (or executable program), optionally
-followed by arguments. The path and arguments may be single\- or double\-quoted
-and/or escaped using a backslash, and should be separated by one or more spaces.
-
-When
-.B cmd
-is executed two arguments are appended after any arguments specified in
-.B cmd
-, as follows:
-
-.B cmd ip_address port_number
-
-Don't use
-.B \-\-ipchange
-in
-.B \-\-mode server
-mode. Use a
-.B \-\-client\-connect
-script instead.
-
-See the "Environmental Variables" section below for
-additional parameters passed as environmental variables.
-
-If you are running in a dynamic IP address environment where
-the IP addresses of either peer could change without notice,
-you can use this script, for example, to edit the
-.I /etc/hosts
-file with the current address of the peer. The script will
-be run every time the remote peer changes its IP address.
-
-Similarly if
-.I our
-IP address changes due to DHCP, we should configure
-our IP address change script (see man page for
-.BR dhcpcd (8)
-) to deliver a
-.B SIGHUP
-or
-.B SIGUSR1
-signal to OpenVPN. OpenVPN will then
-reestablish a connection with its most recently authenticated
-peer on its new IP address.
-.\"*********************************************************
-.TP
-.B \-\-port port
-TCP/UDP port number or port name for both local and remote (sets both
-.B \-\-lport
-and
-.B \-\-rport
-options to given port). The current
-default of 1194 represents the official IANA port number
-assignment for OpenVPN and has been used since version 2.0\-beta17.
-Previous versions used port 5000 as the default.
-.\"*********************************************************
-.TP
-.B \-\-lport port
-Set local TCP/UDP port number or name. Cannot be used together with
-.B \-\-nobind
-option.
-.\"*********************************************************
-.TP
-.B \-\-rport port
-Set TCP/UDP port number or name used by the
-.B \-\-remote
-option. The port can also be set directly using the
-.B \-\-remote
-option.
-.\"*********************************************************
-.TP
-.B \-\-bind [ipv6only]
-Bind to local address and port. This is the default unless any of
-.B \-\-proto tcp\-client
-,
-.B \-\-http\-proxy
-or
-.B \-\-socks\-proxy
-are used.
-
-If the
-.B ipv6only
-keyword is present OpenVPN will bind only to IPv6 (as opposed
-to IPv6 and IPv4) when a IPv6 socket is opened.
-
-.\"*********************************************************
-.TP
-.B \-\-nobind
-Do not bind to local address and port. The IP stack will allocate
-a dynamic port for returning packets. Since the value of the dynamic port
-could not be known in advance by a peer, this option is only suitable for
-peers which will be initiating connections by using the
-.B \-\-remote
-option.
-.\"*********************************************************
-.TP
-.B \-\-dev tunX | tapX | null
-TUN/TAP virtual network device (
-.B X
-can be omitted for a dynamic device.)
-
-See examples section below
-for an example on setting up a TUN device.
-
-You must use either tun devices on both ends of the connection
-or tap devices on both ends. You cannot mix them, as they
-represent different underlying network layers.
-
-.B tun
-devices encapsulate IPv4 or IPv6 (OSI Layer 3) while
-.B tap
-devices encapsulate Ethernet 802.3 (OSI Layer 2).
-.\"*********************************************************
-.TP
-.B \-\-dev\-type device\-type
-Which device type are we using?
-.B device\-type
-should be
-.B tun
-(OSI Layer 3)
-or
-.B tap
-(OSI Layer 2).
-Use this option only if the TUN/TAP device used with
-.B \-\-dev
-does not begin with
-.B tun
-or
-.B tap.
-.\"*********************************************************
-.TP
-.B \-\-topology mode
-Configure virtual addressing topology when running in
-.B \-\-dev tun
-mode. This directive has no meaning in
-.B \-\-dev tap
-mode, which always uses a
-.B subnet
-topology.
-
-If you set this directive on the server, the
-.B \-\-server
-and
-.B \-\-server\-bridge
-directives will automatically push your chosen topology setting to clients
-as well. This directive can also be manually pushed to clients. Like the
-.B \-\-dev
-directive, this directive must always be compatible between client and server.
-
-.B mode
-can be one of:
-
-.B net30 \-\-
-Use a point\-to\-point topology, by allocating one /30 subnet per client.
-This is designed to allow point\-to\-point semantics when some
-or all of the connecting clients might be Windows systems. This is the
-default on OpenVPN 2.0.
-
-.B p2p \-\-
-Use a point\-to\-point topology where the remote endpoint of the client's
-tun interface always points to the local endpoint of the server's tun interface.
-This mode allocates a single IP address per connecting client.
-Only use
-when none of the connecting clients are Windows systems. This mode
-is functionally equivalent to the
-.B \-\-ifconfig\-pool\-linear
-directive which is available in OpenVPN 2.0, is deprecated and will be
-removed in OpenVPN 2.5
-
-.B subnet \-\-
-Use a subnet rather than a point\-to\-point topology by
-configuring the tun interface with a local IP address and subnet mask,
-similar to the topology used in
-.B \-\-dev tap
-and ethernet bridging mode.
-This mode allocates a single IP address per connecting client and works on
-Windows as well. Only available when server and clients are OpenVPN 2.1 or
-higher, or OpenVPN 2.0.x which has been manually patched with the
-.B \-\-topology
-directive code. When used on Windows, requires version 8.2 or higher
-of the TAP\-Win32 driver. When used on *nix, requires that the tun
-driver supports an
-.BR ifconfig (8)
-command which sets a subnet instead of a remote endpoint IP address.
-
-This option exists in OpenVPN 2.1 or higher.
-
-Note: Using
-.B \-\-topology subnet
-changes the interpretation of the arguments of
-.B \-\-ifconfig
-to mean "address netmask", no longer "local remote".
-.\"*********************************************************
-.TP
-.B \-\-dev\-node node
-Explicitly set the device node rather than using
-/dev/net/tun, /dev/tun, /dev/tap, etc. If OpenVPN
-cannot figure out whether
-.B node
-is a TUN or TAP device based on the name, you should
-also specify
-.B \-\-dev\-type tun
-or
-.B \-\-dev\-type tap.
-
-Under Mac OS X this option can be used to specify the default tun
-implementation. Using
-.B \-\-dev\-node utun
-forces usage of the native Darwin tun kernel support. Use
-.B \-\-dev\-node utunN
-to select a specific utun instance. To force using the tun.kext (/dev/tunX) use
-.B \-\-dev\-node tun\fR.
-When not specifying a
-.B \-\-dev\-node
-option openvpn will first try to open utun, and fall back to tun.kext.
-
-On Windows systems, select the TAP\-Win32 adapter which
-is named
-.B node
-in the Network Connections Control Panel or the
-raw GUID of the adapter enclosed by braces.
-The
-.B \-\-show\-adapters
-option under Windows can also be used
-to enumerate all available TAP\-Win32
-adapters and will show both the network
-connections control panel name and the GUID for
-each TAP\-Win32 adapter.
-.TP
-.B \-\-lladdr address
-Specify the link layer address, more commonly known as the MAC address.
-Only applied to TAP devices.
-.\"*********************************************************
-.TP
-.B \-\-iproute cmd
-Set alternate command to execute instead of default iproute2 command.
-May be used in order to execute OpenVPN in unprivileged environment.
-.\"*********************************************************
-.TP
-.B \-\-ifconfig l rn
-Set TUN/TAP adapter parameters.
-.B l
-is the IP address of the local VPN endpoint.
-For TUN devices in point\-to\-point mode,
-.B rn
-is the IP address of the remote VPN endpoint.
-For TAP devices, or TUN devices used with
-.B \-\-topology subnet,
-.B rn
-is the subnet mask of the virtual network segment
-which is being created or connected to.
-
-For TUN devices, which facilitate virtual
-point\-to\-point IP connections (when used in
-.B \-\-topology net30
-or
-.B p2p
-mode),
-the proper usage of
-.B \-\-ifconfig
-is to use two private IP addresses
-which are not a member of any
-existing subnet which is in use.
-The IP addresses may be consecutive
-and should have their order reversed
-on the remote peer. After the VPN
-is established, by pinging
-.B rn,
-you will be pinging across the VPN.
-
-For TAP devices, which provide
-the ability to create virtual
-ethernet segments, or TUN devices in
-.B \-\-topology subnet
-mode (which create virtual "multipoint networks"),
-.B \-\-ifconfig
-is used to set an IP address and
-subnet mask just as a physical
-ethernet adapter would be
-similarly configured. If you are
-attempting to connect to a remote
-ethernet bridge, the IP address
-and subnet should be set to values
-which would be valid on the
-the bridged ethernet segment (note
-also that DHCP can be used for the
-same purpose).
-
-This option, while primarily a proxy for the
-.BR ifconfig (8)
-command, is designed to simplify TUN/TAP
-tunnel configuration by providing a
-standard interface to the different
-ifconfig implementations on different
-platforms.
-
-.B \-\-ifconfig
-parameters which are IP addresses can
-also be specified as a DNS or /etc/hosts
-file resolvable name.
-
-For TAP devices,
-.B \-\-ifconfig
-should not be used if the TAP interface will be
-getting an IP address lease from a DHCP
-server.
-.\"*********************************************************
-.TP
-.B \-\-ifconfig\-noexec
-Don't actually execute ifconfig/netsh commands, instead
-pass
-.B \-\-ifconfig
-parameters to scripts using environmental variables.
-.\"*********************************************************
-.TP
-.B \-\-ifconfig\-nowarn
-Don't output an options consistency check warning
-if the
-.B \-\-ifconfig
-option on this side of the
-connection doesn't match the remote side. This is useful
-when you want to retain the overall benefits of the
-options consistency check (also see
-.B \-\-disable\-occ
-option) while only disabling the ifconfig component of
-the check.
-
-For example,
-if you have a configuration where the local host uses
-.B \-\-ifconfig
-but the remote host does not, use
-.B \-\-ifconfig\-nowarn
-on the local host.
-
-This option will also silence warnings about potential
-address conflicts which occasionally annoy more experienced
-users by triggering "false positive" warnings.
-.\"*********************************************************
-.TP
-.B \-\-route network/IP [netmask] [gateway] [metric]
-Add route to routing table after connection is established.
-Multiple routes can be specified. Routes will be
-automatically torn down in reverse order prior to
-TUN/TAP device close.
-
-This option is intended as
-a convenience proxy for the
-.BR route (8)
-shell command,
-while at the same time providing portable semantics
-across OpenVPN's platform space.
-
-.B netmask
-default \-\- 255.255.255.255
-
-.B gateway
-default \-\- taken from
-.B \-\-route\-gateway
-or the second parameter to
-.B \-\-ifconfig
-when
-.B \-\-dev tun
-is specified.
-
-.B metric
-default \-\- taken from
-.B \-\-route\-metric
-otherwise 0.
-
-The default can be specified by leaving an option blank or setting
-it to "default".
-
-The
-.B network
-and
-.B gateway
-parameters can
-also be specified as a DNS or /etc/hosts
-file resolvable name, or as one of three special keywords:
-
-.B vpn_gateway
-\-\- The remote VPN endpoint address
-(derived either from
-.B \-\-route\-gateway
-or the second parameter to
-.B \-\-ifconfig
-when
-.B \-\-dev tun
-is specified).
-
-.B net_gateway
-\-\- The pre\-existing IP default gateway, read from the routing
-table (not supported on all OSes).
-
-.B remote_host
-\-\- The
-.B \-\-remote
-address if OpenVPN is being run in client mode, and is undefined in server mode.
-.\"*********************************************************
-.TP
-.B \-\-route\-gateway gw|'dhcp'
-Specify a default gateway
-.B gw
-for use with
-.B \-\-route.
-
-If
-.B dhcp
-is specified as the parameter,
-the gateway address will be extracted from a DHCP
-negotiation with the OpenVPN server\-side LAN.
-.\"*********************************************************
-.TP
-.B \-\-route\-metric m
-Specify a default metric
-.B m
-for use with
-.B \-\-route.
-.\"*********************************************************
-.TP
-.B \-\-route\-delay [n] [w]
-Delay
-.B n
-seconds (default=0) after connection
-establishment, before adding routes. If
-.B n
-is 0, routes will be added immediately upon connection
-establishment. If
-.B \-\-route\-delay
-is omitted, routes will be added immediately after TUN/TAP device
-open and
-.B \-\-up
-script execution, before any
-.B \-\-user
-or
-.B \-\-group
-privilege downgrade (or
-.B \-\-chroot
-execution.)
-
-This option is designed to be useful in scenarios where DHCP is
-used to set
-tap adapter addresses. The delay will give the DHCP handshake
-time to complete before routes are added.
-
-On Windows,
-.B \-\-route\-delay
-tries to be more intelligent by waiting
-.B w
-seconds (w=30 by default)
-for the TAP\-Win32 adapter to come up before adding routes.
-.\"*********************************************************
-.TP
-.B \-\-route\-up cmd
-Run command
-.B cmd
-after routes are added, subject to
-.B \-\-route\-delay.
-
-.B cmd
-consists of a path to script (or executable program), optionally
-followed by arguments. The path and arguments may be single\- or double\-quoted
-and/or escaped using a backslash, and should be separated by one or more spaces.
-
-See the "Environmental Variables" section below for
-additional parameters passed as environmental variables.
-.\"*********************************************************
-.TP
-.B \-\-route\-pre\-down cmd
-Run command
-.B cmd
-before routes are removed upon disconnection.
-
-.B cmd
-consists of a path to script (or executable program), optionally
-followed by arguments. The path and arguments may be single\- or double\-quoted
-and/or escaped using a backslash, and should be separated by one or more spaces.
-
-See the "Environmental Variables" section below for
-additional parameters passed as environmental variables.
-.\"*********************************************************
-.TP
-.B \-\-route\-noexec
-Don't add or remove routes automatically. Instead pass routes to
-.B \-\-route\-up
-script using environmental variables.
-.\"*********************************************************
-.TP
-.B \-\-route\-nopull
-When used with
-.B \-\-client
-or
-.B \-\-pull,
-accept options pushed by server EXCEPT for routes, block\-outside\-dns and dhcp
-options like DNS servers.
-
-When used on the client, this option effectively bars the
-server from adding routes to the client's routing table,
-however note that this option still allows the server
-to set the TCP/IP properties of the client's TUN/TAP interface.
-.\"*********************************************************
-.TP
-.B \-\-allow\-pull\-fqdn
-Allow client to pull DNS names from server (rather than being limited
-to IP address) for
-.B \-\-ifconfig,
-.B \-\-route,
-and
-.B \-\-route\-gateway.
-.\"*********************************************************
-.TP
-.B \-\-client\-nat snat|dnat network netmask alias
-This pushable client option sets up a stateless one\-to\-one NAT
-rule on packet addresses (not ports), and is useful in cases
-where routes or ifconfig settings pushed to the client would
-create an IP numbering conflict.
-
-.B network/netmask
-(for example 192.168.0.0/255.255.0.0)
-defines the local view of a resource from the client perspective, while
-.B alias/netmask
-(for example 10.64.0.0/255.255.0.0)
-defines the remote view from the server perspective.
-
-Use
-.B snat
-(source NAT) for resources owned by the client and
-.B dnat
-(destination NAT) for remote resources.
-
-Set
-.B \-\-verb 6
-for debugging info showing the transformation of src/dest
-addresses in packets.
-.\"*********************************************************
-.TP
-.B \-\-redirect\-gateway flags...
-Automatically execute routing commands to cause all outgoing IP traffic
-to be redirected over the VPN. This is a client\-side option.
-
-This option performs three steps:
-
-.B (1)
-Create a static route for the
-.B \-\-remote
-address which forwards to the pre\-existing default gateway.
-This is done so that
-.B (3)
-will not create a routing loop.
-
-.B (2)
-Delete the default gateway route.
-
-.B (3)
-Set the new default gateway to be the VPN endpoint address (derived either from
-.B \-\-route\-gateway
-or the second parameter to
-.B \-\-ifconfig
-when
-.B \-\-dev tun
-is specified).
-
-When the tunnel is torn down, all of the above steps are reversed so
-that the original default route is restored.
-
-Option flags:
-
-.B local \-\-
-Add the
-.B local
-flag if both OpenVPN peers are directly connected via a common subnet,
-such as with wireless. The
-.B local
-flag will cause step
-.B 1
-above to be omitted.
-
-.B autolocal \-\-
-Try to automatically determine whether to enable
-.B local
-flag above.
-
-.B def1 \-\-
-Use this flag to override
-the default gateway by using 0.0.0.0/1 and 128.0.0.0/1
-rather than 0.0.0.0/0. This has the benefit of overriding
-but not wiping out the original default gateway.
-
-.B bypass\-dhcp \-\-
-Add a direct route to the DHCP server (if it is non\-local) which
-bypasses the tunnel
-(Available on Windows clients, may not be available
-on non\-Windows clients).
-
-.B bypass\-dns \-\-
-Add a direct route to the DNS server(s) (if they are non\-local) which
-bypasses the tunnel
-(Available on Windows clients, may not be available
-on non\-Windows clients).
-
-.B block\-local \-\-
-Block access to local LAN when the tunnel is active, except for
-the LAN gateway itself. This is accomplished by routing the local
-LAN (except for the LAN gateway address) into the tunnel.
-
-.B ipv6 \-\-
-Redirect IPv6 routing into the tunnel. This works similar to the
-.B def1
-flag, that is, more specific IPv6 routes are added (2000::/4, 3000::/4),
-covering the whole IPv6 unicast space.
-
-.B !ipv4 \-\-
-Do not redirect IPv4 traffic \- typically used in the flag pair
-.B "ipv6 !ipv4"
-to redirect IPv6\-only.
-.\"*********************************************************
-.TP
-.B \-\-link\-mtu n
-Sets an upper bound on the size of UDP packets which are sent
-between OpenVPN peers. It's best not to set this parameter unless
-you know what you're doing.
-.\"*********************************************************
-.\"*********************************************************
-.TP
-.B \-\-redirect\-private [flags]
-Like \-\-redirect\-gateway, but omit actually changing the default
-gateway. Useful when pushing private subnets.
-.\"*********************************************************
-.TP
-.B \-\-block\-ipv6
-On the client, instead of sending IPv6 packets over the VPN tunnel, all
-IPv6 packets are answered with an ICMPv6 no route host message. On the
-server, all IPv6 packets from clients are answered with an ICMPv6
-no route to host message. This options is intended for cases when IPv6
-should be blocked and other options are not available.
-\.B \-\-block\-ipv6
-will use the remote IPv6 as source address of the ICMPv6 packets if set,
-otherwise will use fe80::7 as source address.
-
-For this option to make sense you actually have to route traffic to the tun
-interface. The following example config block would send all IPv6 traffic to
-OpenVPN and answer all requests with no route to host, effectively blocking
-IPv6.
-
-# client config
-.br
-.B \-\-ifconfig-ipv6
-fd15:53b6:dead::2/64 fd15:53b6:dead::1
-.br
-.B \-\-redirect\-gateway
-ipv6
-.br
-.B \-\-block\-ipv6
-
-# Server config, push a "valid" ipv6 config to the client and block
-# on the server
-.br
-.B \-\-push
-"ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1"
-.br
-.B \-\-push
-"redirect\-gateway ipv6"
-.br
-.B \-\-block\-ipv6
-.\"*********************************************************
-.TP
-.B \-\-tun\-mtu n
-Take the TUN device MTU to be
-.B n
-and derive the link MTU
-from it (default=1500). In most cases, you will probably want to
-leave this parameter set to its default value.
-
-The MTU (Maximum Transmission Units) is
-the maximum datagram size in bytes that can be sent unfragmented
-over a particular network path. OpenVPN requires that packets
-on the control or data channels be sent unfragmented.
-
-MTU problems often manifest themselves as connections which
-hang during periods of active usage.
-
-It's best to use the
-.B \-\-fragment
-and/or
-.B \-\-mssfix
-options to deal with MTU sizing issues.
-.\"*********************************************************
-.TP
-.B \-\-tun\-mtu\-extra n
-Assume that the TUN/TAP device might return as many as
-.B n
-bytes more than the
-.B \-\-tun\-mtu
-size on read. This parameter defaults to 0, which is sufficient for
-most TUN devices. TAP devices may introduce additional overhead in excess
-of the MTU size, and a setting of 32 is the default when TAP devices are used.
-This parameter only controls internal OpenVPN buffer sizing,
-so there is no transmission overhead associated with using a larger value.
-.\"*********************************************************
-.TP
-.B \-\-mtu\-disc type
-Should we do Path MTU discovery on TCP/UDP channel? Only supported on OSes such
-as Linux that supports the necessary system call to set.
-
-.B 'no'
-\-\- Never send DF (Don't Fragment) frames
-.br
-.B 'maybe'
-\-\- Use per\-route hints
-.br
-.B 'yes'
-\-\- Always DF (Don't Fragment)
-.br
-.\"*********************************************************
-.TP
-.B \-\-mtu\-test
-To empirically measure MTU on connection startup,
-add the
-.B \-\-mtu\-test
-option to your configuration.
-OpenVPN will send ping packets of various sizes
-to the remote peer and measure the largest packets
-which were successfully received. The
-.B \-\-mtu\-test
-process normally takes about 3 minutes to complete.
-.\"*********************************************************
-.TP
-.B \-\-fragment max
-Enable internal datagram fragmentation so
-that no UDP datagrams are sent which
-are larger than
-.B max
-bytes.
-
-The
-.B max
-parameter is interpreted in the same way as the
-.B \-\-link\-mtu
-parameter, i.e. the UDP packet size after encapsulation
-overhead has been added in, but not including
-the UDP header itself.
-
-The
-.B \-\-fragment
-option only makes sense when you are using the UDP protocol (
-.B \-\-proto udp
-).
-
-.B \-\-fragment
-adds 4 bytes of overhead per datagram.
-
-See the
-.B \-\-mssfix
-option below for an important related option to
-.B \-\-fragment.
-
-It should also be noted that this option is not meant to replace
-UDP fragmentation at the IP stack level. It is only meant as a
-last resort when path MTU discovery is broken. Using this option
-is less efficient than fixing path MTU discovery for your IP link and
-using native IP fragmentation instead.
-
-Having said that, there are circumstances where using OpenVPN's
-internal fragmentation capability may be your only option, such
-as tunneling a UDP multicast stream which requires fragmentation.
-.\"*********************************************************
-.TP
-.B \-\-mssfix max
-Announce to TCP sessions running over the tunnel that they should limit
-their send packet sizes such that after OpenVPN has encapsulated them,
-the resulting UDP packet size that OpenVPN sends to its peer will not
-exceed
-.B max
-bytes. The default value is
-.B 1450.
-
-The
-.B max
-parameter is interpreted in the same way as the
-.B \-\-link\-mtu
-parameter, i.e. the UDP packet size after encapsulation
-overhead has been added in, but not including
-the UDP header itself. Resulting packet would be at most 28
-bytes larger for IPv4 and 48 bytes for IPv6 (20/40 bytes for IP
-header and 8 bytes for UDP header). Default value of 1450 allows
-IPv4 packets to be transmitted over a link with MTU 1473 or higher
-without IP level fragmentation.
-
-The
-.B \-\-mssfix
-option only makes sense when you are using the UDP protocol
-for OpenVPN peer\-to\-peer communication, i.e.
-.B \-\-proto udp.
-
-.B \-\-mssfix
-and
-.B \-\-fragment
-can be ideally used together, where
-.B \-\-mssfix
-will try to keep TCP from needing
-packet fragmentation in the first place,
-and if big packets come through anyhow
-(from protocols other than TCP),
-.B \-\-fragment
-will internally fragment them.
-
-Both
-.B \-\-fragment
-and
-.B \-\-mssfix
-are designed to work around cases where Path MTU discovery
-is broken on the network path between OpenVPN peers.
-
-The usual symptom of such a breakdown is an OpenVPN
-connection which successfully starts, but then stalls
-during active usage.
-
-If
-.B \-\-fragment
-and
-.B \-\-mssfix
-are used together,
-.B \-\-mssfix
-will take its default
-.B max
-parameter from the
-.B \-\-fragment max
-option.
-
-Therefore, one could lower the maximum UDP packet size
-to 1300 (a good first try for solving MTU\-related
-connection problems) with the following options:
-
-.B \-\-tun\-mtu 1500 \-\-fragment 1300 \-\-mssfix
-.\"*********************************************************
-.TP
-.B \-\-sndbuf size
-Set the TCP/UDP socket send buffer size.
-Defaults to operation system default.
-.\"*********************************************************
-.TP
-.B \-\-rcvbuf size
-Set the TCP/UDP socket receive buffer size.
-Defaults to operation system default.
-.\"*********************************************************
-.TP
-.B \-\-mark value
-Mark encrypted packets being sent with value. The mark value can be
-matched in policy routing and packetfilter rules. This option is
-only supported in Linux and does nothing on other operating systems.
-.\"*********************************************************
-.TP
-.B \-\-socket\-flags flags...
-Apply the given flags to the OpenVPN transport socket.
-Currently, only
-.B TCP_NODELAY
-is supported.
-
-The
-.B TCP_NODELAY
-socket flag is useful in TCP mode, and causes the kernel
-to send tunnel packets immediately over the TCP connection without
-trying to group several smaller packets into a larger packet.
-This can result in a considerably improvement in latency.
-
-This option is pushable from server to client, and should be used
-on both client and server for maximum effect.
-.\"*********************************************************
-.TP
-.B \-\-txqueuelen n
-(Linux only) Set the TX queue length on the TUN/TAP interface.
-Currently defaults to 100.
-.\"*********************************************************
-.TP
-.B \-\-shaper n
-Limit bandwidth of outgoing tunnel data to
-.B n
-bytes per second on the TCP/UDP port.
-Note that this will only work if mode is set to p2p.
-If you want to limit the bandwidth
-in both directions, use this option on both peers.
-
-OpenVPN uses the following algorithm to implement
-traffic shaping: Given a shaper rate of
-.I n
-bytes per second, after a datagram write of
-.I b
-bytes is queued on the TCP/UDP port, wait a minimum of
-.I (b / n)
-seconds before queuing the next write.
-
-It should be noted that OpenVPN supports multiple
-tunnels between the same two peers, allowing you
-to construct full\-speed and reduced bandwidth tunnels
-at the same time,
-routing low\-priority data such as off\-site backups
-over the reduced bandwidth tunnel, and other data
-over the full\-speed tunnel.
-
-Also note that for low bandwidth tunnels
-(under 1000 bytes per second), you should probably
-use lower MTU values as well (see above), otherwise
-the packet latency will grow so large as to trigger
-timeouts in the TLS layer and TCP connections running
-over the tunnel.
-
-OpenVPN allows
-.B n
-to be between 100 bytes/sec and 100 Mbytes/sec.
-.\"*********************************************************
-.TP
-.B \-\-inactive n [bytes]
-Causes OpenVPN to exit after
-.B n
-seconds of inactivity on the TUN/TAP device. The time length of
-inactivity is measured since the last incoming or outgoing tunnel
-packet. The default value is 0 seconds, which disables this feature.
-
-If the optional
-.B bytes
-parameter is included,
-exit if less than
-.B bytes
-of combined in/out traffic are produced on the tun/tap device
-in
-.B n
-seconds.
-
-In any case, OpenVPN's internal ping packets (which are just
-keepalives) and TLS control packets are not considered
-"activity", nor are they counted as traffic, as they are used
-internally by OpenVPN and are not an indication of actual user
-activity.
-.\"*********************************************************
-.TP
-.B \-\-ping n
-Ping remote over the TCP/UDP control channel
-if no packets have been sent for at least
-.B n
-seconds (specify
-.B \-\-ping
-on both peers to cause ping packets to be sent in both directions since
-OpenVPN ping packets are not echoed like IP ping packets).
-When used in one of OpenVPN's secure modes (where
-.B \-\-secret, \-\-tls\-server,
-or
-.B \-\-tls\-client
-is specified), the ping packet
-will be cryptographically secure.
-
-This option has two intended uses:
-
-(1) Compatibility
-with stateful firewalls. The periodic ping will ensure that
-a stateful firewall rule which allows OpenVPN UDP packets to
-pass will not time out.
-
-(2) To provide a basis for the remote to test the existence
-of its peer using the
-.B \-\-ping\-exit
-option.
-.\"*********************************************************
-.TP
-.B \-\-ping\-exit n
-Causes OpenVPN to exit after
-.B n
-seconds pass without reception of a ping
-or other packet from remote.
-This option can be combined with
-.B \-\-inactive, \-\-ping,
-and
-.B \-\-ping\-exit
-to create a two\-tiered inactivity disconnect.
-
-For example,
-
-.B openvpn [options...] \-\-inactive 3600 \-\-ping 10 \-\-ping\-exit 60
-
-when used on both peers will cause OpenVPN to exit within 60
-seconds if its peer disconnects, but will exit after one
-hour if no actual tunnel data is exchanged.
-.\"*********************************************************
-.TP
-.B \-\-ping\-restart n
-Similar to
-.B \-\-ping\-exit,
-but trigger a
-.B SIGUSR1
-restart after
-.B n
-seconds pass without reception of a ping
-or other packet from remote.
-
-This option is useful in cases
-where the remote peer has a dynamic IP address and
-a low\-TTL DNS name is used to track the IP address using
-a service such as
-.I http://dyndns.org/
-+ a dynamic DNS client such
-as
-.B ddclient.
-
-If the peer cannot be reached, a restart will be triggered, causing
-the hostname used with
-.B \-\-remote
-to be re\-resolved (if
-.B \-\-resolv\-retry
-is also specified).
-
-In server mode,
-.B \-\-ping\-restart, \-\-inactive,
-or any other type of internally generated signal will always be
-applied to
-individual client instance objects, never to whole server itself.
-Note also in server mode that any internally generated signal
-which would normally cause a restart, will cause the deletion
-of the client instance object instead.
-
-In client mode, the
-.B \-\-ping\-restart
-parameter is set to 120 seconds by default. This default will
-hold until the client pulls a replacement value from the server, based on
-the
-.B \-\-keepalive
-setting in the server configuration.
-To disable the 120 second default, set
-.B \-\-ping\-restart 0
-on the client.
-
-See the signals section below for more information
-on
-.B SIGUSR1.
-
-Note that the behavior of
-.B SIGUSR1
-can be modified by the
-.B \-\-persist\-tun, \-\-persist\-key, \-\-persist\-local\-ip,
-and
-.B \-\-persist\-remote\-ip
-options.
-
-Also note that
-.B \-\-ping\-exit
-and
-.B \-\-ping\-restart
-are mutually exclusive and cannot be used together.
-.\"*********************************************************
-.TP
-.B \-\-keepalive interval timeout
-A helper directive designed to simplify the expression of
-.B \-\-ping
-and
-.B \-\-ping\-restart.
-
-This option can be used on both client and server side, but it is
-enough to add this on the server side as it will push appropriate
-.B \-\-ping
-and
-.B \-\-ping\-restart
-options to the client. If used on both server and client,
-the values pushed from server will override the client local values.
-
-The
-.B timeout
-argument will be twice as long on the server side. This ensures that
-a timeout is detected on client side before the server side drops
-the connection.
-
-For example,
-.B \-\-keepalive 10 60
-expands as follows:
-
-.nf
-.ft 3
-.in +4
- if mode server:
- ping 10 # Argument: interval
- ping\-restart 120 # Argument: timeout*2
- push "ping 10" # Argument: interval
- push "ping\-restart 60" # Argument: timeout
- else
- ping 10 # Argument: interval
- ping\-restart 60 # Argument: timeout
-.in -4
-.ft
-.fi
-.\"*********************************************************
-.TP
-.B \-\-ping\-timer\-rem
-Run the
-.B \-\-ping\-exit
-/
-.B \-\-ping\-restart
-timer only if we have a remote address. Use this option if you are
-starting the daemon in listen mode (i.e. without an explicit
-.B \-\-remote
-peer), and you don't want to start clocking timeouts until a remote
-peer connects.
-.\"*********************************************************
-.TP
-.B \-\-persist\-tun
-Don't close and reopen TUN/TAP device or run up/down scripts
-across
-.B SIGUSR1
-or
-.B \-\-ping\-restart
-restarts.
-
-.B SIGUSR1
-is a restart signal similar to
-.B SIGHUP,
-but which offers finer\-grained control over
-reset options.
-.\"*********************************************************
-.TP
-.B \-\-persist\-key
-Don't re\-read key files across
-.B SIGUSR1
-or
-.B \-\-ping\-restart.
-
-This option can be combined with
-.B \-\-user nobody
-to allow restarts triggered by the
-.B SIGUSR1
-signal.
-Normally if you drop root privileges in OpenVPN,
-the daemon cannot be restarted since it will now be unable to re\-read protected
-key files.
-
-This option solves the problem by persisting keys across
-.B SIGUSR1
-resets, so they don't need to be re\-read.
-.\"*********************************************************
-.TP
-.B \-\-persist\-local\-ip
-Preserve initially resolved local IP address and port number
-across
-.B SIGUSR1
-or
-.B \-\-ping\-restart
-restarts.
-.\"*********************************************************
-.TP
-.B \-\-persist\-remote\-ip
-Preserve most recently authenticated remote IP address and port number
-across
-.B SIGUSR1
-or
-.B \-\-ping\-restart
-restarts.
-.\"*********************************************************
-.TP
-.B \-\-mlock
-Disable paging by calling the POSIX mlockall function.
-Requires that OpenVPN be initially run as root (though
-OpenVPN can subsequently downgrade its UID using the
-.B \-\-user
-option).
-
-Using this option ensures that key material and tunnel
-data are never written to disk due to virtual
-memory paging operations which occur under most
-modern operating systems. It ensures that even if an
-attacker was able to crack the box running OpenVPN, he
-would not be able to scan the system swap file to
-recover previously used
-ephemeral keys, which are used for a period of time
-governed by the
-.B \-\-reneg
-options (see below), then are discarded.
-
-The downside
-of using
-.B \-\-mlock
-is that it will reduce the amount of physical
-memory available to other applications.
-.\"*********************************************************
-.TP
-.B \-\-up cmd
-Run command
-.B cmd
-after successful TUN/TAP device open
-(pre
-.B \-\-user
-UID change).
-
-.B cmd
-consists of a path to script (or executable program), optionally
-followed by arguments. The path and arguments may be single\- or double\-quoted
-and/or escaped using a backslash, and should be separated by one or more spaces.
-
-The up command is useful for specifying route
-commands which route IP traffic destined for
-private subnets which exist at the other
-end of the VPN connection into the tunnel.
-
-For
-.B \-\-dev tun
-execute as:
-
-.B cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [ init | restart ]
-
-For
-.B \-\-dev tap
-execute as:
-
-.B cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [ init | restart ]
-
-See the "Environmental Variables" section below for
-additional parameters passed as environmental variables.
-
-Note that if
-.B cmd
-includes arguments, all OpenVPN\-generated arguments will be appended
-to them to build an argument list with which the executable will be
-called.
-
-Typically,
-.B cmd
-will run a script to add routes ...
[truncated message content] |
