| Message ID | 20221108134523.2325-1-gert@greenie.muc.de |
|---|---|
| State | Accepted |
| Headers | show |
| Series | [Openvpn-devel,v2] Improve documentation for --dev and --dev-node. | expand |
Hi, On 08/11/2022 14:45, Gert Doering wrote: > 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 <gert@greenie.muc.de> I think the proposed text is much better than before. After ironing out some details in v2 it got even clearer. I see no reason why it should not be merged in this form. Should somebody not feel it's 100% clear, a follow-up patch can always be sent to improve the text even more. Acked-by: Antonio Quartulli <a@unstable.cc> > --- > 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
Thanks for the review.
Indeed, further improvements of our documentation is always possible
(and patches welcome). *This* now concludes my "repair arbitrary name
support for Linux and add documentation" project :-)
Patch has been applied to the master branch.
commit 199081c24a1bb4b9066e542165de9b4a6ce1a8fd
Author: Gert Doering
Date: Tue Nov 8 14:45:23 2022 +0100
Improve documentation for --dev and --dev-node.
Signed-off-by: Gert Doering <gert@greenie.muc.de>
Acked-by: Antonio Quartulli <antonio@openvpn.net>
Message-Id: <20221108134523.2325-1-gert@greenie.muc.de>
URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg25488.html
Signed-off-by: Gert Doering <gert@greenie.muc.de>
--
kind regards,
Gert Doering
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
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 <gert@greenie.muc.de> --- doc/man-sections/vpn-network-options.rst | 38 +++++++++++++++++++----- 1 file changed, 31 insertions(+), 7 deletions(-)