我的书签
添加书签
移除书签NAME
links
| OPENVPN(8) | System Manager's Manual | OPENVPN(8) |
openvpn - Secure IP tunnel daemon
SYNOPSIS
openvpn [ options ... ]
openvpn --help
INTRODUCTION
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: <https://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 openvpn without any parameters.
DESCRIPTION
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 (Static Key mode) or public key security (SSL/TLS mode) using client & server certificates. OpenVPN also supports non-encrypted TCP/UDP tunnels.
OpenVPN is designed to work with the 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.
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.
Generic Options
This section covers generic options which are accessible regardless of which mode OpenVPN is configured as.
--help : Show options.
--auth-nocache : Don't cache --askpass or --auth-user-pass username/passwords in virtual memory.
If specified, this directive will cause OpenVPN to immediately
forget username/password inputs after they are used. As a result, when
OpenVPN needs a username/password, it will prompt for input from stdin,
which may be multiple times during the duration of an OpenVPN
session.
When using **--auth-nocache** in combination with a
user/password file and **--chroot** or **--daemon**, make sure to
use an absolute path.
This directive does not affect the **--http-proxy**
username/password. It is always cached.
--cddir : Change directory to dir prior to reading any files such as configuration files, key files, scripts, etc. dir should be an absolute path, with a leading “/”, and without any references to the current directory such as . or ...
This option is useful when you are running OpenVPN in
**--daemon** mode, and you want to consolidate all of your OpenVPN
control files in one location.
--chrootdir : Chroot to dir after initialization. --chroot essentially redefines dir as being the top level directory tree (/). OpenVPN will therefore be unable to access any files outside this tree. This can be desirable from a security standpoint.
Since the chroot operation is delayed until after
initialization, most OpenVPN options that reference files will operate
in a pre-chroot context.
In many cases, the **dir** parameter can point to an empty
directory, however complications can result when scripts or restarts are
executed after the chroot operation.
Note: The SSL library will probably need /dev/urandom to be
available inside the chroot directory **dir**. This is because SSL
libraries occasionally need to collect fresh randomness. Newer linux
kernels and some BSDs implement a getrandom() or getentropy() syscall
that removes the need for /dev/urandom to be available.
--compat-modeversion : This option provides a convenient way to alter the defaults of OpenVPN to be more compatible with the version version specified. All of the changes this option applies can also be achieved using individual configuration options.
The version specified with this option is the version of
OpenVPN peer OpenVPN should try to be compatible with. In general
OpenVPN should be compatible with the last two previous version without
this option. E.g. OpenVPN 2.6.0 should be compatible with 2.5.x and
2.4.x without this option. However, there might be some edge cases that
still require this option even in these cases.
Note: Using this option reverts defaults to no longer
recommended values and should be avoided if possible.
The following table details what defaults are changed
depending on the version specified.
- 2.5.x or lower: --allow-compression asym is automatically added to the configuration if no other compression options are present.
- 2.4.x or lower: The cipher in --cipher is appended to --data-ciphers.
- 2.3.x or lower: --data-cipher-fallback is automatically added with the same cipher as --cipher.
- 2.3.6 or lower: --tls-version-min 1.0 is added to the configuration when --tls-version-min is not explicitly set.
If not required, this is option should be avoided. Setting this option can lower security or disable features like data-channel offloading.
--configfile : Load additional config options from file where each line corresponds to one command line option, but with the leading -- removed.
If **--config file** is the only option to the openvpn
command, the **--config** can be removed, and the command can be
given as **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:
\\ 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.
For example on Windows, use double backslashes to represent pathnames:
secret "c:\\OpenVPN\\secret.key"
For examples of configuration files, see <https://openvpn.net/community-resources/how-to/>
Here is an example configuration file:
#
## 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
--daemonprogname : Become a daemon after all initialization functions are completed.
Valid syntaxes:
daemon
daemon progname
This option will cause all message and error output to be sent to the syslog file (such as /var/log/messages), except for the output of scripts and ifconfig commands, which will go to /dev/null unless otherwise redirected. The syslog redirection occurs immediately at the point that --daemon is parsed on the command line even though the daemonization point occurs later. If one of the --log options is present, it will supersede syslog redirection.
The optional progname parameter will cause OpenVPN to report its program name to the system logger as progname. This can be useful in linking OpenVPN messages in the syslog file with specific tunnels. When unspecified, progname defaults to openvpn.
When OpenVPN is run with the --daemon option, it will try to delay daemonization until the majority of initialization functions which are capable of generating fatal errors are complete. This means that initialization scripts can test the return status of the openvpn command for a fairly reliable indication of whether the command has correctly initialized and entered the packet forwarding event loop.
In OpenVPN, the vast majority of errors which occur after initialization are non-fatal.
Note: as soon as OpenVPN has daemonized, it can not ask for usernames, passwords, or key pass phrases anymore. This has certain consequences, namely that using a password-protected private key will fail unless the --askpass option is used to tell OpenVPN to ask for the pass phrase (this requirement is new in v2.3.7, and is a consequence of calling daemon() before initializing the crypto layer).
Further, using --daemon together with --auth-user-pass (entered on console) and --auth-nocache will fail as soon as key renegotiation (and reauthentication) occurs.
--disable-dco : Disable “data channel offload” (DCO).
On Linux don't use the ovpn-dco device driver, but rather rely
on the legacy tun module.
You may want to use this option if your server needs to allow
clients older than version 2.4 to connect.
--disable-occ : DEPRECATED Disable “options consistency check” (OCC) in configurations that do not use TLS.
Don't output a warning message if option inconsistencies are
detected between peers. An example of an option inconsistency would be
where one peer uses **--dev tun** while the other peer uses **--dev
tap**.
Use of this option is discouraged, but is provided as a
temporary fix in situations where a recent version of OpenVPN must
connect to an old version.
--engineengine-name : Enable OpenSSL hardware-based crypto engine functionality.
Valid syntaxes:
engine
engine engine-name
If engine-name is specified, use a specific crypto engine. Use the --show-engines standalone option to list the crypto engines which are supported by OpenSSL.
--fast-io : (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to poll/epoll/select prior to the write operation. The purpose of such a call would normally be to block until the device or socket is ready to accept the write. Such blocking is unnecessary on some platforms which don't support write blocking on UDP sockets or TUN/TAP devices. In such cases, one can optimize the event loop by avoiding the poll/epoll/select call, improving CPU efficiency by 5% to 10%.
This option can only be used on non-Windows systems, when
**--proto** **udp** is specified, and when **--shaper** is
*NOT* specified.
--groupgroup : Similar to the --user option, this option changes the group ID of the OpenVPN process to group after initialization.
--ignore-unknown-optionargs : Valid syntax:
ignore-unknown-options opt1 opt2 opt3 ... optN
When one of options opt1 ... optN is encountered in the configuration file the configuration file parsing does not fail if this OpenVPN version does not support the option. Multiple --ignore-unknown-option options can be given to support a larger number of options to ignore.
This option should be used with caution, as there are good security reasons for having OpenVPN fail if it detects problems in a config file. Having said that, there are valid reasons for wanting new software features to gracefully degrade when encountered by older software versions.
--ignore-unknown-option is available since OpenVPN 2.3.3.
--iproutecmd : Set alternate command to execute instead of default iproute2 command. May be used in order to execute OpenVPN in unprivileged environment.
--keying-material-exporterargs : Save Exported Keying Material [RFC5705] of len bytes (must be between 16 and 4095 bytes) using label in environment (exported_keying_material) for use by plugins in OPENVPN_PLUGIN_TLS_FINAL callback.
Valid syntax:
keying-material-exporter label len
Note that exporter labels have the potential to collide with existing PRF labels. In order to prevent this, labels MUST begin with EXPORTER.
--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 --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 **--reneg**
options (see below), then are discarded.
The downside of using **--mlock** is that it will reduce
the amount of physical memory available to other applications.
The limit on how much memory can be locked and how that limit
is enforced are OS-dependent. On Linux the default limit that an
unprivileged process may lock (RLIMIT\_MEMLOCK) is low, and if privileges
are dropped later, future memory allocations will very likely fail. The
limit can be increased using ulimit or systemd directives depending on
how OpenVPN is started.
If the platform has the [getrlimit(2)](https://manpages.debian.org/bookworm/manpages-dev/getrlimit.2.en.html) system call, OpenVPN will
check for the amount of mlock-able memory before calling [mlockall(2)](https://manpages.debian.org/bookworm/manpages-dev/mlockall.2.en.html),
and tries to increase the limit to 100 MB if less than this is
configured. 100 Mb is somewhat arbitrary - it is enough for a
moderately-sized OpenVPN deployment, but the memory usage might go
beyond that if the number of concurrent clients is high.
--nicen : Change process priority after initialization (n greater than 0 is lower priority, n less than zero is higher priority).
--persist-key : Don't re-read key files across SIGUSR1 or --ping-restart.
This option can be combined with **--user** to allow
restarts triggered by the **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
**SIGUSR1** resets, so they don't need to be re-read.
--providersproviders : Load the list of (OpenSSL) providers. This is mainly useful for using an external provider for key management like tpm2-openssl or to load the legacy provider with
--providers legacy default
Behaviour of changing this option between SIGHUP might not be well behaving. If you need to change/add/remove this option, fully restart OpenVPN.
--remap-usr1signal : Control whether internally or externally generated SIGUSR1 signals are remapped to SIGHUP (restart without persisting state) or SIGTERM (exit).
**signal** can be set to **SIGHUP** or **SIGTERM**.
By default, no remapping occurs.
--script-securitylevel : This directive offers policy-level control over OpenVPN's usage of external programs and scripts. Lower level values are more restrictive, higher values are more permissive. Settings for level:
*0* : Strictly no calling of external programs.
*1* : (Default) Only call built-in executables such as ifconfig, ip, route, or netsh.
*2* : Allow calling of built-in executables and user-defined scripts.
*3* : Allow passwords to be passed to scripts via environmental variables (potentially unsafe).
OpenVPN releases before v2.3 also supported a method flag which indicated how OpenVPN should call external commands and scripts. This could be either execve or system. As of OpenVPN 2.3, this flag is no longer accepted. In most *nix environments the execve() approach has been used without any issues.
Some directives such as --up allow options to be passed to the external script. In these cases make sure the script name does not contain any spaces or the configuration parser will choke because it can't determine where the script name ends and script options start.
To run scripts in Windows in earlier OpenVPN versions you needed to either add a full path to the script interpreter which can parse the script or use the system flag to run these scripts. As of OpenVPN 2.3 it is now a strict requirement to have full path to the script interpreter when running non-executables files. This is not needed for executable files, such as .exe, .com, .bat or .cmd files. For example, if you have a Visual Basic script, you must use this syntax now:
--up 'C:\\Windows\\System32\\wscript.exe C:\\Program\ Files\\OpenVPN\\config\\my-up-script.vbs'
Please note the single quote marks and the escaping of the backslashes () and the space character.
The reason the support for the system flag was removed is due to the security implications with shell expansions when executing scripts via the system() call.
--setconcontext : Apply SELinux context after initialization. This essentially provides the ability to restrict OpenVPN's rights to only network I/O operations, thanks to SELinux. This goes further than --user and --chroot in that those two, while being great security features, unfortunately do not protect against privilege escalation by exploitation of a vulnerable system call. You can of course combine all three, but please note that since setcon requires access to /proc you will have to provide it inside the chroot directory (e.g. with mount --bind).
Since the setcon operation is delayed until after
initialization, OpenVPN can be restricted to just network-related system
calls, whereas by applying the context before startup (such as the
OpenVPN one provided in the SELinux Reference Policies) you will have to
allow many things required only during initialization.
Like with chroot, complications can result when scripts or
restarts are executed after the setcon operation, which is why you
should really consider using the **--persist-key** and
**--persist-tun** options.
--statusargs : Write operational status to file every n seconds. n defaults to 60 if not specified.
Valid syntaxes:
status file
status file n
Status can also be written to the syslog by sending a SIGUSR2 signal.
With multi-client capability enabled on a server, the status file includes a list of clients and a routing table. The output format can be controlled by the --status-version option in that case.
For clients or instances running in point-to-point mode, it will contain the traffic statistics.
--status-versionn : Set the status file format version number to n.
This only affects the status file on servers with multi-client
capability enabled. Valid status version values:
*1* : Traditional format (default). The client list contains the following fields comma-separated: Common Name, Real Address, Bytes Received, Bytes Sent, Connected Since.
*2 : A more reliable format for external processing. Compared to version 1*, the client list contains some additional fields: Virtual Address, Virtual IPv6 Address, Username, Client ID, Peer ID, Data Channel Cipher. Future versions may extend the number of fields.
*3 : Identical to 2*, but fields are tab-separated.
--test-crypto : Do a self-test of OpenVPN's crypto options by encrypting and decrypting test packets using the data channel encryption options specified above. This option does not require a peer to function, and therefore can be specified without --dev or --remote.
The typical usage of **--test-crypto** would be something
like this:
openvpn --test-crypto --secret key
or
openvpn --test-crypto --secret key --verb 9
This option is very useful to test OpenVPN after it has been ported to a new platform, or to isolate problems in the compiler, OpenSSL crypto library, or OpenVPN's crypto code. Since it is a self-test mode, problems with encryption and authentication can be debugged independently of network and tunnel issues.
--tmp-dirdir : Specify a directory dir for temporary files. This directory will be used by openvpn processes and script to communicate temporary data with openvpn main process. Note that the directory must be writable by the OpenVPN process after it has dropped it's root privileges.
This directory will be used by in the following cases:
- --client-connect scripts and OPENVPN_PLUGIN_CLIENT_CONNECT plug-in hook to dynamically generate client-specific configuration client_connect_config_file and return success/failure via client_connect_deferred_file when using deferred client connect method
- OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY plug-in hooks returns success/failure via auth_control_file when using deferred auth method and pending authentification via pending_auth_file.
--use-prediction-resistance : Enable prediction resistance on mbed TLS's RNG.
Enabling prediction resistance causes the RNG to reseed in
each call for random. Reseeding this often can quickly deplete the
kernel entropy pool.
If you need this option, please consider running a daemon that
adds entropy to the kernel pool.
--useruser : Change the user ID of the OpenVPN process to user after initialization, dropping privileges in the process. This option is useful to protect the system in the event that some hostile party was able to gain control of an OpenVPN session. Though OpenVPN's security features make this unlikely, it is provided as a second line of defense.
By setting **user** to an unprivileged user dedicated to
run openvpn, the hostile party would be limited in what damage they
could cause. Of course once you take away privileges, you cannot return
them to an OpenVPN session. This means, for example, that if you want to
reset an OpenVPN daemon with a **SIGUSR1** signal (for example in
response to a DHCP reset), you should make use of one or more of the
**--persist** options to ensure that OpenVPN doesn't need to execute
any privileged operations in order to restart (such as re-reading key
files or running **ifconfig** on the TUN device).
NOTE: Previous versions of openvpn used **nobody** as the
example unpriviledged user. It is not recommended to actually use that
user since it is usually used by other system services already. Always
create a dedicated user for openvpn.
--writepidfile : Write OpenVPN's main process ID to file.
Log options
--echoparms : Echo parms to log output.
Designed to be used to send messages to a controlling
application which is receiving the OpenVPN log output.
--errors-to-stderr : Output errors to stderr instead of stdout unless log output is redirected by one of the --log options.
--logfile : Output logging messages to file, including output to stdout/stderr which is generated by called scripts. If file already exists it will be truncated. This option takes effect immediately when it is parsed in the command line and will supersede syslog output if --daemon is also specified. This option is persistent over the entire course of an OpenVPN instantiation and will not be reset by SIGHUP, SIGUSR1, or --ping-restart.
Note that on Windows, when OpenVPN is started as a service,
logging occurs by default without the need to specify this option.
--log-appendfile : Append logging messages to file. If file does not exist, it will be created. This option behaves exactly like --log except that it appends to rather than truncating the log file.
--machine-readable-output : Always write timestamps and message flags to log messages, even when they otherwise would not be prefixed. In particular, this applies to log messages sent to stdout.
--muten : Log at most n consecutive messages in the same category. This is useful to limit repetitive logging of similar message types.
--mute-replay-warnings : Silence the output of replay warnings, which are a common false alarm on WiFi networks. This option preserves the security of the replay protection code without the verbosity associated with warnings about duplicate packets.
--suppress-timestamps : Avoid writing timestamps to log messages, even when they otherwise would be prepended. In particular, this applies to log messages sent to stdout.
--syslogprogname : Direct log output to system logger, but do not become a daemon. See --daemon directive above for description of progname parameter.
--verbn : Set output verbosity to n (default 1). Each level shows all info from the previous levels. Level 3 is recommended if you want a good summary of what's happening without being swamped by output.
*0* : No output except fatal errors.
*1* to 4**** : Normal usage range.
*5 : Outputs R and W* characters to the console for each packet read and write, uppercase is used for TCP/UDP packets and lowercase is used for TUN/TAP packets.
*6* to 11* : Debug info range (see *errlevel.h in the source code for additional information on debug levels).
Protocol options
Options in this section affect features available in the OpenVPN wire protocol. Many of these options also define the encryption options of the data channel in the OpenVPN wire protocol. These options must be configured in a compatible way between both the local and remote side.
--allow-compressionmode : As described in the --compress option, compression is a potentially dangerous option. This option allows controlling the behaviour of OpenVPN when compression is used and allowed.
Valid syntaxes:
allow-compression
allow-compression mode
The mode argument can be one of the following values:
*asym* : OpenVPN will only decompress downlink packets but not compress uplink packets. This also allows migrating to disable compression when changing both server and client configurations to remove compression at the same time is not a feasible option.
*no* (default) : OpenVPN will refuse any compression. If data-channel offloading is enabled, OpenVPN will additionally also refuse compression framing (stub).
*yes* : OpenVPN will send and receive compressed packets.
--authalg : Authenticate data channel packets and (if enabled) tls-auth control channel packets with HMAC using message digest algorithm alg. (The default is SHA1 ). HMAC is a commonly used message authentication algorithm (MAC) that uses a data string, a secure hash algorithm and a key to produce a digital signature.
The OpenVPN data channel protocol uses encrypt-then-mac (i.e.
first encrypt a packet then HMAC the resulting ciphertext), which
prevents padding oracle attacks.
If an AEAD cipher mode (e.g. GCM) is chosen then the specified
**--auth** algorithm is ignored for the data channel and the
authentication method of the AEAD cipher is used instead. Note that
**alg** still specifies the digest used for **tls-auth**.
In static-key encryption mode, the HMAC key is included in the
key file generated by **--genkey**. In TLS mode, the HMAC key is
dynamically generated and shared between peers via the TLS control
channel. If OpenVPN receives a packet with a bad HMAC it will drop the
packet. HMAC usually adds 16 or 20 bytes per packet. Set **alg=none**
to disable authentication.
For more information on HMAC see
*<http://www.cs.ucsd.edu/users/mihir/papers/hmac.html>*
--cipheralg : This option should not be used any longer in TLS mode and still exists for two reasons:
- compatibility with old configurations still carrying it around;
- allow users connecting to OpenVPN peers older than 2.6.0 to have --cipher configured the same way as the remote counterpart. This can avoid MTU/frame size warnings.
Before 2.4.0, this option was used to select the cipher to be configured on the data channel, however, later versions usually ignored this directive in favour of a negotiated cipher. Starting with 2.6.0, this option is always ignored in TLS mode when it comes to configuring the cipher and will only control the cipher for --secret pre-shared-key mode (note: this mode is deprecated and strictly not recommended).
If you wish to specify the cipher to use on the data channel, please see --data-ciphers (for regular negotiation) and --data-ciphers-fallback (for a fallback option when the negotiation cannot take place because the other peer is old or has negotiation disabled).
To see ciphers that are available with OpenVPN, use the --show-ciphers option.
Set alg to none to disable encryption.
--compressalgorithm : DEPRECATED Enable a compression algorithm. Compression is generally not recommended. VPN tunnels which use compression are susceptible to the VORALCE attack vector. See also the migrate parameter below.
The **algorithm** parameter may be **lzo**, **lz4**,
**lz4-v2**, **stub**, **stub-v2**, **migrate** or empty. LZO
and LZ4 are different compression algorithms, with LZ4 generally
offering the best performance with least CPU usage.
The **lz4-v2** and **stub-v2** variants implement a
better framing that does not add overhead when packets cannot be
compressed. All other variants always add one extra framing byte
compared to no compression framing.
Especially **stub-v2** is essentially identical to no
compression and no compression framing as its header indicates IP
version 5 in a tun setup and can (ab)used to complete disable
compression to clients. (See the **migrate** option below)
If the **algorithm** parameter is **stub**,
**stub-v2** or empty, compression will be turned off, but the packet
framing for compression will still be enabled, allowing a different
setting to be pushed later. Additionally, **stub** and **stub-v2**
wil disable announcing **lzo** and **lz4** compression support via
*IV\_* variables to the server.
Note: the **stub** (or empty) option is NOT compatible with
the older option **--comp-lzo no**.
Using **migrate** as compression algorithm enables a
special migration mode. It allows migration away from the
**--compress**/**--comp-lzo** options to no compression. This
option sets the server to no compression mode and the server behaves
identical to a server without a compression option for all clients
without a compression in their config. However, if a client is detected
that indicates that compression is used (via OCC), the server will
automatically add **--push compress stub-v2** to the client specific
configuration if supported by the client and otherwise switch to
**comp-lzo no** and add **--push comp-lzo** to the client specific
configuration.
**\*Security Considerations\***
Compression and encryption is a tricky combination. If an
attacker knows or is able to control (parts of) the plain-text of
packets that contain secrets, the attacker might be able to extract the
secret if compression is enabled. See e.g. the *CRIME* and
*BREACH* attacks on TLS and *VORACLE* on VPNs which also
leverage to break encryption. If you are not entirely sure that the
above does not apply to your traffic, you are advised to *not*
enable compression.
--comp-lzomode : DEPRECATED Enable LZO compression algorithm. Compression is generally not recommended. VPN tunnels which uses compression are suspectible to the VORALCE attack vector.
Use LZO compression -- may add up to 1 byte per packet for
incompressible data. **mode** may be **yes**, **no**, or
**adaptive** (default).
In a server mode setup, it is possible to selectively turn
compression on or off for individual clients.
First, make sure the client-side config file enables selective
compression by having at least one **--comp-lzo** directive, such as
**--comp-lzo no**. This will turn off compression by default, but
allow a future directive push from the server to dynamically change the
**on**/**off**/**adaptive** setting.
Next in a **--client-config-dir** file, specify the
compression setting for the client, for example:
comp-lzo yes
push "comp-lzo yes"
The first line sets the comp-lzo setting for the server side of the link, the second sets the client side.
--comp-noadapt : DEPRECATED When used in conjunction with --comp-lzo, this option will disable OpenVPN's adaptive compression algorithm. Normally, adaptive compression is enabled with --comp-lzo.
Adaptive compression tries to optimize the case where you have
compression enabled, but you are sending predominantly incompressible
(or pre-compressed) packets over the tunnel, such as an FTP or rsync
transfer of a large, compressed file. With adaptive compression, OpenVPN
will periodically sample the compression process to measure its
efficiency. If the data being sent over the tunnel is already
compressed, the compression efficiency will be very low, triggering
openvpn to disable compression for a period of time until the next
re-sample test.
--key-direction : Alternative way of specifying the optional direction parameter for the --tls-auth and --secret options. Useful when using inline files (See section on inline files).
--data-cipherscipher-list : Restrict the allowed ciphers to be negotiated to the ciphers in cipher-list. cipher-list is a colon-separated list of ciphers, and defaults to AES-256-GCM:AES-128-GCM:CHACHA20-POLY1305 when Chacha20-Poly1305 is available and otherwise AES-256-GCM:AES-128-GCM.
For servers, the first cipher from **cipher-list** that is
also supported by the client will be pushed to clients that support
cipher negotiation.
For more details see the chapter on *Data channel cipher
negotiation*. *Especially* if you need to support clients with
OpenVPN versions older than 2.4!
Starting with OpenVPN 2.6 a cipher can be prefixed with a
**?** to mark it as optional. This allows including ciphers in the
list that may not be available on all platforms. E.g.
**AES-256-GCM:AES-128-GCM:?CHACHA20-POLY1305** would only enable
Chacha20-Poly1305 if the underlying SSL library (and its configuration)
supports it.
Cipher negotiation is enabled in client-server mode only. I.e.
if **--mode** is set to *server* (server-side, implied by
setting **--server** ), or if **--pull** is specified
(client-side, implied by setting **--client**).
If no common cipher is found during cipher negotiation, the
connection is terminated. To support old clients/old servers that do not
provide any cipher negotiation support see
**--data-ciphers-fallback**.
If **--compat-mode** is set to a version older than 2.5.0
the cipher specified by **--cipher** will be appended to
**--data-ciphers** if not already present.
This list is restricted to be 127 chars long after conversion
to OpenVPN ciphers.
This option was called **--ncp-ciphers** in OpenVPN 2.4 but
has been renamed to **--data-ciphers** in OpenVPN 2.5 to more
accurately reflect its meaning.
--data-ciphers-fallbackalg : Configure a cipher that is used to fall back to if we could not determine which cipher the peer is willing to use.
This option should only be needed to connect to peers that are
running OpenVPN 2.3 or older versions, and have been configured with
**--enable-small** (typically used on routers or other embedded
devices).
--secretargs : DEPRECATED Enable Static Key encryption mode (non-TLS). Use pre-shared secret file which was generated with --genkey.
Valid syntaxes:
secret file
secret file direction
The optional direction parameter enables the use of 4 distinct keys (HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that each data flow direction has a different set of HMAC and cipher keys. This has a number of desirable security properties including eliminating certain kinds of DoS and message replay attacks.
When the direction parameter is omitted, 2 keys are used bidirectionally, one for HMAC and the other for encryption/decryption.
The direction parameter should always be complementary on either side of the connection, i.e. one side should use 0 and the other should use 1, or both sides should omit it altogether.
The direction parameter requires that file contains a 2048 bit key. While pre-1.5 versions of OpenVPN generate 1024 bit key files, any version of OpenVPN which supports the direction parameter, will also support 2048 bit key file generation using the --genkey option.
Static key encryption mode has certain advantages, the primary being ease of configuration.
There are no certificates or certificate authorities or complicated negotiation handshakes and protocols. The only requirement is that you have a pre-existing secure channel with your peer (such as ssh) to initially copy the key. This requirement, along with the fact that your key never changes unless you manually generate a new one, makes it somewhat less secure than TLS mode (see below). If an attacker manages to steal your key, everything that was ever encrypted with it is compromised. Contrast that to the perfect forward secrecy features of TLS mode (using Diffie Hellman key exchange), where even if an attacker was able to steal your private key, he would gain no information to help him decrypt past sessions.
Another advantageous aspect of Static Key encryption mode is that it is a handshake-free protocol without any distinguishing signature or feature (such as a header or protocol handshake sequence) that would mark the ciphertext packets as being generated by OpenVPN. Anyone eavesdropping on the wire would see nothing but random-looking data.
--tran-windown : Transition window -- our old key can live this many seconds after a new a key renegotiation begins (default 3600 seconds). This feature allows for a graceful transition from old to new key, and removes the key renegotiation sequence from the critical path of tunnel data forwarding.
Client Options
The client options are used when connecting to an OpenVPN server configured to use --server, --server-bridge, or --mode server in its configuration.
--allow-pull-fqdn : Allow client to pull DNS names from server (rather than being limited to IP address) for --ifconfig, --route, and --route-gateway.
--allow-recursive-routing : When this option is set, OpenVPN will not drop incoming tun packets with same destination as host.
--auth-tokentoken : This is not an option to be used directly in any configuration files, but rather push this option from a --client-connect script or a --plugin which hooks into the OPENVPN_PLUGIN_CLIENT_CONNECT or OPENVPN_PLUGIN_CLIENT_CONNECT_V2 calls. This option provides a possibility to replace the clients password with an authentication token during the lifetime of the OpenVPN client.
Whenever the connection is renegotiated and the
**--auth-user-pass-verify** script or **--plugin** making use of
the **OPENVPN\_PLUGIN\_AUTH\_USER\_PASS\_VERIFY** hook is triggered, it
will pass over this token as the password instead of the password the
user provided. The authentication token can only be reset by a full
reconnect where the server can push new options to the client. The
password the user entered is never preserved once an authentication
token has been set. If the OpenVPN server side rejects the
authentication token then the client will receive an **AUTH\_FAILED**
and disconnect.
The purpose of this is to enable two factor authentication
methods, such as HOTP or TOTP, to be used without needing to retrieve a
new OTP code each time the connection is renegotiated. Another use case
is to cache authentication data on the client without needing to have
the users password cached in memory during the life time of the
session.
To make use of this feature, the **--client-connect**
script or **--plugin** needs to put
push "auth-token UNIQUE_TOKEN_VALUE"
into the file/buffer for dynamic configuration data. This will then make the OpenVPN server to push this value to the client, which replaces the local password with the UNIQUE_TOKEN_VALUE.
Newer clients (2.4.7+) will fall back to the original password method after a failed auth. Older clients will keep using the token value and react according to --auth-retry
--auth-token-userbase64username : Companion option to --auth-token. This options allows to override the username used by the client when reauthenticating with the auth-token. It also allows to use --auth-token in setups that normally do not use username and password.
The username has to be base64 encoded.
--auth-user-pass : Authenticate with server using username/password.
Valid syntaxes:
auth-user-pass
auth-user-pass up
If up is present, it must be a file containing username/password on 2 lines. If the password line is missing, OpenVPN will prompt for one.
If up is omitted, username/password will be prompted from the console.
The server configuration must specify an --auth-user-pass-verify script to verify the username/password provided by the client.
--auth-retrytype : Controls how OpenVPN responds to username/password verification errors such as the client-side response to an AUTH_FAILED message from the server or verification failure of the private key password.
Normally used to prevent auth errors from being fatal on the
client side, and to permit username/password requeries in case of
error.
An **AUTH\_FAILED** message is generated by the server if
the client fails **--auth-user-pass** authentication, or if the
server-side **--client-connect** script returns an error status when
the client tries to connect.
**type** can be one of:
*none* : Client will exit with a fatal error (this is the default).
*nointeract* : Client will retry the connection without requerying for an --auth-user-pass username/password. Use this option for unattended clients.
*interact* : Client will requery for an --auth-user-pass username/password and/or private key password before attempting a reconnection.
Note that while this option cannot be pushed, it can be cont
（本文超出站点单文档体积上限，已截断）
