On network management and documenting nmcli

On network management and documenting nmcli

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 1505 bytes --]


During my first encounter with GuixSD, I could not connect to the
Internet for reasons that puzzled me, and I could not find any mention
of it in the manual either.

At first I assumed I had done something wrong with the setup.

I had tried to run wpa_supplicant manually, like I often do on other
distributions.  It's only later that I understood why wpa_supplicant
failed: it was because it was already running! (It's stupid but
wpa_supplicant's error messages are extremely misleading.)

The manual is extremely scarse about network configuration.  Sure
enough, if nm-applet is running it's rather straightforward.  But for a
desktop-environment-less setup and during the install, the default tool
is nmcli only (unless another manager is used, but then the user
probably knows what they are doing).

I don't think any of this is mentioned at all in the manual: I believe
something so essential should be very explicitly documented.

I suggest we add some examples to the Installation info page, for instance:

> nmcli device wifi
> sudo nmcli d w connect "foo SSID" password "foo password"

Mention that tab-completion can be use to complete SSIDs, which is
useful in the event they contain special or invisible characters
(trailing spaces are common).

We should also hint at the (7)nmcli-examples man page.


Unrelated question: why do I need to "sudo" to add a connection?
If I recall correctly, nm-applet does not ask for extra privileges
(could be wrong though).

Comments?

--
Pierre Neidhardt

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: On network management and documenting nmcli

[Oleg Pykhalov]

[-- Attachment #1: Type: text/plain, Size: 758 bytes --]

Hello Pierre,

Pierre Neidhardt <ambrevar@gmail.com> writes:

[…]

> I don't think any of this is mentioned at all in the manual: I believe
> something so essential should be very explicitly documented.
>
> I suggest we add some examples to the Installation info page, for instance:
>
>> nmcli device wifi
>> sudo nmcli d w connect "foo SSID" password "foo password"

I agree, except because of default user on an installation image is
‘root’ (as I remember) invoking a ‘sudo’ command is not required. Cannot
confirm it without burning a USB with installation image and QEMU cannot
boot it from my experience.

[…]

> Comments?

We could pick a ‘nmtui’ program as we pick ‘cfdisk’ instead of ‘fdisk’.

Oleg.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: On network management and documenting nmcli

[Devan Carpenter]

[-- Attachment #1: Type: text/plain, Size: 168 bytes --]

Oleg Pykhalov transcribed 1.8K bytes:
> […]
> 
> > Comments?
> 
> We could pick a ‘nmtui’ program as we pick ‘cfdisk’ instead of ‘fdisk’.

+1



[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: On network management and documenting nmcli

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 389 bytes --]


Devan Carpenter <mail@dvn.me> writes:

> Oleg Pykhalov transcribed 1.8K bytes:
> 
>> We could pick a ‘nmtui’ program as we pick ‘cfdisk’ instead of ‘fdisk’.
>
> +1

Is nmtui on the install image as well?

-- 
Pierre Neidhardt

Cogito cogito ergo cogito sum --
"I think that I think, therefore I think that I am."
		-- Ambrose Bierce, "The Devil's Dictionary"

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: On network management and documenting nmcli

[Devan Carpenter]

[-- Attachment #1: Type: text/plain, Size: 347 bytes --]

Pierre Neidhardt transcribed 1.1K bytes:
> 
> Devan Carpenter <mail@dvn.me> writes:
> 
> > Oleg Pykhalov transcribed 1.8K bytes:
> > 
> >> We could pick a ‘nmtui’ program as we pick ‘cfdisk’ instead of ‘fdisk’.
> >
> > +1
> 
> Is nmtui on the install image as well?
 
I'm not sure. We should consider adding it, if not.


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: On network management and documenting nmcli

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 361 bytes --]


Devan Carpenter <mail@dvn.me> writes:

>> Is nmtui on the install image as well?
>  
> I'm not sure. We should consider adding it, if not.

I find nmcli well documented (nmcli help ...) and convenient to use with
completion.

Besides it works with Eshell! :)
(Which is much more convenient for copy-pasting, among others.)

-- 
Pierre Neidhardt

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: On network management and documenting nmcli

[Chris Marusich]

[-- Attachment #1: Type: text/plain, Size: 2890 bytes --]

Pierre Neidhardt <ambrevar@gmail.com> writes:

> During my first encounter with GuixSD, I could not connect to the
> Internet for reasons that puzzled me, and I could not find any mention
> of it in the manual either.
>
> At first I assumed I had done something wrong with the setup.
>
> I had tried to run wpa_supplicant manually, like I often do on other
> distributions.  It's only later that I understood why wpa_supplicant
> failed: it was because it was already running! (It's stupid but
> wpa_supplicant's error messages are extremely misleading.)
>
> The manual is extremely scarse about network configuration.  Sure
> enough, if nm-applet is running it's rather straightforward.  But for a
> desktop-environment-less setup and during the install, the default tool
> is nmcli only (unless another manager is used, but then the user
> probably knows what they are doing).
>
> I don't think any of this is mentioned at all in the manual: I believe
> something so essential should be very explicitly documented.

Did you know we have an example in the manual a (guix) Preparing for
Installation?  Here it is:

--8<---------------cut here---------------start------------->8---
Wireless connection
     To configure wireless networking, you can create a configuration
     file for the ‘wpa_supplicant’ configuration tool (its location is
     not important) using one of the available text editors such as
     ‘nano’:

          nano wpa_supplicant.conf

     As an example, the following stanza can go to this file and will
     work for many wireless networks, provided you give the actual SSID
     and passphrase for the network you are connecting to:

          network={
            ssid="MY-SSID"
            key_mgmt=WPA-PSK
            psk="the network's secret passphrase"
          }

     Start the wireless service and run it in the background with the
     following command (substitute INTERFACE with the name of the
     network interface you want to use):

          wpa_supplicant -c wpa_supplicant.conf -i INTERFACE -B

     Run ‘man wpa_supplicant’ for more information.
--8<---------------cut here---------------end--------------->8---

What do you think of this example?

I think it's good to add an example or two for common use cases and
provide a reference for further reading, but I don't think we should try
to provide an example in the manual for every possible situation.  For
example, if you need to connect over a WEP-"secured" network (which is
not secure at all) using wpa-supplicant, you will need to adjust the
config file, but I don't think even the official wpa-supplicant official
documentation gives you an example of how to do it.  As far as I know,
WPA (WPA2, I guess?) is the preferred and common choice nowadays, so I
think the example is appropriate.

-- 
Chris

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: On network management and documenting nmcli

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 449 bytes --]


As far as I can remember, the documentation example did not work for me.

I think it is because I had built a custom image on which nmcli was
running because the network-manager service was automatically started,
unbeknownst to me.

Beyond the installation process, I think my example is also relevant for
at least one of the official "lightweight-desktop.scm" configuration
file for which the default way to connect is nmcli.

--
Pierre Neidhardt

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: On network management and documenting nmcli

[Nils Gillmann]

Devan Carpenter transcribed 1.4K bytes:
> Pierre Neidhardt transcribed 1.1K bytes:
> > 
> > Devan Carpenter <mail@dvn.me> writes:
> > 
> > > Oleg Pykhalov transcribed 1.8K bytes:
> > > 
> > >> We could pick a ‘nmtui’ program as we pick ‘cfdisk’ instead of ‘fdisk’.
> > >
> > > +1
> > 
> > Is nmtui on the install image as well?
>  
> I'm not sure. We should consider adding it, if not.
> 

Yes, it is:

readlink $(which nmtui)
/gnu/store/kp99ls7p93j640ghsgfzma0fr9ql72p3-network-manager-1.8.4/bin/nmtui


If I remember correctly NM had something about PAM and groups so that you
could add connections.

Gentoo has a neat little tool in their install image.
net-setup detects cards and prompts you for passwords etc.
https://gitweb.gentoo.org/proj/livecd-tools.git/tree/net-setup

Re: On network management and documenting nmcli

[swedebugia]

On May 13, 2018 9:26:14 AM GMT+02:00, Nils Gillmann <gillmann@infotropique.org> wrote:
... 
>
>Gentoo has a neat little tool in their install image.
>net-setup detects cards and prompts you for passwords etc.
>https://gitweb.gentoo.org/proj/livecd-tools.git/tree/net-setup

I saw no license declarations in those files or in the repo. 
Are they free software? 

Re: On network management and documenting nmcli

[Nils Gillmann]

swedebugia transcribed 391 bytes:
> 
> 
> On May 13, 2018 9:26:14 AM GMT+02:00, Nils Gillmann <gillmann@infotropique.org> wrote:
> ... 
> >
> >Gentoo has a neat little tool in their install image.
> >net-setup detects cards and prompts you for passwords etc.
> >https://gitweb.gentoo.org/proj/livecd-tools.git/tree/net-setup
> 
> I saw no license declarations in those files or in the repo. 
> Are they free software? 

They are meant to be included in the base of the installer image of Gentoo.
Gentoo's default license is GPL2, so I assume they will be licensed in
the context of the image's license.

Re: On network management and documenting nmcli

[Nils Gillmann]

Nils Gillmann transcribed 603 bytes:
> swedebugia transcribed 391 bytes:
> > 
> > 
> > On May 13, 2018 9:26:14 AM GMT+02:00, Nils Gillmann <gillmann@infotropique.org> wrote:
> > ... 
> > >
> > >Gentoo has a neat little tool in their install image.
> > >net-setup detects cards and prompts you for passwords etc.
> > >https://gitweb.gentoo.org/proj/livecd-tools.git/tree/net-setup
> > 
> > I saw no license declarations in those files or in the repo. 
> > Are they free software? 
> 
> They are meant to be included in the base of the installer image of Gentoo.
> Gentoo's default license is GPL2, so I assume they will be licensed in
> the context of the image's license.

For reference: https://packages.gentoo.org/packages/app-misc/livecd-tools
where they use the default Gentoo license (GPL2). You interact with this
usually with portage, so you will see the license statement then.
iirc the license file is then included on the system which builds the
ebuild through the definition of the license in the package definition.

Re: On network management and documenting nmcli

[Chris Marusich]

[-- Attachment #1: Type: text/plain, Size: 1609 bytes --]

Pierre Neidhardt <ambrevar@gmail.com> writes:

> As far as I can remember, the documentation example did not work for me.
>
> I think it is because I had built a custom image on which nmcli was
> running because the network-manager service was automatically started,
> unbeknownst to me.
>
> Beyond the installation process, I think my example is also relevant for
> at least one of the official "lightweight-desktop.scm" configuration
> file for which the default way to connect is nmcli.

The example in the manual is intended for the situation in which someone
is installing GuixSD using the official installation image.  If you're
using a custom image, or if you're using an installed system built from
lightweight-desktop.scm or something else, then the instructions may not
apply.  I think that's appropriate.

Once a user installs whatever system they want to use, it's partially up
to them to understand how to use it.  For example, we don't fully
document all the features of GNOME just because we package it as a
desktop environment.  I think the same goes for tools like nmtui.  If a
user wants to use it, they will figure out how to use it.  The various
methods for network management are described in the manual (see: "(guix)
Networking Services").  I don't feel like there are any egregious
omissions related to networking or nmtui in particular.

If there is a common problem that people trip over during the official
installation process, then it might be a different story.  However, it
doesn't sound like that's the case.  Am I missing something?

-- 
Chris

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: On network management and documenting nmcli

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 507 bytes --]


You are very true, and while the manual hints at
lightweight-desktop.scm, it does not go any further with respect to
giving an outlook of what to expect from it: which services, which
programs, etc.

With little Scheme code the experienced users can investigate that by
themselves, but it's not quite obvious for newcomers.

If not only for nmcli, I would suggest we document more those
pre-defined profiles for the sake of making GuixSD more approachable.

--
Pierre Neidhardt

Every path has its puddle.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: On network management and documenting nmcli

[swedebugia]

On 2018-05-13 21:21, Pierre Neidhardt wrote:
> You are very true, and while the manual hints at
> lightweight-desktop.scm, it does not go any further with respect to
> giving an outlook of what to expect from it: which services, which
> programs, etc.
>
> With little Scheme code the experienced users can investigate that by
> themselves, but it's not quite obvious for newcomers.
>
> If not only for nmcli, I would suggest we document more those
> pre-defined profiles for the sake of making GuixSD more approachable.
I agree.

Here we could choose between just listing them in the manual which 
increases the work on updating the manual when we change the default 
profiles or
Giving the newcomers the means to see for themselves what 
programs/services they contain. This should be done in a way that 
explains more than the name of the service/package does.

Perhaps a new guix command is needed for this e.g.:

% guix show %default-services

getty              | A service that serves tty

cups               | Printing service that enables printing

...
For information about how to remove or add services see Services (info) in the manual.

This command "guix show" could then be hinted at in the example 
configuration files.

---
Swedebugia

Re: On network management and documenting nmcli

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 180 bytes --]


swedebugia <swedebugia@riseup.net> writes:

> Perhaps a new guix command is needed for this e.g.:
>
> % guix show %default-services

I like this!

-- 
Pierre Neidhardt

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: On network management and documenting nmcli

[Ludovic Courtès]

Hello,

swedebugia <swedebugia@riseup.net> skribis:

> Perhaps a new guix command is needed for this e.g.:
>
> % guix show %default-services
>
> getty              | A service that serves tty
>
> cups               | Printing service that enables printing

‘guix system search’ should help a bit, but it doesn’t show the value of
‘%default-services’ currently.

If you’re using Emacs, the latest version of Emacs-Guix has this new
‘guix-default-services’ command that does exactly what you’re
suggesting.

HTH!

Ludo’.

Re: On network management and documenting nmcli

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 547 bytes --]


Ludovic Courtès <ludo@gnu.org> writes:

> If you’re using Emacs, the latest version of Emacs-Guix has this new
> ‘guix-default-services’ command that does exactly what you’re
> suggesting.

It's great but it's not obvious enough for newcomers in my opinion.

We need something in the manual that makes explicit which service is
run, among which which network manager is currently running.

Asking newcomers to install Emacs + Emacs-Guix is too much a stretch in
my opinion (as much as I love it!).

-- 
Pierre Neidhardt

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: On network management and documenting nmcli

[swedebugia]

[-- Attachment #1: Type: text/plain, Size: 1109 bytes --]



On May 23, 2018 5:45:53 PM GMT+02:00, Pierre Neidhardt <ambrevar@gmail.com> wrote:
>
>Ludovic Courtès <ludo@gnu.org> writes:
>
>> If you’re using Emacs, the latest version of Emacs-Guix has this new
>> ‘guix-default-services’ command that does exactly what you’re
>> suggesting.
>
>It's great but it's not obvious enough for newcomers in my opinion.
>
>We need something in the manual that makes explicit which service is
>run, among which which network manager is currently running.
>
>Asking newcomers to install Emacs + Emacs-Guix is too much a stretch in
>my opinion (as much as I love it!).

Agreed.

Emacs-Guix is a frontend in my opinion. 
We should make sure that everything it provides is possible on the command line as well.

I would like to try to prepare a patch but this might be a little too challenging for me atm. to implement. (without guidance).

Maybe a general command to query the current running system configuration is what we want and this listing of running services (and default services) is a subset of what it provides.
-- 
Cheers Swedebugia 

[-- Attachment #2: Type: text/html, Size: 1288 bytes --]

Re: On network management and documenting nmcli

[Ludovic Courtès]

Pierre Neidhardt <ambrevar@gmail.com> skribis:

> Ludovic Courtès <ludo@gnu.org> writes:
>
>> If you’re using Emacs, the latest version of Emacs-Guix has this new
>> ‘guix-default-services’ command that does exactly what you’re
>> suggesting.
>
> It's great but it's not obvious enough for newcomers in my opinion.

Sure.  So there’s ‘guix system search’ and ‘guix system extension-graph’
which can help visualize what’s going on.

Perhaps we need another command, like ‘guix system show’, which would
list the services used by a particular config?  Thoughts?

Ludo’.

Re: On network management and documenting nmcli

[Pierre Neidhardt]

[-- Attachment #1: Type: text/plain, Size: 468 bytes --]


Ludovic Courtès <ludo@gnu.org> writes:

> Perhaps we need another command, like ‘guix system show’, which would
> list the services used by a particular config?  Thoughts?

I like it, I think it's more relevant in terms of user interface than
what Swedebugia suggest with 'guix show %desktop-services', because in
the latter case the user must already know the variable, and it does not
tell anything about the current system.

-- 
Pierre Neidhardt

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]