Translation(s): English - French - Italiano - Русский - 简体中文
How to use a WiFi interface
This page describes how to configure a WiFi interface on a Debian system, for use on a network.
Once your wireless device has an interface available (verifiable by running "ip link show"), it is required to be configured to access a network. If you do not have a wireless interface present, please refer to WiFi for information on obtaining a driver, or the necessary firmware for your device.
Wireless network interface configuration requires a backend, generally wpa_supplicant (often in conjunction with ifupdown and other utilities) or IWD. These can be used with connection managers that provide advanced functionality, and an easier way to configure them. Examples of these would generally be NetworkManager,ConnMan, systemd-networkd, and Wicd.
The WEP algorithm is insecure and deprecated by WPA. Use of WEP is not recommended and is not covered within this document.
Contents
Automatic
NetworkManager
For the average desktop user, the easiest way to configure your network is to install the GUI frontend for NetworkManager that corresponds to your desktop. NetworkManager itself is a frontend for different network backends (wpa_supplicant by default) that abstracts away the configuration and simplifies it. Your wireless interface should not be referenced within Debian's /etc/network/interfaces file.
NetworkManager Frontends
NetworkManager on GNOME
As of GNOME 3, integration with NetworkManager is baked into GNOME Shell, and will appear in the settings and as an icon in the top-right of your screen as long as it's running.
Open the "Networks" section of your settings, select your network in the list, enter the password as prompted, and you should be ready to surf the web.
The network-manager-gnome package still exists and provides a systray applet for other desktops, but will not make any difference with GNOME 3.
See the NetworkManager page for frequently asked questions, documentation and support references.
NetworkManager on KDE Plasma
The KDE Plasma task should bring in plasma-nm during system installation without any extra steps being required, and its usage should be intuitive. If you aren't sure how to use it though, or if you installed the desktop manually and might not have brought it in, the following will likely be useful.
Ensure your user account is a member of the netdev group.
Install the plasma-nm package.
- Restart your Plasma session (most easily by logging out and logging back in).
- A new applet (with a traditional "no Wi-Fi signal" icon) will appear in the system tray. Click this icon.
- Neighboring wireless networks with a broadcasted SSID should be listed:
- Click on the desired network's name.
- If the network uses WPA encryption with a password (aka passphrase/pre-shared key), you will be prompted to enter it. After providing, click the "Connect" button.
- The wireless network connection will be activated.
- Click "Connect to Other Wireless Network...".
- Enter the network's name in "Name (ESSID)".
- Tick "Use Encryption" if in use on the network.
- Select the encryption method used (usually "WPA Personal").
- Enter the passphrase/pre-shared key at "Password".
- Select "WPA 1" or "WPA 2" for the protocol version, as used by the network.
- Click the "Connect" button to activate the wireless network connection.
See the NetworkManager page for frequently asked questions, documentation and support references.
NetworkManager on a generic desktop/headless session
If there is no GUI frontend available, the "nmcli" and "nmtui" commands are available as CLI and TUI frontends respectively for NetworkManager.
Troubleshooting & Tips for NetworkManager
WiFi can scan, but not connect using NetworkManager (Debian 9 Stretch)
If you find that your wireless network device can scan, but will not complete connecting, try turning off MAC address randomization.
Write inside /etc/NetworkManager/NetworkManager.conf:
[device] wifi.scan-rand-mac-address=no
After doing this, restart NetworkManager with service NetworkManager restart
Setting up a WiFi hotspot
In recent years, NetworkManager is sophisticated enough to set up a WiFi hotspot that "just works" (i.e. sets up a local private net, with DHCP and IP forwarding). In some desktops, such as KDE Plasma, a button to create a hotspot is visible in the network applet if two separate wireless network interfaces are present. Alternatively, it can be created manually with a command similar to:
nmcli dev wifi hotspot ifname wlp4s0 ssid test password "test1234"
Source: https://unix.stackexchange.com/a/384513
Changing the backend
It's possible to replace wpa_supplicant with IWD in NetworkManager in Debian 10 and newer, though Debian 11 is recommended for the best experience as there are known issues with the old version of IWD present in Debian 10. For more information on how to switch, see NetworkManager/iwd.
IWCtl
While also available as backend for ConnMan, NetworkManager, and systemd-networkd, it's also possible to nearly base your entire networking stack on one codebase with IWD alone. It's an all-in-one wireless client, wireless daemon, and even a DHCP client optionally! At its best, your entire networking stack can be as minimal as IWD + systemd-resolved, and this works wonderfully for many scenarios. It has virtually zero dependencies and uses modern kernel features as often as possible. Anecdotal reports suggest that it's much faster to connect to networks than wpa_supplicant, and has better roaming support, among other perceived improvements.
First, install the iwd package. If you've installed wpasupplicant, either uninstall the package, or stop and disable the wpa_supplicant service with:
systemctl --now disable wpa_supplicant
Then, ensure that the newly-installed IWD service is enabled and running with with:
systemctl --now enable iwd
Network Configuration
If you plan to go the route of using IWD standalone, you should first enable some essential features in IWD's configuration file, which can be found at /etc/iwd/main.conf. Edit this file with root permissions using your favorite editor.
iwd can be configured to configure the network on its own, without requiring external tools or systems to do so. To enable network configuration, add this section to the configuration file:
[General] EnableNetworkConfiguration=true
Static network configuration can be specified in iwd's network configuration files, as documented in man iwd.network and in the iwd wiki. As per man iwd.config, "If no static IP configuration has been provided for a network, iwd will attempt to obtain the dynamic addresses from the network through the built-in DHCP client."
IPv6
To enable IPv6 support, add this section to the configuration file:
[Network] EnableIPv6=true
Note: IPv6 is still somewhat broken as of version 1.19.
Enabling IPv6 can cause segmentation faults upon connection. Upstream believes that this has been fixed by commit d0f00698245a ("dhcp6: Switch to BOUND before LEASE_OBTAINED"), but acknowledges that "IPv6 support in iwd is still somewhat experimental since we still lack support for SLAAC," although "DHCPv6 should be mostly functional."
After making changes to iwd's configuration file, restart the service with "service iwd restart" to have them take effect.
Configuring iwd Via iwctl
Start the IWCtl client by running iwctl as your standard user (not root!), which will start an interactive prompt. You can run help to get a full list of commands here. (If you actually want to prevent non-root users from configuring iwd, see the directions here.)
To connect to a Wi-Fi network in the most typical scenario, first type device list to find the name of your wireless device. We will use wlan0 in this example, but your name may be different, and potentially much longer if your system renames interfaces to a unique name.
After you have the device name, run something like station wlan0 scan to have the device scan for networks. You can then list these networks by running station wlan0 get-networks. After you've found the network you intend to connect to, run station wlan0 connect Router123, replacing Router123 with the name of the network. Put the name of the network in double-quotes if it contains a space. (Note that you can use tab completion to enter the network name, and iwd will even help with the quoting.)
IWCtl will then prompt you for the passphrase. After entering this, IWD will connect to the network, and store it permanently in the /var/lib/iwd directory. After being added in this way, IWD will attempt to auto-connect to the network in the future.
Try running ping 1.1.1.1 to see if you can reach an IP, and then ping gnu.org to see if you can reach a domain. If you can't reach an IP, something's gone horribly wrong when connecting to the network. If you can't reach a domain but you can reach an IP, you'll need to configure your DNS. The simplest way to accomplish that is ...
Setting up DNS resolution for IWD (Simple)
If "EnableNetworkConfiguration=true" is set, you'll also need to configure IWD's name resolving service. It supports systemd-resolved and resolvconf. If unspecified, it uses systemd-resolved. Refer to the IWD.CONFIG(5) page if you care about using resolvconf instead.
If DNS is nonfunctional, you likely need to configure systemd-resolved for use with IWD. Enable and start the systemd-resolved service, if it isn't already, by running:
systemctl enable --now systemd-resolved
Then, symlink /etc/resolv.conf to /run/systemd/resolve/stub-resolv.conf by running:
# ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
That should be enough to get you online. If you want to make changes to your DNS configuration, refer to the /etc/systemd/resolved.conf file, and the associated manpage at RESOLVED.CONF(5)
Debugging and Testing
To help diagnose problems, run iwd manually (as opposed to via systemd) with the debug switch: iwd -d.
Further reading
Keep in mind, this is just covering the most basic of basics for getting online in a completely typical scenario, and it might not apply to you! For more advanced setups, refer to the help output for IWCtl. Documentation on other options for the /etc/iwd/main.conf file can be found in [5/iwd.config|IWD.CONFIG(5)]]. Documentation for the network files in /var/lib/iwd can be found in IWD.NETWORK(5).
Some of the information here was adapted from this lovely blogpost, which has more details and more ideas for how you can configure your own setup: https://insanity.industries/post/simple-networking/
The official iwd documentation is here.
As usual, ?ArchWiki has excellent documentation of iwd usage and configuration.
Wicd
Wicd is not available in Debian 11/Bullseye or newer, due to the deprecation of Python 2.
You must remove network-manager to get wicd to work. Check to see if network-manager is installed and see if, after you installed the driver, your wireless is already working in the notification area of your desktop manager. You may already be good to go.
wicd (Wireless Interface Connection Daemon) is a lightweight alternative to NetworkManager, using wpa_supplicant as a backend. It is environment-independent, making it suitable for all desktop environments, including GNOME, Xfce, LXDE, and Fluxbox. Like NetworkManager, wicd is configured via a graphical interface. Your wireless interface should not be referenced within Debian's /etc/network/interfaces file.
Update the list of available packages and install the wicd package:
# apt update # apt install wicd
Amend /etc/network/interfaces to contain only the following:
# This file describes the network interfaces available on your system # and how to activate them. For more information, see interfaces(5). # The loopback network interface auto lo iface lo inet loopback
Note: as of wheezy it is fine to have your wireless interface in /etc/network/interfaces, but not required. You can set the wireless interface (e.g. wlan0) in the wicd client's preferences.
If not already performed, add your regular user account to the netdev group and reload DBus:
# adduser yourusername netdev # service dbus restart
Start the wicd daemon:
# service wicd start
Start the wicd GUI with your regular user account:
# exit $ wicd-client -n
See also wicd frequently asked questions.
ConnMan
ConnMan is another network frontend designed for embedded devices. Example usage:
# apt install connman $ /usr/sbin/connmanctl connmanctl> enable wifi connmanctl> scan wifi Scan completed for wifi connmanctl> services $SSID wifi_f8d111090ed6_6d617269636f6e5f64655f6d6965726461_managed_psk ... ... connmanctl> agent on Agent registered connmanctl> connect wifi_f8d111090ed6_6d617269636f6e5f64655f6d6965726461_managed_psk Agent RequestInput wifi_f8d111090ed6_6d617269636f6e5f64655f6d6965726461_managed_psk Passphrase = [ Type=psk, Requirement=mandatory, Alternates=[ WPS ] ] WPS = [ Type=wpspin, Requirement=alternate ] Passphrase? $PASS Connected wifi_f8d111090ed6_6d617269636f6e5f64655f6d6965726461_managed_psk connmanctl> quit
After the configuration, connman remembers your SSID selections and reusees them automatically. Don't worry about long HEXes - in client mode TAB auto-completion works both for commands and data.
Manual
Using IWD
While IWD is often a backend for more comprehensive connection managers, it can also be used fully standalone, and is completely distinct from wpa_supplicant. With virtually no extra dependencies, it's one of the lightest and simplest methods for configuring wireless networking. See the IWD section for more information, and view the IWD.NETWORK(5) manpage if you're interested in writing manual connection files for IWD rather than going through IWCtl.
Using ifupdown and wireless-tools
This recipe is for unencrypted (open) wifi networks. It is known to rely only on the limited tooling available in debian-live-standard ISO images for Debian Buster.
Edit /etc/network/interfaces like so -- assuming a network ESSID named Home Network and a network device named wlp2s0:
allow-hotplug wlp2s0
iface wlp2s0 inet dhcp
wireless-essid Home Network(Note the lack of quotation or escaping of spaces in the argument to wireless-essid.)
Using ifupdown and wpasupplicant
These instructions require and make use of ifupdown, iproute2, wpasupplicant (For WPA2 support), iw, and wireless-tools. Ensure you have all of these installed before continuing. You also might be interested in the instructions below that only use ifupdown and wpasupplicant, along with using a more advanced configuration. See #wpasupplicant
Find your wireless interface and bring it up: (NOTE: wlp2s0 is an example, you will need to make sure to use the correct device name for your system)
# ip a # iw dev # ip link set wlp2s0 up
Scan for available networks and get network details (If you already know your wifi network id/ESSID, you can skip this step):
$ su -l # iwlist scan
Now edit /etc/network/interfaces. The required configuration is much dependent on your particular setup. The following example will work for most commonly found WPA/WPA2 networks:
# my wifi device
allow-hotplug wlp2s0
iface wlp2s0 inet dhcp
wpa-ssid ESSID
wpa-psk PASSWORDBring up your interface and verify the connection:
# ifup wlp2s0 # iw wlp2s0 link # ip a
You can manually bring your interface up and down with the ifup and ifdown commands. If you added allow-hotplug wlp2s0 as in the example above, the interface will be brought up automatically at boot.
For further information on available configuration options, see man interfaces, man iw, man wireless and /usr/share/doc/wireless-tools/README.Debian.
WPS
WPS-PBC
Find your WiFi network where WPS is enabled.
# iwlist scan
wlan0 Scan completed :
Cell 01 - Address: 11:22:33:44:55:66
Channel:11
Frequency:2.462 GHz (Channel 11)
Quality=64/70 Signal level=-46 dBm
...Use wpa_cli to connect to the MAC address provided by the scan.
# wpa_cli wps_pbc 11:22:33:44:55:66
Then press the WPS button on your access point to start the PBC mode.
Once connected, start dhclient to obtain a dynamic IP address.
dhclient wlan0
Using systemd and wpa_supplicant
Systemd-networkd is used to bring the wireless interface up and wpa_supplicant will assist with connection to SSID.
Interface name
There is a major issue that wpa_supplicant must be configured for each wireless interface separately. Although the kernel still names the wireless interfaces like wlan0 there are system-wide udev rules, which rename it based on its MAC address to something like wlx00147c5bb799. If you use multiple USB WiFi dongles, it is helpful to setup udev rule to name the wireless interface the same for every dongle. The chosen name must not be the same as the kernel assigned names ( wlan0 ).
E.g. /etc/udev/rules.d/70-wireless-usb.rules:
ACTION=="add", SUBSYSTEM=="net", KERNEL=="wlan0", NAME="usbwifi"
Reboot is required to make this rule effective.
systemd-networkd
First, disable ifup/ifdown configuration (if it exists) by simply renaming the file and directory:
$ su -l -c "mv /etc/network/interfaces /etc/network/interfaces.save $ su -l -c "mv /etc/network/interfaces.d /etc/network/interfaces.d.save
If not needed for anything else, you can also apt purge ifupdown package.
Create a configuration file for the wireless interface - see SystemdNetworkd wiki page for details. E.g. /etc/systemd/network/30-wlan.network:
[Match]
Name=usbwifi
Type=wlan
WLANInterfaceType=station
[Network]
DHCP=ipv4
[DHCP]
UseDNS=yes
wpa_supplicant
If not done yet, install wpa_supplicant package.
Create a configuration file with SSID networks, e.g. /etc/wpa_supplicant/wpa_supplicant-usbwifi.conf (the file name is important!):
ctrl_interface=DIR=/run/wpa_supplicant GROUP=netdev
update_config=1
# Multiple `network` sections can be added for each SSID
network={
ssid="myssid"
psk="myssid_password"
}Enable and start wpa_supplicant service for usbwifi interface:
systemctl enable --now wpa_supplicant@usbwifi.service
This service watches for usbwifi interface getting up and then it runs the wpa_supplicant program with the corresponding configuration file /etc/wpa_supplicant/wpa_supplicant-usbwifi.conf.
Finally, enable and start the systemd-networkd service:
$ su -l -c "systemctl enable --now systemd-networkd"
The usbwifi interface should be up. Check with:
$ ip address $ su -l -c "systemctl status wpa_supplicant@usbwifi.service" $ su -l -c "systemctl status systemd-networkd.service"
You can also setup systemd-resolved.service to manage domain name resolution, it also provides resolvconf command for apps which need it. In such case, uninstall other packages, which provide the same service (e.g. apt purge resolvconf).
If many changes are done to network setup, it might be helpful to simply reboot and check again.
wpa_supplicant
WPA and WPA2 is also known as "WPA Personal" and "WPA2 Personal" respectively.
wpa_supplicant is a WPA client and IEEE 802.1X supplicant.
The wpasupplicant package provides wpa-* the ifupdown options for /etc/network/interfaces. If these options are specified, wpa_supplicant is started in the background when your wireless interface is raised and stopped when brought down.
- GNOME and KDE users shouldn't configure wpa_supplicant manually. Use NetworkManager as explained above.
Before continuing, install the wpasupplicant package.
/etc/network/interfaces and wpa_supplicant
This section describes a simple setup for wireless interface and one or more WiFi networks. Instead of configuring wpa-ssid and wpa-psk directly in /etc/network/interfaces as shown above on this page, the wpa_supplicant configuration is done separately.
Add your wireless interface to /etc/network/interfaces. For this example, it is wlan0:
# ... # Keep existing info as is and only add these new lines (the # comments can be deleted) allow-hotplug wlan0 # This will bring the interface up, when WiFi device (USB dongle etc.) is plugged in. auto wlan0 # This will bring the interface up during system boot. iface wlan0 inet dhcp # This will try to obtain IP address via DHCP wpa-conf /etc/wpa_supplicant/wpa_supplicant-wlan0.conf # This will use wpa_supplicant program to connect to SSID
Now, you can use wpa_passphrase to calculate WPA PSK hash for WiFi password - its output is a full network section for the configuration file /etc/wpa_supplicant/wpa_supplicant-wlan0.conf. Also, you can restrict the conf file permissions as a security measure:
$ su -l -c "wpa_passphrase myssid my_very_secret_passphrase >> /etc/wpa_supplicant/wpa_supplicant-wlan0.conf" $ su -l -c "chmod 0600 /etc/wpa_supplicant/wpa_supplicant-wlan0.conf"
Repeat the above step for any other SSID you want your system to connect to automatically.
Further, edit the file /etc/wpa_supplicant/wpa_supplicant-wlan0.conf and add these lines with update_config and ctrl_interface:
update_config=1
ctrl_interface=DIR=/run/wpa_supplicant GROUP=netdev
# Multiple "network" sections are allowed, wpa_supplicant will scan all available brodcasted SSIDs.
network={
ssid="myssid"
#psk="my_very_secret_passphrase"
psk=ccb290fd4fe6b22935cbae31449e050edd02ad44627b16ce0151668f5f53c01b
}Now, try to get wlan0 interface up manually:
$ su -l -c "ifup wlan0"
If all works and the interface wlan0 obtained IP address successfuly (check with command ip address), you should also try to reboot the system to check if the connection is established automatically during boot.
Note that this setup does not depend on wpa_supplicant.service and it runs a separate wpa_supplicant process to connect to SSID.
Additional wpa-* options are described within /usr/share/doc/wpasupplicant/README.modes.gz. This should also be read if connecting to a network not broadcasting its SSID.
For general /etc/network/interfaces information, see the interfaces(5) man page.
WPA-EAP
For networks using EAP-TLS, you are required to establish a wpa_supplicant configuration file and provide the client-side certificate. An example WPA2-EAP configuration file can be found at /usr/share/doc/wpasupplicant/examples/wpa2-eap-ccmp.conf.
Once available, reference your configuration file in /etc/network/interfaces. For example:
allow-hotplug wlan0 iface wlan0 inet dhcp wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
More information can be found in the wpa_supplicant.conf(5) man page. A fully-commented wpa_supplicant configuration file example is at /usr/share/doc/wpasupplicant/README.wpa_supplicant.conf.gz.
Switching Connections
To switch between multiple distinct configurations:
Use ifscheme. This integrates with the "Debian" way of doing networking, using ifup and /etc/network/interfaces, and allows you to set up different schemes for network configuration. See the manpage for more information: IFSCHEME(8)
You can use guessnet(8) to switch profiles automatically by your location.
Security consideration
Every member of a network can listen to other members' traffic (whether it's an unencrypted public hot-spot, or a WEP/WPA/WPA2, or LAN). Use SSL/TLS protocols (HTTPS, IMAPS...) or VPN to preserve your privacy.
- WEP is so insecure that it is basically equivalent to not using any encryption at all.
WPA1 is deprecated. Use WPA2 instead.
Make sure you use a strong pass-phrase.
Network security, see: https://www.aircrack-ng.org/doku.php?id=tutorial.
See Also
WiFi/AdHoc - Establishing a WiFi network without an access point.