Skip to contentSkip to conversation

Adjust Linux+FreeBSD DCO device name handling to 'non DCO linux style'

PATCH In review Gert Doering 4 participants 15 messages Aug 29, 2022 – Nov 11, 2022

lore
Share & tools
lore
#0 lore raw

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
index 94803acd..94b0d322 100644
@@ -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
Acked-by on v1 1/1
#1 lore raw
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.

Kristof

Acked-by on v1 1/1
#2 lore raw
In reply to Gert Doering

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.

---
  src/openvpn/tun.c | 10 ++++++----
  1 file changed, 6 insertions(+), 4 deletions(-)
src/openvpn/tun.c +0 -2
index 94803acd..94b0d322 100644
@@ -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
#3 lore raw
In reply to Gert Doering

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

#4 lore raw

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
index 5b2f8470..559b2464 100644
@@ -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
#5 lore raw

Re: [Openvpn-devel] [PATCH] Improve documentation for --dev and --dev-node.

Quoted 60 lines · Gert Doering

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 +26 -7
index 5b2f8470..559b2464 100644
@@ -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 -0
    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,

Signature · 1 line
Antonio Quartulli
#6 lore raw

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]...
#7 lore raw

Re: [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 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?

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
#8 lore raw

Re: [Openvpn-devel] [PATCH] Improve documentation for --dev and --dev-node.

In reply to Gert Doering
Quoted 28 lines · Gert Doering

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 +5 -3
index 5b2f8470..559b2464 100644
@@ -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
#9 lore raw

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 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 +0 -0
index 5b2f8470..559b2464 100644
@@ -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.

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
#11 lore raw

Re: [Openvpn-devel] [PATCH] Improve documentation for --dev and --dev-node.

In reply to David Sommerseth

Hi,

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]...
#10 lore raw

Re: [Openvpn-devel] [PATCH] Improve documentation for --dev and --dev-node.

In reply to Antonio Quartulli
Quoted 46 lines · Antonio Quartulli

Hi,

Quoted 34 lines · David Sommerseth
Quoted 33 lines · Gert Doering

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 +0 -0
index 5b2f8470..559b2464 100644
@@ -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.

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 most 
Quoted 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 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.
--------------------------

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
#12 lore raw

PATCH v2 1/1 Improve documentation for --dev and --dev-node.

In reply to Gert Doering

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*

---
 doc/man-sections/vpn-network-options.rst | 38 +++++++++++++++++++-----
 1 file changed, 31 insertions(+), 7 deletions(-)
doc/man-sections/vpn-network-options.rst +31 -7
index 5b2f8470..72cf9064 100644
@@ -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
Acked-by on v2 1/1
#13 lore raw

Re: [Openvpn-devel] [PATCH v2] Improve documentation for --dev and --dev-node.

Hi,

Quoted 4 lines · Gert Doering

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.

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*

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
index 5b2f8470..72cf9064 100644
@@ -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
#14 lore raw

[Openvpn-devel] [PATCH applied] Re: Improve documentation for --dev and --dev-node.

In reply to Gert Doering

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 <[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