diff options
Diffstat (limited to 'docs/configuration/interfaces/wireless.rst')
| -rw-r--r-- | docs/configuration/interfaces/wireless.rst | 573 |
1 files changed, 573 insertions, 0 deletions
diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst new file mode 100644 index 00000000..2de3b126 --- /dev/null +++ b/docs/configuration/interfaces/wireless.rst @@ -0,0 +1,573 @@ +.. _wireless-interface: + +################### +Wireless LAN (WiFi) +################### + +:abbr:`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless +support (commonly referred to as Wi-Fi) by means of compatible hardware. If your +hardware supports it, VyOS supports multiple logical wireless interfaces per +physical device. + +There are three modes of operation for a wireless interface: + +* :abbr:`WAP (Wireless Access-Point)` provides network access to connecting + stations if the physical hardware supports acting as a WAP + +* A station acts as a Wi-Fi client accessing the network through an available + WAP + +* Monitor, the system passively monitors any kind of wireless traffic + +If the system detects an unconfigured wireless device, it will be automatically +added the configuration tree, specifying any detected settings (for example, +its MAC address) and configured to run in monitor mode. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: ../_include/interface-common-with-dhcp.txt + :var0: wireless + :var1: wlan0 + +Wireless options +================ + +.. cfgcmd:: set interfaces wireless <interface> channel <number> + + Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n) channels range from + 1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 173 + +.. cfgcmd:: set interfaces wireless <interface> country-code <cc> + + Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed + to indicate country in which device is operating. This can limit available + channels and transmit power. + + .. note:: This option is mandatory in Access-Point mode. + +.. cfgcmd:: set interfaces wireless <interface> disable-broadcast-ssid + + Send empty SSID in beacons and ignore probe request frames that do not specify + full SSID, i.e., require stations to know SSID. + +.. cfgcmd:: set interfaces wireless <interface> expunge-failing-stations + + Disassociate stations based on excessive transmission failures or other + indications of connection loss. + + This depends on the driver capabilities and may not be available with all + drivers. + +.. cfgcmd:: set interfaces wireless <interface> isolate-stations + + Client isolation can be used to prevent low-level bridging of frames between + associated stations in the BSS. + + By default, this bridging is allowed. + +.. cfgcmd:: set interfaces wireless <interface> max-stations + + Maximum number of stations allowed in station table. New stations will be + rejected after the station table is full. IEEE 802.11 has a limit of 2007 + different association IDs, so this number should not be larger than that. + + This defaults to 2007. + +.. cfgcmd:: set interfaces wireless <interface> mgmt-frame-protection + + Management Frame Protection (MFP) according to IEEE 802.11w + +.. cfgcmd:: set interfaces wireless <interface> mode <a | b | g | n | ac> + + Operation mode of wireless radio. + + * ``a`` - 802.11a - 54 Mbits/sec + * ``b`` - 802.11b - 11 Mbits/sec + * ``g`` - 802.11g - 54 Mbits/sec (default) + * ``n`` - 802.11n - 600 Mbits/sec + * ``ac`` - 802.11ac - 1300 Mbits/sec + +.. cfgcmd:: set interfaces wireless <interface> physical-device <device> + + Wireless hardware device used as underlay radio. + + This defaults to phy0. + +.. cfgcmd:: set interfaces wireless <interface> reduce-transmit-power <number> + + Add Power Constraint element to Beacon and Probe Response frames. + + This option adds Power Constraint element when applicable and Country element + is added. Power Constraint element is required by Transmit Power Control. + + Valid values are 0..255. + +.. cfgcmd:: set interfaces wireless <interface> ssid <ssid> + + SSID to be used in IEEE 802.11 management frames + +.. cfgcmd:: set interfaces wireless <interface> type <access-point | station | monitor> + + Wireless device type for this interface + + * ``access-point`` - Access-point forwards packets between other nodes + * ``station`` - Connects to another access point + * ``monitor`` - Passively monitor all packets on the frequency/channel + +PPDU +---- + +.. cfgcmd:: set interfaces wireless <interface> capabilities require-ht + +.. cfgcmd:: set interfaces wireless <interface> capabilities require-hvt + +HT (High Throughput) capabilities (802.11n) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht 40mhz-incapable + + Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht auto-powersave + + WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht channel-set-width <ht20 | ht40+ | ht40-> + + Supported channel width set. + + * ``ht40-`` - Both 20 MHz and 40 MHz with secondary channel below the primary + channel + * ``ht40+`` - Both 20 MHz and 40 MHz with secondary channel above the primary + channel + + .. note:: There are limits on which channels can be used with HT40- and HT40+. + Following table shows the channels that may be available for HT40- and HT40+ + use per IEEE 802.11n Annex J: + + Depending on the location, not all of these channels may be available for use! + + .. code-block:: none + + freq HT40- HT40+ + 2.4 GHz 5-13 1-7 (1-9 in Europe/Japan) + 5 GHz 40,48,56,64 36,44,52,60 + + .. note:: 40 MHz channels may switch their primary and secondary channels if + needed or creation of 40 MHz channel maybe rejected based on overlapping + BSSes. These changes are done automatically when hostapd is setting up the + 40 MHz channel. + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht delayed-block-ack + + Enable HT-delayed Block Ack ``[DELAYED-BA]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht dsss-cck-40 + + DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht greenfield + + This enables the greenfield option which sets the ``[GF]`` option + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht ldpc + + Enable LDPC coding capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht lsig-protection + + Enable L-SIG TXOP protection capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht max-amsdu <3839 | 7935> + + Maximum A-MSDU length 3839 (default) or 7935 octets + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht short-gi <20 | 40> + + Short GI capabilities for 20 and 40 MHz + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht smps <static | dynamic> + + Spatial Multiplexing Power Save (SMPS) settings + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc rx <num> + + Enable receiving PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities ht stbc tx + + Enable sending PPDU using STBC (Space Time Block Coding) + +VHT (Very High Throughput) capabilities (802.11ac) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-count + + Number of antennas on this card + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht antenna-pattern-fixed + + Set if antenna pattern does not change during the lifetime of an association + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht beamform + <single-user-beamformer | single-user-beamformee | multi-user-beamformer | + multi-user-beamformee> + + Beamforming capabilities: + + * ``single-user-beamformer`` - Support for operation as single user beamformer + * ``single-user-beamformee`` - Support for operation as single user beamformee + * ``multi-user-beamformer`` - Support for operation as single user beamformer + * ``multi-user-beamformee`` - Support for operation as single user beamformer + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht center-channel-freq <freq-1 | freq-2> + + VHT operating channel center frequency - center freq 1 (for use with 80, 80+80 and 160 modes) + + VHT operating channel center frequency - center freq 2 (for use with the 80+80 mode) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht channel-set-width <0 | 1 | 2 | 3> + + * ``0`` - 20 or 40 MHz channel width (default) + * ``1`` - 80 MHz channel width + * ``2`` - 160 MHz channel width + * ``3`` - 80+80 MHz channel width + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht ldpc + + Enable LDPC (Low Density Parity Check) coding capability + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht link-adaptation + + VHT link adaptation capabilities + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht max-mpdu <value> + + Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht max-mpdu-exp <value> + + Set the maximum length of A-MPDU pre-EOF padding that the station can receive + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht short-gi <80 | 160> + + Short GI capabilities + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc rx <num> + + Enable receiving PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht stbc tx + + Enable sending PPDU using STBC (Space Time Block Coding) + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht tx-powersave + + Enable VHT TXOP Power Save Mode + +.. cfgcmd:: set interfaces wireless <interface> capabilities vht vht-cf + + Station supports receiving VHT variant HT Control field + +Wireless options (Station/Client) +================================= + +The example creates a wireless station (commonly referred to as Wi-Fi client) +that accesses the network through the WAP defined in the above example. The +default physical device (``phy0``) is used. + +.. code-block:: none + + set interfaces wireless wlan0 type station + set interfaces wireless wlan0 address dhcp + set interfaces wireless wlan0 ssid Test + set interfaces wireless wlan0 security wpa + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address dhcp + security { + wpa { + passphrase "12345678" + } + } + ssid TEST + type station + } + +Security +======== + +:abbr:`WPA (Wi-Fi Protected Access)` and WPA2 Enterprise in combination with +802.1x based authentication can be used to authenticate users or computers +in a domain. + +The wireless client (supplicant) authenticates against the RADIUS server +(authentication server) using an :abbr:`EAP (Extensible Authentication +Protocol)` method configured on the RADIUS server. The WAP (also referred +to as authenticator) role is to send all authentication messages between the +supplicant and the configured authentication server, thus the RADIUS server +is responsible for authenticating the users. + +The WAP in this example has the following characteristics: + +* IP address ``192.168.2.1/24`` +* Network ID (SSID) ``Enterprise-TEST`` +* WPA passphrase ``12345678`` +* Use 802.11n protocol +* Wireless channel ``1`` +* RADIUS server at ``192.168.3.10`` with shared-secret ``VyOSPassword`` + +.. code-block:: none + + set interfaces wireless wlan0 address '192.168.2.1/24' + set interfaces wireless wlan0 type access-point + set interfaces wireless wlan0 channel 1 + set interfaces wireless wlan0 mode n + set interfaces wireless wlan0 ssid 'TEST' + set interfaces wireless wlan0 security wpa mode wpa2 + set interfaces wireless wlan0 security wpa cipher CCMP + set interfaces wireless wlan0 security wpa radius server 192.168.3.10 key 'VyOSPassword' + set interfaces wireless wlan0 security wpa radius server 192.168.3.10 port 1812 + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + radius { + server 192.168.3.10 { + key 'VyOSPassword' + port 1812 + } + } + } + } + ssid "Enterprise-TEST" + type access-point + } + } + system { + [...] + wifi-regulatory-domain DE + } + + +VLAN +==== + +Regular VLANs (802.1q) +---------------------- + +.. cmdinclude:: ../_include/interface-vlan-8021q.txt + :var0: wireless + :var1: wlan0 + +QinQ (802.1ad) +-------------- + +.. cmdinclude:: ../_include/interface-vlan-8021ad.txt + :var0: wireless + :var1: wlan0 + +********* +Operation +********* + +.. opcmd:: show interfaces wireless info + +Use this command to view operational status and wireless-specific information +about all wireless interfaces. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless info + Interface Type SSID Channel + wlan0 access-point VyOS-TEST-0 1 + +.. opcmd:: show interfaces wireless detail + +Use this command to view operational status and detailes wireless-specific +information about all wireless interfaces. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless detail + wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 + + wlan1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.100.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:ffff:2ed3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 166072 5282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 183413 5430 0 0 0 0 + +.. opcmd:: show interfaces wireless <wlanX> + +This command shows both status and statistics on the specified wireless interface. +The wireless interface identifier can range from wlan0 to wlan999. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 + wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether XX:XX:XX:XX:XX:c3 brd XX:XX:XX:XX:XX:ff + inet xxx.xxx.99.254/24 scope global wlan0 + valid_lft forever preferred_lft forever + inet6 fe80::xxxx:xxxx:fe54:2fc3/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 66072 282 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 83413 430 0 0 0 0 + + +.. opcmd:: show interfaces wireless <wlanX> brief + +This command gives a brief status overview of a specified wireless interface. +The wireless interface identifier can range from wlan0 to wlan999. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 brief + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + wlan0 192.168.2.254/24 u/u + + +.. opcmd:: show interfaces wireless <wlanX> queue + +Use this command to view wireless interface queue information. +The wireless interface identifier can range from wlan0 to wlan999. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 queue + qdisc pfifo_fast 0: root bands 3 priomap 1 2 2 2 1 2 0 0 1 1 1 1 1 1 1 1 + Sent 810323 bytes 6016 pkt (dropped 0, overlimits 0 requeues 0) + rate 0bit 0pps backlog 0b 0p requeues 0 + + +.. opcmd:: show interfaces wireless <wlanX> scan + +This command is used to retrieve information about WAP within the range of your +wireless interface. This command is useful on wireless interfaces configured +in station mode. + +.. note:: Scanning is not supported on all wireless drivers and wireless + hardware. Refer to your driver and wireless hardware documentation for + further details. + +.. code-block:: none + + vyos@vyos:~$ show interfaces wireless wlan0 scan + Address SSID Channel Signal (dbm) + 00:53:3b:88:6e:d8 WLAN-576405 1 -64.00 + 00:53:3b:88:6e:da Telekom_FON 1 -64.00 + 00:53:00:f2:c2:a4 BabyView_F2C2A4 6 -60.00 + 00:53:3b:88:6e:d6 Telekom_FON 100 -72.00 + 00:53:3b:88:6e:d4 WLAN-576405 100 -71.00 + 00:53:44:a4:96:ec KabelBox-4DC8 56 -81.00 + 00:53:d9:7a:67:c2 WLAN-741980 1 -75.00 + 00:53:7c:99:ce:76 Vodafone Homespot 1 -86.00 + 00:53:44:a4:97:21 KabelBox-4DC8 1 -78.00 + 00:53:44:a4:97:21 Vodafone Hotspot 1 -79.00 + 00:53:44:a4:97:21 Vodafone Homespot 1 -79.00 + 00:53:86:40:30:da Telekom_FON 1 -86.00 + 00:53:7c:99:ce:76 Vodafone Hotspot 1 -86.00 + 00:53:44:46:d2:0b Vodafone Hotspot 1 -87.00 + + +******** +Examples +******** + +The following example creates a WAP. When configuring multiple WAP interfaces, +you must specify unique IP addresses, channels, Network IDs commonly referred +to as :abbr:`SSID (Service Set Identifier)`, and MAC addresses. + +The WAP in this example has the following characteristics: + +* IP address ``192.168.2.1/24`` +* Network ID (SSID) ``TEST`` +* WPA passphrase ``12345678`` +* Use 802.11n protocol +* Wireless channel ``1`` + +.. code-block:: none + + set interfaces wireless wlan0 address '192.168.2.1/24' + set interfaces wireless wlan0 type access-point + set interfaces wireless wlan0 channel 1 + set interfaces wireless wlan0 mode n + set interfaces wireless wlan0 ssid 'TEST' + set interfaces wireless wlan0 security wpa mode wpa2 + set interfaces wireless wlan0 security wpa cipher CCMP + set interfaces wireless wlan0 security wpa passphrase '12345678' + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address 192.168.2.1/24 + channel 1 + mode n + security { + wpa { + cipher CCMP + mode wpa2 + passphrase "12345678" + } + } + ssid "TEST" + type access-point + } + } + system { + [...] + wifi-regulatory-domain DE + } + +To get it to work as a access point with this configuration you will need +to set up a DHCP server to work with that network. You can - of course - also +bridge the Wireless interface with any configured bridge +(:ref:`bridge-interface`) on the system. |