From patchwork Tue Nov 8 02:45:23 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Gert Doering X-Patchwork-Id: 2839 Return-Path: Delivered-To: patchwork@openvpn.net Delivered-To: patchwork@openvpn.net Received: from director11.mail.ord1d.rsapps.net ([172.27.255.8]) by backend30.mail.ord1d.rsapps.net with LMTP id KAI2LMtkamO6NgAAIUCqbw (envelope-from ) for ; Tue, 08 Nov 2022 09:16:43 -0500 Received: from proxy3.mail.iad3a.rsapps.net ([172.27.255.8]) by director11.mail.ord1d.rsapps.net with LMTP id qDsiLMtkamM5dwAAvGGmqA (envelope-from ) for ; Tue, 08 Nov 2022 09:16:43 -0500 Received: from smtp16.gate.iad3a ([172.27.255.8]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by proxy3.mail.iad3a.rsapps.net with LMTPS id 6F74JMtkamOJegAAYaqY3Q (envelope-from ) for ; Tue, 08 Nov 2022 09:16:43 -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: smtp16.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: f7bb5250-5f6f-11ed-80dc-5254004ee196-1-1 Received: from [216.105.38.7] ([216.105.38.7:39286] helo=lists.sourceforge.net) by smtp16.gate.iad3a.rsapps.net (envelope-from ) (ecelerity 4.2.38.62370 r(:)) with ESMTPS (cipher=DHE-RSA-AES256-GCM-SHA384) id 65/4A-05921-AC46A636; Tue, 08 Nov 2022 09:16:42 -0500 Received: from [127.0.0.1] (helo=sfs-ml-4.v29.lw.sourceforge.com) by sfs-ml-4.v29.lw.sourceforge.com with esmtp (Exim 4.95) (envelope-from ) id 1osPOf-0000mj-4F; Tue, 08 Nov 2022 14:16:13 +0000 Received: from [172.30.20.202] (helo=mx.sourceforge.net) by sfs-ml-4.v29.lw.sourceforge.com with esmtps (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.95) (envelope-from ) id 1osPOd-0000md-RZ for openvpn-devel@lists.sourceforge.net; Tue, 08 Nov 2022 14:16: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=ao04Tm7g+848ROM4qQVHyJml3mzBwJQyusef/QMJh/U=; b=REYh0q5Tb7z8uErRwbsFCoaQDx kc0TKeeOcYmaEhG2Ug60DmLtpYF7zsMfmadAkjLspwfuYSmQabLSRy0au3lzUEz+k1KgVqAOx7VkL qgVc2kkBz9n8h0uCqvUorNsFrdFTFFHQVOd2XQSECqM6mP15ztXQ9NFaJb40NV09+Sgg=; 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=ao04Tm7g+848ROM4qQVHyJml3mzBwJQyusef/QMJh/U=; b=g9LaMtrrkbAh1cFzU5JmRqfeWK nwzZP1Eqtl12dIShCEabW1RZwZZZ6XLIksdXszBM/g0STkAcmr8dLGAfvBb/jOrlTKPF7i05lEPL9 1m83cL56VCXjDj6lTpMzj8YL7z1nCVvLedMTK1UHwo5EI/K2F7hZKcAZmRBnXrYOwJ38=; 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 1osPOa-00031t-5q for openvpn-devel@lists.sourceforge.net; Tue, 08 Nov 2022 14:16: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 2A8DjP4H002338 for ; Tue, 8 Nov 2022 14:45:25 +0100 Received: (from gert@localhost) by blue.greenie.muc.de (8.17.1.9/8.17.1.9/Submit) id 2A8DjPxw002337 for openvpn-devel@lists.sourceforge.net; Tue, 8 Nov 2022 14:45:25 +0100 From: Gert Doering To: openvpn-devel@lists.sourceforge.net Date: Tue, 8 Nov 2022 14:45:23 +0100 Message-Id: <20221108134523.2325-1-gert@greenie.muc.de> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220912074149.31160-1-gert@greenie.muc.de> References: <20220912074149.31160-1-gert@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_PASS SPF: sender matches SPF record -0.0 SPF_HELO_PASS SPF: HELO matches SPF record X-Headers-End: 1osPOa-00031t-5q Subject: [Openvpn-devel] [PATCH v2] 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. v2: disambiguate Linux ("all drivers") and FreeBSD ("only DCO"), add comment about --dev-type being necessary for devices not starting with tun* or tap* 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..72cf9064 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 device names (e.g. ``--dev tun-home``) will only work on + FreeBSD (with the DCO kernel driver for ``tun`` devices) and Linux + (for both ``tun`` and ``tap`` devices, DCO and tun/tap driver). + + If such a device name starts with ``tun`` or ``tap`` (e.g. ``tun-home``), + OpenVPN will choose the right device type automatically. Otherwise the + desired device type needs to be specified with ``--dev-type tun`` or + ``--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