| Message ID | 20220912074149.31160-1-gert@greenie.muc.de |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [Openvpn-devel] Improve documentation for --dev and --dev-node. | expand |
On 12/09/2022 09:41, 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. > > Signed-off-by: Gert Doering <gert@greenie.muc.de> > --- > 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 I like this improved version as it tries to bring clarity. However, I feel it is too vague as to which platform does what. For example the last paragraph starts with "On other platform", but what are these "other platforms"? Maybe it's just me, but saying "other platforms" or "some platforms" or "most platforms" without explicitly saying which ones is the same as to not really documenting the behaviour. Because I am still unable to understand which platform does what. Should we rather split this platform by platform with related paragraphs? What do you think? Cheers,
Hi, On Tue, Sep 13, 2022 at 11:38:29PM +0200, Antonio Quartulli wrote: > > + 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 > > > I like this improved version as it tries to bring clarity. However, I > feel it is too vague as to which platform does what. > > For example the last paragraph starts with "On other platform", but what > are these "other platforms"? The intent was to list the 3 platforms where --dev-node does something special, and then "other platforms" is "everything else" (technically, all platforms that call open_tun_generic(), so I'm not absolutely sure if AIX or Solaris qualify... but I'm not going to mention AIX or Solaris there, as it's way too unimportant and will just increase text length). Especially as it's not even working on "all other platforms" due to limitations, the documentation won't get less vague than the actual implementation... > Maybe it's just me, but saying "other platforms" or "some platforms" or > "most platforms" without explicitly saying which ones is the same as to > not really documenting the behaviour. Because I am still unable to > understand which platform does what. > > Should we rather split this platform by platform with related paragraphs? > > What do you think? We could do that, and nobody would really read it - it would just get long, with quite some repetitions (the BSDs are all very similar, except when they are not)... I'm still for "on platforms that are not Windows, MacOS or Linux, --dev-node will usually not do what you want, so forget about it right away" - wrapped in a slightly longer text :-) gert
Hi, On 14/09/2022 08:23, Gert Doering wrote: > Hi, > > On Tue, Sep 13, 2022 at 11:38:29PM +0200, Antonio Quartulli wrote: >>> + 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 >> >> >> I like this improved version as it tries to bring clarity. However, I >> feel it is too vague as to which platform does what. >> >> For example the last paragraph starts with "On other platform", but what >> are these "other platforms"? > > The intent was to list the 3 platforms where --dev-node does something > special, and then "other platforms" is "everything else" (technically, > all platforms that call open_tun_generic(), so I'm not absolutely sure > if AIX or Solaris qualify... but I'm not going to mention AIX or Solaris > there, as it's way too unimportant and will just increase text length). > > Especially as it's not even working on "all other platforms" due to > limitations, the documentation won't get less vague than the actual > implementation... > >> Maybe it's just me, but saying "other platforms" or "some platforms" or >> "most platforms" without explicitly saying which ones is the same as to >> not really documenting the behaviour. Because I am still unable to >> understand which platform does what. >> >> Should we rather split this platform by platform with related paragraphs? >> >> What do you think? > > We could do that, and nobody would really read it - it would just get > long, with quite some repetitions (the BSDs are all very similar, except > when they are not)... > > I'm still for "on platforms that are not Windows, MacOS or Linux, --dev-node > will usually not do what you want, so forget about it right away" - wrapped > in a slightly longer text :-) Ok, so it's not the comment that is vague, but it's the implementation itself that is not clean. Well, then let's go with your new doc and let's see if we can improve the implementation after 2.6 is done. Acked-by: Antonio Quartulli <a@unstable.cc> Cheers, > > gert
On 12/09/2022 09:41, 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. > > Signed-off-by: Gert Doering <gert@greenie.muc.de> > --- > 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. > + This is confusing and not quite right. I've used "--dev home" for a long time on Linux with tun devices. But it requires "--dev-type tun". There are no dependencies on DCO in this use case. [...snip...] > @@ -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``. IIRC correctly on Windows (too many years since last time with a more advanced setup there), --dev-node does not influence the naming of the tap-windows6 interface, but is a reference to the pre-created interface. Windows didn't use to create interfaces on-the-fly like on Linux/BSD/macOS. Not sure if that has changed with tap-windows6 and neither how this is with wintun or ovpn-dco-win.
Hi, On 14/09/2022 09:33, David Sommerseth wrote: > On 12/09/2022 09:41, 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. >> >> Signed-off-by: Gert Doering <gert@greenie.muc.de> >> --- >> 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. >> + > > This is confusing and not quite right. I've used "--dev home" for a > long time on Linux with tun devices. But it requires "--dev-type tun". > There are no dependencies on DCO in this use case. The text refers to two cases: * Linux * FreeBSD with DCO maybe the wording made it sound different? > > [...snip...] > >> @@ -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``. > > IIRC correctly on Windows (too many years since last time with a more > advanced setup there), --dev-node does not influence the naming of the > tap-windows6 interface, but is a reference to the pre-created interface. > Windows didn't use to create interfaces on-the-fly like on > Linux/BSD/macOS. Not sure if that has changed with tap-windows6 and > neither how this is with wintun or ovpn-dco-win. It has not changed, but the "other platforms" the text is talking about does not include Windows. Cheers, > >
Hi, On Wed, Sep 14, 2022 at 09:33:46AM +0200, David Sommerseth wrote: > > + 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. > > + > > This is confusing and not quite right. I've used "--dev home" for a > long time on Linux with tun devices. But it requires "--dev-type tun". > There are no dependencies on DCO in this use case. The sentence above should have read "Linux and (FreeBSD with the DCO driver)". FreeBSD *with* DCO can do arbitrary names, without, it's "tun<N>" and "tap<N>" only. Suggestions how to word this better? I'll add "if the arbitrary device name does not start with 'tun' or 'tap', Linux needs a --dev-type tun/tap to tell". > [...snip...] > > > @@ -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``. > > IIRC correctly on Windows (too many years since last time with a more > advanced setup there), --dev-node does not influence the naming of the > tap-windows6 interface, but is a reference to the pre-created interface. Windows is not part of "other platforms" here, but covered in the preceding paragraph -> so, yes, that's what it says there :-) gert
On 14/09/2022 09:38, Antonio Quartulli wrote: > Hi, > > On 14/09/2022 09:33, David Sommerseth wrote: >> On 12/09/2022 09:41, 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. >>> >>> Signed-off-by: Gert Doering <gert@greenie.muc.de> >>> --- >>> 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. >>> + >> >> This is confusing and not quite right. I've used "--dev home" for a >> long time on Linux with tun devices. But it requires "--dev-type >> tun". There are no dependencies on DCO in this use case. > > The text refers to two cases: > * Linux > * FreeBSD with DCO > > maybe the wording made it sound different? Ahh, so FreeBSD don't support arbitrary names with plain tun interfaces? If so, then I misread the sentence. Perhaps this is clearer? -------------------------- Arbitrary names (e.g. ``--dev home``) will not work on most platforms. Linux supports arbitrary names in addition to FreeBSD when using the DCO kernel driver. This will require ``--dev-type`` to be set. -------------------------- >> >> [...snip...] >> >>> @@ -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``. >> >> IIRC correctly on Windows (too many years since last time with a more >> advanced setup there), --dev-node does not influence the naming of the >> tap-windows6 interface, but is a reference to the pre-created >> interface. Windows didn't use to create interfaces on-the-fly like >> on Linux/BSD/macOS. Not sure if that has changed with tap-windows6 >> and neither how this is with wintun or ovpn-dco-win. > > It has not changed, but the "other platforms" the text is talking about > does not include Windows. Okay, then it's fine. -- kind regards, David Sommerseth OpenVPN Inc
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
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 <gert@greenie.muc.de> --- doc/man-sections/vpn-network-options.rst | 38 +++++++++++++++++++----- 1 file changed, 31 insertions(+), 7 deletions(-)