Improve the documentation for --dhcp-option
PATCH 1/1 Improve the documentation for --dhcp-option
From: Selva Nair <[email protected]...>
Make clear that --dhcp-option is not processed on non-Windows clients and the user is expected to handle it using an --up script.
--- doc/openvpn.8 | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-)
doc/openvpn.8 +13 -5
@@ -6026,13 +6026,21 @@ scope IDs. The Scope ID becomes a part of the NetBIOS name, making the name uniq .B DISABLE\-NBT \-\- Disable Netbios\-over\-TCP/IP. -Note that if +Note that +.B \-\-dhcp\-option +is processed only on Windows clients. If .B \-\-dhcp\-option -is pushed via +is used directly on or pushed via .B \-\-push -to a non\-windows client, the option will be saved in the client's -environment before the up script is called, under -the name "foreign_option_{n}". +to a non\-windows client, the option is +.B only +saved in the client's +environment before the +.B \-\-up +script is called, under the name "foreign_option_{n}". +The user has to arrange an +.B \-\-up +script to pick up those parameters and act on them as required. .\"********************************************************* .TP .B \-\-tap\-sleep n
Signature · 1 line
2.1.4
Hi,
this situation has been hanging around for so long is this brief note really enough? Considering that the manual has numerous other URLs why not include this URL here:
https://community.openvpn.net/openvpn/wiki/Pushing-DNS-to-clients
We already have this:
https://community.openvpn.net/openvpn/wiki/SWEET32
Please consider adding it.
Thanks
tct
Quoted 43 lines · On 18/03/2019 21:16, [email protected]... wrote:
From: Selva Nair <[email protected]...>
Make clear that --dhcp-option is not processed on non-Windows clients and the user is expected to handle it using an --up script.
Signed-off-by Selva Nair <[email protected]...>--- doc/openvpn.8 | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-)doc/openvpn.8 +13
-5@@ -6026,13 +6026,21 @@ scope IDs. The Scope ID becomes a part of the NetBIOS name, making the name uniq .B DISABLE\-NBT \-\- Disable Netbios\-over\-TCP/IP. -Note that if +Note that +.B \-\-dhcp\-option +is processed only on Windows clients. If .B \-\-dhcp\-option -is pushed via +is used directly on or pushed via .B \-\-push -to a non\-windows client, the option will be saved in the client's -environment before the up script is called, under -the name "foreign_option_{n}". +to a non\-windows client, the option is +.B only +saved in the client's +environment before the +.B \-\-up +script is called, under the name "foreign_option_{n}". +The user has to arrange an +.B \-\-up +script to pick up those parameters and act on them as required. .\"********************************************************* .TP .B \-\-tap\-sleep n
Hi,
Quoted 10 lines · tincanteksup
Hi,
this situation has been hanging around for so long is this brief note really enough? Considering that the manual has numerous other URLs why not include this URL here:
https://community.openvpn.net/openvpn/wiki/Pushing-DNS-to-clientsWe already have this:
https://community.openvpn.net/openvpn/wiki/SWEET32
the problem with URLs is that they become obsolete and we need to re-patch the manual in order to update them (or ensure the URL always work/redirect to something).
However, I was thinking that a WARNING in the log when parsing a dhcp-option without any script configured (on non-windows platform) may also be beneficial.
Not many people will read it, but at least it will be there to be seen at the first attempt of understanding what's wrong.
What do you think?
This said, the warning could/should be implemented as a separate patch.
Regards,
Signature · 1 line
Antonio Quartulli
Hi,
Quoted 11 lines · Antonio Quartulli
Hi,
Quoted 7 lines · tincanteksup
Hi,
this situation has been hanging around for so long is this brief note really enough? Considering that the manual has numerous other URLs why not include this URL here:
https://community.openvpn.net/openvpn/wiki/Pushing-DNS-to-clients
Quoted 7 lines
Quoted 3 lines
We already have this:
https://community.openvpn.net/openvpn/wiki/SWEET32the problem with URLs is that they become obsolete and we need to re-patch the manual in order to update them (or ensure the URL always work/redirect to something).
I have the same opinion about URLs. On top of that the wiki description is inadequate and inaccurate. But that's a different topic.
The patch was meant to remove the ambiguity in the current wording. We could add a line saying many distributions include such scripts and front-ends such as network manager, tunnelblick, OpenVPN for Android etc. also handle some dhcp-options. (I don't use any of them, so guessing here..)
Quoted 5 lines
However, I was thinking that a WARNING in the log when parsing a dhcp-option without any script configured (on non-windows platform) may also be beneficial.
This would catch some obvious cases but not when a script is being used for some other purpose. Still, sounds useful.
Selva
Am 20.03.19 um 14:25 schrieb Selva Nair:
Quoted 27 lines
Hi,
Quoted 11 lines · Antonio Quartulli
Hi,
Quoted 7 lines · tincanteksup
Hi,
this situation has been hanging around for so long is this brief note really enough? Considering that the manual has numerous other URLs why not include this URL here:
https://community.openvpn.net/openvpn/wiki/Pushing-DNS-to-clientsQuoted 7 lines
Quoted 3 lines
We already have this:
https://community.openvpn.net/openvpn/wiki/SWEET32the problem with URLs is that they become obsolete and we need to re-patch the manual in order to update them (or ensure the URL always work/redirect to something).
I have the same opinion about URLs. On top of that the wiki description is inadequate and inaccurate. But that's a different topic.
Quoted 6 lines
The patch was meant to remove the ambiguity in the current wording. We could add a line saying many distributions include such scripts and front-ends such as network manager, tunnelblick, OpenVPN for Android etc. also handle some dhcp-options. (I don't use any of them, so guessing here..)
Yes. Most platforms and client interpret this option. Only OpenVPN itself only interprets it only Windows and Android. It should probably changed to reflect reality.
Arne
Quoted 18 lines · Selva Nair
Hi,
Quoted 15 lines · Antonio Quartulli
Hi,
Quoted 10 lines · tincanteksup
Hi,
this situation has been hanging around for so long is this brief note really enough? Considering that the manual has numerous other URLs why not include this URL here:
https://community.openvpn.net/openvpn/wiki/Pushing-DNS-to-clientsWe already have this:
https://community.openvpn.net/openvpn/wiki/SWEET32
Quoted 8 lines
Quoted 3 lines
the problem with URLs is that they become obsolete and we need to re-patch the manual in order to update them (or ensure the URL always work/redirect to something).
I have the same opinion about URLs. On top of that the wiki description is inadequate and inaccurate. But that's a different topic.
Inadequate:
Compared to NOTHING, the page is at least a step toward documentation.
Inaccurate:
Please expand ..
Hi,
Quoted 36 lines · Arne Schwabe
Am 20.03.19 um 14:25 schrieb Selva Nair:
Quoted 27 lines
Hi,
Quoted 11 lines · Antonio Quartulli
Hi,
Quoted 7 lines · tincanteksup
Hi,
this situation has been hanging around for so long is this brief note really enough? Considering that the manual has numerous other URLs why not include this URL here:
https://community.openvpn.net/openvpn/wiki/Pushing-DNS-to-clientsQuoted 7 lines
Quoted 3 lines
We already have this:
https://community.openvpn.net/openvpn/wiki/SWEET32the problem with URLs is that they become obsolete and we need to re-patch the manual in order to update them (or ensure the URL always work/redirect to something).
I have the same opinion about URLs. On top of that the wiki description is inadequate and inaccurate. But that's a different topic.
Quoted 6 lines
The patch was meant to remove the ambiguity in the current wording. We could add a line saying many distributions include such scripts and front-ends such as network manager, tunnelblick, OpenVPN for Android etc. also handle some dhcp-options. (I don't use any of them, so guessing here..)
Quoted 3 lines
Yes. Most platforms and client interpret this option. Only OpenVPN itself only interprets it only Windows and Android. It should probably changed to reflect reality.
In case of Android, its only sent to the management, right? As the man page is about
OpenVPN core, I would say the current statement that the option is handled only on
Windows is correct.
But its useful to expand on the usage on other platforms. I can add a line about scripts in OS
distributions and front-ends/UI like Android that can transparently handle it.
Selva
Quoted 31 lines · tincanteksup
Quoted 18 lines · Selva Nair
Hi,
Quoted 15 lines · Antonio Quartulli
Hi,
Quoted 10 lines · tincanteksup
Hi,
this situation has been hanging around for so long is this brief note really enough? Considering that the manual has numerous other URLs why not include this URL here:
https://community.openvpn.net/openvpn/wiki/Pushing-DNS-to-clientsWe already have this:
https://community.openvpn.net/openvpn/wiki/SWEET32Quoted 8 lines
Quoted 3 lines
the problem with URLs is that they become obsolete and we need to re-patch the manual in order to update them (or ensure the URL always work/redirect to something).
I have the same opinion about URLs. On top of that the wiki description is inadequate and inaccurate. But that's a different topic.
Quoted 5 lines
Inadequate:
Compared to NOTHING, the page is at least a step toward documentation.Inaccurate:
Please expand ..
The wiki states that on Windows using version 2.4, OpenVPN-GUI+interactive service required for processing this option. Not so.
Just as in 2.3, it works if run as admin. In fact, several setups run OpenVPN on boot using OpenVPNService, and --dhcp-option does work for them. With 2.4, it also works as limited user if started using the interactive service (for example, using OpenVPN-GUI).
In both 2.3 and 2.4, the critical piece is not overriding --ipwin32 method (adaptive or dynamic is required and the latter is the default).
Selva
Quoted 37 lines · tincanteksup
Quoted 18 lines · Selva Nair
Hi,
Quoted 15 lines · Antonio Quartulli
Hi,
Quoted 10 lines · tincanteksup
Hi,
this situation has been hanging around for so long is this brief note really enough? Considering that the manual has numerous other URLs why not include this URL here:
https://community.openvpn.net/openvpn/wiki/Pushing-DNS-to-clientsWe already have this:
https://community.openvpn.net/openvpn/wiki/SWEET32Quoted 8 lines
Quoted 3 lines
the problem with URLs is that they become obsolete and we need to re-patch the manual in order to update them (or ensure the URL always work/redirect to something).
I have the same opinion about URLs. On top of that the wiki description is inadequate and inaccurate. But that's a different topic.
Inadequate:
Compared to NOTHING, the page is at least a step toward documentation.Inaccurate:
Please expand ..
Quoted 7 lines
In case of Android, its only sent to the management, right? As the man page is about
OpenVPN core, I would say the current statement that the option is handled only on
Windows is correct.
Well everything is just to managment on Android, even opening the tun device. But Android and Win32 are the two platforms on which the core parses the DNS option and explicity calls functions to set a DNS server.
Arne
bonjour
Quoted 33 lines · Selva Nair
Quoted 31 lines · tincanteksup
Quoted 26 lines · Selva Nair
Hi,
Quoted 11 lines · Antonio Quartulli
Hi,
Quoted 7 lines · tincanteksup
Hi,
this situation has been hanging around for so long is this brief note really enough? Considering that the manual has numerous other URLs why not include this URL here:
https://community.openvpn.net/openvpn/wiki/Pushing-DNS-to-clientsQuoted 7 lines
Quoted 3 lines
We already have this:
https://community.openvpn.net/openvpn/wiki/SWEET32the problem with URLs is that they become obsolete and we need to re-patch the manual in order to update them (or ensure the URL always work/redirect to something).
I have the same opinion about URLs. On top of that the wiki description is inadequate and inaccurate. But that's a different topic.
Quoted 8 lines
Quoted 5 lines
Inadequate:
Compared to NOTHING, the page is at least a step toward documentation.Inaccurate:
Please expand ..The wiki states that on Windows using version 2.4, OpenVPN-GUI+interactive service required for processing this option. Not so.
I am actively promoting 2.4 use, I am not re-writing the manual.
Quoted 4 lines
Just as in 2.3, it works if run as admin. In fact, several setups run OpenVPN on boot using OpenVPNService, and --dhcp-option does work for them. With 2.4, it also works as limited user if started using the interactive service (for example, using OpenVPN-GUI).
I am actively demoting 2.3 use, I am not re-writing the manual.
Quoted 4 lines
In both 2.3 and 2.4, the critical piece is not overriding --ipwin32 method (adaptive or dynamic is required and the latter is the default).
I am actively promoting the use of the Interactive Service. I am not rewriting the manual ..
If a problem arises from using Openvpn as the page describes then, depending on the cause, a resolution can be pursued ..
thanks
tct
bonjour
Quoted 13 lines · Antonio Quartulli
Hi,
Quoted 10 lines · tincanteksup
Hi,
this situation has been hanging around for so long is this brief note really enough? Considering that the manual has numerous other URLs why not include this URL here:
https://community.openvpn.net/openvpn/wiki/Pushing-DNS-to-clientsWe already have this:
https://community.openvpn.net/openvpn/wiki/SWEET32
Reinserted from my original post:
Quoted 9 lines
Quoted 1 line
Please consider adding it.
the problem with URLs is that they become obsolete and we need to re-patch the manual in order to update them (or ensure the URL always work/redirect to something).
Quoted 8 lines
However, I was thinking that a WARNING in the log when parsing a dhcp-option without any script configured (on non-windows platform) may also be beneficial.
Not many people will read it, but at least it will be there to be seen at the first attempt of understanding what's wrong.
What do you think?
The argument against using URLs in the Manual has these facts to refute:
* URLs are already in use in the manual
* I cited another example of using a URL in the manual.
* Some URLS in use in the manual are external to openvpn.net
* Using URLs in online documentation is The standard practice.
* There are even URLs in the Openvpn log files ..
It is easier to maintain linked documentation than it is to have to patch the source so, given that the link is under the openvpn.net wing, this seems perfectly reasonable to me.
Adding a warning for this problem in the log file is unsuitable:
* When the situation changes the source will have to be maintained.
* The situation will change.
* It is easier to maintain linked documentation to account for change.
* Log files are for diagnosing problems and should not have any URLs..
(Except for one URL to ${help}.openvpn, a URL which is unlikely to change and can therefore be easily maintained by OpenVPN Inc and remove that burden from the FOSS Openvpn development team)
my2c thanks
tct
Quoted 5 lines
This said, the warning could/should be implemented as a separate patch.
Regards,
Quoted 59 lines · tincanteksup
bonjour
Quoted 33 lines · Selva Nair
Quoted 31 lines · tincanteksup
Quoted 26 lines · Selva Nair
Hi,
Quoted 11 lines · Antonio Quartulli
Hi,
Quoted 7 lines · tincanteksup
Hi,
this situation has been hanging around for so long is this brief note really enough? Considering that the manual has numerous other URLs why not include this URL here:
https://community.openvpn.net/openvpn/wiki/Pushing-DNS-to-clientsQuoted 7 lines
Quoted 3 lines
We already have this:
https://community.openvpn.net/openvpn/wiki/SWEET32the problem with URLs is that they become obsolete and we need to re-patch the manual in order to update them (or ensure the URL always work/redirect to something).
I have the same opinion about URLs. On top of that the wiki description is inadequate and inaccurate. But that's a different topic.
Quoted 8 lines
Quoted 5 lines
Inadequate:
Compared to NOTHING, the page is at least a step toward documentation.Inaccurate:
Please expand ..The wiki states that on Windows using version 2.4, OpenVPN-GUI+interactive service required for processing this option. Not so.
I am actively promoting 2.4 use, I am not re-writing the manual.
Quoted 4 lines
Just as in 2.3, it works if run as admin. In fact, several setups run OpenVPN on boot using OpenVPNService, and --dhcp-option does work for them. With 2.4, it also works as limited user if started using the interactive service (for example, using OpenVPN-GUI).
I am actively demoting 2.3 use, I am not re-writing the manual.
Quoted 4 lines
In both 2.3 and 2.4, the critical piece is not overriding --ipwin32 method (adaptive or dynamic is required and the latter is the default).
Quoted 9 lines
I am actively promoting the use of the Interactive Service. I am not rewriting the manual ..
If a problem arises from using Openvpn as the page describes then, depending on the cause, a resolution can be pursued ..
thanks
tct
This thread was _initially_ about pushing DNS to Linux clients.
Correcion
Quoted 6 lines
From: Selva Nair <[email protected]...>
Make clear that --dhcp-option is not processed on
non-Windows clientsThis thread was _initially_ about pushing DNS to Linux clients.
I mean "non-windows" clients.
Hi,
Quoted 5 lines · On Mon, Mar 18, 2019 at 05:16:49PM -0400, [email protected]... wrote:
From: Selva Nair <[email protected]...>
Make clear that --dhcp-option is not processed on non-Windows clients and the user is expected to handle it using an --up script.
I'm going through "lost" patches in patchwork - and this one is still relevant, I think, but the documentation looks much different now (.rst).
Could you re-send?
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]...PATCH v2 1/1 Improve the documentation for --dhcp-option
In reply to [email protected]...From: Selva Nair <[email protected]...>
- Stress that these are handled internally only on some platforms
- Correct the statement about wintun
- Document DOMAIN-SEARCH
---
v2: Rebase to master and reword to match the new rst version
Add doc for DOMAIN-SEARCH
doc/man-sections/vpn-network-options.rst | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-)
doc/man-sections/vpn-network-options.rst +17 -6
@@ -93,12 +93,18 @@ routing. or :code:`tap`. --dhcp-option args - Set additional network settings via DHCP. On Windows, this is parsed by - the ``tap-windows6`` or ``wintun`` driver. On other platforms these - options can be picked up by an ``--up`` script or plug-in if it has been - pushed by the OpenVPN server. The option will then be saved in the - client's environment before the ``--up`` script is called, under the name - :code:`foreign_option_{n}`. + Set additional network parameters on supported platforms. May be specified + on the client or pushed from the server. On Windows these options are + handled by the ``tap-windows6`` driver by default or directly by OpenVPN + if dhcp is disabled or the ``wintun`` driver is in use. The + ``OpenVPN for Android`` client also handles them internally. + + On all other platforms these options are only saved in the client's + environment under the name :code:`foreign_options_{n}` before the + ``--up`` script is called. A plugin or an ``--up`` script must be used to + pick up and interpret these as required. Many Linux distributions include + such scripts and some third-party user interfaces such as tunnelblick also + come with scripts that process these options. Valid syntax: ::
@@ -108,6 +114,11 @@ routing. :code:`DOMAIN` ``name`` Set Connection-specific DNS Suffix to :code:`name`. + :code:`DOMAIN-SEARCH` ``name`` + Add :code:`name` to the domain search list. + Repeat this option to add more entries. Up to + 10 domains are supported. + :code:`DNS` ``address`` Set primary domain name server IPv4 or IPv6 address. Repeat this option to set secondary DNS server addresses.
Signature · 1 line
2.17.1
Thanks!
Your patch has been applied to the master and release/2.5 branch.
commit 2da29362cc93aa1b8c24386e162b9cdd3b55c3b1 (master) commit 64f0b1c07e1d4579cdb3d6a9df27555071c1ed04 (master)
Author: Selva Nair Date: Sun Aug 16 15:06:39 2020 -0400
Improve the documentation for --dhcp-option
Signed-off-by: Selva Nair <[email protected]...>
Acked-by: Gert Doering <[email protected]...>
Message-Id: <[email protected]...>
URL: https://www.mail-archive.com/[email protected]/msg20759.html
Signed-off-by: Gert Doering <[email protected]...>--
kind regards,
Gert Doering