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