Adjust Linux+FreeBSD DCO device name handling to 'non DCO linux style'
PATCH 1/1 Adjust Linux+FreeBSD DCO device name handling to 'non DCO linux style'
On Linux, tun devices are created according to the following algorithm
--dev tun -> try tun0, tun1, ... tun255, use first free
--dev anything -> create a TUN device named "anything"
(as long as "anything" is not "null" or "tap[N]")
DCO was following the "other platform convention", where everything not having a digit was iterated ("--dev tun-home" -> "tun-home0") - which does not work for classic tun/tap devices on the BSDs anyway, so is not the best model.
Adjust open_tun_dco_generic() to document expected behaviour and do the thing.
--- src/openvpn/tun.c | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-)
src/openvpn/tun.c +6 -4
@@ -1943,12 +1943,14 @@ open_tun_dco_generic(const char *dev, const char *dev_type, }/* -* dynamic open is indicated by --dev specified without -* explicit unit number. Try opening DCO device named "[dev]n" -* where n = [0, 255]. +* unlike "open_tun_generic()", DCO on Linux and FreeBSD follows +* the device naming model of "non-DCO linux", that is: +* --dev tun -> try tun0, tun1, ... tun255, use first free +* --dev <anything> -> (try to) create a tun device named "anything" +* ("--dev tap" and "--dev null" are caught earlier and not handled here) */ -if (!tun_name_is_fixed (dev)) +if (strcmp (dev,"tun" ) ==0 ) {for (int i =0 ; i <256 ; ++i) {
Signature · 1 line
2.25.1
Quoted 10 lines · Gert Doering
On Linux, tun devices are created according to the following algorithm
--dev tun -> try tun0, tun1, ... tun255, use first free
--dev anything -> create a TUN device named "anything"
(as long as "anything" is not "null" or "tap[N]")DCO was following the "other platform convention", where everything not having a digit was iterated ("--dev tun-home" -> "tun-home0") - which does not work for classic tun/tap devices on the BSDs anyway, so is not the best model.
Quoted 4 lines
Adjust
open_tun_dco_generic()to document expected behaviour and do the thing.Signed-off-by Gert Doering <[email protected]...>
Kristof
Hi,
Quoted 28 lines · Gert Doering
On Linux, tun devices are created according to the following algorithm
--dev tun -> try tun0, tun1, ... tun255, use first free
--dev anything -> create a TUN device named "anything"
(as long as "anything" is not "null" or "tap[N]")DCO was following the "other platform convention", where everything not having a digit was iterated ("--dev tun-home" -> "tun-home0") - which does not work for classic tun/tap devices on the BSDs anyway, so is not the best model.
Adjust
open_tun_dco_generic()to document expected behaviour and do the thing.Signed-off-by Gert Doering <[email protected]...>--- src/openvpn/tun.c | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-)src/openvpn/tun.c +0
-2@@ -1943,12 +1943,14 @@ open_tun_dco_generic(const char *dev, const char *dev_type, }/* -* dynamic open is indicated by --dev specified without -* explicit unit number. Try opening DCO device named "[dev]n"
src/openvpn/tun.c open_tun_dco_generic(const char *dev, const char *dev_type, · line 1953
Quoted 10 lines
src/openvpn/tun.c +6
-2-* where n = [0, 255]. +* unlike "open_tun_generic()", DCO on Linux and FreeBSD follows +* the device naming model of "non-DCO linux", that is: +* --dev tun -> try tun0, tun1, ... tun255, use first free +* --dev <anything> -> (try to) create a tun device named "anything" +* ("--dev tap" and "--dev null" are caught earlier and not handled here) */ -if (!tun_name_is_fixed (dev)) +if (strcmp (dev,"tun" ) ==0 )
you need to add a space after the ','.
src/openvpn/tun.c open_tun_dco_generic(const char *dev, const char *dev_type, · line 1956
Quoted 3 lines
src/openvpn/tun.c +0
-0{for (int i =0 ; i <256 ; ++i) {
Other than that you get a 2nd ACK:
I wonder if we should document this behaviour somewhere else? i.e. manpage?
It seems that even us developers are puzzled by what it is supposed to happen.
Cheers,
Signature · 1 line
Antonio Quartulli
Thanks for the review. strcmp() fixed (space) as instructed.
I'll send a manpage patch next to (try to...) document the expected behaviour across platforms.
Your patch has been applied to the master branch.
commit a5cf4cfb77f74588759d96258e7435e54db12b2c
Author: Gert Doering Date: Mon Aug 29 21:01:24 2022 +0200
Adjust Linux+FreeBSD DCO device name handling to 'non DCO linux style'
Signed-off-by: Gert Doering <[email protected]...>
Acked-by: Kristof Provost <[email protected]...>
Acked-by: Antonio Quartulli <[email protected]...>
Message-Id: <[email protected]...>
URL: https://www.mail-archive.com/[email protected]/msg25134.html
Signed-off-by: Gert Doering <[email protected]...>--
kind regards,
Gert Doering
PATCH 1/1 Improve documentation for --dev and --dev-node.
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.
--- doc/man-sections/vpn-network-options.rst | 38 +++++++++++++++++++----- 1 file changed, 31 insertions(+), 7 deletions(-)
doc/man-sections/vpn-network-options.rst +31 -7
@@ -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
Signature · 1 line
2.35.1
Re: [Openvpn-devel] [PATCH] Improve documentation for --dev and --dev-node.
Quoted 60 lines · Gert Doering
During the research for commit
a5cf4cfb77f745it 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 <[email protected]...>--- doc/man-sections/vpn-network-options.rst | 38 +++++++++++++++++++----- 1 file changed, 31 insertions(+), 7 deletions(-)doc/man-sections/vpn-network-options.rst +26
-7@@ -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
doc/man-sections/vpn-network-options.rst routing. · line 122
Quoted 10 lines
doc/man-sections/vpn-network-options.rst +5
-0TAP-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,
Signature · 1 line
Antonio Quartulli
Re: [Openvpn-devel] [PATCH] Improve documentation for --dev and --dev-node.
Hi,
Quoted 10 lines · Antonio Quartulli
doc/man-sections/vpn-network-options.rst routing. · line 122
Quoted 8 lines
doc/man-sections/vpn-network-options.rst +5
-0+ 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
Quoted 5 lines
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...
Quoted 8 lines
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
Signature · 6 lines
"If was one thing all people took for granted, was conviction that if you
feed honest figures into a computer, honest figures come out. Never doubted
it myself till I met a computer with a sense of humor."
Robert A. Heinlein, The Moon is a Harsh Mistress
Gert Doering - Munich, Germany [email protected]...Antonio Quartulli
Acked-byRe: [Openvpn-devel] [PATCH] Improve documentation for --dev and --dev-node.
Hi,
Quoted 38 lines · Gert Doering
Hi,
Quoted 10 lines · Antonio Quartulli
doc/man-sections/vpn-network-options.rst routing. · line 122
Quoted 8 lines
doc/man-sections/vpn-network-options.rst +5
-0+ 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 ifQuoted 5 lines
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...
Quoted 8 lines
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?
Quoted 7 lines
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.
Cheers,
Quoted 2 lines
gert
Signature · 1 line
Antonio Quartulli
Re: [Openvpn-devel] [PATCH] Improve documentation for --dev and --dev-node.
In reply to Gert DoeringQuoted 28 lines · Gert Doering
During the research for commit
a5cf4cfb77f745it 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 <[email protected]...>--- doc/man-sections/vpn-network-options.rst | 38 +++++++++++++++++++----- 1 file changed, 31 insertions(+), 7 deletions(-)doc/man-sections/vpn-network-options.rst +5
-3@@ -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
doc/man-sections/vpn-network-options.rst routing. · line 86
Quoted 10 lines
doc/man-sections/vpn-network-options.rst +10
-0+ 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...]
doc/man-sections/vpn-network-options.rst routing. · line 118
Quoted 8 lines
doc/man-sections/vpn-network-options.rst +4
-0@@ -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.
Signature · 4 lines
kind regards, David Sommerseth OpenVPN Inc
Re: [Openvpn-devel] [PATCH] Improve documentation for --dev and --dev-node.
Hi,
Quoted 33 lines · David Sommerseth
Quoted 32 lines · Gert Doering
During the research for commit
a5cf4cfb77f745it 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 <[email protected]...>---
doc/man-sections/vpn-network-options.rst| 38 +++++++++++++++++++-----1 file changed, 31 insertions(+), 7 deletions(-)doc/man-sections/vpn-network-options.rst +0
-0@@ -69,15 +69,34 @@ routing.dev tap4
dev ovpn
- When the device name starts with :code:tunor :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:tunor :code:tapis + platform dependent.doc/man-sections/vpn-network-options.rst +7
-0+ + 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. +
Quoted 8 lines
doc/man-sections/vpn-network-options.rst routing. · line 86
Quoted 6 lines
+ Arbitrary names (e.g. ``--dev home``) will not work on most platforms, + with the exception of Linux and FreeBSD with the DCO kernel driver.
doc/man-sections/vpn-network-options.rst +4
-0+ + 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?
Quoted 16 lines
[...snip...]
Quoted 9 lines
doc/man-sections/vpn-network-options.rst +0
-0@@ -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,
Quoted 2 lines
Signature · 1 line
Antonio Quartulli
Re: [Openvpn-devel] [PATCH] Improve documentation for --dev and --dev-node.
In reply to David SommersethHi,
Quoted 11 lines · David Sommerseth
Quoted 11 lines
doc/man-sections/vpn-network-options.rst +11
-0+ 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.
Quoted 8 lines
doc/man-sections/vpn-network-options.rst routing. · line 86
Quoted 4 lines
doc/man-sections/vpn-network-options.rst +4
-0+ + 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".
Quoted 6 lines
[...snip...]
Quoted 4 lines
doc/man-sections/vpn-network-options.rst +0
-0@@ -93,6 +112,11 @@ routing. both the network connections control panel name and the GUID for each TAP-Win32 adapter.
Quoted 8 lines
doc/man-sections/vpn-network-options.rst routing. · line 118
Quoted 4 lines
doc/man-sections/vpn-network-options.rst +4
-0+ 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
Signature · 6 lines
"If was one thing all people took for granted, was conviction that if you
feed honest figures into a computer, honest figures come out. Never doubted
it myself till I met a computer with a sense of humor."
Robert A. Heinlein, The Moon is a Harsh Mistress
Gert Doering - Munich, Germany [email protected]...Re: [Openvpn-devel] [PATCH] Improve documentation for --dev and --dev-node.
In reply to Antonio QuartulliQuoted 46 lines · Antonio Quartulli
Hi,
Quoted 34 lines · David Sommerseth
Quoted 33 lines · Gert Doering
During the research for commit
a5cf4cfb77f745it 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 <[email protected]...>---
doc/man-sections/vpn-network-options.rst| 38 +++++++++++++++++++-----1 file changed, 31 insertions(+), 7 deletions(-)doc/man-sections/vpn-network-options.rst +0
-0@@ -69,15 +69,34 @@ routing.dev tap4
dev ovpn
- When the device name starts with :code:tunor :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:tunor :code:tapis + platform dependent.doc/man-sections/vpn-network-options.rst +8
-0+ + 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 mostQuoted 8 lines
doc/man-sections/vpn-network-options.rst routing. · line 86
Quoted 6 lines
platforms,
+ with the exception of Linux and FreeBSD with the DCO kernel driver.doc/man-sections/vpn-network-options.rst +4
-0+ + 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.
Quoted 5 lines
The text refers to two cases:
* Linux
* FreeBSD with DCOmaybe 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.
--------------------------
Quoted 15 lines
Quoted 14 lines
[...snip...]
Quoted 9 lines
doc/man-sections/vpn-network-options.rst +0
-0@@ -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.
Quoted 1 line
It has not changed, but the "other platforms" the text is talking about does not include Windows.
Okay, then it's fine.
Signature · 4 lines
kind regards, David Sommerseth OpenVPN Inc
PATCH v2 1/1 Improve documentation for --dev and --dev-node.
In reply to Gert DoeringDuring 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*
--- doc/man-sections/vpn-network-options.rst | 38 +++++++++++++++++++----- 1 file changed, 31 insertions(+), 7 deletions(-)
doc/man-sections/vpn-network-options.rst +31 -7
@@ -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
Signature · 1 line
2.35.1
Re: [Openvpn-devel] [PATCH v2] Improve documentation for --dev and --dev-node.
Hi,
Quoted 4 lines · Gert Doering
During the research for commit
a5cf4cfb77f745it turned out that OpenVPN's behaviour regarding "--dev arbitrary-name" is very platform-specific and not very well documented.
Quoted 8 lines
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 <[email protected]...>
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.
Quoted 62 lines
--- doc/man-sections/vpn-network-options.rst | 38 +++++++++++++++++++----- 1 file changed, 31 insertions(+), 7 deletions(-)doc/man-sections/vpn-network-options.rst +31
-7@@ -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
Signature · 1 line
Antonio Quartulli
[Openvpn-devel] [PATCH applied] Re: Improve documentation for --dev and --dev-node.
In reply to Gert DoeringThanks 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 <[email protected]...>
Acked-by: Antonio Quartulli <[email protected]...>
Message-Id: <[email protected]...>
URL: https://www.mail-archive.com/[email protected]/msg25488.html
Signed-off-by: Gert Doering <[email protected]...>--
kind regards,
Gert Doering