Bug 1403594 - Poorly documented nmcli options
Summary: Poorly documented nmcli options
Keywords:
Status: CLOSED EOL
Alias: None
Product: Fedora
Classification: Fedora
Component: NetworkManager
Version: 24
Hardware: All
OS: Linux
unspecified
unspecified
Target Milestone: ---
Assignee: Lubomir Rintel
QA Contact: Fedora Extras Quality Assurance
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2016-12-11 18:34 UTC by Peter Tselios
Modified: 2017-08-08 19:25 UTC (History)
4 users (show)

Fixed In Version:
Clone Of:
Environment:
Last Closed: 2017-08-08 19:25:49 UTC
Type: Bug
Embargoed:


Attachments (Terms of Use)

Description Peter Tselios 2016-12-11 18:34:32 UTC
Description of problem:
I try to use my own DNS servers in conjuction with the ISP resolvers as well. I don't want to run dnsmasq for my reasons. Anyway, I was hopping to find something in the nmcli man pages and I found the dns-options and dns-priority. 
However, the man pages are not explaining what they do, how you setup those options and of course there are no examples. 

Version-Release number of selected component (if applicable):
F24

How reproducible:
100%

Steps to Reproduce:
1. man 5 nmcli-config
2. Search for the dns and find the aforementioned options.

Actual results:
man pages have a technical description of the options, but they are not mention what those options are doing or how to set them up. 

Expected results:
At least a definition of the options and some examples in the relevant man page. 

Additional info:

Comment 1 Thomas Haller 2016-12-11 22:06:48 UTC
> Steps to Reproduce:
> 1. man 5 nmcli-config

a man page "nmcli-config" does not exist. It would be helpful to describe which documentation you were reading, and in which way you found it lacking.

`man nmcli` says:

       modify [--temporary] [id | uuid | path] ID
       {option value | [+|-]setting.property value}...
           Add, modify or remove properties in the connection profile.

       ...

           See nm-settings(5) for complete reference of setting and property
           names, their descriptions and default values. The setting and
           property can be abbreviated provided they are unique.



`man nm-settings` describes ipv4.dns-options and ipv4.dns-priority.
I give you, the description for dns-options is not clear. It's the "options" from `man resolv.conf`. 


the same manuals are accessible online (from upstream): https://developer.gnome.org/NetworkManager/stable/manpages.html

Comment 2 Peter Tselios 2016-12-12 14:54:25 UTC
Sorry, I mean nm-settings

Comment 3 Thomas Haller 2016-12-14 18:29:13 UTC
regarding ipv4.dns-options I changed: https://cgit.freedesktop.org/NetworkManager/NetworkManager/commit/?id=f2355633a9aaad6257aadfac409e65a6d0912180

The documentation about dns-priority seems clear to me (?).


Please give concrete suggestions how it should be improved. Thanks.

Comment 4 Peter Tselios 2016-12-14 21:55:38 UTC
dns-options: Now it IS clear, thank you.

dns-priority: Regarding the priority, I **guess** that you specify the priority as a space separated list and assigns the given priority to each server set previously. 
Meaning, if I have :
   
    ipv4.dns "10.0.0.10 8.8.8.8 4.4.4.4"
    ipv4.priority "10 5 1" 

then the 10.0.0.10 will have a priority of 10, 8.8.8.8 priority 5 etc.

If my guess is right, I believe it should worth mentioning it in the examples and in the table as well. 

If not, then obviously it's not clear!

Thanks for the quick resolution on the 1st.

Comment 6 Peter Tselios 2016-12-19 17:10:53 UTC
Much better. It's clear that we talk about different settings. 
Although I have to admit that personally I am a little bit confused. 
Let me see if I understand this:
ipv4.dns is specific to a connection.
dns-priority is about ALL dns settings in all connections. 

If so, what's the meaning of it? There will be only one active connection each time (with the exception of a VON I guess), right?

Comment 7 Thomas Haller 2016-12-19 17:53:18 UTC
>  There will be only one active connection each time 

You can have multiple connections in NetworkManager (aka. profiles).

On one networking interface (device), you can only have one connection active at each time. If you have multiple devices, you can have multiple connections activate -- on different devices!
Of course, for one device you might have multiple connections that are in the state of activating/deactivating on that device. But only one of them is *active* at each time.

There is also a somewhat arbitrary restriction, that a connection can only be active at one device at each time.
Similarly, in a given moment, one connection might be activating/deactivation on multiple devices (or the same one). But it's only *active* on exactly one device.

This is not true for VPNs, which are different types of connections.

<<<<<<<<

ipv4.dns,ipv4.dns-options vs. ipv4.dns-priority is similar to:

- connection.autoconnect vs. connection.autoconnect-priority
- ipv4.routes,ipv4.gateway vs. ipv4.route-metric
- ipv6.routes,ipv6.gateway vs. ipv6.route-metric

That is, the first properties are the configuration *for* the connection.
But the priority/metric properties only really matter when moderating the property with multiple active connections.

Comment 8 Peter Tselios 2016-12-19 18:49:13 UTC
Please write them somewhere in the documentation!!!! Honestly, it's just very nice. 

A lot of people think that you can have only one set of DNS servers, but, it's clear that you can have a different set of DNS settings. 

So, let's see if I can find a very nice argument on why to use NM in a Datacenter:
Let's say you have 2 connections, like those:

mng eth0 10.0.0.1 (Management Ntw)
data eth1 192.168.0.1 (Data Traffic/DMZ ntw)

Then you specify different DNS servers for each connection. If you specify the SAME priority on the DNS, then NM you "send" the DNS query to the DNS servers set for each connection. 

Right?

Comment 9 Thomas Haller 2016-12-20 10:14:05 UTC
(In reply to Peter Tselios from comment #8)

> Then you specify different DNS servers for each connection. If you specify
> the SAME priority on the DNS, then NM you "send" the DNS query to the DNS
> servers set for each connection. 

As `man resolv.conf` details, resolver tries the nameservers in the specified order. The priority is mostly about the order of DNS servers in resolv.conf.
If two active connections have the same priority, then the one which also has the default-route is considered more important. If both have the same priority and both don't have the default route, then their order is undefined.

Note that with dns=dnsmasq, the DNS plugin might not care about the order (see  --strict-order and --all-servers in `man dnsmasq).

Using a negative priority can be used to mark a connection as exclusive. In that case, only DNS settings from the connection(s) with the lowest priority are merged into the resulting resolv.conf.

Comment 10 Fedora End Of Life 2017-07-26 00:04:07 UTC
This message is a reminder that Fedora 24 is nearing its end of life.
Approximately 2 (two) weeks from now Fedora will stop maintaining
and issuing updates for Fedora 24. It is Fedora's policy to close all
bug reports from releases that are no longer maintained. At that time
this bug will be closed as EOL if it remains open with a Fedora  'version'
of '24'.

Package Maintainer: If you wish for this bug to remain open because you
plan to fix it in a currently maintained version, simply change the 'version'
to a later Fedora version.

Thank you for reporting this issue and we are sorry that we were not
able to fix it before Fedora 24 is end of life. If you would still like
to see this bug fixed and are able to reproduce it against a later version
of Fedora, you are encouraged  change the 'version' to a later Fedora
version prior this bug is closed as described in the policy above.

Although we aim to fix as many bugs as possible during every release's
lifetime, sometimes those efforts are overtaken by events. Often a
more recent Fedora release includes newer upstream software that fixes
bugs or makes them obsolete.

Comment 11 Fedora End Of Life 2017-08-08 19:25:49 UTC
Fedora 24 changed to end-of-life (EOL) status on 2017-08-08. Fedora 24 is
no longer maintained, which means that it will not receive any further
security or bug fix updates. As a result we are closing this bug.

If you can reproduce this bug against a currently maintained version of
Fedora please feel free to reopen this bug against that version. If you
are unable to reopen this bug, please file a new report against the
current release. If you experience problems, please add a comment to this
bug.

Thank you for reporting this bug and we are sorry it could not be fixed.


Note You need to log in before you can comment on or make changes to this bug.