[gentoo-commits] proj/netifrc:master commit in: doc/

[Robin H. Johnson]

commit:     51a7c4fae619a05b8f179f5f03b3e8a556df7205
Author:     Robin H. Johnson <robbat2 <AT> gentoo <DOT> org>
AuthorDate: Tue Jun  2 21:35:31 2020 +0000
Commit:     Robin H. Johnson <robbat2 <AT> gentoo <DOT> org>
CommitDate: Tue Jun  2 21:35:31 2020 +0000
URL:        https://gitweb.gentoo.org/proj/netifrc.git/commit/?id=51a7c4fa

doc/net.example.Linux: document !wireless better

Users that used layer2 wireless configuration external to netifrc and
had previously configured netifrc with:
`modules="!iwconfig !wpa_supplicant"`
were surprised by the introduction of the iw & iwd modules, because the
modules tries to auto-configure the wireless interfaces.

Document that `modules="!wireless"` is a better configuration knob for
this situation.

Bug: https://bugs.gentoo.org/717226
Signed-off-by: Robin H. Johnson <robbat2 <AT> gentoo.org>

 doc/net.example.Linux.in | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/doc/net.example.Linux.in b/doc/net.example.Linux.in
index 53d9e84..4fc603b 100644
--- a/doc/net.example.Linux.in
+++ b/doc/net.example.Linux.in
@@ -43,8 +43,20 @@
 # You can also specify which modules not to use - for example you may be
 # using a supplicant or linux-wlan-ng to control wireless configuration but
 # you still want to configure network settings per SSID associated with.
-#modules="!iwconfig !wpa_supplicant"
-# IMPORTANT: If you need the above, please disable modules in that order
+#
+# A common case here may be using hostapd or other external configuration of
+# the wireless hardware at layer 2, but leaving netifrc to configure the layer
+# 3 networking
+#
+# Best practice for this situation is to disable ALL netifrc wireless modules:
+#modules="!wireless"
+#
+# This supersedes older cases where each module was disabled seperately:
+# If new modules are introduced that provide wireless support, they may be used
+# automatically otherwise, causing situations like
+# https://bugs.gentoo.org/717226
+# Do not use a line like this anymore:
+#modules="!iwconfig !wpa_supplicant !iw !iwd"
 
 
 ##############################################################################
@@ -435,9 +447,8 @@
 # won't have associated then)
 
 # If you're using anything else to configure wireless on your interface AND
-# you have installed wpa_supplicant, you need to disable wpa_supplicant
-#modules="!iwconfig !wpa_supplicant"
-#or
+# you have installed wpa_supplicant, you need to disable wpa_supplicant.
+# Please see the note about hostapd in the MODULES section.
 #modules="!wireless"
 
 ##############################################################################