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.
v2: disambiguate Linux ("all drivers") and FreeBSD ("only DCO"), add
comment about --dev-type being necessary for devices not starting with
tun* or tap*
Signed-off-by: Gert Doering <gert@greenie.muc.de>
Acked-by: Antonio Quartulli <antonio@openvpn.net>
Message-Id: <20221108134523.2325-1-gert@greenie.muc.de>
URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg25488.html
Signed-off-by: Gert Doering <gert@greenie.muc.de>
Gert Doering authored on 2022/11/08 22:45:23Showing 1 changed files
| ... | ... |
@@ -69,15 +69,34 @@ routing. |
| 69 | 69 |
dev tap4 |
| 70 | 70 |
dev ovpn |
| 71 | 71 |
|
| 72 |
- When the device name starts with :code:`tun` or :code:`tap`, the device |
|
| 73 |
- type is extracted automatically. Otherwise the ``--dev-type`` option |
|
| 74 |
- needs to be added as well. |
|
| 72 |
+ What happens if the device name is not :code:`tun` or :code:`tap` is |
|
| 73 |
+ platform dependent. |
|
| 74 |
+ |
|
| 75 |
+ On most platforms, :code:`tunN` (e.g. tun2, tun30) and :code:`tapN` |
|
| 76 |
+ (e.g. tap3) will create a numbered tun/tap interface with the number |
|
| 77 |
+ specified - this is useful if multiple OpenVPN instances are active, |
|
| 78 |
+ and the instance-to-device mapping needs to be known. Some platforms |
|
| 79 |
+ do not support "numbered tap", so trying ``--dev tap3`` will fail. |
|
| 80 |
+ |
|
| 81 |
+ Arbitrary device names (e.g. ``--dev tun-home``) will only work on |
|
| 82 |
+ FreeBSD (with the DCO kernel driver for ``tun`` devices) and Linux |
|
| 83 |
+ (for both ``tun`` and ``tap`` devices, DCO and tun/tap driver). |
|
| 84 |
+ |
|
| 85 |
+ If such a device name starts with ``tun`` or ``tap`` (e.g. ``tun-home``), |
|
| 86 |
+ OpenVPN will choose the right device type automatically. Otherwise the |
|
| 87 |
+ desired device type needs to be specified with ``--dev-type tun`` or |
|
| 88 |
+ ``--dev-type tap``. |
|
| 89 |
+ |
|
| 90 |
+ On Windows, only the names :code:`tun` and :code:`tap` are supported. |
|
| 91 |
+ Selection among multiple installed drivers or driver instances is done |
|
| 92 |
+ with ``--dev-node`` and ``--windows-driver``. |
|
| 75 | 93 |
|
| 76 | 94 |
--dev-node node |
| 77 |
- Explicitly set the device node rather than using :code:`/dev/net/tun`, |
|
| 78 |
- :code:`/dev/tun`, :code:`/dev/tap`, etc. If OpenVPN cannot figure out |
|
| 79 |
- whether ``node`` is a TUN or TAP device based on the name, you should |
|
| 80 |
- also specify ``--dev-type tun`` or ``--dev-type tap``. |
|
| 95 |
+ This is a highly system dependent option to influence tun/tap driver |
|
| 96 |
+ selection. |
|
| 97 |
+ |
|
| 98 |
+ On Linux, tun/tap devices are created by accessing :code:`/dev/net/tun`, |
|
| 99 |
+ and this device name can be changed using ``--dev-node ...``. |
|
| 81 | 100 |
|
| 82 | 101 |
Under Mac OS X this option can be used to specify the default tun |
| 83 | 102 |
implementation. Using ``--dev-node utun`` forces usage of the native |
| ... | ... |
@@ -93,6 +112,11 @@ routing. |
| 93 | 93 |
both the network connections control panel name and the GUID for each |
| 94 | 94 |
TAP-Win32 adapter. |
| 95 | 95 |
|
| 96 |
+ On other platforms, ``--dev-node node`` will influence the naming of the |
|
| 97 |
+ created tun/tap device, if supported on that platform. If OpenVPN cannot |
|
| 98 |
+ figure out whether ``node`` is a TUN or TAP device based on the name, |
|
| 99 |
+ you should also specify ``--dev-type tun`` or ``--dev-type tap``. |
|
| 100 |
+ |
|
| 96 | 101 |
--dev-type device-type |
| 97 | 102 |
Which device type are we using? ``device-type`` should be :code:`tun` |
| 98 | 103 |
(OSI Layer 3) or :code:`tap` (OSI Layer 2). Use this option only if |