From patchwork Mon Feb 14 06:33:42 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Frank Lichtenheld X-Patchwork-Id: 2287 Return-Path: Delivered-To: patchwork@openvpn.net Delivered-To: patchwork@openvpn.net Received: from director14.mail.ord1d.rsapps.net ([172.30.191.6]) by backend41.mail.ord1d.rsapps.net with LMTP id eBHAGsOSCmIAaQAAqwncew (envelope-from ) for ; Mon, 14 Feb 2022 12:34:59 -0500 Received: from proxy17.mail.ord1d.rsapps.net ([172.30.191.6]) by director14.mail.ord1d.rsapps.net with LMTP id 6EPiHsOSCmLBCAAAeJ7fFg (envelope-from ) for ; Mon, 14 Feb 2022 12:34:59 -0500 Received: from smtp36.gate.ord1d ([172.30.191.6]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by proxy17.mail.ord1d.rsapps.net with LMTPS id WP3HHsOSCmJNDAAAWC7mWg (envelope-from ) for ; Mon, 14 Feb 2022 12:34:59 -0500 X-Spam-Threshold: 95 X-Spam-Score: 0 X-Spam-Flag: NO X-Virus-Scanned: OK X-Orig-To: openvpnslackdevel@openvpn.net X-Originating-Ip: [216.105.38.7] Authentication-Results: smtp36.gate.ord1d.rsapps.net; iprev=pass policy.iprev="216.105.38.7"; spf=pass smtp.mailfrom="openvpn-devel-bounces@lists.sourceforge.net" smtp.helo="lists.sourceforge.net"; dkim=fail (signature verification failed) header.d=sourceforge.net; dkim=fail (signature verification failed) header.d=sf.net; dmarc=none (p=nil; dis=none) header.from=lichtenheld.com X-Suspicious-Flag: YES X-Classification-ID: 6e255b38-8dbc-11ec-b41f-525400c11307-1-1 Received: from [216.105.38.7] ([216.105.38.7:36166] helo=lists.sourceforge.net) by smtp36.gate.ord1d.rsapps.net (envelope-from ) (ecelerity 4.2.38.62370 r(:)) with ESMTPS (cipher=DHE-RSA-AES256-GCM-SHA384) id 5C/14-05864-2C29A026; Mon, 14 Feb 2022 12:34:58 -0500 Received: from [127.0.0.1] (helo=sfs-ml-2.v29.lw.sourceforge.com) by sfs-ml-2.v29.lw.sourceforge.com with esmtp (Exim 4.94.2) (envelope-from ) id 1nJfEd-000681-UM; Mon, 14 Feb 2022 17:33:58 +0000 Received: from [172.30.20.202] (helo=mx.sourceforge.net) by sfs-ml-2.v29.lw.sourceforge.com with esmtps (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1nJfEb-00067q-Vo for openvpn-devel@lists.sourceforge.net; Mon, 14 Feb 2022 17:33:56 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sourceforge.net; s=x; h=Content-Transfer-Encoding:MIME-Version:References: In-Reply-To:Message-Id:Date:Subject:To:From:Sender:Reply-To:Cc:Content-Type: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=okQCfRflmol7vQux1kTX9I78ine7Z856I+lLOmAAzdA=; b=bAQ4juCM93z9+4ovb9K0JjTLQv GLI0PYTlmUUCjGVJOCpSrtAE8f/yESn/X6uAxRjeOlkDYyp+SzQRH21vMHbI57VVdRMxbY1sbhRWP xxGuyn42jgN7uaVsfPNEx0nuttZte8hdIwvBO3I48CqJutVlxagA46c7wJbxcEdvaKaE=; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sf.net; s=x ; h=Content-Transfer-Encoding:MIME-Version:References:In-Reply-To:Message-Id: Date:Subject:To:From:Sender:Reply-To:Cc:Content-Type:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=okQCfRflmol7vQux1kTX9I78ine7Z856I+lLOmAAzdA=; b=bZIH7v6frclJtsNv3ixsTn8Oh/ iGkf0dU5KtGr0kJ39IHX38GjuVkg0qRAKJ+v/5ubtDptLqXkSCXKxTcVCspJGRZ2blgWSQCmK+9Li udZRUgcd1bl+3OswnVL1OxYRKtZXkZS5z0Od8yWyaHVnhCG10BIGbuZGa3veEBO4NKT0=; Received: from mout-p-102.mailbox.org ([80.241.56.152]) by sfi-mx-1.v28.lw.sourceforge.com with esmtps (TLS1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.94.2) id 1nJfEZ-001nZb-2s for openvpn-devel@lists.sourceforge.net; Mon, 14 Feb 2022 17:33:56 +0000 Received: from smtp1.mailbox.org (smtp1.mailbox.org [80.241.60.240]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (P-384) server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by mout-p-102.mailbox.org (Postfix) with ESMTPS id 4JyBCb3n0bz9sRK for ; Mon, 14 Feb 2022 18:33:47 +0100 (CET) From: Frank Lichtenheld To: openvpn-devel@lists.sourceforge.net Date: Mon, 14 Feb 2022 18:33:42 +0100 Message-Id: <20220214173342.12655-1-frank@lichtenheld.com> In-Reply-To: <20211209171138.8589-2-frank@lichtenheld.com> References: <20211209171138.8589-2-frank@lichtenheld.com> MIME-Version: 1.0 X-Spam-Report: Spam detection software, running on the system "util-spamd-2.v13.lw.sourceforge.com", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see the administrator of that system for details. Content preview: - Broken/missing formatting - Make it obvious which arguments are optional Only the files touched have been reviewed, all other files likely have similar issues. Signed-off-by: Frank Lichtenheld --- doc/man-sections/client-options.rst | 4 ++-- doc/man-sections/generic-options.rst | 34 ++++++++++++++++++++-------- doc/man-sections/link-o [...] Content analysis details: (-0.7 points, 6.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -0.7 RCVD_IN_DNSWL_LOW RBL: Sender listed at https://www.dnswl.org/, low trust [80.241.56.152 listed in list.dnswl.org] -0.0 RCVD_IN_MSPIKE_H2 RBL: Average reputation (+2) [80.241.56.152 listed in wl.mailspike.net] 0.0 SPF_NONE SPF: sender does not publish an SPF Record 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record -0.0 T_SCC_BODY_TEXT_LINE No description available. X-Headers-End: 1nJfEZ-001nZb-2s Subject: [Openvpn-devel] [PATCH 2/3 v2] doc: fix misc documentation issues X-BeenThere: openvpn-devel@lists.sourceforge.net X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: openvpn-devel-bounces@lists.sourceforge.net X-getmail-retrieved-from-mailbox: Inbox - Broken/missing formatting - Make it obvious which arguments are optional Only the files touched have been reviewed, all other files likely have similar issues. Signed-off-by: Frank Lichtenheld Acked-By: David Sommerseth --- doc/man-sections/client-options.rst | 4 ++-- doc/man-sections/generic-options.rst | 34 ++++++++++++++++++++-------- doc/man-sections/link-options.rst | 26 +++++++++++++-------- src/openvpn/options.c | 2 +- 4 files changed, 43 insertions(+), 23 deletions(-) v2: remove some changes David disliked. Not that important. diff --git a/doc/man-sections/client-options.rst b/doc/man-sections/client-options.rst index 92a02e28..c7cec176 100644 --- a/doc/man-sections/client-options.rst +++ b/doc/man-sections/client-options.rst @@ -398,7 +398,7 @@ configuration. If hostname resolve fails for ``--remote``, retry resolve for ``n`` seconds before failing. - Set ``n`` to "infinite" to retry indefinitely. + Set ``n`` to :code:`infinite` to retry indefinitely. By default, ``--resolv-retry infinite`` is enabled. You can disable by setting n=0. @@ -417,7 +417,7 @@ configuration. --server-poll-timeout n When connecting to a remote server do not wait for more than ``n`` seconds for a response before trying the next server. The default value - is 120s. This timeout includes proxy and TCP connect timeouts. + is :code:`120`. This timeout includes proxy and TCP connect timeouts. --static-challenge args Enable static challenge/response protocol diff --git a/doc/man-sections/generic-options.rst b/doc/man-sections/generic-options.rst index a8f049f2..9060a235 100644 --- a/doc/man-sections/generic-options.rst +++ b/doc/man-sections/generic-options.rst @@ -48,7 +48,7 @@ which mode OpenVPN is configured as. 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 + 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. @@ -75,7 +75,7 @@ which mode OpenVPN is configured as. --config file Load additional config options from ``file`` where each line corresponds - to one command line option, but with the leading '--' removed. + to one command line option, but with the leading :code:`--` 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 @@ -130,8 +130,14 @@ which mode OpenVPN is configured as. 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 + 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 :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 @@ -142,7 +148,7 @@ which mode OpenVPN is configured as. 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". + unspecified, ``progname`` defaults to :code:`openvpn`. When OpenVPN is run with the ``--daemon`` option, it will try to delay daemonization until the majority of initialization functions which are @@ -166,6 +172,8 @@ which mode OpenVPN is configured as. renegotiation (and reauthentication) occurs. --disable-occ + Disable "options consistency check" (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``. @@ -177,6 +185,11 @@ which mode OpenVPN is configured as. --engine engine-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. @@ -191,7 +204,7 @@ which mode OpenVPN is configured as. 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. + udp`` is specified, and when ``--shaper`` is *NOT* specified. --group group Similar to the ``--user`` option, this option changes the group ID of @@ -221,7 +234,7 @@ which mode OpenVPN is configured as. 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 + 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. @@ -289,13 +302,13 @@ which mode OpenVPN is configured as. --providers legacy default - Behaviour of changing this option between SIGHUP might not be well behaving. + Behaviour of changing this option between :code:`SIGHUP` might not be well behaving. If you need to change/add/remove this option, fully restart OpenVPN. --remap-usr1 signal Control whether internally or externally generated :code:`SIGUSR1` signals are remapped to :code:`SIGHUP` (restart without persisting state) or - SIGTERM (exit). + :code:`SIGTERM` (exit). ``signal`` can be set to :code:`SIGHUP` or :code:`SIGTERM`. By default, no remapping occurs. @@ -372,7 +385,8 @@ which mode OpenVPN is configured as. consider using the ``--persist-key`` and ``--persist-tun`` options. --status args - Write operational status to ``file`` every ``n`` seconds. + Write operational status to ``file`` every ``n`` seconds. ``n`` defaults + to :code:`60` if not specified. Valid syntaxes: :: diff --git a/doc/man-sections/link-options.rst b/doc/man-sections/link-options.rst index 1cf6dd84..52df843d 100644 --- a/doc/man-sections/link-options.rst +++ b/doc/man-sections/link-options.rst @@ -71,6 +71,9 @@ the local and the remote host. keepalive interval timeout + Send ping once every ``interval`` seconds, restart if ping is not received + for ``timeout`` seconds. + 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 ``--ping`` and ``--ping-restart`` options to the client. If used on both server and @@ -113,7 +116,7 @@ the local and the remote host. ``--nobind`` option. --mark value - Mark encrypted packets being sent with value. The mark value can be + 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. @@ -202,7 +205,7 @@ the local and the remote host. 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 --remote + for peers which will be initiating connections by using the ``--remote`` option. --passtos @@ -226,6 +229,8 @@ the local and the remote host. (2) To provide a basis for the remote to test the existence of its peer using the ``--ping-exit`` option. + When using OpenVPN in server mode see also ``--keepalive``. + --ping-exit n Causes OpenVPN to exit after ``n`` seconds pass without reception of a ping or other packet from remote. This option can be combined with @@ -326,18 +331,19 @@ the local and the remote host. --replay-window args Modify the replay protection sliding-window size and time window. - Valid syntax: - :: + Valid syntaxes:: - replay-window n [t] + replay-window n + replay-window n t - Use a replay protection sliding-window of size **n** and a time window - of **t** seconds. + Use a replay protection sliding-window of size ``n`` and a time window + of ``t`` seconds. - By default **n** is 64 (the IPSec default) and **t** is 15 seconds. + By default ``n`` is :code:`64` (the IPSec default) and ``t`` is + :code:`15` seconds. - This option is only relevant in UDP mode, i.e. when either **--proto - udp** is specified, or no **--proto** option is specified. + This option is only relevant in UDP mode, i.e. when either ``--proto + udp`` is specified, or no ``--proto`` option is specified. When OpenVPN tunnels IP packets over UDP, there is the possibility that packets might be dropped or delivered out of order. Because OpenVPN, diff --git a/src/openvpn/options.c b/src/openvpn/options.c index 2538421b..92aeba3d 100644 --- a/src/openvpn/options.c +++ b/src/openvpn/options.c @@ -344,7 +344,7 @@ static const char usage_message[] = " and received from TCP/UDP (caps) or tun/tap (lc)\n" " : 6 to 11 -- debug messages of increasing verbosity\n" "--mute n : Log at most n consecutive messages in the same category.\n" - "--status file n : Write operational status to file every n seconds.\n" + "--status file [n] : Write operational status to file every n seconds.\n" "--status-version [n] : Choose the status file format version number.\n" " Currently, n can be 1, 2, or 3 (default=1).\n" "--disable-occ : Disable options consistency check between peers.\n"