Bug#863496: debian-handbook: add a wireless configuration section

2017-07-04 Thread Matthew Donnelly
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

2017-05-27 Thread Matthew Donnelly
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