manual page should explain what is meant by Wireless SSID Profiles and how they are handled

[perkelix]

As someone pointed out in an unrelated bug report downstream at Debian, the manual page doesn't say what Wireless SSID Profiles are or how dhcpcd manages them. The answer is documented at https://wiki.archlinux.org/title/Dhcpcd#10-wpa_supplicant

[rsmarples]

from dhcpd.conf.5

ssid ssid
Subsequent options are only parsed for this wireless ssid.

It's documented in the same way as interface and arp profile options. Is this not good enough?

All the wpa_supplicant hook does is start/stop wpa_supplicant - nothing more, nothing less.
It's not installed by default because this is better managed elsewhere these days and only exists for less capable systems.

[perkelix]

It doesn't explain how dhcpcd interacts with wpasupplicant. The config option is for an SSID-specific block of options, but the above Arch Linux documentation suggests that dhcpcd really is matching with a PHY-specific wpasupplicant configuration instead or, if not found, falls back on the default wpasupplicant configuration.

[rsmarples]

There is no relationship between the ssid dhcpcd option and the wpa supplicant hook script.

Since I added the -M option to upstream wpa supplicant, my personal need and infact any need for the hook script is now gone. I was surprised when some people objected to me removing the hook script, so it just lives as an example.

[perkelix]

A new upstream version that supports the -M option seemingly isn't widely distributed: due to regressions in 2.11, some distributions still ship with 2.10.

Anyhow, whatever seems self-evident to you isn't to someone trying to understand where to put the SSID and PSK password they intend on passing via a specifc interface or, if that's expected to be handled by a separate config file, what is the expected filename convention.

[rsmarples]

https://w1.fi/cgit/hostap/commit/wpa_supplicant/wpa_supplicant.c?id=2e997eece5776eca0a99d53893e343539f9f8eb2

I’m pretty sure there has been a release in the past 10 years.

[rsmarples]

So the ssid option in dhcpcd is an instruction of what dhcpcd should do when it connects to that ssid.

There is no support for setting any wireless options in dhcpcd.

dhcpcd-ui project communicates with wpa supplicant directly and will configure its config file for ssid and psk. But dhcpcd itself plays no part in that.

[perkelix]

https://w1.fi/cgit/hostap/commit/wpa_supplicant/wpa_supplicant.c?id=2e997eece5776eca0a99d53893e343539f9f8eb2

I’m pretty sure there has been a release in the past 10 years.

Thanks. Here's what Debian has:

$ sudo wpa_supplicant --help
wpa_supplicant: invalid option -- '-'
wpa_supplicant v2.10
Copyright (c) 2003-2022, Jouni Malinen <j@w1.fi> and contributors

This software may be distributed under the terms of the BSD license.
See README for more details.

This product includes software developed by the OpenSSL Project
for use in the OpenSSL Toolkit (http://www.openssl.org/)

usage:
  wpa_supplicant [-BddhKLqqstuvW] [-P<pid file>] [-g<global ctrl>] \
        [-G<group>] \
        -i<ifname> -c<config file> [-C<ctrl>] [-D<driver>] [-p<driver_param>] \
        [-b<br_ifname>] [-e<entropy file>] [-f<debug file>] \
        [-o<override driver>] [-O<override ctrl>] \
        [-N -i<ifname> -c<conf> [-C<ctrl>] [-D<driver>] \
        [-m<P2P Device config file>] \
        [-p<driver_param>] [-b<br_ifname>] [-I<config file>] ...]

drivers:
  nl80211 = Linux nl80211/cfg80211
  wext = Linux wireless extensions (generic)
  wired = Wired Ethernet driver
  macsec_linux = MACsec Ethernet driver for Linux
  none = no driver (RADIUS server/WPS ER)
options:
  -b = optional bridge interface name
  -B = run daemon in the background
  -c = Configuration file
  -C = ctrl_interface parameter (only used if -c is not)
  -d = increase debugging verbosity (-dd even more)
  -D = driver name (can be multiple drivers: nl80211,wext)
  -e = entropy file
  -f = log output to debug file instead of stdout
  -g = global ctrl_interface
  -G = global ctrl_interface group
  -h = show this help text
  -i = interface name
  -I = additional configuration file
  -K = include keys (passwords, etc.) in debug output
  -L = show license (BSD)
  -m = Configuration file for the P2P Device interface
  -N = start describing new interface
  -o = override driver parameter for new interfaces
  -O = override ctrl_interface parameter for new interfaces
  -p = driver parameters
  -P = PID file
  -q = decrease debugging verbosity (-qq even less)
  -s = log output to syslog instead of stdout
  -t = include timestamp in debug messages
  -T = record to Linux tracing in addition to logging
       (records all messages regardless of debug verbosity)
  -u = enable DBus control interface
  -v = show version
  -W = wait for a control interface monitor before starting
example:
  wpa_supplicant -Dnl80211 -iwlan0 -c/etc/wpa_supplicant.conf

No -M option in sight.

[rsmarples]

So that sounds like a Debian issue?
Gentoo for example has had it enabled for a long time:
https://gitweb.gentoo.org/repo/gentoo.git/tree/net-wireless/wpa_supplicant/wpa_supplicant-2.10-r6.ebuild#n142

[rsmarples]

To be clear, the wpa_supplicant -M option with the parameter of "*" to match all interfaces is the equivalent of the wpa_supplicant hook script here.

[perkelix]

So that sounds like a Debian issue?

Possibly. A quick googling shows that other distributions ship with an even more spartan list of enabled command line options.

Either way, expecting people to know that dhcpcd expects wpasupplicant to support -M, or otherwise requires the optional script, remains a problem.

[rsmarples]

No it doesn’t. dhcpcd doesn’t care about wpa supplicant or any other userland mechanism of link management.

Debian for example encourages ifupdown which favours explicit interface enablement and could start/stop wpa supplicant here without the need for the -M switch.

[rsmarples]

Is there anything to do here or can we close this bug?

[perkelix]

I still think that the manual page should say that dhcpcd will request a similarily-named wpa_supplicant configuration using wpa_supplicant's -M flag. Comments in the exit script should state that the script is deprecated since wpa_supplicant has supported the -M flag used by dhcpcd's ssid profiles since version XX. Conversely, the script should no longer ship by default.

[rsmarples]

Eh?

dhcpcd does not talk to wpa_supplicant, nor hint at what configuration it should use, nor get any configuration from it.
dhcpcd only looks at the SSID the interface is connected to (this is a kernel call) and then picks a dhcpcd profile to match it.

wpa_supplicant's -M flag is so that it can work 100% independently from dhcpcd's hook scripts.
The hook script only started or stopped wpa_supplicant on the interface. Nothing more. It did not influence in any way which SSID wpa_supplicant should connect to.

The -M flag tells wpa_supplicant to start on the interfaces which match a pattern. Nothing more. No configuration is expressed or implied.

If any documentation needs to be done for this, it should be done in a Debian man page or a wiki - How to configure wpa_supplicant to start automatically.

[rsmarples]

Or it put it in more simple terms, it's like asking the drivers manual for your car to state how the road ahead should be laid.

[perkelix]

Given how your above explanations make the purpose and mechanics of ssid profiles even more confusing than before for this downstream maintainer, you might wanna ponder how drastically more opaque the matter is for mere users asking me about this.

[rsmarples]

$ ifconfig iwm0
iwm0: flags=0x8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
        ssid "Obi-LAN Kenobi" nwkey *****
        powersave off
        bssid de:b3:70:dc:ab:36 chan 100
        address: 7c:5c:f8:59:7b:b2
        media: IEEE802.11 autoselect (OFDM54 mode 11a)
        status: active

dhcpcd.conf.5

     interface interface
             Subsequent options are only parsed for this interface.

     ssid ssid
             Subsequent options are only parsed for this wireless ssid.

dhcpcd.conf

interface iwm0
    static ip_address=10.1.2.3/24

ssid "Obi-LAN Kenobi"
    static ip_address=192.168.1.2/24

ssid "May the 4th be with you"
    static ip_address=172.16.5.5/24

IF the interface name is iwm0, then give it a static ip address of 10.1.2.3/24
IF the ssid we are connected to for any interface is "Obi-LAN Kenobi" then give it a static ip address of 192.168.1.2/24
IF the ssid we are connected to for any interface is "May the 4th be with you" then give it a static ip address of 172.16.5.5/24

Which ssid we connect to is not the decision of dhcpcd, that's up to something else - just in the same way dhcpcd does not set or control the interface name.

Does this help?

[perkelix]

Yes. The above dhcpcd.conf example should be added to the manual page, along with the explanation below it, to emphasize that it merely defines the network configuration performed on the interface (or all/any, if none specified?), but authentication to the SSID remains the responsibility of wpa_supplicant.

One point remains unclear: Does dhcpcd parse the content of /etc/wpa_supplicant/ for files that match that SSID or interface name? If yes, according to which filename syntax? This should also be explained in the manual page.

[rsmarples]

Yes. The above dhcpcd.conf example should be added to the manual page, along with the explanation below it, to emphasize that it merely defines the network configuration performed on the interface (or all/any, if none specified?), but authentication to the SSID remains the responsibility of wpa_supplicant.

Could be wpa_supplicant, iwd, OpenBSD kernel wpa, NetBSD iwconfig, FreeBSD ifconfig. There are a lot of tools in this area that do the same job.

One point remains unclear: Does dhcpcd parse the content of /etc/wpa_supplicant/ for files that match that SSID or interface name? If yes, according to which filename syntax? This should also be explained in the manual page.

No. dhcpcd talks only to the kernel. On Linux dhcpcd listens to udev as well for interface readyness so udev can rename interfaces without dhcpcd getting in the way.

On Linux we use the convoluted netlink command NL80211_CMD_GET_SCAN to work out which SSID the interface is connected to.
https://github.com/NetworkConfiguration/dhcpcd/blob/master/src/if-linux.c#L1525

[perkelix]

Thanks That's somewhat more clear. I made the following change in Debian:

dhcpcd (1:10.2.2-6) experimental; urgency=medium

  * [control]
    + dhcpcd: Recommends: wpasupplicant | iwd | wireless-tools
      dhcpcd uses netlink's NL80211_CMD_GET_SCAN to determine the SSID profile
      in /etc/dhcpcd.conf it should use. This remains agnostic to what tool is
      used to configure the radio and authenticate to the AccessPoint.

I think that the manual page could state something similar to clarify how dhcpcd uses the SSID profile.