[pkg-wpa-devel] Bug#513194: Bug#513194: wpasupplicant: Please document wpa-* interface

[Stefan Lippers-Hollmann]

Hi

On Wednesday 06 July 2011, Erik Saule wrote:
> > > The existence of wpa-* interface are mentionned NOWHERE where we might
> > > find some relevant information, despite I looked in many places:
> > > ifconfig(8), ifup(8), interfaces(5), wpa_supplicant(8),
> > > wpa_supplicant.conf(5) (which only provide exemples and no actuall
> > > manual) or wireless(7).
> > 
> > Besides manpages, /usr/share/doc/<packagename>/ is the canonical 
> > location for package documentation and usage examples. I think
> > /usr/share/doc/wpasupplicant/README.Debian.gz in particular, combined
> > with refinements in the other files, will answer your questions.
> > 
> > wpa_supplicant.conf(5) explicitly refers to 
> > /usr/share/doc/<packagename>/ as well.
> 
> I see what you mean, I missed that reference while looking for more
> information on wpa_supplicant.conf.
[...]
> > What information are you missing from /usr/share/doc/wpasupplicant/ and
> > wpasupplicant's manpages? Normally both ifupdown integration and even 
> > more exotic configuration options should be explained therein.
> 
> I believe the information I was missing from the manpages of both
> wpa_supplicant or the more generic canonical ifconfig(8) and ifup(8)
> or even wireless(7) is the existence of the feature. The only place
> where the wpa-* configuration is provided is inside

It may make sense to add a short stanza, hinting towards 
/usr/share/doc/wpasupplicant/ to interfaces(5), indeed.

> /usr/share/doc/wpasupplicant/. And existence of that feature is
> provided in no other place where one would expect to find it such as
> the man of wireless, the (non existant) man of ifupdown or its
> /usr/share/doc/<packagename>/
> 
> The debian reference manual quickly mention the use of wpa- to
> configure a given network but gives no hint at the existence of the
> roaming feature [1].

I've given a short overview for roaming recently at 
http://lists.debian.org/debian-devel/2011/04/msg00184.html
of course, I don't expect anyone to find that particular mail.

All of the wpa_supplicant.conf examples/ syntax can be used there, 
including pretty complex IEEE80211X configurations involving 
certificates and different encryption algorithms. With all regular
wireless networks preconfigured, and maybe augmented by wpa_gui[1], the
roaming feature can handle pretty much all wireless situations 
transparently.

> tldr; the documentation in /usr/share/doc/wpasupplicant
> /usr/share/doc/wpasupplicant/README.Debian.gz provides a reasonnable
> documentation of the wpa-* hooks to ifupdown but you basically have to
> stumble on the feature to find it since it is mentionned or referenced
> nowhere.
> 
> [1] http://www.debian.org/doc/manuals/debian-reference/ch05.en.html#_the_basic_network_configuration_with_ifupdown_legacy

Regards
	Stefan Lippers-Hollmann

[1]	for wpa_gui to be really useful, you need to be member of the 
	system group defined by ctrl_interface_group in wpa_supplicant.conf.