diff options
Diffstat (limited to 'doc/man-sections/generic-options.rst')
| -rw-r--r-- | doc/man-sections/generic-options.rst | 438 |
1 files changed, 438 insertions, 0 deletions
diff --git a/doc/man-sections/generic-options.rst b/doc/man-sections/generic-options.rst new file mode 100644 index 0000000..a07fe7e --- /dev/null +++ b/doc/man-sections/generic-options.rst @@ -0,0 +1,438 @@ +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. + +--cd dir + 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 :code:`.` or :code:`..`. + + 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. + +--chroot dir + 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 random. Newer linux kernels and some + BSDs implement a getrandom() or getentropy() syscall that removes the + need for /dev/urandom to be available. + +--config file + 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 + +--daemon progname + Become a daemon after all initialization functions are completed. This + option will cause all message and error output to be sent to the syslog + file (such as :code:`/var/log/messages`), except for the output of + scripts and ifconfig commands, which will go to :code:`/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-occ + 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. + +--engine engine-name + Enable OpenSSL hardware-based crypto engine functionality. + + 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. + +--group group + Similar to the ``--user`` option, this option changes the group ID of + the OpenVPN process to ``group`` after initialization. + +--ignore-unknown-option args + 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. + +--iproute cmd + Set alternate command to execute instead of default ``iproute2`` command. + May be used in order to execute OpenVPN in unprivileged environment. + +--keying-material-exporter args + Save Exported Keying Material [RFC5705] of len bytes (must be between 16 + and 4095 bytes) using ``label`` in environment + (:code:`exported_keying_material`) for use by plugins in + :code:`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 + :code:`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. + +--nice n + 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 :code:`SIGUSR1` or ``--ping-restart``. + + This option can be combined with ``--user nobody`` to allow restarts + triggered by the :code:`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 :code:`SIGUSR1` + resets, so they don't need to be re-read. + +--remap-usr1 signal + Control whether internally or externally generated :code:`SIGUSR1` signals + are remapped to :code:`SIGHUP` (restart without persisting state) or + SIGTERM (exit). + + ``signal`` can be set to :code:`SIGHUP` or :code:`SIGTERM`. By default, + no remapping occurs. + +--script-security level + 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``: + + :code:`0` + Strictly no calling of external programs. + + :code:`1` + (Default) Only call built-in executables such as ifconfig, + ip, route, or netsh. + + :code:`2` + Allow calling of built-in executables and user-defined + scripts. + + :code:`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 :code:`execve` or :code:`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 :code:`system` flag was removed is due to + the security implications with shell expansions when executing scripts + via the :code:`system()` call. + +--setcon context + 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. + +--status args + Write operational status to ``file`` every ``n`` seconds. + + Valid syntaxes: + :: + + status file + status file n + + Status can also be written to the syslog by sending a :code:`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-version n + 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: + + :code:`1` + Traditional format (default). The client list contains the + following fields comma-separated: Common Name, Real Address, Bytes + Received, Bytes Sent, Connected Since. + + :code:`2` + A more reliable format for external processing. Compared to + version :code:`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. + + :code:`3` + Identical to :code:`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-dir dir + 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 :code:`OPENVPN_PLUGIN_CLIENT_CONNECT` + plug-in hook to dynamically generate client-specific configuration + :code:`client_connect_config_file` and return success/failure via + :code:`client_connect_deferred_file` when using deferred client connect + method + + * :code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` plug-in hooks returns + success/failure via :code:`auth_control_file` when using deferred auth + method + + * :code:`OPENVPN_PLUGIN_ENABLE_PF` plugin hook to pass filtering rules + via ``pf_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. + +--user user + 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 :code:`nobody` or somebody similarly unprivileged, + 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 :code:`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). + +--writepid file + Write OpenVPN's main process ID to ``file``. |