Bug#863496: debian-handbook: add a wireless configuration section
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 > > Wireless Client Configuration > > 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". > 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. lsusb and lspci > > > > Example lsusb output > Please use for shell sessions. You don't need to use an example tag, you could just integrate the 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 lsusb within a . > ... I use "[...]" for skipped content. > Bus 001 Device 002: ID 148f:5370 Ralink Technology, Corp. RT5370 Wireless > Adapter > ... > The wireless interface should be listed in the output of ip > addr. ip addr > > Example ip addr output > > 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 > > Again, you don't need the surrounding , go straight to the (not ). All other previous points also apply. > > 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 ) » 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). > 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. > Use 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, > > Set the wireless interface up > > Set interface up > > root@~-> ip link set wlan0 up > > Drop this example and use ip link set wlan0 up directly in the flow of the main text (always do taht for single line samples without any useful output). > > 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
Bug#863496: debian-handbook: add a wireless configuration section
Thanks! Here is the patch. Let me know if I need to change anything. 734a735,1077 > > Wireless Client Configuration > > 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. > While manually configuring a wireless interface involves more work and > resets after every reboot, it works on all Linux distributions and > is important to know when troubleshooting wireless issues. Manually > configuring a wireless client can be broken into three steps: > ensure the wireless interface is detected and functional, connect > and authenticate to the AP, and obtain an IP address. > > > 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. > > > > Example lsusb output > > root@~-> lsusb > ... > Bus 001 Device 002: ID 148f:5370 Ralink Technology, Corp. RT5370 Wireless Adapter > ... > > > > The wireless interface should be listed in the output of ip addr. > > Example ip addr output > > 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 > > > > 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. In the kernel configuration menu, go to Device Drivers -> > Network Device Support -> Wirless LAN and enable the drivers needed > for your wireless device. There may also be wireless drivers in > Device Drivers -> Staging Drivers. 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. > > > 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. > > > Set the wireless interface up > > Set interface up > > root@~-> ip link set wlan0 up > > > > 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. > 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. > > > > For open authentication > > root@~-> iwconfig wlan0 essid AP > > > > > For WEP authentication > > root@~-> iwconfig wlan0 essid AP key s:qwert > > > > > For WPA authentication > > 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. > > > > The wireless interface now needs to obtain an ip address. > > For a static IP address > > root@~-> #Replace 192.168.1.2 with the desired ip address > root@~-> #and /24 with the required netmask. > root@~-> ip addr add 192.168.1.2/24 dev wlan0 > > > > For a DHCP IP address > > root@~-> dhcpcd wlan0 > > > > The client is now connected to the AP. However, the kernel has > not been configured to use this as the default route. To make the > wireless interface the default, execute > > > Set default route > > root@~-> #Replace 192.168.1.1 with the IP address of
Bug#863496: debian-handbook: add a wireless configuration section
Hello, On Sat, 27 May 2017, Matthew Donnelly wrote: > I have been browsing through The Debian Administrator's Handbook and noticed > that there is no section describing how to configure wireless from the command > line. This was a major struggle when I first used Debian, and I would like to > write a section (probably in 8.2 of the handbook) illustrating how to do this. > Any help related to how I should create and submit the patch is welcomed. The sources of the book are available in a git repository: $ git clone https://anonscm.debian.org/git/debian-handbook/debian-handbook.git You can then edit with the docbook files with a plain text editor: $ vim debian-handbook/en-US/08_basic-configuration.xml And send me your patch (generated with "git diff" for example). That said, I can take of this with a small extension to the explanation about ifupdown: For wireless interfaces, you must have the wpasupplicant package, which provides many wpa-* options that can be used in /etc/network/interfaces. Have a look at /usr/share/doc/wpasupplicant/README.Debian.gz for examples and explanations. The most common options are wpa-ssid (which defines the name of the wireless network to join) and wpa-psk (which defines the passphrase or the key protecting the network). iface wlan0 inet dhcp wpa-ssid MyNetWork wpa-psk plaintextsecret Were you looking for more than that? 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/
Bug#863496: debian-handbook: add a wireless configuration section
Missed that line wrap ... Dear Maintainer, I apologize if this is out of place or I am missing something; this is my first contribution to open source. I have been browsing through The Debian Administrator's Handbook and noticed that there is no section describing how to configure wireless from the command line. This was a major struggle when I first used Debian, and I would like to write a section (probably in 8.2 of the handbook) illustrating how to do this. Any help related to how I should create and submit the patch is welcomed. Thank You, Matthew D
Bug#863496: debian-handbook: add a wireless configuration section
Package: debian-handbook Version: 8.20151209~deb8u1 Severity: wishlist Dear Maintainer, I apologize if this is out of place or I am missing something; this is my first contribution to open source. I have been browsing through The Debian Administrator's Handbook and noticed that there is no section describing how to configure wireless from the command line. This was a major struggle when I first used Debian, and I would like to write a section (probably in 8.2 of the handbook) illustrating how to do this. Any help related to how I should create and submit the patch is welcomed. Thank You, Matthew D -- System Information: Debian Release: 8.8 Architecture: amd64 (x86_64) Kernel: Linux 3.16.0-4-amd64 (SMP w/2 CPU cores) Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8) Shell: /bin/sh linked to /bin/dash Init: systemd (via /run/systemd/system) -- no debconf information
