From patchwork Sun Sep 11 21:41:49 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gert Doering X-Patchwork-Id: 2750 Return-Path: Delivered-To: patchwork@openvpn.net Delivered-To: patchwork@openvpn.net Received: from director8.mail.ord1d.rsapps.net ([172.27.255.58]) by backend30.mail.ord1d.rsapps.net with LMTP id MNDtEUfjHmN3JwAAIUCqbw (envelope-from ) for ; Mon, 12 Sep 2022 03:44:07 -0400 Received: from proxy10.mail.iad3a.rsapps.net ([172.27.255.58]) by director8.mail.ord1d.rsapps.net with LMTP id eB13EUfjHmN+OAAAfY0hYg (envelope-from ) for ; Mon, 12 Sep 2022 03:44:07 -0400 Received: from smtp19.gate.iad3a ([172.27.255.58]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by proxy10.mail.iad3a.rsapps.net with LMTPS id KFHsCEfjHmNeMQAAnQ/bqA (envelope-from ) for ; Mon, 12 Sep 2022 03:44:07 -0400 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: smtp19.gate.iad3a.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=greenie.muc.de X-Suspicious-Flag: YES X-Classification-ID: ad943044-326e-11ed-8267-5254005d39f2-1-1 Received: from [216.105.38.7] ([216.105.38.7:58324] helo=lists.sourceforge.net) by smtp19.gate.iad3a.rsapps.net (envelope-from ) (ecelerity 4.2.38.62370 r(:)) with ESMTPS (cipher=DHE-RSA-AES256-GCM-SHA384) id 99/3B-16082-643EE136; Mon, 12 Sep 2022 03:44:06 -0400 Received: from [127.0.0.1] (helo=sfs-ml-1.v29.lw.sourceforge.com) by sfs-ml-1.v29.lw.sourceforge.com with esmtp (Exim 4.95) (envelope-from ) id 1oXe65-000514-LA; Mon, 12 Sep 2022 07:43:13 +0000 Received: from [172.30.20.202] (helo=mx.sourceforge.net) by sfs-ml-1.v29.lw.sourceforge.com with esmtps (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.95) (envelope-from ) id 1oXe63-00050l-CJ for openvpn-devel@lists.sourceforge.net; Mon, 12 Sep 2022 07:43:11 +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=jo5Oc6b0LpLdJyAvw9G2UcZrumnJA9xjZqOCcLnHl1c=; b=gj9yyQAqVDUM3dGgaOCsoDs4z6 84+uRezd6KS4GZ/c1hE6d2Z/txCoUAFu1Iusax6lCTT21KLqKDNmSCeRLc6baDmaZ1JNQf0PaZHcs FS7qJV+8qmvySDzeMSQQQ+9yIQ1VLjq+Maay1c4Rin8StlX91Ho3jMvVp5Yp70VtfhS8=; 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=jo5Oc6b0LpLdJyAvw9G2UcZrumnJA9xjZqOCcLnHl1c=; b=ibhMnCP9RGfSTrzbSDdtfAemN7 iwCWOwVKO9sAIZ3bZBAXPOtvQMGat6qITMPC27PNx7TMGNqveR9l6D41GIYZkE20MFXiZ0vtKvBkg udXoQiZgFLkVUZChCbqcQeaUiy7BGF7ux6VTh5erOwE8YCUNmJSZMBtw0pX95H5hZ64M=; Received: from dhcp-174.greenie.muc.de ([193.149.48.174] helo=blue.greenie.muc.de) by sfi-mx-2.v28.lw.sourceforge.com with esmtps (TLS1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.95) id 1oXe5y-0008QZ-Ed for openvpn-devel@lists.sourceforge.net; Mon, 12 Sep 2022 07:43:11 +0000 Received: from blue.greenie.muc.de (localhost [127.0.0.1]) by blue.greenie.muc.de (8.17.1/8.17.1) with ESMTP id 28C7frGG031409 for ; Mon, 12 Sep 2022 09:41:53 +0200 Received: (from gert@localhost) by blue.greenie.muc.de (8.17.1.9/8.17.1/Submit) id 28C7frac031408 for openvpn-devel@lists.sourceforge.net; Mon, 12 Sep 2022 09:41:53 +0200 From: Gert Doering To: openvpn-devel@lists.sourceforge.net Date: Mon, 12 Sep 2022 09:41:49 +0200 Message-Id: <20220912074149.31160-1-gert@greenie.muc.de> X-Mailer: git-send-email 2.35.1 In-Reply-To: <202208301957.27UJv74w093000@chekov.greenie.muc.de> References: <202208301957.27UJv74w093000@chekov.greenie.muc.de> 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: During the research for commit a5cf4cfb77f745 it turned out that OpenVPN's behaviour regarding "--dev arbitrary-name" is very platform-specific and not very well documented. The referenced commit fixed DCO behaviour to be in line with non-DCO linux behaviour, this commit catches up on the documentation. Content analysis details: (-0.0 points, 6.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -0.0 SPF_HELO_PASS SPF: HELO matches SPF record -0.0 SPF_PASS SPF: sender matches SPF record -0.0 T_SCC_BODY_TEXT_LINE No description available. X-Headers-End: 1oXe5y-0008QZ-Ed Subject: [Openvpn-devel] [PATCH] Improve documentation for --dev and --dev-node. 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 During the research for commit a5cf4cfb77f745 it turned out that OpenVPN's behaviour regarding "--dev arbitrary-name" is very platform-specific and not very well documented. The referenced commit fixed DCO behaviour to be in line with non-DCO linux behaviour, this commit catches up on the documentation. Signed-off-by: Gert Doering Acked-by: Antonio Quartulli --- doc/man-sections/vpn-network-options.rst | 38 +++++++++++++++++++----- 1 file changed, 31 insertions(+), 7 deletions(-) diff --git a/doc/man-sections/vpn-network-options.rst b/doc/man-sections/vpn-network-options.rst index 5b2f8470..559b2464 100644 --- a/doc/man-sections/vpn-network-options.rst +++ b/doc/man-sections/vpn-network-options.rst @@ -69,15 +69,34 @@ routing. dev tap4 dev ovpn - When the device name starts with :code:`tun` or :code:`tap`, the device - type is extracted automatically. Otherwise the ``--dev-type`` option - needs to be added as well. + What happens if the device name is not :code:`tun` or :code:`tap` is + platform dependent. + + On most platforms, :code:`tunN` (e.g. tun2, tun30) and :code:`tapN` + (e.g. tap3) will create a numbered tun/tap interface with the number + specified - this is useful if multiple OpenVPN instances are active, + and the instance-to-device mapping needs to be known. Some platforms + do not support "numbered tap", so trying ``--dev tap3`` will fail. + + Arbitrary names (e.g. ``--dev home``) will not work on most platforms, + with the exception of Linux and FreeBSD with the DCO kernel driver. + + There, arbitrary names are allowed, and will create a tun or DCO + device named as requested. + + Linux also supports arbitrary named tap devices, if TAP is requested + with ``--dev somename --dev-type tap``. + + On Windows, only the names :code:`tun` and :code:`tap` are supported. + Selection among multiple installed drivers or driver instances is done + with ``--dev-node`` and ``--windows-driver``. --dev-node node - Explicitly set the device node rather than using :code:`/dev/net/tun`, - :code:`/dev/tun`, :code:`/dev/tap`, etc. If OpenVPN cannot figure out - whether ``node`` is a TUN or TAP device based on the name, you should - also specify ``--dev-type tun`` or ``--dev-type tap``. + This is a highly system dependent option to influence tun/tap driver + selection. + + On Linux, tun/tap devices are created by accessing :code:`/dev/net/tun`, + and this device name can be changed using ``--dev-node ...``. Under Mac OS X this option can be used to specify the default tun implementation. Using ``--dev-node utun`` forces usage of the native @@ -93,6 +112,11 @@ routing. both the network connections control panel name and the GUID for each TAP-Win32 adapter. + On other platforms, ``--dev-node node`` will influence the naming of the + created tun/tap device, if supported on that platform. If OpenVPN cannot + figure out whether ``node`` is a TUN or TAP device based on the name, + you should also specify ``--dev-type tun`` or ``--dev-type tap``. + --dev-type device-type Which device type are we using? ``device-type`` should be :code:`tun` (OSI Layer 3) or :code:`tap` (OSI Layer 2). Use this option only if