Hello, On Tue, 04 Jul 2017, Matthew Donnelly wrote: > Thanks! Here is the patch. Let me know if I need to change anything.
I'm doing a review since I'm about to continue to work on the stretch update. First I usually prefer a unified diff and you should be really using "git format-patch" so that your changes are made on top of the git repository and so that I can quickly merge your work. I'll mention the problems only on the first occurrence but they often have to be fixed in multiple places in the text. 734a735,1077 > <section id="sect.wireless-client"> > <title>Wireless Client Configuration</title> > > <para>Wireless Fidelity (WiFi) enable a Debian machine to connect > to a wireless access point (AP) such as a router. In Debian, there > are two ways of connecting to an AP. The first is manual configuration. Please always use "access point" and not the abbreviation. If you say there are two ways, then you need to give them both immediately. And then explain that we go into more details on the first way which is "manually installing". > <para>In order for a wireless device to be detected by Debian, the > kernel must have support for the device and the correct firmware > needs to be installed. To determine if the wireless interface is > detected, run lsusb for a usb based wireless adapter or lspci for > a pci based wireless adapter. <command>lsusb</command> and <command>lspci</command> > </para> > > <example id="example.wireless-client-lsusb"> > <title>Example lsusb output</title> > <programlisting> Please use <screen> for shell sessions. You don't need to use an example tag, you could just integrate the <screen> directly betweez two para and make the relationship obvious by ending the former para with ":" (hence implying that below is an example illustrating what got just stated). > root@~-> lsusb The root shell is always shown with a simple "#". You need <userinput>lsusb</userinput> within a <screen>. > ... I use "[...]" for skipped content. > Bus 001 Device 002: ID 148f:5370 Ralink Technology, Corp. RT5370 Wireless > Adapter > ... > <para>The wireless interface should be listed in the output of ip > addr.</para> <command>ip addr</command> > <example id="example.wireless-client-ipaddr"> > <title>Example ip addr output</title> > <programlisting> > root@~-> ip addr > 1: wlan0: <BROADCAST,MULTICAST> mtu 1500 qdisc mq state DOWN group > default qlen 1000 > link/ether xx:xx:xx:xx:xx:xx brd ff:ff:ff:ff:ff:ff > </programlisting> > </example> Again, you don't need the surrounding <example>, go straight to the <screen> (not <programlisting>). All other previous points also apply. > > <para>If your wireless device is not listed in either lsusb/lspci > or ip addr, then the device is not being detected by the kernel. > Most likely, the kernel does not have support compiled in for the > wireless device. To enable support, you will need to compile a custom > kernel. This is not "most likely" as the Debian kernel builds all the existing modules. Either the kernel is too old (try kernel in stable-backports) or the hardware is not supported by the mainline kernel (there may be external drivers available). > Some wireless chipsets > (such as for the RT5370 device in the example output) require closed > source firmware. To install this firmware, enable the non-free > repository in /etc/apt/sources.list, run apt-get update, and install > the firmware required. For the specific RT5370 chipset in the example, > the firmware-ralink package is needed. To find information about your > specific wireless chipset, see https://wiki.debian.org/WiFi. Please include an « (see <xref linkend="sect.apt-sources.list"/>) » when you refer to "enable the non-free repository". To identify the correct firmware package you can instruct the user to try a search on the name of his wireless chipset: $ apt search RT5370 Better, you can rely on isenkram-autoinstall-firmware to do everything for you (from the isenkram package). > <para>Now that the wireless interface is detected by the kernel, > it can be connected to an AP. As an example, "wlan0" will be the > wireless interface name, "AP" will be the name of the AP to connect > to, "qwert" will be the password for the WEP AP and "password" > will be the password for the WPA AP. Adjust accordingly. > </para> Use <literal> for sample values. Use realistic values that could be taken out of the Falcot use-case that we follow in the book. Name the essid "falcotsa" for example, > > <para>Set the wireless interface up</para> > <example id="example.wireless-client-interface-up"> > <title>Set interface up</title> > <programlisting> > root@~-> ip link set wlan0 up > </programlisting> > </example> Drop this example and use <command>ip link set wlan0 up</command> directly in the flow of the main text (always do taht for single line samples without any useful output). > > <para>An AP can require one of three authentication methods: open, > WEP, and WPA. Open authentication require no authentication at all; > any client within range can connect to an open AP. > WEP encryption is obsolete and can be broken in a matter of minutes. s/broken/cracked/ > While WEP should never be used to secure an AP, it is included here > for completeness. WPA is the prefered method of authentication for an > AP. > </para> > > <example id="example.wireless-client-open-setup"> > <title>For open authentication</title> > <programlisting> > root@~-> iwconfig wlan0 essid AP > </programlisting> > </example> > > <example id="example.wireless-client-WEP-setup"> > <title>For WEP authentication</title> > <programlisting> > root@~-> iwconfig wlan0 essid AP key s:qwert > </programlisting> > </example> > > <example id="example.wireless-client-WPA-setup"> > <title>For WPA authentication</title> > <programlisting> > root@~-> #Generate a configuration with > root@~-> wpa_passphrase AP password > /etc/wpa_supplicant.conf > root@~-> #Connect to the access point with > root@~-> wpa_supplicant -B -D wext -i wlan0 -c /etc/wpa_supplicant.conf > root@~-> #This may generate some warnings that can be ignored for now. > </programlisting> > </example> > > <para>The wireless interface now needs to obtain an ip address.</para> >From here one, the explanations are rather generic and should probably be moved in another section covering manual configuration of any network interface. Also we should probably cover first the use of /etc/network/interfaces before the manual installation. All in all, I have the feeling that you are covering too much in this section. > <para>A wireless interface can also be configured using > /etc/network/interfaces. This method is simpler than manual > configuration And we already cover this in https://debian-handbook.info/browse/stable/sect.network-config.html#sect.interface-ethernet so you should probably only refer to the supplementary options to add when you use a WLAN interface instead of wire ethernet. And not give full blown examples. > <para>Finally, restart the network</para> > <example id="example.wireless-client-restart"> > <title>Restart the network</title> > <programlisting> > root@~-> systemctl restart network Are you sure of this invocation? ifupdown provides the "networking" unit, not a "network" one. And this should be inlined in a sentence, not an <example>. > <section id="sect.wireless-AP"> > <title>Wireless Access Point Configuration</title> [...] > <para>Start the AP.</para> > <example id="example.wireless-AP-start"> > <title>Start the AP</title> > <programlisting> > root@~-> hostapd /etc/hostapd/hostapd.conf > </programlisting> > </example> hostapd has an init script so I would suggest to document how to use that one by editing /etc/default/hostapd. > <para>Finally, assign a static IP address so that connected client > can directly connect to the AP.</para> > <example id="example.wireless-AP-static-ip"> > <title>Add static IP</title> > <programlisting> > root@~-> ip addr add 192.168.1.1/24 dev wlan0 > </programlisting> > </example> This is not a permanent setting. For everything else you explain how to make it permanent but not here. Why? Cheers, -- Raphaël Hertzog ◈ Debian Developer Support Debian LTS: https://www.freexian.com/services/debian-lts.html Learn to master Debian: https://debian-handbook.info/get/
