On Sat, Nov 09, 2019 at 02:58:33PM +0200, Stefan Sperling wrote:
> On Fri, Nov 08, 2019 at 09:37:15AM -0700, Theo de Raadt wrote:
> > Stefan Sperling <[email protected]> wrote:
> >
> > > .Cm join .
> > > .It Cm -nwid
> > > -Set the NWID to the empty string to allow the interface to connect
> > > -to any available access point.
> > > +Clear the currently configured network ID.
> >
> >
> > I don't understand. You are assuming that sentence will have obvious
> > consequences for users?
>
> Well there is a lack of precision all over the existing documentation.
> Here is an attempt at making the wording more clear, across several commands.
>
> This documents behaviour which results from commits I have made up until
> this morning plus the diff which started this discussion.
>
hi stefan. i like your diff. i'll inline some minor comments:
> diff refs/heads/master refs/heads/no-assoc-any
> blob - 79a5adcd2197d91d9780f29a2c97a091b9177389
> blob + b72de717651a63917a966e65a5165db47a9c8347
> --- sbin/ifconfig/ifconfig.8
> +++ sbin/ifconfig/ifconfig.8
> @@ -962,43 +962,78 @@ show the list of channels supported by the device.
> Unset the desired channel.
> It doesn't affect the channel to be created for IBSS or Host AP mode.
> .It Cm join Ar id
> -Add the network with NWID/ESSID
> +Add the network with ESSID
> .Ar id
> -to the list of auto-join networks.
> -Information about such networks is retained,
> -such that configured interfaces can automatically switch to such networks
> -as necessary.
> -Note that
> +to the
> .Cm join
> -does not represent a complete "wireless profile" as only the
> -.Cm wpakey , nwkey ,
> -and
> -.Cm nwid
> -parameters are retained.
> -IEEE802.11 mode (11a/11b/11g/11n) and channel parameters are not retained,
> -so should not be included.
> +list.
> +The interface will automatically attempt to connect to networks on this
> +list if they are found during a scan.
> .Pp
> The
> .Ar id
> can either be any text string up to 32 characters in length,
> or a series of hexadecimal digits up to 64 digits.
> -Any necessary
> -.Cm wpakey
> +If
> +.Ar id
> +is the empty string
> +.Qq
i think .Pq Qq will be clearer - it marks up as: ("")
> +and none of the networks on the
> +.Cm join
> +list are found during a scan, the interface may automatically
i think "will" is clearer than "may" here
> +connect to any available networks, provided they do not require
> +WEP or WPA authentication.
> +.Pp
> +Apart from the
> +.Ar id
i would stick a " ," after "id"
> +the
> +.Cm join
> +list will record
> +.Cm wpakey ,
> +.Cm wpaprotos ,
> or
> .Cm nwkey
> -arguments should be specified on the same line.
> -The empty string allows the interface to automatically connect to any
> -available access points if no known access points are found.
> -May not be used with
> -.Cm nwid .
> +parameters for the network, provided they are passed in the same invocation
> of
> +.Nm .
> +Because multiple access points may exist in a given network, the
> +.Cm mode
> +(11a/11b/11g/11n),
> +.Cm chan ,
> +and
> +.Cm bssid
> +parameters cannot be stored with
> +.Cm join .
> +However, they may be used separately to force the selection of a
> +particular access point when the automatic access point selection
> +turns out to be suboptimal.
> +.Pp
> +.Cm join
> +and
> +.Cm nwid
> +cannot be used together in the same invocation of
> +.Nm .
> .It Cm -join Ar id
> -Remove the network with NWID
> -.Ar id ,
> -from the list of auto-join networks.
> +Remove the network with ESSID
> +.Ar id
> +from the
> +.Cm join
> +list and disconnect the interface from the access point if it is currently
> +connected to this network.
> +The interface will keep scanning for access points as long as it remains
> +marked as
> +.Dq up .
> +A new connection will be established either if a network on the
> +.Cm join
> +list is found during the scan, or if a network ID is configured with
the comma above can go
> +.Cm nwid .
> .It Cm joinlist
> -Show the list of currently configured auto-join networks.
> +Show the list of networks stored on the
> +.Cm join
> +list.
> .It Cm -joinlist
> -Remove all networks in the list of auto-join networks.
> +Remove all networks from the
> +.Cm join
> +list.
> .It Cm nwflag Ar flag
> Set specified flag.
> The flag name can be:
> @@ -1040,17 +1075,35 @@ and
> .It Cm -nwflag Ar flag
> Remove specified flag.
> .It Cm nwid Ar id
> -Connect to the network with NWID
> +Connect to the network with NWID/ESSID
> .Ar id .
> -Unlike auto-join networks,
> -information about the network is not retained.
> -The empty string allows the interface to connect to any available
> -access points.
> -May not be used with
> -.Cm join .
> +Unlike
> +.Cm join ,
> +the
> +.Cm nwid
> +option only allows one network to be configured at a time.
> +The
> +.Cm nwid
> +option may not be used together with
> +.Cm join
> +in the same invocation of
> +.Nm
> +but may be used to momentarily override the automatic selection of
> +networks stored in the
> +.Cm join
> +list.
> .It Cm -nwid
> -Set the NWID to the empty string to allow the interface to connect
> -to any available access point.
> +Clear the network ID configured with
> +.Cm nwid ,
this comma can go too
> +and disconnect the interface from the access point if it is currently
> +connected to this network.
> +The interface will keep scanning for access points as long as it remains
> +marked as
> +.Dq up .
> +A new connection will be established either if a network on the
> +.Cm join
> +list is found during the scan, or if a network ID is configured with
i would zap this comma too.
> +.Cm nwid .
> .It Cm nwkey Ar key
> Enable WEP encryption using the specified
> .Ar key .
> @@ -1117,6 +1170,18 @@ If an access point cannot be selected due to incompati
> interface configuration,
> .Nm
> indicates mismatching configuration items with an exclamation mark.
> +.Pp
> +Because the list of access points is continuously updated while a scan
> +is in progress,
> +.Cm scan
> +may sometimes show incomplete scan results.
> +.Pp
> +Some interfaces support scanning in the background while remaining
> +associated to the current access point.
i wonder if the individual driver pages which do support this should say
so? otherwise how will anyone know?
> +The superuser may use
> +.Cm scan
> +to trigger a background scan while associated, which will update the scan
> +result list and also trigger a search for a better access point to roam to.
> .It Cm wpa
> Enable Wi-Fi Protected Access.
> WPA is a Wi-Fi Alliance protocol based on the IEEE 802.11i standard.
>
thanks for doing this!
jmc
