Skip to contentSkip to conversation

Improve the documentation for --dhcp-option

PATCH In review [email protected]... 5 participants 16 messages Mar 18, 2019 – Aug 17, 2020

lore
Share & tools
lore
#0 lore raw

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
index ce44044..993c8bd 100644
@@ -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
#1 lore raw

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.

---
  doc/openvpn.8 | 18 +++++++++++++-----
  1 file changed, 13 insertions(+), 5 deletions(-)
doc/openvpn.8 +13 -5
index ce44044..993c8bd 100644
@@ -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
#2 lore raw

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

We 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
author
#3 lore raw

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/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).

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

#4 lore raw

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

Quoted 7 lines
Quoted 3 lines

We 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).

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

#7 lore raw
In reply to Selva Nair
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-clients

We 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 ..

author
#5 lore raw
In reply to Arne Schwabe

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

Quoted 7 lines
Quoted 3 lines

We 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).

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

author
#8 lore raw
In reply to tincanteksup
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-clients

We 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.

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

We 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 ..

#6 lore raw
In reply to Selva Nair
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

#9 lore raw
In reply to Selva Nair

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

Quoted 7 lines
Quoted 3 lines

We 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).

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

#12 lore raw
In reply to Antonio Quartulli

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

We 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,

#10 lore raw
In reply to tincanteksup
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-clients

Quoted 7 lines
Quoted 3 lines

We 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).

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.

#11 lore raw

Correcion

Quoted 6 lines

From: Selva Nair <[email protected]...>

Make clear that --dhcp-option is not processed on
non-Windows clients

This thread was _initially_ about pushing DNS to Linux clients.

I mean "non-windows" clients.

#13 lore raw
In reply to [email protected]...

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

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
index 7100c1ae..825dd1ca 100644
@@ -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
Acked-by on v2 1/1
#15 lore raw

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