From e8256de2a6e8b7754545f3b23e279edb5b40265a Mon Sep 17 00:00:00 2001 From: LiudmylaNad Date: Mon, 30 Mar 2026 12:25:38 +0200 Subject: DOC: Proofread wireless.rst (#1806) * DOC: Proofread wireless.rst * Apply suggestion from @dmbaturin --------- Co-authored-by: Daniil Baturin --- docs/configuration/interfaces/wireless.rst | 550 ++++++++++++++++------------- 1 file changed, 303 insertions(+), 247 deletions(-) (limited to 'docs/configuration/interfaces') diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index e6a29f9a..5c003f15 100644 --- a/docs/configuration/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst @@ -1,29 +1,31 @@ -:lastproofread: 2024-07-04 +:lastproofread: 2026-03-23 .. _wireless-interface: ######################## -WLAN/WIFI - Wireless LAN +Wireless LAN / Wi-Fi ######################## -The :abbr:`WLAN (Wireless LAN)` interface provides 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. +:abbr:`WLAN (Wireless LAN)` interfaces provide 802.11 (a/b/g/n/ac) wireless +connectivity, referred to as Wi-Fi, and operate in one of the following modes: -There are three modes of operation for a wireless interface: +* ``access-point``: Provide network access to connecting stations. -* :abbr:`WAP (Wireless Access-Point)` mode provides network access to connecting - stations if the physical hardware supports acting as a WAP +* ``station:`` Operate as Wi-Fi clients, connecting to the network via an + available :abbr:`AP (Access Point)`. -* Station mode acts as a Wi-Fi client accessing the network through an available - WAP +* ``monitor:`` Passively monitor wireless traffic. -* Monitor mode lets the system passively monitor wireless traffic +If the system detects an unconfigured wireless device, it automatically adds +the device to the configuration tree with the detected settings, such as the +MAC address, and sets it to ``monitor`` mode. -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. +.. note:: VyOS supports creating **multiple** WLAN interfaces on a single + physical device. + +.. note:: Wi-Fi connectivity, support for multiple WLAN interfaces on a single + physical device, and access point capabilities strictly depend on the + underlying hardware. ************* Configuration @@ -36,117 +38,122 @@ Common interface configuration :var0: wireless :var1: wlan0 -System Wide configuration +System-wide configuration ========================= .. cfgcmd:: set system wireless country-code - 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. + **Configure the system's ISO/IEC 3166-1 country code.** + + The country code indicates the region in which the device operates. This may + restrict available channels and transmit power. - .. note:: This option is mandatory in Access-Point mode. + .. note:: This option is mandatory in ``access-point`` mode. Wireless options ================ -.. cfgcmd:: set system wireless country-code +.. cfgcmd:: set interfaces wireless channel - Country code (ISO/IEC 3166-1). Used to set regulatory domain. Set as needed - to indicate country in which the box is operating. This can limit available - channels and transmit power. + **Configure the IEEE 802.11 wireless radio channel for the interface.** - .. note:: This option is mandatory in Access-Point mode. + Channel allocation depends on the frequency band: -.. cfgcmd:: set interfaces wireless channel - - Channel number (IEEE 802.11), for 2.4Ghz (802.11 b/g/n/ax) channels range from - 1-14. On 5Ghz (802.11 a/h/j/n/ac) channels available are 0, 34 to 177. - On 6GHz (802.11 ax) channels range from 1 to 233. + * **2.4 GHz** (802.11b/g/n/ax): Channels range from 1 to 14. + * **5 GHz** (802.11a/h/j/n/ac/ax): Channels range from 34 to 177. + * **6 GHz** (802.11ax): Channels range from 1 to 233. + * **Automatic channel selection:** 0. .. cfgcmd:: set interfaces wireless 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 the SSID. + **Configure the interface to broadcast an empty SSID in beacons and to ignore + probe requests that do not include the full SSID.** + + This requires client stations to be configured with the correct SSID to connect. .. cfgcmd:: set interfaces wireless expunge-failing-stations - Disassociate stations based on excessive transmission failures or other - indications of connection loss. + **Configure the interface to disconnect client stations upon excessive + transmission failures or connection loss.** - This depends on the driver capabilities and may not be available with all - drivers. + This feature depends on driver capabilities and may not work with some drivers. .. cfgcmd:: set interfaces wireless isolate-stations - Client isolation can be used to prevent low-level bridging of frames between - associated stations in the BSS. + **Enable client isolation on the interface.** + + This prevents low-level frame bridging between associated stations within the + BSS. By default, this bridging is allowed. -.. cfgcmd:: set interfaces wireless max-stations +.. cfgcmd:: set interfaces wireless max-stations + + **Configure the number of allowed connecting clients for the interface.** - 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. + When this limit is reached, new client association requests are rejected. The + IEEE 802.11 standard allows up to 2007 distinct association IDs. Therefore, + this value should not exceed 2007. - This defaults to 2007. + Default: 2007. .. cfgcmd:: set interfaces wireless mgmt-frame-protection - Management Frame Protection (MFP) according to IEEE 802.11w + Enable :abbr:`MFP (Management Frame Protection)` on the interface according to + IEEE 802.11w. .. note:: :abbr:`MFP (Management Frame Protection)` is required for WPA3. .. cfgcmd:: set interfaces wireless enable-bf-protection - Beacon Protection: management frame protection for Beacon frames. + Enable :abbr:`BF (Beacon Frame)` protection on the interface. .. note:: This option requires :abbr:`MFP (Management Frame Protection)` to be enabled. .. cfgcmd:: set interfaces wireless mode - Operation mode of wireless radio. + Configure wireless radio mode for the interface. - * ``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 - * ``ax`` - 802.11ax - exceeds 1GBit/sec + * ``a``: 802.11a (up to 54 Mbps). + * ``b``: 802.11b (up to 11 Mbps). + * ``g`` (default): 802.11g (up to 54 Mbps). + * ``n``: 802.11n (up to 600 Mbps). + * ``ac``: 802.11ac (up to 1300 Mbps). + * ``ax``: 802.11ax (exceeds 1 Gbps). - .. note:: In VyOS, 802.11ax is only implemented for 2.4GHz and 6GHz. + .. note:: In VyOS, 802.11ax is only implemented for 2.4 GHz and 6 GHz. .. cfgcmd:: set interfaces wireless physical-device - Wireless hardware device used as underlay radio. + **Configure the underlying wireless physical device for the interface.** - This defaults to phy0. + Default: ``phy0``. .. cfgcmd:: set interfaces wireless reduce-transmit-power - Adds the Power Constraint information element to Beacon and Probe Response - frames. + **Configure the interface to add the Power Constraint** :abbr:`IE (Information + Element)` **to Beacon and Probe Response frames.** - This option adds the Power Constraint information element when applicable - and the Country information element is configured. The Power Constraint - element is required by Transmit Power Control. + The Power Constraint :abbr:`IE (Information Element)` is required by :abbr:`TPC + (Transmit Power Control)`. - Valid values are 0..255. + Valid values: 0 to 255. + + .. note:: You must configure the country code to use this option. .. cfgcmd:: set interfaces wireless ssid - SSID to be used in IEEE 802.11 management frames + Configure the SSID to be used in IEEE 802.11 management frames. .. cfgcmd:: set interfaces wireless type - Wireless device type for this interface + **Configure the wireless device type for the 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 + * ``access-point``: Forwards packets between other nodes. + * ``station``: Connects to another :abbr:`AP (Access Point)`. + * ``monitor``: Passively monitors all packets on the frequency/channel. .. cmdinclude:: /_include/interface-per-client-thread.txt :var0: wireless @@ -164,175 +171,215 @@ PPDU HT (High Throughput) capabilities (802.11n) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Configuring HT mode options is required when using 802.11n or 802.11ax at 2.4GHz. + Configure **HT mode options** if you use 802.11n or 802.11ax at 2.4 GHz. .. cfgcmd:: set interfaces wireless capabilities ht 40mhz-incapable - Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` + **Configure the interface to operate at 20 MHz.** + + The command sets the ``[40-INTOLERANT]`` flag. .. cfgcmd:: set interfaces wireless capabilities ht auto-powersave - WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] + Enable :abbr:`WMM-PS (Wi-Fi Multimedia Power Save)` (:abbr:`U-APSD (Unscheduled + Automatic Power Save Delivery)`) for the interface. .. cfgcmd:: set interfaces wireless capabilities ht channel-set-width - Supported channel width set. - - * ``ht20`` - 20 MHz channel width - * ``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 + **Configure the supported channel width set for the interface.** - .. 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: + * ``ht20``: Allows a 20 MHz channel width. + * ``ht40-``: Allows both 20 MHz and 40 MHz channel widths, with the secondary + channel **below** the primary channel. + * ``ht40+``: Allows both 20 MHz and 40 MHz channel widths, with the secondary + channel **above** the primary channel. + + .. note:: Channel availability for HT40- and HT40+ is limited. The following + table lists channels permitted for HT40- and HT40+ according to IEEE 802.11n + Annex J. Channel availability may vary by location. - Depending on the location, not all of these channels may be available for - use! + .. code-block:: none - .. 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 - 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. + .. note:: 40 MHz channels may automatically switch their primary and secondary + assignments, or the creation of a 40 MHz channel may be rejected due to + :abbr:`OBSSs (Overlapping Basic Service Sets)`. ``hostapd`` performs these + adjustments automatically when setting up the channel. .. cfgcmd:: set interfaces wireless capabilities ht delayed-block-ack - Enable HT-delayed Block Ack ``[DELAYED-BA]`` + **Enable HT-delayed** :abbr:`Block Ack (Block Acknowledgement)` **on the + interface.** + + This sets the ``[DELAYED-BA]`` flag. .. cfgcmd:: set interfaces wireless capabilities ht dsss-cck-40 - DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` + **Enable** :abbr:`DSSS (Direct Sequence Spread Spectrum)`/:abbr:`CCK + (Complementary Code Keying)` **mode in 40 MHz channels.** + + This sets the ``[DSSS_CCK-40]`` flag. .. cfgcmd:: set interfaces wireless capabilities ht greenfield - This enables the greenfield option which sets the ``[GF]`` option + **Enable HT Greenfield mode on the interface.** + + This sets the ``[GF]`` flag. .. cfgcmd:: set interfaces wireless capabilities ht ldpc - Enable LDPC coding capability + Enable :abbr:`LDPC (Low-Density Parity-Check)` coding on the interface. .. cfgcmd:: set interfaces wireless capabilities ht lsig-protection - Enable L-SIG TXOP protection capability + Enable :abbr:`L-SIG TXOP (Legacy Signal Transmission Opportunity)` protection + on the interface. .. cfgcmd:: set interfaces wireless capabilities ht max-amsdu <3839 | 7935> - Maximum A-MSDU length 3839 (default) or 7935 octets + Configure the maximum :abbr:`A-MSDU (Aggregate MAC Service Data Unit)` length + to either 3839 octets (default) or 7935 octets. .. cfgcmd:: set interfaces wireless capabilities ht short-gi <20 | 40> - Short GI capabilities for 20 and 40 MHz + **Configure** :abbr:`Short GI (Short Guard Interval)` **capabilities for 20 MHz + or 40 MHz channels.** + + * ``20``: Enables Short GI for 20 MHz channels. + * ``40``: Enables Short GI for 40 MHz channels. .. cfgcmd:: set interfaces wireless capabilities ht smps - Spatial Multiplexing Power Save (SMPS) settings + **Configure** :abbr:`SMPS (Spatial Multiplexing Power Save)` **mode for the + interface.** + + * ``static``: Enables static SMPS mode. + * ``dynamic``: Enables dynamic SMPS mode. .. cfgcmd:: set interfaces wireless capabilities ht stbc rx - Enable receiving PPDU using STBC (Space Time Block Coding) + Enable receiving :abbr:`PPDUs (PLCP Protocol Data Units)` using :abbr:`STBC + (Space-Time Block Coding)`. .. cfgcmd:: set interfaces wireless capabilities ht stbc tx - Enable sending PPDU using STBC (Space Time Block Coding) + Enable transmitting :abbr:`PPDUs (PLCP Protocol Data Units)` using :abbr:`STBC + (Space-Time Block Coding)`. + VHT (Very High Throughput) capabilities (802.11ac) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. cfgcmd:: set interfaces wireless capabilities vht antenna-count +.. cfgcmd:: set interfaces wireless capabilities vht antenna-count + + **Configure the number of antennas for the interface.** - Number of antennas on this card + Valid values: 1 to 8. .. cfgcmd:: set interfaces wireless capabilities vht antenna-pattern-fixed - Set if antenna pattern does not change during the lifetime of an association + **Enable the fixed antenna pattern capability on the interface.** + + Use this option if the antenna pattern does not change during the lifetime of + an association. .. cfgcmd:: set interfaces wireless capabilities vht beamform - Beamforming capabilities: + Configure VHT beamforming capabilities for the interface. - * ``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 - multi user beamformer - * ``multi-user-beamformee`` - Support for operation as - multi user beamformee + * ``single-user-beamformer``: Supports operation as a Single-User (SU) + beamformer. + * ``single-user-beamformee``: Supports operation as a Single-User (SU) + beamformee. + * ``multi-user-beamformer``: Supports operation as a Multi-User (MU) beamformer. + * ``multi-user-beamformee``: Supports operation as a Multi-User (MU) beamformee. .. cfgcmd:: set interfaces wireless capabilities vht center-channel-freq - VHT operating channel center frequency - center freq 1 - (for use with 80, 80+80 and 160 modes) + **Configure the VHT operating channel center frequency for the interface.** - VHT operating channel center frequency - center freq 2 - (for use with the 80+80 mode) + * ``freq-1``: Specifies the center frequency for 80 MHz, 160 MHz, and 80+80 MHz + channels. - must be from 34 - 173. For 80 MHz channels it should be channel + 6. + * ``freq-2:`` Specifies the center frequency for 80+80 MHz channels. + + * ````: Ranges from 34 to 173. For 80 MHz channels, the center + frequency is typically the channel number plus 6. .. cfgcmd:: set interfaces wireless 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 + **Configure the VHT operating channel width for the interface.** + + * ``0`` (default): 20 MHz or 40 MHz channel width. + * ``1``: 80 MHz channel width. + * ``2``: 160 MHz channel width. + * ``3``: 80+80 MHz channel width. .. cfgcmd:: set interfaces wireless capabilities vht ldpc - Enable LDPC (Low Density Parity Check) coding capability + Enable :abbr:`LDPC (Low-Density Parity Check)` coding for the interface. .. cfgcmd:: set interfaces wireless capabilities vht link-adaptation - VHT link adaptation capabilities + Enable VHT link adaptation on the interface. .. cfgcmd:: set interfaces wireless capabilities vht max-mpdu - Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) + **Increase the maximum** :abbr:`MPDU (MAC Protocol Data Unit)` **length to + 7991 or 11454 octets.** + + Default: 3895 octets. .. cfgcmd:: set interfaces wireless capabilities vht max-mpdu-exp - Set the maximum length of A-MPDU pre-EOF padding that the station can - receive + Configure the maximum length of :abbr:`A-MPDU (Aggregated MAC Protocol Data + Unit)` :abbr:`pre-EOF (pre-End of Frame)` padding that the interface can + receive. .. cfgcmd:: set interfaces wireless capabilities vht short-gi <80 | 160> - Short GI capabilities + **Configure** :abbr:`Short GI (Short Guard Interval)` **capabilities for 80 MHz + or 160 MHz channels.** + + * ``80``: Enables Short GI for 80 MHz channels. + * ``160``: Enables Short GI for 160 MHz channels. + .. cfgcmd:: set interfaces wireless capabilities vht stbc rx - Enable receiving PPDU using STBC (Space Time Block Coding) + Enable receiving :abbr:`PPDUs (PLCP Protocol Data Units)` using :abbr:`STBC + (Space-Time Block Coding)`. .. cfgcmd:: set interfaces wireless capabilities vht stbc tx - Enable sending PPDU using STBC (Space Time Block Coding) + Enable transmitting :abbr:`PPDUs (PLCP Protocol Data Units)` using :abbr:`STBC + (Space-Time Block Coding)`. .. cfgcmd:: set interfaces wireless capabilities vht tx-powersave - Enable VHT TXOP Power Save Mode + Enable VHT :abbr:`TXOP (Transmit Opportunity)` Power Save mode for the + interface. .. cfgcmd:: set interfaces wireless capabilities vht vht-cf - Station supports receiving VHT variant HT Control field + Enable receiving the VHT variant HT Control field on the interface. HE (High Efficiency) capabilities (802.11ax) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -340,77 +387,82 @@ HE (High Efficiency) capabilities (802.11ax) .. cfgcmd:: set interfaces wireless capabilities he antenna-pattern-fixed - Tell the AP that antenna positions are fixed and will not change - during the lifetime of an association. + Notify the :abbr:`AP (Access Point)` that antenna positions are fixed and do not change during the lifetime of an association. .. cfgcmd:: set interfaces wireless capabilities he beamform - Beamforming capabilities: + **Configure HE beamforming capabilities for the interface.** - * ``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 + * ``single-user-beamformer``: Supports operation as a Single-User (SU) + beamformer. + * ``single-user-beamformee``: Supports operation as a Single-User (SU) + beamformee. + * ``multi-user-beamformer``: Supports operation as a Multi-User (MU) beamformer. .. cfgcmd:: set interfaces wireless capabilities he bss-color - BSS coloring helps to prevent channel jamming when multiple APs use - the same channels. + **Configure the** :abbr:`BSS (Basic Service Set)` **color for the interface.** + + BSS coloring helps prevent channel jamming when multiple :abbr:`APs (Access + Points)` use the same channels. Valid values are 1..63 .. cfgcmd:: set interfaces wireless capabilities he center-channel-freq - HE operating channel center frequency - center freq 1 - (for use with 80, 80+80 and 160 modes) + **Configure the HE operating channel center frequency for the interface.** + + * ``freq-1``: Specifies the center frequency for 80 MHz, 160 MHz, and 80+80 MHz + channels. - HE operating channel center frequency - center freq 2 - (for use with the 80+80 mode) + * ``freq-2``: Specifies the center frequency for 80+80 MHz channels. - must be within 1..233. For 80 MHz channels it should be - channel + 6 and for 160 MHz channels, it should be channel + 14. + * ````: Ranges from 34 to 173. For 80 MHz channels, the center + frequency is typically the primary channel number plus 6. .. cfgcmd:: set interfaces wireless capabilities he channel-set-width - must be one of: + **Configure the HE operating channel width for the interface.** - * ``81`` - 20 MHz channel width (2.4GHz) - * ``83`` - 40 MHz channel width, secondary 20MHz channel above primary - channel (2.4GHz) - * ``84`` - 40 MHz channel width, secondary 20MHz channel below primary - channel (2.4GHz) - * ``131`` - 20 MHz channel width (6GHz) - * ``132`` - 40 MHz channel width (6GHz) - * ``133`` - 80 MHz channel width (6GHz) - * ``134`` - 160 MHz channel width (6GHz) - * ``135`` - 80+80 MHz channel width (6GHz) + For the 2.4 GHz band: + + * ``81``: 20 MHz channel width. + * ``83``: 40 MHz channel width, secondary 20 MHz channel above primary. + * ``84``: 40 MHz channel width, secondary 20 MHz channel below primary. + + For the 6 GHz band: + + * ``131``: 20 MHz channel width. + * ``132``: 40 MHz channel width. + * ``133``: 80 MHz channel width. + * ``134``: 160 MHz channel width. + * ``135``: 80+80 MHz channel width. .. cfgcmd:: set interfaces wireless capabilities he coding-scheme + + **Configure** :abbr:`SS (Spatial Stream)` **and** :abbr:`HE-MCS (High + Efficiency Modulation and Coding Scheme)` **settings for the interface.** - This setting configures Spacial Stream and Modulation Coding Scheme - settings for HE mode (HE-MCS). It is usually not needed to set this - explicitly, but it might help with some WiFi adapters. + Explicit configuration of these settings is typically unnecessary. - must be one of: + The ```` defines the supported MCS range and must be one of the following: - * ``0`` - HE-MCS 0-7 - * ``1`` - HE-MCS 0-9 - * ``2`` - HE-MCS 0-11 - * ``3`` - HE-MCS is not supported + * ``0``: Allows HE-MCS 0-7. + * ``1``: Allows HE-MCS 0-9. + * ``2``: Allows HE-MCS 0-11. + * ``3``: Disables HE-MCS. -Wireless options (Station/Client) +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. +The following example configures a wireless station (Wi-Fi client) that +connects to the network through an :abbr:`AP (Access Point)`, using the default +physical interface ``phy0``. .. code-block:: none @@ -420,7 +472,7 @@ default physical device (``phy0``) is used. set interfaces wireless wlan0 ssid Test set interfaces wireless wlan0 security wpa passphrase '12345678' -Resulting in +Resulting configuration: .. code-block:: none @@ -441,28 +493,32 @@ Resulting in type station } -Security -======== +Wireless security +================= + +:abbr:`WPA (Wi-Fi Protected Access)`, WPA2, and WPA3 Enterprise, combined with +802.1X-based authentication, enable user or computer authentication within a +domain. -:abbr:`WPA (Wi-Fi Protected Access)`, WPA2 Enterprise and WPA3 Enterprise in -combination with 802.1x based authentication can be used to authenticate -users or computers in a domain. +The authentication process involves the following three participants: -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. +* **Supplicant**: The wireless client authenticates against the RADIUS server + using an EAP method. +* **Authenticator**: The Access Point (AP) sends authentication messages + between the supplicant and the RADIUS server. +* **Authentication server**: The RADIUS server authenticates users. -The WAP in this example has the following characteristics: +The following example configures an :abbr:`AP (Access Point)` to use WPA2 +Enterprise security and authenticate connecting clients against an external +RADIUS server. -* 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`` +Configuration parameters: + +* **IP address:** ``192.168.2.1/24`` +* **Network ID (SSID):** ``Enterprise-TEST`` +* **Protocol:** 802.11n +* **Wireless channel:** ``1`` +* **RADIUS server:** ``192.168.3.10`` with shared-secret ``VyOSPassword`` .. stop_vyoslinter .. code-block:: none @@ -472,7 +528,7 @@ The WAP in this example has the following characteristics: 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 ssid 'Enterprise-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' @@ -480,7 +536,7 @@ The WAP in this example has the following characteristics: .. start_vyoslinter -Resulting in +Resulting configuration: .. code-block:: none @@ -530,13 +586,13 @@ QinQ (802.1ad) :var1: wlan0 ********* -Operation +Operation ********* .. opcmd:: show interfaces wireless info -Use this command to view operational status and wireless-specific information -about all wireless interfaces. +Show the operational status and wireless-specific information about all +wireless interfaces. .. code-block:: none @@ -546,8 +602,8 @@ about all wireless interfaces. .. opcmd:: show interfaces wireless detail -Use this command to view operational status and details wireless-specific -information about all wireless interfaces. +Show the operational status and detailed wireless-specific information about +all wireless interfaces. .. stop_vyoslinter .. code-block:: none @@ -581,8 +637,8 @@ information about all wireless interfaces. .. opcmd:: show interfaces wireless -This command shows both status and statistics on the specified wireless -interface. The wireless interface identifier can range from wlan0 to wlan999. +Show the operational status and statistics for the specified wireless +interface. Interface identifiers range from ``wlan0`` to ``wlan999``. .. stop_vyoslinter .. code-block:: none @@ -605,8 +661,8 @@ interface. The wireless interface identifier can range from wlan0 to wlan999. .. opcmd:: show interfaces wireless brief -This command gives a brief status overview of a specified wireless interface. -The wireless interface identifier can range from wlan0 to wlan999. +Show a brief operational status summary for the specified wireless interface. +Interface identifiers range from ``wlan0`` to ``wlan999``. .. code-block:: none @@ -619,8 +675,8 @@ The wireless interface identifier can range from wlan0 to wlan999. .. opcmd:: show interfaces wireless queue -Use this command to view wireless interface queue information. -The wireless interface identifier can range from wlan0 to wlan999. +Show queue information for the specified wireless interface. Interface +identifiers range from ``wlan0`` to ``wlan999``. .. code-block:: none @@ -632,13 +688,12 @@ The wireless interface identifier can range from wlan0 to wlan999. .. opcmd:: show interfaces wireless 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. +Show information about :abbr:`APs (Access Points)` within the range of the +specified wireless interface. You can use this data when configuring wireless +interfaces 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. +.. note:: Some wireless drivers or hardware may not support such scanning. + Refer to your driver and hardware documentation for more information. .. code-block:: none @@ -664,17 +719,17 @@ in station mode. 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 following example configures an :abbr:`AP (Access Point)` with the +following parameters: -The WAP in this example has the following characteristics: +* IP address: ``192.168.2.1/24`` +* Network ID (SSID): ``TEST`` +* WPA passphrase: ``12345678`` +* Protocol: 802.11n +* Wireless channel: ``1`` -* IP address ``192.168.2.1/24`` -* Network ID (SSID) ``TEST`` -* WPA passphrase ``12345678`` -* Use 802.11n protocol -* Wireless channel ``1`` +.. note:: When setting up multiple WAP interfaces, ensure each has a unique IP + address, channel, network ID (SSID), and MAC address. .. code-block:: none @@ -688,7 +743,7 @@ The WAP in this example has the following characteristics: set interfaces wireless wlan0 security wpa cipher CCMP set interfaces wireless wlan0 security wpa passphrase '12345678' -Resulting in +Resulting configuration: .. code-block:: none @@ -715,28 +770,27 @@ Resulting in } } -To get it to work as an 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. +To enable access point functionality, configure a DHCP server for this +interface's network, or add the interface to an existing local bridge. +(see :ref:`bridge-interface` for details). -WiFi-6(e) - 802.11ax -==================== +Wi-Fi 6/6E (802.11ax) +===================== -The following examples will show valid configurations for WiFi-6 (2.4GHz) -and WiFi-6e (6GHz) Access-Points with the following characteristics: +The following examples configure Wi-Fi 6 (2.4 GHz) and Wi-Fi 6E (6 GHz) +:abbr:`APs (Access Points)` with the following parameters: -* Network ID (SSID) ``test.ax`` -* WPA passphrase ``super-dooper-secure-passphrase`` -* Use 802.11ax protocol -* Wireless channel ``11`` for 2.4GHz -* Wireless channel ``5`` for 6GHz +* Network ID (SSID): ``test.ax`` +* WPA passphrase: ``super-dooper-secure-passphrase`` +* Protocol: 802.11ax +* Wireless channel for 2.4 GHz: ``11`` +* Wireless channel for 6 GHz: ``5`` -Example Configuration: WiFi-6 at 2.4GHz ---------------------------------------- +Example configuration: Wi-Fi 6 at 2.4 GHz +----------------------------------------- -You may expect real throughputs around 10MBytes/s or higher in crowded areas. +You may expect real throughput around 10 MB/s or higher in crowded areas. .. code-block:: none @@ -768,7 +822,7 @@ You may expect real throughputs around 10MBytes/s or higher in crowded areas. set interfaces wireless wlan0 type access-point commit -Resulting in +Resulting configuration: .. code-block:: none @@ -824,13 +878,14 @@ Resulting in } } -Example Configuration: WiFi-6e at 6GHz --------------------------------------- +Example configuration: Wi-Fi 6E at 6 GHz +---------------------------------------- -You may expect real throughputs around 50MBytes/s to 150MBytes/s, -depending on obstructions by walls, water, metal or other materials -with high electro-magnetic dampening at 6GHz. Best results are achieved -with the AP being in the same room and in line-of-sight. +You may expect real throughput between 50 MB/s and 150 MB/s, depending on +obstructions from walls, water, metal, or other materials with high +electromagnetic damping at 6 GHz. + +Best results are achieved when the AP is in the same room and in line of sight. .. code-block:: none @@ -841,7 +896,7 @@ with the AP being in the same room and in line-of-sight. set interfaces wireless wlan0 capabilities he beamform single-user-beamformer set interfaces wireless wlan0 capabilities he bss-color 13 set interfaces wireless wlan0 capabilities he channel-set-width 134 - set interfaces wireless wlan0 capabilities he capabilities he center-channel-freq freq-1 15 + set interfaces wireless wlan0 capabilities he center-channel-freq freq-1 15 set interfaces wireless wlan0 channel 5 set interfaces wireless wlan0 description "802.11ax 6GHz" set interfaces wireless wlan0 mode ax @@ -858,7 +913,7 @@ with the AP being in the same room and in line-of-sight. set interfaces wireless wlan0 stationary-ap commit -Resulting in +Resulting configuration: .. code-block:: none @@ -913,9 +968,10 @@ Resulting in Intel AX200 =========== -The Intel AX200 card does not work out of the box in AP mode, see -https://unix.stackexchange.com/questions/598275/intel-ax200-ap-mode. You can -still put this card into AP mode using the following configuration: +The Intel AX200 card does not operate out of the box in ``access-point`` mode. + +You can still enable :abbr:`AP (Access Point)` functionality on this hardware +by applying the following configuration: .. stop_vyoslinter .. code-block:: none -- cgit v1.2.3 From a01c2c4ed50470141e7d7bbd31a3ab17418e9936 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Mon, 30 Mar 2026 14:11:57 +0300 Subject: Add TODO markers, fill placeholders, mark stub pages (#1802) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * chore: add TODO markers for 12 files needing cfgcmd/opcmd conversion Co-Authored-By: Claude Sonnet 4.6 * fix: fill TBD placeholder in flow-accounting, remove TBD in static routes Co-Authored-By: Claude Sonnet 4.6 * docs: add stub admonitions to 3 minimal pages Co-Authored-By: Claude Sonnet 4.6 * fix: replace non-RFC IP addresses and suppress false positives in linter Replace public IPs with RFC 5737 documentation addresses and add stop/start_vyoslinter markers for false positives (MAC addresses, OIDs, NAT64 well-known prefix). Co-Authored-By: Claude Sonnet 4.6 * fix: replace remaining non-RFC IPs and suppress MAC address false positive - Replace 8.8.8.8 (Google DNS) with 192.0.2.1 (RFC 5737) in: - docs/configexamples/ansible.rst (3 occurrences) - docs/configexamples/nmp.rst (1 occurrence) - docs/automation/terraform/terraformvSphere.rst (1 occurrence) - Wrap SHA-256 certificate fingerprint in openvpn-examples.rst with stop_vyoslinter/start_vyoslinter to suppress false-positive IPv6 flag Co-Authored-By: Claude Sonnet 4.6 * fix: wrap long lines to comply with 80-char line length limit Wrapped prose content exceeding 80 characters in 9 documentation files. Only RST prose and directive content was modified; code block contents were left untouched as they are exempt from the linter. Co-Authored-By: Claude Sonnet 4.6 * fix: wrap 2 remaining long lines for linter compliance Co-Authored-By: Claude Opus 4.6 (1M context) * fix: suppress linter for long URL reference in terraformvSphere.rst * fix: address Copilot review suggestions — broken links, typos, YAML indentation - Fix broken inline RST links split across lines in sysctl.rst, eve-ng.rst, oracle.rst (stub notes with VyOS documentation repository link) - Fix YAML indentation in both playbook code blocks in ansible.rst - Fix typo "VyoS" -> "VyOS" in ansible.rst - Fix typo "desition" -> "decision" in terraformvSphere.rst - Fix 4 occurrences of "Terrafom" -> "Terraform" in terraformvSphere.rst - Fix :doc: role split across two lines in openvpn-examples.rst - Wrap long paragraph in openconnect.rst to <=80 chars and remove unnecessary stop/start_vyoslinter markers Co-Authored-By: Claude Sonnet 4.6 * fix: resolve remaining linter failures — long lines and OID false positive Co-Authored-By: Claude Sonnet 4.6 * fix: revert 8.8.8.8 replacements, use stop_vyoslinter instead --------- Co-authored-by: Claude Sonnet 4.6 --- docs/automation/terraform/terraformvSphere.rst | 45 ++-- docs/configexamples/ansible.rst | 264 +++++++++++---------- docs/configexamples/fwall-and-bridge.rst | 12 +- docs/configexamples/nmp.rst | 18 +- docs/configexamples/site-2-site-cisco.rst | 10 +- docs/configuration/firewall/index.rst | 3 + docs/configuration/interfaces/openvpn-examples.rst | 21 +- docs/configuration/interfaces/vti.rst | 3 + docs/configuration/nat/nat64.rst | 7 + docs/configuration/nat/nat66.rst | 8 +- docs/configuration/policy/examples.rst | 3 + docs/configuration/protocols/static.rst | 35 +-- docs/configuration/service/snmp.rst | 3 + docs/configuration/system/flow-accounting.rst | 4 +- docs/configuration/system/sysctl.rst | 6 + .../vpn/ipsec/troubleshooting_ipsec.rst | 7 +- docs/configuration/vpn/openconnect.rst | 20 +- docs/configuration/vpn/rsa-keys.rst | 16 +- docs/installation/cloud/oracle.rst | 6 + docs/installation/virtual/eve-ng.rst | 6 + 20 files changed, 309 insertions(+), 188 deletions(-) (limited to 'docs/configuration/interfaces') diff --git a/docs/automation/terraform/terraformvSphere.rst b/docs/automation/terraform/terraformvSphere.rst index 5d39261b..5a9aa8f5 100644 --- a/docs/automation/terraform/terraformvSphere.rst +++ b/docs/automation/terraform/terraformvSphere.rst @@ -5,22 +5,27 @@ Deploying VyOS in the vSphere infrastructure ============================================ -With the help of Terraform, you can quickly deploy VyOS-based infrastructure in the vSphere. +With the help of Terraform, you can quickly deploy VyOS-based +infrastructure in the vSphere. Also we will make provisioning using Ansible. -In this case, we'll create the necessary files for Terraform and Ansible next using Terraform we'll create a single instance on the vSphere cloud and make provisioning using Ansible. +In this case, we'll create the necessary files for Terraform and +Ansible next using Terraform we'll create a single instance on the +vSphere cloud and make provisioning using Ansible. Preparation steps for deploying VyOS on vSphere ----------------------------------------------- -How to create a single instance and install your configuration using Terraform+Ansible+vSphere +How to create a single instance and install your configuration using +Terraform+Ansible+vSphere Step by step: vSphere - 1 Collect all data in to file "terraform.tfvars" and create resources for example "terraform" + 1 Collect all data in to file "terraform.tfvars" and create + resources for example "terraform" Terraform @@ -37,7 +42,10 @@ Terraform mkdir /root/vsphereterraform - 4 Copy all files into your Terraform project "/root/vsphereterraform" (vyos.tf, var.tf, terraform.tfvars,version.tf), more detailed see `Structure of files Terrafom for vSphere`_ + 4 Copy all files into your Terraform project + "/root/vsphereterraform" (vyos.tf, var.tf, terraform.tfvars, + version.tf), more detailed see + `Structure of files Terraform for vSphere`_ 5 Type the commands : @@ -56,13 +64,15 @@ Ansible 3 Create the folder for example /root/vsphereterraform/ - 4 Copy all files into your Ansible project "/root/vsphereterraform/" (ansible.cfg, instance.yml,"all"), more detailed see `Structure of files Ansible for vSphere`_ + 4 Copy all files into your Ansible project + "/root/vsphereterraform/" (ansible.cfg, instance.yml, "all"), + more detailed see `Structure of files Ansible for vSphere`_ Start -Type the commands on your Terrafom instance: +Type the commands on your Terraform instance: .. code-block:: none @@ -72,7 +82,8 @@ Type the commands on your Terrafom instance: yes -After executing all the commands you will have your VyOS instance on the vSphere with your configuration, it's a very convenient desition. +After executing all the commands you will have your VyOS instance on +the vSphere with your configuration, it's a very convenient decision. If you need to delete the instance please type the command: .. code-block:: none @@ -80,19 +91,19 @@ If you need to delete the instance please type the command: terraform destroy -Structure of files Terrafom for vSphere +Structure of files Terraform for vSphere --------------------------------------- .. code-block:: none . - ├── vyos.tf # The main script - ├── versions.tf # File for the changing version of Terraform. - ├── var.tf # File for the changing version of Terraform. - └── terraform.tfvars # The value of all variables (passwords, login, ip adresses and so on) + ├── vyos.tf # The main script + ├── versions.tf # File for the changing version of Terraform. + ├── var.tf # File for the changing version of Terraform. + └── terraform.tfvars # The value of all variables -File contents of Terrafom for vSphere +File contents of Terraform for vSphere ------------------------------------- vyos.tf @@ -373,7 +384,7 @@ instance.yml - name: "Configure general settings for the VyOS hosts group" vyos_config: lines: - - set system name-server 8.8.8.8 + - set system name-server 192.0.2.1 save: true @@ -396,5 +407,9 @@ Sourse files for vSphere from GIT All files about the article can be found here_ +.. stop_vyoslinter + .. _here: https://github.com/vyos/vyos-automation/tree/main/TerraformCloud/Vsphere_terraform_ansible_single_vyos_instance-main +.. start_vyoslinter + diff --git a/docs/configexamples/ansible.rst b/docs/configexamples/ansible.rst index 0f4dbbda..4241c706 100644 --- a/docs/configexamples/ansible.rst +++ b/docs/configexamples/ansible.rst @@ -9,7 +9,8 @@ Ansible example Setting up Ansible on a server running the Debian operating system. =================================================================== -In this example, we will set up a simple use of Ansible to configure multiple VyoS routers. +In this example, we will set up a simple use of Ansible to configure +multiple VyOS routers. We have four pre-configured routers with this configuration: Using the general schema for example: @@ -23,10 +24,10 @@ We have four pre-configured routers with this configuration: .. code-block:: none - set interfaces ethernet eth0 address dhcp - set service ssh - commit - save + set interfaces ethernet eth0 address dhcp + set service ssh + commit + save * vyos7 - 192.0.2.105 * vyos8 - 192.0.2.106 @@ -37,180 +38,189 @@ Install Ansible: ==================== .. code-block:: none - # apt-get install ansible - Do you want to continue? [Y/n] y + # apt-get install ansible + Do you want to continue? [Y/n] y Install Paramiko: ===================== .. code-block:: none - #apt-get install -y python3-paramiko + #apt-get install -y python3-paramiko Check the version: ================== .. code-block:: none - # ansible --version - ansible 2.10.8 - config file = None - configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] - ansible python module location = /usr/lib/python3/dist-packages/ansible - executable location = /usr/bin/ansible - python version = 3.9.2 (default, Feb 28 2021, 17:03:44) [GCC 10.2.1 20210110] + # ansible --version + ansible 2.10.8 + config file = None + configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] + ansible python module location = /usr/lib/python3/dist-packages/ansible + executable location = /usr/bin/ansible + python version = 3.9.2 (default, Feb 28 2021, 17:03:44) [GCC 10.2.1 20210110] Basic configuration of ansible.cfg: ======================================= .. code-block:: none - # nano /root/ansible.cfg - [defaults] - host_key_checking = no + # nano /root/ansible.cfg + [defaults] + host_key_checking = no Add all the VyOS hosts: ======================= .. code-block:: none - # nano /root/hosts - [vyos_hosts] - vyos7 ansible_ssh_host=192.0.2.105 - vyos8 ansible_ssh_host=192.0.2.106 - vyos9 ansible_ssh_host=192.0.2.107 - vyos10 ansible_ssh_host=192.0.2.108 + # nano /root/hosts + [vyos_hosts] + vyos7 ansible_ssh_host=192.0.2.105 + vyos8 ansible_ssh_host=192.0.2.106 + vyos9 ansible_ssh_host=192.0.2.107 + vyos10 ansible_ssh_host=192.0.2.108 Add general variables: ====================== .. code-block:: none - # mkdir /root/group_vars/ - # nano /root/group_vars/vyos_hosts - ansible_python_interpreter: /usr/bin/python3 - ansible_network_os: vyos - ansible_connection: network_cli - ansible_user: vyos - ansible_ssh_pass: vyos + # mkdir /root/group_vars/ + # nano /root/group_vars/vyos_hosts + ansible_python_interpreter: /usr/bin/python3 + ansible_network_os: vyos + ansible_connection: network_cli + ansible_user: vyos + ansible_ssh_pass: vyos Add a simple playbook with the tasks for each router: ===================================================== +.. stop_vyoslinter + .. code-block:: none - # nano /root/main.yml - - --- - - hosts: vyos_hosts - gather_facts: 'no' - tasks: - - name: Configure general settings for the vyos hosts group - vyos_config: - lines: - - set system name-server 8.8.8.8 - - set interfaces ethernet eth0 description '#WAN#' - - set interfaces ethernet eth1 description '#LAN#' - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable - - set system host-name {{ inventory_hostname }} - save: - true - + # nano /root/main.yml + + --- + - hosts: vyos_hosts + gather_facts: 'no' + tasks: + - name: Configure general settings for the vyos hosts group + vyos_config: + lines: + - set system name-server 8.8.8.8 + - set interfaces ethernet eth0 description '#WAN#' + - set interfaces ethernet eth1 description '#LAN#' + - set interfaces ethernet eth2 disable + - set interfaces ethernet eth3 disable + - set system host-name {{ inventory_hostname }} + save: true + +.. start_vyoslinter + Start the playbook: =================== .. code-block:: none - ansible-playbook -i hosts main.yml - PLAY [vyos_hosts] ************************************************************** - - TASK [Configure general settings for the vyos hosts group] ********************* - ok: [vyos9] - ok: [vyos10] - ok: [vyos7] - ok: [vyos8] - - PLAY RECAP ********************************************************************* - vyos10 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos7 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos8 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos9 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + ansible-playbook -i hosts main.yml + PLAY [vyos_hosts] ************************************************************** + + TASK [Configure general settings for the vyos hosts group] ********************* + ok: [vyos9] + ok: [vyos10] + ok: [vyos7] + ok: [vyos8] + + PLAY RECAP ********************************************************************* + vyos10 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos7 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos8 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos9 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 Check the result on the vyos10 router: ====================================== +.. stop_vyoslinter + .. code-block:: none - vyos@vyos10:~$ show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 192.0.2.108/24 u/u WAN - eth1 - u/u LAN - eth2 - A/D - eth3 - A/D - lo 127.0.0.1/8 u/u - ::1/128 - - vyos@vyos10:~$ sh configuration commands | grep 8.8.8.8 - set system name-server '8.8.8.8' + vyos@vyos10:~$ show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 192.0.2.108/24 u/u WAN + eth1 - u/u LAN + eth2 - A/D + eth3 - A/D + lo 127.0.0.1/8 u/u + ::1/128 + + vyos@vyos10:~$ sh configuration commands | grep 8.8.8.8 + set system name-server '8.8.8.8' + +.. start_vyoslinter The simple way without configuration of the hostname (one task for all routers): ================================================================================ +.. stop_vyoslinter + .. code-block:: none - # nano /root/hosts_v2 - [vyos_hosts_group] - vyos7 ansible_ssh_host=192.0.2.105 - vyos8 ansible_ssh_host=192.0.2.106 - vyos9 ansible_ssh_host=192.0.2.107 - vyos10 ansible_ssh_host=192.0.2.108 - [vyos_hosts_group:vars] - ansible_python_interpreter=/usr/bin/python3 - ansible_user=vyos - ansible_ssh_pass=vyos - ansible_network_os=vyos - ansible_connection=network_cli - - # nano /root/main_v2.yml - --- - - hosts: vyos_hosts_group - - connection: network_cli - gather_facts: 'no' - - tasks: - - name: Configure remote vyos_hosts_group - vyos_config: - lines: - - set system name-server 8.8.8.8 - - set interfaces ethernet eth0 description WAN - - set interfaces ethernet eth1 description LAN - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable - save: - true - + # nano /root/hosts_v2 + [vyos_hosts_group] + vyos7 ansible_ssh_host=192.0.2.105 + vyos8 ansible_ssh_host=192.0.2.106 + vyos9 ansible_ssh_host=192.0.2.107 + vyos10 ansible_ssh_host=192.0.2.108 + [vyos_hosts_group:vars] + ansible_python_interpreter=/usr/bin/python3 + ansible_user=vyos + ansible_ssh_pass=vyos + ansible_network_os=vyos + ansible_connection=network_cli + + # nano /root/main_v2.yml + --- + - hosts: vyos_hosts_group + connection: network_cli + gather_facts: 'no' + tasks: + - name: Configure remote vyos_hosts_group + vyos_config: + lines: + - set system name-server 8.8.8.8 + - set interfaces ethernet eth0 description WAN + - set interfaces ethernet eth1 description LAN + - set interfaces ethernet eth2 disable + - set interfaces ethernet eth3 disable + save: true + +.. start_vyoslinter + .. code-block:: none - - # ansible-playbook -i hosts_v2 main_v2.yml - - PLAY [vyos_hosts_group] ******************************************************** - - TASK [Configure remote vyos_hosts_group] *************************************** - ok: [vyos8] - ok: [vyos7] - ok: [vyos9] - ok: [vyos10] - - PLAY RECAP ********************************************************************* - vyos10 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos7 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos8 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - vyos9 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - - -In the next chapter of the example, we'll use Ansible with jinja2 templates and variables. + + # ansible-playbook -i hosts_v2 main_v2.yml + + PLAY [vyos_hosts_group] ******************************************************** + + TASK [Configure remote vyos_hosts_group] *************************************** + ok: [vyos8] + ok: [vyos7] + ok: [vyos9] + ok: [vyos10] + + PLAY RECAP ********************************************************************* + vyos10 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos7 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos8 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + vyos9 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 + + +In the next chapter of the example, we'll use Ansible with jinja2 +templates and variables. diff --git a/docs/configexamples/fwall-and-bridge.rst b/docs/configexamples/fwall-and-bridge.rst index 32c53fa5..34744a5d 100644 --- a/docs/configexamples/fwall-and-bridge.rst +++ b/docs/configexamples/fwall-and-bridge.rst @@ -353,12 +353,16 @@ For example, while a host tries to get an IP address from a DHCP server in br1 all DHCP discover are dropped, and in br2, we can see that DHCP offers from untrusted servers are dropped: +.. stop_vyoslinter + .. code-block:: none - vyos@bridge:~$ show log firewall bridge - Sep 17 14:22:35 kernel: [bri-NAM-br2-fwd-22-D]IN=eth7 OUT=eth5 MAC=50:00:00:09:00:00:50:00:00:04:00:00:08:00 SRC=10.2.2.199 DST=10.2.2.92 LEN=322 TOS=0x10 PREC=0x00 TTL=128 ID=0 DF PROTO=UDP SPT=67 DPT=68 LEN=302 - Sep 17 14:28:18 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 - Sep 17 14:28:19 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 + vyos@bridge:~$ show log firewall bridge + Sep 17 14:22:35 kernel: [bri-NAM-br2-fwd-22-D]IN=eth7 OUT=eth5 MAC=50:00:00:09:00:00:50:00:00:04:00:00:08:00 SRC=10.2.2.199 DST=10.2.2.92 LEN=322 TOS=0x10 PREC=0x00 TTL=128 ID=0 DF PROTO=UDP SPT=67 DPT=68 LEN=302 + Sep 17 14:28:18 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 + Sep 17 14:28:19 kernel: [bri-NAM-br1-pre-10-D]IN=eth3 OUT= MAC=ff:ff:ff:ff:ff:ff:00:50:79:66:68:0c:08:00 SRC=0.0.0.0 DST=255.255.255.255 LEN=392 TOS=0x10 PREC=0x00 TTL=16 ID=0 PROTO=UDP SPT=68 DPT=67 LEN=372 + +.. start_vyoslinter And with operational mode commands, we can check rules matchers, actions, and diff --git a/docs/configexamples/nmp.rst b/docs/configexamples/nmp.rst index 913e7107..318e9a91 100644 --- a/docs/configexamples/nmp.rst +++ b/docs/configexamples/nmp.rst @@ -7,19 +7,25 @@ NMP example ########### Consider how to quickly set up NMP and VyOS for monitoring. -NMP is multi-vendor network monitoring from 'SolarWinds' built to scale and expand with the needs of your network. +NMP is multi-vendor network monitoring from 'SolarWinds' built to +scale and expand with the needs of your network. Configuration 'VyOS' ==================== -First prepare our VyOS router for connection to NMP. We have to set up the SNMP protocol and connectivity between the router and NMP. +First prepare our VyOS router for connection to NMP. We have to set +up the SNMP protocol and connectivity between the router and NMP. + +.. stop_vyoslinter .. code-block:: none - set interfaces ethernet eth0 address 'dhcp' - set system name-server '8.8.8.8' - set service snmp community router authorization 'test' - set service snmp community router network '0.0.0.0/0' + set interfaces ethernet eth0 address 'dhcp' + set system name-server '8.8.8.8' + set service snmp community router authorization 'test' + set service snmp community router network '0.0.0.0/0' + +.. start_vyoslinter Configuration 'NMP' diff --git a/docs/configexamples/site-2-site-cisco.rst b/docs/configexamples/site-2-site-cisco.rst index 96e48d07..5b5f1fd7 100644 --- a/docs/configexamples/site-2-site-cisco.rst +++ b/docs/configexamples/site-2-site-cisco.rst @@ -28,7 +28,7 @@ VyOS set interfaces tunnel tun1 ip adjust-mss '1336' set interfaces tunnel tun1 mtu '1376' set interfaces tunnel tun1 remote '10.1.1.6' - set interfaces tunnel tun1 source-address '88.2.2.1' + set interfaces tunnel tun1 source-address '198.51.100.1' - IPsec: @@ -59,9 +59,9 @@ VyOS set vpn ipsec site-to-site peer cisco_hub connection-type 'initiate' set vpn ipsec site-to-site peer cisco_hub default-esp-group 'e1' set vpn ipsec site-to-site peer cisco_hub ike-group 'i1' - set vpn ipsec site-to-site peer cisco_hub local-address '88.2.2.1' + set vpn ipsec site-to-site peer cisco_hub local-address '198.51.100.1' set vpn ipsec site-to-site peer cisco_hub remote-address '10.1.1.6' - set vpn ipsec site-to-site peer cisco_hub tunnel 1 local prefix '88.2.2.1/32' + set vpn ipsec site-to-site peer cisco_hub tunnel 1 local prefix '198.51.100.1/32' set vpn ipsec site-to-site peer cisco_hub tunnel 1 protocol 'gre' set vpn ipsec site-to-site peer cisco_hub tunnel 1 remote prefix '10.1.1.6/32' set vpn ipsec site-to-site peer cisco_hub virtual-address '0.0.0.0' @@ -141,7 +141,7 @@ Verification --------- ---------- --- ----------- eth0 - u/u eth1 - u/u - eth2 88.2.2.1/24 u/u + eth2 198.51.100.1/24 u/u eth3 172.16.1.2/24 u/u lo 127.0.0.1/8 u/u ::1/128 @@ -157,7 +157,7 @@ Verification IPv4 Crypto IKEv2 SA Tunnel-id Local Remote fvrf/ivrf Status - 5 10.1.1.6/4500 88.2.2.1/4500 none/none READY + 5 10.1.1.6/4500 198.51.100.1/4500 none/none READY Encr: AES-CBC, keysize: 256, PRF: SHA256, Hash: SHA256, DH Grp:5, Auth sign: PSK, Auth verify: PSK Life/Active Time: 86400/2694 sec CE id: 0, Session-id: 2 diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index a5b88839..79d59563 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -4,6 +4,9 @@ Firewall ######## +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + .. warning:: Due to a race condition that can lead to a failure during boot process, all interfaces are initialized before firewall is configured. This leads to a situation where the system is open to all traffic, and can be diff --git a/docs/configuration/interfaces/openvpn-examples.rst b/docs/configuration/interfaces/openvpn-examples.rst index 46409975..34cabddf 100644 --- a/docs/configuration/interfaces/openvpn-examples.rst +++ b/docs/configuration/interfaces/openvpn-examples.rst @@ -2,6 +2,9 @@ Site-to-site ============ +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + OpenVPN is popular for client-server setups, but its site-to-site mode is less common and often not supported by router appliances. Despite limited support, it is effective for quickly establishing tunnels between routers. @@ -29,9 +32,9 @@ In both cases, we will use the following settings: * The ``persistent-tunnel`` directive allows us to configure tunnel-related attributes, such as firewall policy, as we would on any standard network interface. -* If known, the remote router's IP address can be configured using the - ``remote-host`` directive. If unknown, it can be omitted. We assume the remote - router has a dynamic IP address. +* If known, the remote router's IP address can be configured using + the ``remote-host`` directive. If unknown, it can be omitted. + We assume the remote router has a dynamic IP address. .. figure:: /_static/images/openvpn_site2site_diagram.jpg @@ -87,11 +90,15 @@ You do **not** need to copy the certificate to the other router. Instead, retrieve its SHA-256 fingerprint. Since OpenVPN currently supports only SHA-256 fingerprints, use the following command: +.. stop_vyoslinter + .. code-block:: none vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79 +.. start_vyoslinter + .. note:: Certificate names are arbitrary. While ``openvpn-local`` and ``openvpn-remote`` are used here, you may choose any names. @@ -456,7 +463,7 @@ Check the tunnel status: Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since ----------- ------------------ ----------- ---------------- ---------- ---------- ------------------- - client1 172.110.12.54:33166 10.23.1.10 172.18.201.10:1194 3.4 KB 3.4 KB 2024-06-11 12:07:25 + client1 172.16.12.54:33166 10.23.1.10 172.18.201.10:1194 3.4 KB 3.4 KB 2024-06-11 12:07:25 @@ -639,7 +646,11 @@ below: } } -For a detailed example, refer to :doc:`OpenVPN with LDAP`. +.. stop_vyoslinter + +For a detailed example, refer to :doc:`OpenVPN with LDAP `. + +.. start_vyoslinter Multi-factor authentication =========================== diff --git a/docs/configuration/interfaces/vti.rst b/docs/configuration/interfaces/vti.rst index 1704b9d1..9c2dc1eb 100644 --- a/docs/configuration/interfaces/vti.rst +++ b/docs/configuration/interfaces/vti.rst @@ -4,6 +4,9 @@ VTI - Virtual Tunnel Interface ############################## +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + Set Virtual Tunnel Interface .. code-block:: none diff --git a/docs/configuration/nat/nat64.rst b/docs/configuration/nat/nat64.rst index e8a3a0e6..8608da9f 100644 --- a/docs/configuration/nat/nat64.rst +++ b/docs/configuration/nat/nat64.rst @@ -4,6 +4,9 @@ NAT64 ##### +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + :abbr:`NAT64 (IPv6-to-IPv4 Prefix Translation)` is a critical component in modern networking, facilitating communication between IPv6 and IPv4 networks. This documentation outlines the setup, configuration, and usage of the NAT64 @@ -69,6 +72,8 @@ NAT64 client configuration: Test from the IPv6 only client: +.. stop_vyoslinter + .. code-block:: none vyos@r1:~$ ping 64:ff9b::192.0.2.1 count 2 @@ -79,3 +84,5 @@ Test from the IPv6 only client: --- 64:ff9b::192.0.2.1 ping statistics --- 2 packets transmitted, 2 received, 0% packet loss, time 1023ms rtt min/avg/max/mdev = 0.351/0.362/0.373/0.011 ms + +.. start_vyoslinter diff --git a/docs/configuration/nat/nat66.rst b/docs/configuration/nat/nat66.rst index 42f63fc9..d7d8e8be 100644 --- a/docs/configuration/nat/nat66.rst +++ b/docs/configuration/nat/nat66.rst @@ -4,6 +4,9 @@ NAT66(NPTv6) ############ +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + :abbr:`NPTv6 (IPv6-to-IPv6 Network Prefix Translation)` is an address translation technology based on IPv6 networks, used to convert an IPv6 address prefix in an IPv6 message into another IPv6 address prefix. @@ -151,8 +154,9 @@ R2: set service router-advert interface br1 prefix ::/0 -Use the following topology to translate internal user local addresses (``fc::/7``) -to DHCPv6-PD provided prefixes from an ISP connected to a VyOS HA pair. +Use the following topology to translate internal user local addresses +(``fc::/7``) to DHCPv6-PD provided prefixes from an ISP connected to +a VyOS HA pair. .. figure:: /_static/images/vyos_1_5_nat66_dhcpv6_wdummy.png :alt: VyOS NAT66 DHCPv6 using a dummy interface diff --git a/docs/configuration/policy/examples.rst b/docs/configuration/policy/examples.rst index d822d839..11c1d625 100644 --- a/docs/configuration/policy/examples.rst +++ b/docs/configuration/policy/examples.rst @@ -2,6 +2,9 @@ BGP Example ########### +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + **Policy definition:** .. code-block:: none diff --git a/docs/configuration/protocols/static.rst b/docs/configuration/protocols/static.rst index 3e3eb47b..e9016abc 100644 --- a/docs/configuration/protocols/static.rst +++ b/docs/configuration/protocols/static.rst @@ -70,10 +70,12 @@ IPv4 BFD Configure a static route for `` using gateway `
` and use the gateway address as BFD peer destination address. -.. cfgcmd:: set protocols static route next-hop
bfd profile +.. cfgcmd:: set protocols static route next-hop
+ bfd profile - Configure a static route for `` using gateway `
` and use the - gateway address as BFD peer destination address with BFD profile ``. + Configure a static route for `` using gateway `
` + and use the gateway address as BFD peer destination address with + BFD profile ``. .. cfgcmd:: set protocols static route next-hop
bfd multi-hop source-address @@ -153,10 +155,12 @@ IPv6 Unicast Routes .. note:: Routes with a distance of 255 are effectively disabled and not installed into the kernel. -.. cfgcmd:: set protocols static route6 next-hop
segments +.. cfgcmd:: set protocols static route6 next-hop
+ segments - It is possible to specify a static route for ipv6 prefixes using an SRv6 segments - instruction. The `/` separator can be used to specify multiple segment instructions. + It is possible to specify a static route for ipv6 prefixes using + an SRv6 segments instruction. The `/` separator can be used to + specify multiple segment instructions. Example: @@ -202,8 +206,9 @@ IPv6 Interface Routes .. cfgcmd:: set protocols static route6 interface segments - It is possible to specify a static route for ipv6 prefixes using an SRv6 segments - instruction. The `/` separator can be used to specify multiple segment instructions. + It is possible to specify a static route for ipv6 prefixes using + an SRv6 segments instruction. The `/` separator can be used to + specify multiple segment instructions. Example: @@ -219,13 +224,15 @@ IPv6 BFD Configure a static route for `` using gateway `
` and use the gateway address as BFD peer destination address. -.. cfgcmd:: set protocols static route6 next-hop
bfd profile +.. cfgcmd:: set protocols static route6 next-hop
+ bfd profile - Configure a static route for `` using gateway `
` and use the - gateway address as BFD peer destination address with BFD profile ``. + Configure a static route for `` using gateway `
` + and use the gateway address as BFD peer destination address with + BFD profile ``. -.. cfgcmd:: set protocols static route6 next-hop
bfd multi-hop - source-address +.. cfgcmd:: set protocols static route6 next-hop
+ bfd multi-hop source-address Configure a static route for `` using gateway `
` and use the gateway address as BFD peer destination address with source address @@ -271,7 +278,5 @@ IPv6 Blackhole Routes Alternate Routing Tables ************************ -TBD - Alternate routing tables are used with policy based routing by utilizing :ref:`vrf`. diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/snmp.rst index b444ab85..9e91cc50 100644 --- a/docs/configuration/service/snmp.rst +++ b/docs/configuration/service/snmp.rst @@ -4,6 +4,9 @@ SNMP #### +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + :abbr:`SNMP (Simple Network Management Protocol)` is an Internet Standard protocol for collecting and organizing information about managed devices on IP networks and for modifying that information to change device behavior. diff --git a/docs/configuration/system/flow-accounting.rst b/docs/configuration/system/flow-accounting.rst index a339df75..cb18839a 100644 --- a/docs/configuration/system/flow-accounting.rst +++ b/docs/configuration/system/flow-accounting.rst @@ -84,7 +84,9 @@ CLI command. You may disable using the local in-memory table with the command: .. cfgcmd:: set system flow-accounting syslog-facility - TBD + Configure the syslog facility used for flow-accounting log messages. + Available facilities follow standard syslog conventions (e.g., + ``daemon``, ``local0`` through ``local7``). Flow Export ----------- diff --git a/docs/configuration/system/sysctl.rst b/docs/configuration/system/sysctl.rst index 06e15031..d1398822 100644 --- a/docs/configuration/system/sysctl.rst +++ b/docs/configuration/system/sysctl.rst @@ -4,6 +4,12 @@ Sysctl ###### +.. note:: This page is a stub and needs expansion. + Contributions welcome via the + VyOS `documentation repository`_. + +.. _documentation repository: https://github.com/vyos/vyos-documentation + This chapeter describes how to configure kernel parameters at runtime. ``sysctl`` is used to modify kernel parameters at runtime. The parameters diff --git a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst index fdeb347d..8494f0ea 100644 --- a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst +++ b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst @@ -4,6 +4,9 @@ Troubleshooting Site-to-Site VPN IPsec ###################################### +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + ************ Introduction ************ @@ -286,8 +289,8 @@ The reason of this problem is showed on the responder side. Jun 23 08:16:12 charon-systemd[2440]: no acceptable proposal found Jun 23 08:16:12 charon[2440]: 01[IKE] failed to establish CHILD_SA, keeping IKE_SA -Encryption **AES_CBC_128** is configured in IKE policy on the responder but **AES_CBC_256** -is configured on the initiator side. +Encryption **AES_CBC_128** is configured in IKE policy on the +responder but **AES_CBC_256** is configured on the initiator side. Prefixes in Policies Mismatch ============================= diff --git a/docs/configuration/vpn/openconnect.rst b/docs/configuration/vpn/openconnect.rst index 11824e50..d5c76e3e 100644 --- a/docs/configuration/vpn/openconnect.rst +++ b/docs/configuration/vpn/openconnect.rst @@ -4,6 +4,9 @@ OpenConnect ########### +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + OpenConnect-compatible server feature has been available since Equuleus (1.3). Openconnect VPN supports SSL connection and offers full network access. SSL VPN network extension connects the end-user system to the corporate network with @@ -81,9 +84,22 @@ For generating an OTP key in VyOS, you can use the CLI command User Certificate Authentication =============================== -You can configure users to be authenticated by certificate by setting the authentication mode to certificate, and defining what field (by OID) in the certificate will be used to identify the username. Two pre-defined shortcuts for Common Name (OID 2.5.4.3) and User ID (OID 0.9.2342.19200300.100.1.1) have been provide as cn or uid. Otherwise a specific OID value must be provided. +You can configure users to be authenticated by certificate by setting +the authentication mode to certificate, and defining what field (by OID) +in the certificate will be used to identify the username. Two pre-defined + +.. stop_vyoslinter + +shortcuts for Common Name (OID 2.5.4.3) and User ID +(OID 0.9.2342.19200300.100.1.1) have been provided as cn or uid. -The user's certificate must be signed by the certificate authority defined in the configuration for it to be validated for authentication. +.. start_vyoslinter + +Otherwise a specific OID value must be provided. + +The user's certificate must be signed by the certificate authority +defined in the configuration for it to be validated for +authentication. .. code-block:: none diff --git a/docs/configuration/vpn/rsa-keys.rst b/docs/configuration/vpn/rsa-keys.rst index 0508522f..ce9aa720 100644 --- a/docs/configuration/vpn/rsa-keys.rst +++ b/docs/configuration/vpn/rsa-keys.rst @@ -2,6 +2,10 @@ ######## RSA-Keys ######## + +.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd + directives for command coverage tracking. + RSA can be used for services such as key exchanges and for encryption purposes. To make IPSec work with dynamic address on one/both sides, we will have to use RSA keys for authentication. They are very fast and easy to setup. @@ -51,10 +55,14 @@ On the RIGHT: Now you are ready to setup IPsec. The key points: -1. Since both routers do not know their effective public addresses, we set the local-address of the peer to "any". -2. On the initiator, we set the peer address to its public address, but on the responder we only set the id. -3. On the initiator, we need to set the remote-id option so that it can identify IKE traffic from the responder correctly. -4. On the responder, we need to set the local id so that initiator can know who's talking to it for the point #3 to work. +1. Since both routers do not know their effective public addresses, + we set the local-address of the peer to "any". +2. On the initiator, we set the peer address to its public address, + but on the responder we only set the id. +3. On the initiator, we need to set the remote-id option so that it + can identify IKE traffic from the responder correctly. +4. On the responder, we need to set the local id so that initiator + can know who's talking to it for the point #3 to work. On the LEFT (static address): diff --git a/docs/installation/cloud/oracle.rst b/docs/installation/cloud/oracle.rst index 1d02335b..f5e03329 100644 --- a/docs/installation/cloud/oracle.rst +++ b/docs/installation/cloud/oracle.rst @@ -4,6 +4,12 @@ Oracle ###### +.. note:: This page is a stub and needs expansion. + Contributions welcome via the + VyOS `documentation repository`_. + +.. _documentation repository: https://github.com/vyos/vyos-documentation + .. stop_vyoslinter References ---------- diff --git a/docs/installation/virtual/eve-ng.rst b/docs/installation/virtual/eve-ng.rst index 855daeb0..0dd07db8 100644 --- a/docs/installation/virtual/eve-ng.rst +++ b/docs/installation/virtual/eve-ng.rst @@ -4,6 +4,12 @@ EVE-NG ###### +.. note:: This page is a stub and needs expansion. + Contributions welcome via the + VyOS `documentation repository`_. + +.. _documentation repository: https://github.com/vyos/vyos-documentation + References ========== -- cgit v1.2.3 From 62619024cfc7497a2f1f444a5a7012cb5d8d3302 Mon Sep 17 00:00:00 2001 From: LiudmylaNad Date: Fri, 3 Apr 2026 15:26:31 +0200 Subject: DOC: Proofread wwan.rst (#1812) --- docs/configuration/interfaces/wwan.rst | 74 ++++++++++++++++++---------------- 1 file changed, 39 insertions(+), 35 deletions(-) (limited to 'docs/configuration/interfaces') diff --git a/docs/configuration/interfaces/wwan.rst b/docs/configuration/interfaces/wwan.rst index b4b6a9ce..7ab3ac74 100644 --- a/docs/configuration/interfaces/wwan.rst +++ b/docs/configuration/interfaces/wwan.rst @@ -1,15 +1,15 @@ -:lastproofread: 2024-07-04 +:lastproofread: 2026-03-30 .. _wwan-interface: -################################# -WWAN - Wireless Wide-Area-Network -################################# +#### +WWAN +#### -The Wireless Wide-Area-Network interface provides access (through a wireless -modem/wwan) to wireless networks provided by various cellular providers. +:abbr:`WWAN (Wireless Wide Area Network)` interfaces provide access to cellular +networks via a cellular modem or card. -VyOS uses the `interfaces wwan` subsystem for configuration. +Configure these interfaces under the ``interfaces wwan`` node. ************* Configuration @@ -64,14 +64,18 @@ Common interface configuration :var0: wwan :var1: wwan0 -WirelessModem (WWAN) options -============================ +WWAN options +============ .. cfgcmd:: set interfaces wwan apn - Every WWAN connection requires an :abbr:`APN (Access Point Name)` which is - used by the client to dial into the ISPs network. This is a mandatory - parameter. Contact your Service Provider for correct APN. + **Configure the** :abbr:`APN (Access Point Name)` **for the WWAN connection.** + + Every WWAN connection requires an :abbr:`APN (Access Point Name)` to connect to + the cellular network. + + This parameter is mandatory. Contact your service provider for the correct + :abbr:`APN (Access Point Name)`. ********* @@ -80,7 +84,8 @@ Operation .. opcmd:: show interfaces wwan - Show detailed information on given `` + Show the operational status and traffic statistics for the specified WWAN + interface. .. code-block:: none @@ -99,7 +104,7 @@ Operation .. opcmd:: show interfaces wwan summary - Show detailed information summary on given `` + Show WWAN module hardware characteristics and connection information. .. code-block:: none @@ -166,7 +171,7 @@ Operation .. opcmd:: show interfaces wwan capabilities - Show WWAN module hardware capabilities. + Show WWAN module radio capabilities. .. code-block:: none @@ -181,7 +186,7 @@ Operation .. opcmd:: show interfaces wwan firmware - Show WWAN module firmware. + Show WWAN module firmware information. .. code-block:: none @@ -208,7 +213,7 @@ Operation .. opcmd:: show interfaces wwan imsi - Show WWAN module IMSI. + Show the IMSI of the associated SIM card. .. code-block:: none @@ -226,7 +231,7 @@ Operation .. opcmd:: show interfaces wwan msisdn - Show WWAN module MSISDN. + Show the MSISDN of the associated SIM card. .. code-block:: none @@ -244,7 +249,7 @@ Operation .. opcmd:: show interfaces wwan signal - Show WWAN module signal strength. + Show signal information for the cellular connection. .. code-block:: none @@ -293,20 +298,20 @@ Operation Example ******* -The following example is based on a Sierra Wireless MC7710 miniPCIe card (only -the form factor in reality it runs UBS) and Deutsche Telekom as ISP. The card -is assembled into a :ref:`pc-engines-apu4`. +The following example shows how to configure a cellular connection using a +Sierra Wireless MC7710 miniPCIe card that operates over USB despite its form +factor. The card is installed in a :ref:`pc-engines-apu4`. .. code-block:: none set interfaces wwan wwan0 apn 'internet.telekom' set interfaces wwan wwan0 address 'dhcp' -***************** -Supported Modules -***************** +****************** +Supported hardware +****************** -The following hardware modules have been tested successfully in an +The following WWAN modules have been successfully tested with a :ref:`pc-engines-apu4` board: * Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) @@ -318,19 +323,18 @@ The following hardware modules have been tested successfully in an * HP LT4120 Snapdragon X5 LTE *************** -Firmware Update +Firmware update *************** -All available WWAN cards have a built-in, reprogrammable firmware. Most vendors -provide regular updates to firmware used in the baseband chip. +WWAN modules include reprogrammable firmware, and most vendors regularly +provide updates for it. -As VyOS makes use of the QMI interface to connect to the WWAN modem cards, the -firmware can be reprogrammed. +Since VyOS communicates with these devices via the QMI interface, you can +update firmware directly within the system using the ``qmi-firmware-update`` +utility. -To update the firmware, VyOS also ships the `qmi-firmware-update` binary. To -upgrade the firmware of an e.g. Sierra Wireless MC7710 module to the firmware -provided in the file ``9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe`` -use the following command: +The following example shows how to update the firmware for a Sierra Wireless +MC7710 module using the provided .cwe file. .. code-block:: bash -- cgit v1.2.3 From b682f2e30b61f100e460ba81bb8ce6bf30464f3d Mon Sep 17 00:00:00 2001 From: LiudmylaNad Date: Fri, 3 Apr 2026 15:27:41 +0200 Subject: DOC: Add CLIs and their description for VTIs (#1811) --- docs/configuration/interfaces/vti.rst | 102 +++++++++++++++++++++++++++++----- 1 file changed, 87 insertions(+), 15 deletions(-) (limited to 'docs/configuration/interfaces') diff --git a/docs/configuration/interfaces/vti.rst b/docs/configuration/interfaces/vti.rst index 9c2dc1eb..e45c17d9 100644 --- a/docs/configuration/interfaces/vti.rst +++ b/docs/configuration/interfaces/vti.rst @@ -1,20 +1,92 @@ .. _vti-interface: ############################## -VTI - Virtual Tunnel Interface +VTI (virtual tunnel interface) ############################## -.. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd - directives for command coverage tracking. +:abbr:`VTIs (virtual tunnel interfaces)` let you create secure, encrypted +tunnels between private networks or hosts across public infrastructure, such as +the Internet. They operate alongside an underlying IPsec tunnel, which handles +encapsulation and encryption, while VTIs function exclusively as routing +interfaces. -Set Virtual Tunnel Interface +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: /_include/interface-address.txt + :var0: vti + :var1: vti0 + +.. cmdinclude:: /_include/interface-description.txt + :var0: vti + :var1: vti0 + +.. cmdinclude:: /_include/interface-disable.txt + :var0: vti + :var1: vti0 + +.. cmdinclude:: /_include/interface-ip.txt + :var0: vti + :var1: vti0 + +.. cmdinclude:: /_include/interface-ipv6.txt + :var0: vti + :var1: vti0 + +.. cmdinclude:: /_include/interface-mtu.txt + :var0: vti + :var1: vti0 + +.. cfgcmd:: set interfaces vti mirror egress + + Configure mirroring of outgoing traffic from the specified VTI to the + designated monitor interface. + +.. cfgcmd:: set interfaces vti mirror ingress + + Configure mirroring of incoming traffic from the specified VTI to the + designated monitor interface. + +.. cfgcmd:: set interfaces vti redirect + + Enable redirection of incoming packets to the specified interface. + +.. cmdinclude:: /_include/interface-vrf.txt + :var0: vti + :var1: vti0 + +********* +Operation +********* + +.. opcmd:: show interfaces vti + + Show the operational status and traffic statistics for the specified VTI. + +.. opcmd:: show interfaces vti brief + + Show a brief operational status summary for the specified VTI. + + +******* +Example +******* + +**Configure a VTI** + +Assign IPv4 and IPv6 addresses to the VTI, along with a brief description: .. code-block:: none set interfaces vti vti0 address 192.168.2.249/30 set interfaces vti vti0 address 2001:db8:2::249/64 + set interfaces vti vti0 description "Description" -Results in: +Resulting configuration: .. code-block:: none @@ -25,19 +97,19 @@ Results in: description "Description" } -.. warning:: When using site-to-site IPsec with VTI interfaces, - be sure to disable route autoinstall +.. warning:: When configuring site-to-site IPsec with VTIs, ensure that route + autoinstall is disabled. .. code-block:: none set vpn ipsec options disable-route-autoinstall -More details about the IPsec and VTI issue and option disable-route-autoinstall -https://blog.vyos.io/vyos-1-dot-2-0-development-news-in-july +For more information about the IPsec and VTI issue, as well as the +``disable-route-autoinstall`` option, see: +https://blog.vyos.io/vyos-1-dot-2-0-development-news-in-july. -The root cause of the problem is that for VTI tunnels to work, their traffic -selectors have to be set to 0.0.0.0/0 for traffic to match the tunnel, even -though actual routing decision is made according to netfilter marks. Unless -route insertion is disabled entirely, StrongSWAN thus mistakenly inserts a -default route through the VTI peer address, which makes all traffic routed -to nowhere. \ No newline at end of file +The root cause of the problem is that VTI tunnels require their traffic +selectors to be set to ``0.0.0.0/0`` for traffic to match the tunnel, even +though routing decisions are based on netfilter marks. Unless route insertion +is explicitly disabled, strongSWAN incorrectly inserts a default route through +the VTI peer address, causing all traffic to be misrouted. -- cgit v1.2.3 From b5858598e32441560da34a4a62dc687fe4df9c16 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Fri, 10 Apr 2026 21:26:49 +0300 Subject: docs: standardize RST heading hierarchy to # overline across 21 files (#1827) Normalize top-level page headings from = or * underline-only to # overline+underline format, following RST/Sphinx best practices for consistent heading hierarchy. Co-authored-by: Claude Opus 4.6 (1M context) --- docs/automation/vyos-ansible.rst | 3 ++- docs/automation/vyos-napalm.rst | 3 ++- docs/automation/vyos-netmiko.rst | 3 ++- docs/automation/vyos-pyvyos.rst | 3 ++- docs/configexamples/azure-vpn-bgp.rst | 3 ++- docs/configexamples/azure-vpn-dual-bgp.rst | 3 ++- docs/configexamples/firewall.rst | 6 ++++-- docs/configexamples/fwall-and-bridge.rst | 3 ++- docs/configexamples/fwall-and-vrf.rst | 3 ++- docs/configexamples/index.rst | 3 ++- docs/configexamples/policy-based-ipsec-and-firewall.rst | 3 ++- docs/configexamples/site-2-site-cisco.rst | 3 ++- docs/configexamples/wan-load-balancing.rst | 3 ++- docs/configexamples/zone-policy.rst | 3 ++- docs/configuration/interfaces/tunnel.rst | 3 ++- docs/configuration/service/mdns.rst | 3 ++- docs/configuration/system/lcd.rst | 4 ++-- docs/installation/update.rst | 3 ++- docs/installation/virtual/docker.rst | 4 ++-- docs/installation/virtual/libvirt.rst | 4 ++-- docs/installation/virtual/proxmox.rst | 4 ++-- 21 files changed, 44 insertions(+), 26 deletions(-) (limited to 'docs/configuration/interfaces') diff --git a/docs/automation/vyos-ansible.rst b/docs/automation/vyos-ansible.rst index 0ebcb924..993d1b21 100644 --- a/docs/automation/vyos-ansible.rst +++ b/docs/automation/vyos-ansible.rst @@ -2,8 +2,9 @@ .. _vyos-ansible: +####### Ansible -======= +####### VyOS supports configuration via ansible. Need to install ``ansible`` and ``python3-paramiko`` module diff --git a/docs/automation/vyos-napalm.rst b/docs/automation/vyos-napalm.rst index 75e20b3c..dc4d154f 100644 --- a/docs/automation/vyos-napalm.rst +++ b/docs/automation/vyos-napalm.rst @@ -2,8 +2,9 @@ .. _vyos-napalm: +###### Napalm -====== +###### VyOS supports some napalm_ functions for configuration and op-mode. It requires more tests. diff --git a/docs/automation/vyos-netmiko.rst b/docs/automation/vyos-netmiko.rst index 075b0f34..53082e52 100644 --- a/docs/automation/vyos-netmiko.rst +++ b/docs/automation/vyos-netmiko.rst @@ -2,8 +2,9 @@ .. _vyos-netmiko: +####### Netmiko -======= +####### VyOS supports configuration via netmiko_. It requires to install ``python3-netmiko`` module. diff --git a/docs/automation/vyos-pyvyos.rst b/docs/automation/vyos-pyvyos.rst index 948534f8..c178aeb6 100644 --- a/docs/automation/vyos-pyvyos.rst +++ b/docs/automation/vyos-pyvyos.rst @@ -2,8 +2,9 @@ .. _vyos-pyvyos: +###### pyvyos -====== +###### pyvyos is a Python library designed for interacting with VyOS devices through their API. This documentation is intended to guide you in using pyvyos for diff --git a/docs/configexamples/azure-vpn-bgp.rst b/docs/configexamples/azure-vpn-bgp.rst index 03d637d8..597a4d15 100644 --- a/docs/configexamples/azure-vpn-bgp.rst +++ b/docs/configexamples/azure-vpn-bgp.rst @@ -2,8 +2,9 @@ .. _examples-azure-vpn-bgp: +############################################################ Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) ------------------------------------------------------------- +############################################################ This guide shows an example of a route-based IKEv2 site-to-site VPN to Azure using VTI and BGP for dynamic routing updates. diff --git a/docs/configexamples/azure-vpn-dual-bgp.rst b/docs/configexamples/azure-vpn-dual-bgp.rst index d37aa85c..04a6a631 100644 --- a/docs/configexamples/azure-vpn-dual-bgp.rst +++ b/docs/configexamples/azure-vpn-dual-bgp.rst @@ -2,8 +2,9 @@ .. _examples-azure-vpn-dual-bgp: +###################################################################### Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) ----------------------------------------------------------------------- +###################################################################### This guide shows an example of a redundant (active-active) route-based IKEv2 site-to-site VPN to Azure using VTI diff --git a/docs/configexamples/firewall.rst b/docs/configexamples/firewall.rst index a1ad7e19..6968eb04 100644 --- a/docs/configexamples/firewall.rst +++ b/docs/configexamples/firewall.rst @@ -1,9 +1,11 @@ :lastproofread: 2024-09-11 +################# Firewall Examples -================= +################# -This section contains examples of firewall configurations for various deployments. +This section contains examples of firewall configurations for various +deployments. .. toctree:: :maxdepth: 2 diff --git a/docs/configexamples/fwall-and-bridge.rst b/docs/configexamples/fwall-and-bridge.rst index 34744a5d..134dd6c0 100644 --- a/docs/configexamples/fwall-and-bridge.rst +++ b/docs/configexamples/fwall-and-bridge.rst @@ -1,7 +1,8 @@ :lastproofread: 2024-09-11 +########################### Bridge and firewall example ---------------------------- +########################### Scenario and requirements ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/configexamples/fwall-and-vrf.rst b/docs/configexamples/fwall-and-vrf.rst index 38663a18..992b625e 100644 --- a/docs/configexamples/fwall-and-vrf.rst +++ b/docs/configexamples/fwall-and-vrf.rst @@ -1,5 +1,6 @@ +######################## VRF and firewall example ------------------------- +######################## Scenario and requirements ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/configexamples/index.rst b/docs/configexamples/index.rst index 7f173b4a..b5985d7f 100644 --- a/docs/configexamples/index.rst +++ b/docs/configexamples/index.rst @@ -1,7 +1,8 @@ .. _examples: +######################## Configuration Blueprints -======================== +######################## This chapter contains various configuration examples: diff --git a/docs/configexamples/policy-based-ipsec-and-firewall.rst b/docs/configexamples/policy-based-ipsec-and-firewall.rst index 60f8b888..5d98e944 100644 --- a/docs/configexamples/policy-based-ipsec-and-firewall.rst +++ b/docs/configexamples/policy-based-ipsec-and-firewall.rst @@ -1,8 +1,9 @@ .. _examples-policy-based-ipsec-and-firewall: +######################################################## Policy-Based Site-to-Site VPN and Firewall Configuration --------------------------------------------------------- +######################################################## This guide shows an example policy-based IKEv2 site-to-site VPN between two VyOS routers, and firewall configuration. diff --git a/docs/configexamples/site-2-site-cisco.rst b/docs/configexamples/site-2-site-cisco.rst index 5b5f1fd7..e8322002 100644 --- a/docs/configexamples/site-2-site-cisco.rst +++ b/docs/configexamples/site-2-site-cisco.rst @@ -1,7 +1,8 @@ .. _examples-site-2-site-cisco: +############################################# Site-to-Site IPSec VPN to Cisco using FlexVPN ---------------------------------------------- +############################################# This guide shows a sample configuration for FlexVPN site-to-site Internet Protocol Security (IPsec)/Generic Routing Encapsulation (GRE) tunnel. diff --git a/docs/configexamples/wan-load-balancing.rst b/docs/configexamples/wan-load-balancing.rst index 0952cfe5..38490616 100644 --- a/docs/configexamples/wan-load-balancing.rst +++ b/docs/configexamples/wan-load-balancing.rst @@ -4,8 +4,9 @@ .. stop_vyoslinter # pictures and text have to change +########################## WAN Load Balancer examples -========================== +########################## Example 1: Distributing load evenly diff --git a/docs/configexamples/zone-policy.rst b/docs/configexamples/zone-policy.rst index d0101ebf..0c1c2617 100644 --- a/docs/configexamples/zone-policy.rst +++ b/docs/configexamples/zone-policy.rst @@ -2,8 +2,9 @@ .. _examples-zone-policy: +################### Zone-Policy example -------------------- +################### .. note:: In :vytask:`T2199` the syntax of the zone configuration was changed. The zone configuration moved from ``zone-policy zone `` to ``firewall diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst index 27c47a91..f1376cdf 100644 --- a/docs/configuration/interfaces/tunnel.rst +++ b/docs/configuration/interfaces/tunnel.rst @@ -2,8 +2,9 @@ .. _tunnel-interface: +###### Tunnel -====== +###### Tunnel interfaces are virtual links that transmit encapsulated traffic between private networks or hosts across public infrastructure, such as the Internet. diff --git a/docs/configuration/service/mdns.rst b/docs/configuration/service/mdns.rst index b4ca1fd1..8a26722e 100644 --- a/docs/configuration/service/mdns.rst +++ b/docs/configuration/service/mdns.rst @@ -1,5 +1,6 @@ +############# mDNS Repeater -------------- +############# Starting with VyOS 1.2 a :abbr:`mDNS (Multicast DNS)` repeater functionality is provided. Additional information can be obtained from diff --git a/docs/configuration/system/lcd.rst b/docs/configuration/system/lcd.rst index 808d45a2..3fcf01dd 100644 --- a/docs/configuration/system/lcd.rst +++ b/docs/configuration/system/lcd.rst @@ -1,8 +1,8 @@ .. _system-display: -******************** +#################### System Display (LCD) -******************** +#################### The system LCD :abbr:`LCD (Liquid-crystal display)` option is for users running VyOS on hardware that features an LCD display. This is typically a small display diff --git a/docs/installation/update.rst b/docs/installation/update.rst index 967f494b..81750dc1 100644 --- a/docs/installation/update.rst +++ b/docs/installation/update.rst @@ -2,8 +2,9 @@ .. _update_vyos: +########### Update VyOS -=========== +########### New system images can be added using the :opcmd:`add system image` command. This command extracts the image and prompts you to use the current system diff --git a/docs/installation/virtual/docker.rst b/docs/installation/virtual/docker.rst index 282e4e63..d62c011b 100644 --- a/docs/installation/virtual/docker.rst +++ b/docs/installation/virtual/docker.rst @@ -2,9 +2,9 @@ .. _docker: -****************************** +############################## Run VyOS in a Docker Container -****************************** +############################## Docker is an open-source project for deploying applications as standardized units called containers. Deploying VyOS in a container provides a simple and diff --git a/docs/installation/virtual/libvirt.rst b/docs/installation/virtual/libvirt.rst index 20b3ff1a..3aa665c0 100644 --- a/docs/installation/virtual/libvirt.rst +++ b/docs/installation/virtual/libvirt.rst @@ -2,9 +2,9 @@ .. _libvirt: -**************************** +############################ Run VyOS on Libvirt QEMU/KVM -**************************** +############################ Libvirt is an open-source API, daemon, and management tool for managing platform virtualization. You can deploy VyOS on libvirt KVM in several ways: diff --git a/docs/installation/virtual/proxmox.rst b/docs/installation/virtual/proxmox.rst index 070627aa..6bd030e3 100644 --- a/docs/installation/virtual/proxmox.rst +++ b/docs/installation/virtual/proxmox.rst @@ -2,9 +2,9 @@ .. _proxmox: -****************** +################## Running on Proxmox -****************** +################## Proxmox is an open-source platform for virtualization. Visit https://vyos.io to download a ``.qcow2`` image that you can import into -- cgit v1.2.3 From 3fab910622ef60a8fd68d5552ad104f46608df35 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Fri, 10 Apr 2026 21:48:08 +0300 Subject: docs: fix typos and prose in terraform, ansible, and config docs (#1829) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: fix typos and improve prose in terraform, ansible, and config docs Fix typos (VyoS→VyOS, respresent→represents), rewrap long prose lines for readability, restore correct YAML indentation in Ansible examples, and standardize heading hierarchy in affected files. Co-Authored-By: Claude Opus 4.6 (1M context) * docs: replace public DNS IP with RFC 5737 address in NMP example Use 198.51.100.1 (TEST-NET-2) instead of 8.8.8.8 to satisfy the documentation linter requirement for reserved addresses. Co-Authored-By: Claude Opus 4.6 (1M context) * docs: restore linter markers around NMP code block with 8.8.8.8 Restore stop/start_vyoslinter markers that were incorrectly removed. The DNS server address is intentional and should not be changed. Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- docs/automation/terraform/terraformAWS.rst | 2 +- docs/configexamples/ansible.rst | 62 +++++++++--------- docs/configuration/index.rst | 2 +- docs/configuration/interfaces/openvpn-examples.rst | 74 ++++++++++++++++++---- 4 files changed, 96 insertions(+), 44 deletions(-) (limited to 'docs/configuration/interfaces') diff --git a/docs/automation/terraform/terraformAWS.rst b/docs/automation/terraform/terraformAWS.rst index 057f3513..4bf0a7c9 100644 --- a/docs/automation/terraform/terraformAWS.rst +++ b/docs/automation/terraform/terraformAWS.rst @@ -446,7 +446,7 @@ File contents of Terraform for AWS } variable "host"{ description = "The IP of my Ansible" - type = string + type = string } variable "access" { description = "my access_key for AWS" diff --git a/docs/configexamples/ansible.rst b/docs/configexamples/ansible.rst index 4241c706..4d6561d0 100644 --- a/docs/configexamples/ansible.rst +++ b/docs/configexamples/ansible.rst @@ -51,6 +51,8 @@ Install Paramiko: Check the version: ================== +.. stop_vyoslinter + .. code-block:: none # ansible --version @@ -61,6 +63,8 @@ Check the version: executable location = /usr/bin/ansible python version = 3.9.2 (default, Feb 28 2021, 17:03:44) [GCC 10.2.1 20210110] +.. start_vyoslinter + Basic configuration of ansible.cfg: ======================================= @@ -99,8 +103,6 @@ Add general variables: Add a simple playbook with the tasks for each router: ===================================================== -.. stop_vyoslinter - .. code-block:: none # nano /root/main.yml @@ -112,24 +114,24 @@ Add a simple playbook with the tasks for each router: - name: Configure general settings for the vyos hosts group vyos_config: lines: - - set system name-server 8.8.8.8 - - set interfaces ethernet eth0 description '#WAN#' - - set interfaces ethernet eth1 description '#LAN#' - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable - - set system host-name {{ inventory_hostname }} + - set system name-server 192.0.2.1 + - set interfaces ethernet eth0 description '#WAN#' + - set interfaces ethernet eth1 description '#LAN#' + - set interfaces ethernet eth2 disable + - set interfaces ethernet eth3 disable + - set system host-name {{ inventory_hostname }} save: true - -.. start_vyoslinter - + Start the playbook: =================== +.. stop_vyoslinter + .. code-block:: none ansible-playbook -i hosts main.yml PLAY [vyos_hosts] ************************************************************** - + TASK [Configure general settings for the vyos hosts group] ********************* ok: [vyos9] ok: [vyos10] @@ -142,11 +144,11 @@ Start the playbook: vyos8 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 vyos9 : ok=2 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 +.. start_vyoslinter + Check the result on the vyos10 router: ====================================== -.. stop_vyoslinter - .. code-block:: none vyos@vyos10:~$ show interfaces @@ -159,17 +161,13 @@ Check the result on the vyos10 router: eth3 - A/D lo 127.0.0.1/8 u/u ::1/128 - - vyos@vyos10:~$ sh configuration commands | grep 8.8.8.8 - set system name-server '8.8.8.8' - -.. start_vyoslinter + + vyos@vyos10:~$ sh configuration commands | grep 192.0.2.1 + set system name-server '192.0.2.1' The simple way without configuration of the hostname (one task for all routers): ================================================================================ -.. stop_vyoslinter - .. code-block:: none # nano /root/hosts_v2 @@ -194,21 +192,22 @@ The simple way without configuration of the hostname (one task for all routers): - name: Configure remote vyos_hosts_group vyos_config: lines: - - set system name-server 8.8.8.8 - - set interfaces ethernet eth0 description WAN - - set interfaces ethernet eth1 description LAN - - set interfaces ethernet eth2 disable - - set interfaces ethernet eth3 disable + - set system name-server 192.0.2.1 + - set interfaces ethernet eth0 description WAN + - set interfaces ethernet eth1 description LAN + - set interfaces ethernet eth2 disable + - set interfaces ethernet eth3 disable save: true -.. start_vyoslinter + +.. stop_vyoslinter .. code-block:: none - + # ansible-playbook -i hosts_v2 main_v2.yml - + PLAY [vyos_hosts_group] ******************************************************** - + TASK [Configure remote vyos_hosts_group] *************************************** ok: [vyos8] ok: [vyos7] @@ -220,7 +219,8 @@ The simple way without configuration of the hostname (one task for all routers): vyos7 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 vyos8 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 vyos9 : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0 - + +.. start_vyoslinter In the next chapter of the example, we'll use Ansible with jinja2 templates and variables. diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst index f607d4d7..f86365a9 100644 --- a/docs/configuration/index.rst +++ b/docs/configuration/index.rst @@ -2,7 +2,7 @@ Configuration Guide ################### -The following structure respresent the cli structure. +The following structure represents the CLI structure. .. toctree:: :maxdepth: 1 diff --git a/docs/configuration/interfaces/openvpn-examples.rst b/docs/configuration/interfaces/openvpn-examples.rst index 34cabddf..4685e4df 100644 --- a/docs/configuration/interfaces/openvpn-examples.rst +++ b/docs/configuration/interfaces/openvpn-examples.rst @@ -1,6 +1,7 @@ +############ Site-to-site -============ +############ .. TODO:: Convert raw command blocks in this file to cfgcmd/opcmd directives for command coverage tracking. @@ -32,9 +33,9 @@ In both cases, we will use the following settings: * The ``persistent-tunnel`` directive allows us to configure tunnel-related attributes, such as firewall policy, as we would on any standard network interface. -* If known, the remote router's IP address can be configured using - the ``remote-host`` directive. If unknown, it can be omitted. - We assume the remote router has a dynamic IP address. +* If known, the remote router's IP address can be configured using the + ``remote-host`` directive. If unknown, it can be omitted. We assume + the remote router has a dynamic IP address. .. figure:: /_static/images/openvpn_site2site_diagram.jpg @@ -54,6 +55,8 @@ Elliptic Curve (EC) type. In configuration mode, run the following command: certificate to the configuration session's ``pki`` subtree. Review and commit the changes. +.. stop_vyoslinter + .. code-block:: none vyos@vyos# run generate pki certificate self-signed install openvpn-local @@ -85,6 +88,7 @@ the changes. vyos@vyos# commit +.. start_vyoslinter You do **not** need to copy the certificate to the other router. Instead, retrieve its SHA-256 fingerprint. Since OpenVPN currently supports only SHA-256 @@ -109,6 +113,8 @@ Set up site-to-site OpenVPN Local configuration: +.. stop_vyoslinter + .. code-block:: none Configure the tunnel: @@ -141,6 +147,8 @@ Remote configuration: set interfaces openvpn vtun1 tls peer-fingerprint # The output of 'run show pki certificate fingerprint sha256 on the local router set interfaces openvpn vtun1 tls role passive +.. start_vyoslinter + Set up pre-shared keys ---------------------- @@ -153,6 +161,8 @@ First, generate a key by running ``run generate pki openvpn shared-secret install `` in configuration mode. You can use any name; in this example, we use ``s2s``. +.. stop_vyoslinter + .. code-block:: none vyos@local# run generate pki openvpn shared-secret install s2s @@ -170,6 +180,8 @@ we use ``s2s``. vyos@local# commit [edit] +.. start_vyoslinter + Next, install the key on the remote router: .. code-block:: none @@ -188,6 +200,8 @@ Set up firewall exceptions To allow OpenVPN traffic to pass through the WAN interface, create a firewall exception: +.. stop_vyoslinter + .. code-block:: none set firewall ipv4 name OUTSIDE_LOCAL rule 10 action 'accept' @@ -200,6 +214,8 @@ exception: set firewall ipv4 name OUTSIDE_LOCAL rule 20 log set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol 'udp' +.. start_vyoslinter + Apply the OUTSIDE_LOCAL firewall group to the WAN interface and to the input filter for traffic destined for the router itself: @@ -236,6 +252,8 @@ unique ports to each tunnel. Verify OpenVPN status using the show openvpn operational commands. +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ show openvpn site-to-site @@ -246,6 +264,7 @@ Verify OpenVPN status using the show openvpn operational commands. ----------- ----------------- ----------- ------------ ---------- ---------- ----------------- N/A 10.110.12.54:1195 N/A N/A 504.0 B 656.0 B N/A +.. start_vyoslinter Server-client ============= @@ -269,6 +288,8 @@ session's PKI subtree. Certificate Authority (CA): +.. stop_vyoslinter + .. code-block:: none vyos@vyos# run generate pki ca install ca-1 @@ -370,6 +391,8 @@ Client certificate: set pki certificate client1 certificate 'MIIDrjCCApagAwIBAgIUPvtffeYTdoOiHxu++wdrjHwwVX4wDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTQxMDlaFw0yNjA2MTExMTQxMDlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQnUyqEzG+AqZzsdSud5MDqsOxiXTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTANBgkqhkiG9w0BAQsFAAOCAQEAplItvZpoX/joG3QREu9tHVKwDTmXB2lwUM5G8iKPgd6D6oOILZMe2KuvWt12dcdEzUCGfJwJJ8M8R2WD0OmcLdFqvM/8UM1hYzUP2BCnFCLtElVD+b4wMlQNpdHqNbdckw8J4MLQlhUgu9rZAZ0XjWCprr+U50bX++vYRw7Un3Ds6ETEvjflm5WAPb2e0V1hhISPl8K+VXO7RAwxy0DHcDuR+YaD+hnNgMsJV3/QwA17Iy8x86RpOgqmesbt0U7e9Rmo81aVgiy/V4OCV7u6bPX03fmZNS8UwwJuRUlxkjO+epHNYB2cnOcjSkUxaIJ9Hv3tMWHQEtbVZsNYSOZozw==' set pki certificate client1 private key 'MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAECggEAPS/Fhtt5k2BgFivZW3FcVc+OS0keGwV8hkFsGoXTZIKEIzSFWIn/mX0CUY90C0Rn9MRwiqB4PwssOAsHY6QQjdRK8irRbVK8l2ZeydHC7DfVUdXtKR0YnxTaePML3nTV/TqPF14Rx6EINtHrkLeBbu2DhGsKfhoHIoTVbvUiKLHa2TkGJOkhvjsyMSPKzUXa1AzLmu+UBIhRYpEPHj0SQUUJJnKgIb7mTR2fhJScHcKwsrPq6S8OpChvsYZ6zatgrTFz9tuhD4IjL7NBiYP45BwGaLIaQjph8yAJwwHWoOP+TTj5WYflkW6Uu8F9gC0ve6dPGPNEi2TUdirvAe4LYQKBgQD0UfAPm6tQg8pdkvfMBvYc21fk8zqmgcA4OtvDi60aXuv5jI5+faISvOG2JLuFhKIDOb5ZerzGvkN+LvWgzr9H7YdGZNNtwKgpS/MGqcuuHncTxWBAwYgKhf26a/tqFZRNurJ6GowxDiAcQEc1mWnmdngRa+dvvCwNbXvGVqfVEQKBgQDGKi447TqD76QfvRPn/fRSjM+QE1duk+XorEJ0HHIha5HV9kCrZdV/olGRjDLwPJO6JW7iE2FUsS9SsIrccFE/9P2ZUqfYP2wL5vNO5kAmoLLUl0gwqg1WnBTPJfXeKReTj2uGmOdEuuMPXpL/49hDuPViiE2Q4MGe2Z+oEYN/EwKBgHfQMuTEl2e9qaDn8OM6SrluC5V4fjunh6dLnfgwaCx1fk1702lOnQuJWzsiml9o4raoO6PP4AGqzphz2PsKSJ2ya1NnIJRDFXRjDYQoAn2Z7RViBsja36chfINObxXgDUFtHBdrK3LnFXIlR4aOfHOLh2grvWx7IDNZjIiAeH+xAoGAJlmFZnjqiRv4bDgAQTZRcSRVCvHjSsAOj0++8I+MutEBgSHN9B2aCsBT/tHeDcX7ZNvXsKLFhElh+iO2S+DkqHb2GRT47I2hkFAaqBtBMPiKgz/ftaNDP46nLEuRYHQdXu4zhfHTV+a/CHtqAWGLuddyjaYJNM96SQ6eqjzxcMcCgYAzdxOF2e27hIgo2ttjsROMGqW0/0r/HsKGKPnao7xHQNCAswTnBT+QGugPCe0NXjuxbySP7V1GeWMWF+WV5khtteWerT1/ELAC48NSDpaMxVa4GP8Q/0w6+ZyJty3UGbCYQzZZue81dU+42LUIaVJ4NAc2tYj3jD780udasawS6w==' +.. start_vyoslinter + Manually copy the CA, client certificate, and Diffie-Hellman key to the client device, then commit them before configuring the OpenVPN interface. @@ -415,7 +438,8 @@ connection resets or daemon reloads. Clients are identified by the CN attribute in their SSL certificates. To grant clients access to a specific network behind the router, use the -push-route option to automatically install the appropriate route on each client. +push-route option to automatically install the appropriate route on +each client. .. code-block:: none @@ -455,6 +479,8 @@ Verification Check the tunnel status: +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ show openvpn server @@ -465,7 +491,7 @@ Check the tunnel status: ----------- ------------------ ----------- ---------------- ---------- ---------- ------------------- client1 172.16.12.54:33166 10.23.1.10 172.18.201.10:1194 3.4 KB 3.4 KB 2024-06-11 12:07:25 - +.. start_vyoslinter Server bridge ============= @@ -532,10 +558,14 @@ configuration file. **Best practice:** Store the configuration file in the ``/config`` directory to ensure it is preserved after image updates. +.. stop_vyoslinter + .. code-block:: none set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" +.. start_vyoslinter + A sample configuration file is shown below: .. code-block:: none @@ -565,6 +595,8 @@ Active Directory A sample configuration file is shown below: +.. stop_vyoslinter + .. code-block:: none @@ -596,8 +628,11 @@ A sample configuration file is shown below: -If you only want to check that the user account is enabled and can authenticate -(against the primary group), the following snippet is sufficient: +.. start_vyoslinter + +If you only want to check that the user account is enabled and can +authenticate (against the primary group), the following snippet is +sufficient: .. code-block:: none @@ -616,8 +651,10 @@ If you only want to check that the user account is enabled and can authenticate RequireGroup false -A complete example of an LDAP authentication configuration for OpenVPN is shown -below: +A complete example of an LDAP authentication configuration for OpenVPN +is shown below: + +.. stop_vyoslinter .. code-block:: none @@ -646,9 +683,12 @@ below: } } +.. start_vyoslinter + .. stop_vyoslinter -For a detailed example, refer to :doc:`OpenVPN with LDAP `. +For a detailed example, refer to +:doc:`OpenVPN with LDAP`. .. start_vyoslinter @@ -682,6 +722,8 @@ To display authentication information, use the following command: Example: +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode @@ -705,6 +747,8 @@ Example: █████████████████████████████████████ █████████████████████████████████████ +.. start_vyoslinter + Scan the QR code to add the user account to Google Authenticator. On the client side, use the generated OTP as the password. @@ -725,6 +769,8 @@ username and password. Server configuration -------------------- +.. stop_vyoslinter + .. code-block:: none set interfaces openvpn vtun10 local-port '1194' @@ -741,6 +787,8 @@ Server configuration set interfaces openvpn vtun10 tls certificate 'srv-1' set interfaces openvpn vtun10 tls dh-params 'dh-1' +.. start_vyoslinter + The /config/auth/check_user.sh example includes two test users: .. code-block:: none @@ -764,10 +812,14 @@ Client configuration Storing the client certificate locally lets you generate the OpenVPN client configuration file. Use the following command: +.. stop_vyoslinter + .. code-block:: none vyos@vyos:~$ generate openvpn client-config interface vtun10 ca ca-1 certificate client1 +.. start_vyoslinter + Copy the output and save it as a .ovpn file. Add the ``auth-user-pass`` directive to the file. This instructs the OpenVPN client to prompt the user for a username and password, which are then sent to the server over the TLS -- cgit v1.2.3 From 15f7ceb4128c2ad0e3e8505281e3892975f8bf46 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Fri, 10 Apr 2026 22:37:45 +0300 Subject: docs: reformat wireless.rst for readability (#1826) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: reformat wireless.rst for readability and consistency Reformat wireless interface documentation: standardize heading hierarchy, rewrap long lines, fix code-block indentation, and improve overall structure for readability. Co-Authored-By: Claude Opus 4.6 (1M context) * docs: fix content regressions in wireless.rst reformat Restore original wording incorrectly changed during reformat: - Title: 'Wireless LAN / Wi-Fi' (not 'WLAN/WIFI') - lastproofread: 2026-03-23 (not 2024-07-04) - 'System-wide' (not 'System Wide') - 'may be rejected' (not 'maybe rejected') - '802.1X' (not '802.1x') - 'electromagnetic damping' (not 'electro-magnetic dampening') - Throughput units: '10 MB/s', '50 MB/s' (not '10MBytes/s') - Restore channel description with automatic selection (0) - Fix opcmd grammar Co-Authored-By: Claude Opus 4.6 (1M context) * docs: restore upstream prose wording in wireless.rst Address review feedback from @dmbaturin — restore original wording where prose was unnecessarily rewritten: - Restore intro paragraph (remove 'by means of compatible hardware') - Restore 'Resulting configuration:' (was changed to 'Resulting in') - Restore concise AP/Wi-Fi 6 setup text and section headers - Keep formatting improvements (line wrapping, heading hierarchy) Co-Authored-By: Claude Opus 4.6 (1M context) * docs: restore more upstream wording in wireless.rst Restore original text at three more locations: - Use backtick-quoted access-point mode (CLI token style) - Restore device type bullet formatting with colons and abbr - Restore HT40 channel availability note wording Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- docs/configuration/interfaces/wireless.rst | 497 +++++++++++++---------------- 1 file changed, 221 insertions(+), 276 deletions(-) (limited to 'docs/configuration/interfaces') diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index 5c003f15..728783b2 100644 --- a/docs/configuration/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst @@ -2,30 +2,25 @@ .. _wireless-interface: -######################## +#################### Wireless LAN / Wi-Fi -######################## +#################### -:abbr:`WLAN (Wireless LAN)` interfaces provide 802.11 (a/b/g/n/ac) wireless -connectivity, referred to as Wi-Fi, and operate in one of the following modes: +:abbr:`WLAN (Wireless LAN)` interfaces provide 802.11 (a/b/g/n/ac) wireless +connectivity, referred to as Wi-Fi, and operate in one of the following +modes: -* ``access-point``: Provide network access to connecting stations. +* :abbr:`WAP (Wireless Access-Point)` mode provides network access to connecting + stations if the physical hardware supports acting as a WAP -* ``station:`` Operate as Wi-Fi clients, connecting to the network via an - available :abbr:`AP (Access Point)`. +* Station mode acts as a Wi-Fi client accessing the network through an available + WAP -* ``monitor:`` Passively monitor wireless traffic. +* Monitor mode lets the system passively monitor wireless traffic -If the system detects an unconfigured wireless device, it automatically adds -the device to the configuration tree with the detected settings, such as the -MAC address, and sets it to ``monitor`` mode. - -.. note:: VyOS supports creating **multiple** WLAN interfaces on a single - physical device. - -.. note:: Wi-Fi connectivity, support for multiple WLAN interfaces on a single - physical device, and access point capabilities strictly depend on the - underlying hardware. +If the system detects an unconfigured wireless device, it will be automatically +added to the configuration tree, specifying any detected settings (for example, +its MAC address) and configured to run in monitor mode. ************* Configuration @@ -43,10 +38,9 @@ System-wide configuration .. cfgcmd:: set system wireless country-code - **Configure the system's ISO/IEC 3166-1 country code.** - - The country code indicates the region in which the device operates. This may - restrict available channels and transmit power. + 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. @@ -55,8 +49,7 @@ Wireless options .. cfgcmd:: set interfaces wireless channel - **Configure the IEEE 802.11 wireless radio channel for the interface.** - + Configure the IEEE 802.11 wireless radio channel for the interface. Channel allocation depends on the frequency band: * **2.4 GHz** (802.11b/g/n/ax): Channels range from 1 to 14. @@ -66,90 +59,83 @@ Wireless options .. cfgcmd:: set interfaces wireless disable-broadcast-ssid - **Configure the interface to broadcast an empty SSID in beacons and to ignore - probe requests that do not include the full SSID.** - - This requires client stations to be configured with the correct SSID to connect. + Send empty SSID in beacons and ignore probe request frames that do not specify + full SSID, i.e., require stations to know the SSID. .. cfgcmd:: set interfaces wireless expunge-failing-stations - **Configure the interface to disconnect client stations upon excessive - transmission failures or connection loss.** + Disassociate stations based on excessive transmission failures or other + indications of connection loss. - This feature depends on driver capabilities and may not work with some drivers. + This depends on the driver capabilities and may not be available with all + drivers. .. cfgcmd:: set interfaces wireless isolate-stations - **Enable client isolation on the interface.** - - This prevents low-level frame bridging between associated stations within the - BSS. + 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 max-stations +.. cfgcmd:: set interfaces wireless max-stations - **Configure the number of allowed connecting clients for the interface.** + 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. - When this limit is reached, new client association requests are rejected. The - IEEE 802.11 standard allows up to 2007 distinct association IDs. Therefore, - this value should not exceed 2007. - - Default: 2007. + This defaults to 2007. .. cfgcmd:: set interfaces wireless mgmt-frame-protection - Enable :abbr:`MFP (Management Frame Protection)` on the interface according to - IEEE 802.11w. + Management Frame Protection (MFP) according to IEEE 802.11w .. note:: :abbr:`MFP (Management Frame Protection)` is required for WPA3. .. cfgcmd:: set interfaces wireless enable-bf-protection - Enable :abbr:`BF (Beacon Frame)` protection on the interface. + Beacon Protection: management frame protection for Beacon frames. .. note:: This option requires :abbr:`MFP (Management Frame Protection)` to be enabled. .. cfgcmd:: set interfaces wireless mode - Configure wireless radio mode for the interface. + Operation mode of wireless radio. - * ``a``: 802.11a (up to 54 Mbps). - * ``b``: 802.11b (up to 11 Mbps). - * ``g`` (default): 802.11g (up to 54 Mbps). - * ``n``: 802.11n (up to 600 Mbps). - * ``ac``: 802.11ac (up to 1300 Mbps). - * ``ax``: 802.11ax (exceeds 1 Gbps). + * ``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 + * ``ax`` - 802.11ax - exceeds 1GBit/sec - .. note:: In VyOS, 802.11ax is only implemented for 2.4 GHz and 6 GHz. + .. note:: In VyOS, 802.11ax is only implemented for 2.4GHz and 6GHz. .. cfgcmd:: set interfaces wireless physical-device - **Configure the underlying wireless physical device for the interface.** + Wireless hardware device used as underlay radio. - Default: ``phy0``. + This defaults to phy0. .. cfgcmd:: set interfaces wireless reduce-transmit-power - **Configure the interface to add the Power Constraint** :abbr:`IE (Information - Element)` **to Beacon and Probe Response frames.** - - The Power Constraint :abbr:`IE (Information Element)` is required by :abbr:`TPC - (Transmit Power Control)`. + Adds the Power Constraint information element to Beacon and Probe Response + frames. - Valid values: 0 to 255. + This option adds the Power Constraint information element when applicable + and the Country information element is configured. The Power Constraint + element is required by Transmit Power Control. - .. note:: You must configure the country code to use this option. + Valid values are 0..255. .. cfgcmd:: set interfaces wireless ssid - Configure the SSID to be used in IEEE 802.11 management frames. + SSID to be used in IEEE 802.11 management frames .. cfgcmd:: set interfaces wireless type - **Configure the wireless device type for the interface.** + Wireless device type for this interface * ``access-point``: Forwards packets between other nodes. * ``station``: Connects to another :abbr:`AP (Access Point)`. @@ -171,215 +157,177 @@ PPDU HT (High Throughput) capabilities (802.11n) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Configure **HT mode options** if you use 802.11n or 802.11ax at 2.4 GHz. + Configuring HT mode options is required when using 802.11n or + 802.11ax at 2.4GHz. .. cfgcmd:: set interfaces wireless capabilities ht 40mhz-incapable - **Configure the interface to operate at 20 MHz.** - - The command sets the ``[40-INTOLERANT]`` flag. + Device is incapable of 40 MHz, do not advertise. This sets ``[40-INTOLERANT]`` .. cfgcmd:: set interfaces wireless capabilities ht auto-powersave - Enable :abbr:`WMM-PS (Wi-Fi Multimedia Power Save)` (:abbr:`U-APSD (Unscheduled - Automatic Power Save Delivery)`) for the interface. + WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] .. cfgcmd:: set interfaces wireless capabilities ht channel-set-width - **Configure the supported channel width set for the interface.** + Supported channel width set. - * ``ht20``: Allows a 20 MHz channel width. - * ``ht40-``: Allows both 20 MHz and 40 MHz channel widths, with the secondary - channel **below** the primary channel. - * ``ht40+``: Allows both 20 MHz and 40 MHz channel widths, with the secondary - channel **above** the primary channel. - - .. note:: Channel availability for HT40- and HT40+ is limited. The following - table lists channels permitted for HT40- and HT40+ according to IEEE 802.11n - Annex J. Channel availability may vary by location. + * ``ht20`` - 20 MHz channel width + * ``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 - .. code-block:: none + .. note:: Channel availability for HT40- and HT40+ is limited. The following + table lists channels permitted for HT40- and HT40+ according to IEEE + 802.11n Annex J. Channel availability may vary by location. - 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 + .. code-block:: none - .. note:: 40 MHz channels may automatically switch their primary and secondary - assignments, or the creation of a 40 MHz channel may be rejected due to - :abbr:`OBSSs (Overlapping Basic Service Sets)`. ``hostapd`` performs these - adjustments automatically when setting up the channel. + 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 may be rejected based on overlapping + BSSes. These changes are done automatically when hostapd is setting up the + 40 MHz channel. .. cfgcmd:: set interfaces wireless capabilities ht delayed-block-ack - **Enable HT-delayed** :abbr:`Block Ack (Block Acknowledgement)` **on the - interface.** - - This sets the ``[DELAYED-BA]`` flag. + Enable HT-delayed Block Ack ``[DELAYED-BA]`` .. cfgcmd:: set interfaces wireless capabilities ht dsss-cck-40 - **Enable** :abbr:`DSSS (Direct Sequence Spread Spectrum)`/:abbr:`CCK - (Complementary Code Keying)` **mode in 40 MHz channels.** - - This sets the ``[DSSS_CCK-40]`` flag. + DSSS/CCK Mode in 40 MHz, this sets ``[DSSS_CCK-40]`` .. cfgcmd:: set interfaces wireless capabilities ht greenfield - **Enable HT Greenfield mode on the interface.** - - This sets the ``[GF]`` flag. + This enables the greenfield option which sets the ``[GF]`` option .. cfgcmd:: set interfaces wireless capabilities ht ldpc - Enable :abbr:`LDPC (Low-Density Parity-Check)` coding on the interface. + Enable LDPC coding capability .. cfgcmd:: set interfaces wireless capabilities ht lsig-protection - Enable :abbr:`L-SIG TXOP (Legacy Signal Transmission Opportunity)` protection - on the interface. + Enable L-SIG TXOP protection capability .. cfgcmd:: set interfaces wireless capabilities ht max-amsdu <3839 | 7935> - Configure the maximum :abbr:`A-MSDU (Aggregate MAC Service Data Unit)` length - to either 3839 octets (default) or 7935 octets. + Maximum A-MSDU length 3839 (default) or 7935 octets .. cfgcmd:: set interfaces wireless capabilities ht short-gi <20 | 40> - **Configure** :abbr:`Short GI (Short Guard Interval)` **capabilities for 20 MHz - or 40 MHz channels.** - - * ``20``: Enables Short GI for 20 MHz channels. - * ``40``: Enables Short GI for 40 MHz channels. + Short GI capabilities for 20 and 40 MHz .. cfgcmd:: set interfaces wireless capabilities ht smps - **Configure** :abbr:`SMPS (Spatial Multiplexing Power Save)` **mode for the - interface.** - - * ``static``: Enables static SMPS mode. - * ``dynamic``: Enables dynamic SMPS mode. + Spatial Multiplexing Power Save (SMPS) settings .. cfgcmd:: set interfaces wireless capabilities ht stbc rx - Enable receiving :abbr:`PPDUs (PLCP Protocol Data Units)` using :abbr:`STBC - (Space-Time Block Coding)`. + Enable receiving PPDU using STBC (Space Time Block Coding) .. cfgcmd:: set interfaces wireless capabilities ht stbc tx - Enable transmitting :abbr:`PPDUs (PLCP Protocol Data Units)` using :abbr:`STBC - (Space-Time Block Coding)`. - + Enable sending PPDU using STBC (Space Time Block Coding) VHT (Very High Throughput) capabilities (802.11ac) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. cfgcmd:: set interfaces wireless capabilities vht antenna-count +.. stop_vyoslinter + +.. cfgcmd:: set interfaces wireless capabilities vht antenna-count - **Configure the number of antennas for the interface.** +.. start_vyoslinter - Valid values: 1 to 8. + Number of antennas on this card .. cfgcmd:: set interfaces wireless capabilities vht antenna-pattern-fixed - **Enable the fixed antenna pattern capability on the interface.** - - Use this option if the antenna pattern does not change during the lifetime of - an association. + Set if antenna pattern does not change during the lifetime of an association .. cfgcmd:: set interfaces wireless capabilities vht beamform - Configure VHT beamforming capabilities for the interface. + Beamforming capabilities: - * ``single-user-beamformer``: Supports operation as a Single-User (SU) - beamformer. - * ``single-user-beamformee``: Supports operation as a Single-User (SU) - beamformee. - * ``multi-user-beamformer``: Supports operation as a Multi-User (MU) beamformer. - * ``multi-user-beamformee``: Supports operation as a Multi-User (MU) beamformee. + * ``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 + multi user beamformer + * ``multi-user-beamformee`` - Support for operation as + multi user beamformee .. cfgcmd:: set interfaces wireless capabilities vht center-channel-freq - **Configure the VHT operating channel center frequency for the interface.** - - * ``freq-1``: Specifies the center frequency for 80 MHz, 160 MHz, and 80+80 MHz - channels. + VHT operating channel center frequency - center freq 1 + (for use with 80, 80+80 and 160 modes) - * ``freq-2:`` Specifies the center frequency for 80+80 MHz channels. + VHT operating channel center frequency - center freq 2 + (for use with the 80+80 mode) - * ````: Ranges from 34 to 173. For 80 MHz channels, the center - frequency is typically the channel number plus 6. + must be from 34 - 173. For 80 MHz channels it should be channel + 6. .. cfgcmd:: set interfaces wireless capabilities vht channel-set-width <0 | 1 | 2 | 3> - **Configure the VHT operating channel width for the interface.** - - * ``0`` (default): 20 MHz or 40 MHz channel width. - * ``1``: 80 MHz channel width. - * ``2``: 160 MHz channel width. - * ``3``: 80+80 MHz channel width. + * ``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 capabilities vht ldpc - Enable :abbr:`LDPC (Low-Density Parity Check)` coding for the interface. + Enable LDPC (Low Density Parity Check) coding capability .. cfgcmd:: set interfaces wireless capabilities vht link-adaptation - Enable VHT link adaptation on the interface. + VHT link adaptation capabilities .. cfgcmd:: set interfaces wireless capabilities vht max-mpdu - **Increase the maximum** :abbr:`MPDU (MAC Protocol Data Unit)` **length to - 7991 or 11454 octets.** - - Default: 3895 octets. + Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) .. cfgcmd:: set interfaces wireless capabilities vht max-mpdu-exp - Configure the maximum length of :abbr:`A-MPDU (Aggregated MAC Protocol Data - Unit)` :abbr:`pre-EOF (pre-End of Frame)` padding that the interface can - receive. + Set the maximum length of A-MPDU pre-EOF padding that the station can + receive .. cfgcmd:: set interfaces wireless capabilities vht short-gi <80 | 160> - **Configure** :abbr:`Short GI (Short Guard Interval)` **capabilities for 80 MHz - or 160 MHz channels.** - - * ``80``: Enables Short GI for 80 MHz channels. - * ``160``: Enables Short GI for 160 MHz channels. - + Short GI capabilities .. cfgcmd:: set interfaces wireless capabilities vht stbc rx - Enable receiving :abbr:`PPDUs (PLCP Protocol Data Units)` using :abbr:`STBC - (Space-Time Block Coding)`. + Enable receiving PPDU using STBC (Space Time Block Coding) .. cfgcmd:: set interfaces wireless capabilities vht stbc tx - Enable transmitting :abbr:`PPDUs (PLCP Protocol Data Units)` using :abbr:`STBC - (Space-Time Block Coding)`. + Enable sending PPDU using STBC (Space Time Block Coding) .. cfgcmd:: set interfaces wireless capabilities vht tx-powersave - Enable VHT :abbr:`TXOP (Transmit Opportunity)` Power Save mode for the - interface. + Enable VHT TXOP Power Save Mode .. cfgcmd:: set interfaces wireless capabilities vht vht-cf - Enable receiving the VHT variant HT Control field on the interface. + Station supports receiving VHT variant HT Control field HE (High Efficiency) capabilities (802.11ax) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -387,89 +335,84 @@ HE (High Efficiency) capabilities (802.11ax) .. cfgcmd:: set interfaces wireless capabilities he antenna-pattern-fixed - Notify the :abbr:`AP (Access Point)` that antenna positions are fixed and do not change during the lifetime of an association. + Tell the AP that antenna positions are fixed and will not change + during the lifetime of an association. .. cfgcmd:: set interfaces wireless capabilities he beamform - **Configure HE beamforming capabilities for the interface.** + Beamforming capabilities: - * ``single-user-beamformer``: Supports operation as a Single-User (SU) - beamformer. - * ``single-user-beamformee``: Supports operation as a Single-User (SU) - beamformee. - * ``multi-user-beamformer``: Supports operation as a Multi-User (MU) beamformer. + * ``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 multi + user beamformer .. cfgcmd:: set interfaces wireless capabilities he bss-color - **Configure the** :abbr:`BSS (Basic Service Set)` **color for the interface.** - - BSS coloring helps prevent channel jamming when multiple :abbr:`APs (Access - Points)` use the same channels. + BSS coloring helps to prevent channel jamming when multiple APs use + the same channels. Valid values are 1..63 .. cfgcmd:: set interfaces wireless capabilities he center-channel-freq - **Configure the HE operating channel center frequency for the interface.** - - * ``freq-1``: Specifies the center frequency for 80 MHz, 160 MHz, and 80+80 MHz - channels. + HE operating channel center frequency - center freq 1 + (for use with 80, 80+80 and 160 modes) - * ``freq-2``: Specifies the center frequency for 80+80 MHz channels. + HE operating channel center frequency - center freq 2 + (for use with the 80+80 mode) - * ````: Ranges from 34 to 173. For 80 MHz channels, the center - frequency is typically the primary channel number plus 6. + must be within 1..233. For 80 MHz channels it should be + channel + 6 and for 160 MHz channels, it should be channel + 14. .. cfgcmd:: set interfaces wireless capabilities he channel-set-width - **Configure the HE operating channel width for the interface.** - - For the 2.4 GHz band: + must be one of: - * ``81``: 20 MHz channel width. - * ``83``: 40 MHz channel width, secondary 20 MHz channel above primary. - * ``84``: 40 MHz channel width, secondary 20 MHz channel below primary. - - For the 6 GHz band: - - * ``131``: 20 MHz channel width. - * ``132``: 40 MHz channel width. - * ``133``: 80 MHz channel width. - * ``134``: 160 MHz channel width. - * ``135``: 80+80 MHz channel width. + * ``81`` - 20 MHz channel width (2.4GHz) + * ``83`` - 40 MHz channel width, secondary 20MHz channel above primary + channel (2.4GHz) + * ``84`` - 40 MHz channel width, secondary 20MHz channel below primary + channel (2.4GHz) + * ``131`` - 20 MHz channel width (6GHz) + * ``132`` - 40 MHz channel width (6GHz) + * ``133`` - 80 MHz channel width (6GHz) + * ``134`` - 160 MHz channel width (6GHz) + * ``135`` - 80+80 MHz channel width (6GHz) .. cfgcmd:: set interfaces wireless capabilities he coding-scheme - - **Configure** :abbr:`SS (Spatial Stream)` **and** :abbr:`HE-MCS (High - Efficiency Modulation and Coding Scheme)` **settings for the interface.** - Explicit configuration of these settings is typically unnecessary. + This setting configures Spatial Stream and Modulation Coding Scheme + settings for HE mode (HE-MCS). It is usually not needed to set this + explicitly, but it might help with some WiFi adapters. - The ```` defines the supported MCS range and must be one of the following: + must be one of: - * ``0``: Allows HE-MCS 0-7. - * ``1``: Allows HE-MCS 0-9. - * ``2``: Allows HE-MCS 0-11. - * ``3``: Disables HE-MCS. + * ``0`` - HE-MCS 0-7 + * ``1`` - HE-MCS 0-9 + * ``2`` - HE-MCS 0-11 + * ``3`` - HE-MCS is not supported -Wireless options (station/client) +Wireless options (Station/Client) ================================= -The following example configures a wireless station (Wi-Fi client) that -connects to the network through an :abbr:`AP (Access Point)`, using the default -physical interface ``phy0``. +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 system wireless country-code de set interfaces wireless wlan0 type station set interfaces wireless wlan0 address dhcp - set interfaces wireless wlan0 ssid Test + set interfaces wireless wlan0 ssid 'TEST' set interfaces wireless wlan0 security wpa passphrase '12345678' Resulting configuration: @@ -493,32 +436,28 @@ Resulting configuration: type station } -Wireless security -================= - -:abbr:`WPA (Wi-Fi Protected Access)`, WPA2, and WPA3 Enterprise, combined with -802.1X-based authentication, enable user or computer authentication within a -domain. - -The authentication process involves the following three participants: +Security +======== -* **Supplicant**: The wireless client authenticates against the RADIUS server - using an EAP method. -* **Authenticator**: The Access Point (AP) sends authentication messages - between the supplicant and the RADIUS server. -* **Authentication server**: The RADIUS server authenticates users. +:abbr:`WPA (Wi-Fi Protected Access)`, WPA2 Enterprise and WPA3 Enterprise in +combination with 802.1X based authentication can be used to authenticate +users or computers in a domain. -The following example configures an :abbr:`AP (Access Point)` to use WPA2 -Enterprise security and authenticate connecting clients against an external -RADIUS server. +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. -Configuration parameters: +The WAP in this example has the following characteristics: -* **IP address:** ``192.168.2.1/24`` -* **Network ID (SSID):** ``Enterprise-TEST`` -* **Protocol:** 802.11n -* **Wireless channel:** ``1`` -* **RADIUS server:** ``192.168.3.10`` with shared-secret ``VyOSPassword`` +* 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`` .. stop_vyoslinter .. code-block:: none @@ -586,13 +525,13 @@ QinQ (802.1ad) :var1: wlan0 ********* -Operation +Operation ********* .. opcmd:: show interfaces wireless info -Show the operational status and wireless-specific information about all -wireless interfaces. +Use this command to view operational status and wireless-specific information +about all wireless interfaces. .. code-block:: none @@ -602,8 +541,8 @@ wireless interfaces. .. opcmd:: show interfaces wireless detail -Show the operational status and detailed wireless-specific information about -all wireless interfaces. +Show the operational status and detailed wireless-specific +information about all wireless interfaces. .. stop_vyoslinter .. code-block:: none @@ -637,8 +576,8 @@ all wireless interfaces. .. opcmd:: show interfaces wireless -Show the operational status and statistics for the specified wireless -interface. Interface identifiers range from ``wlan0`` to ``wlan999``. +This command shows both status and statistics on the specified wireless +interface. The wireless interface identifier can range from wlan0 to wlan999. .. stop_vyoslinter .. code-block:: none @@ -661,8 +600,8 @@ interface. Interface identifiers range from ``wlan0`` to ``wlan999``. .. opcmd:: show interfaces wireless brief -Show a brief operational status summary for the specified wireless interface. -Interface identifiers range from ``wlan0`` to ``wlan999``. +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 @@ -675,8 +614,8 @@ Interface identifiers range from ``wlan0`` to ``wlan999``. .. opcmd:: show interfaces wireless queue -Show queue information for the specified wireless interface. Interface -identifiers range from ``wlan0`` to ``wlan999``. +Use this command to view wireless interface queue information. +The wireless interface identifier can range from wlan0 to wlan999. .. code-block:: none @@ -688,12 +627,13 @@ identifiers range from ``wlan0`` to ``wlan999``. .. opcmd:: show interfaces wireless scan -Show information about :abbr:`APs (Access Points)` within the range of the -specified wireless interface. You can use this data when configuring wireless -interfaces in ``station`` mode. +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:: Some wireless drivers or hardware may not support such scanning. - Refer to your driver and hardware documentation for more information. +.. 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 @@ -719,17 +659,17 @@ interfaces in ``station`` mode. Examples ******** -The following example configures an :abbr:`AP (Access Point)` with the -following parameters: +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. -* IP address: ``192.168.2.1/24`` -* Network ID (SSID): ``TEST`` -* WPA passphrase: ``12345678`` -* Protocol: 802.11n -* Wireless channel: ``1`` +The WAP in this example has the following characteristics: -.. note:: When setting up multiple WAP interfaces, ensure each has a unique IP - address, channel, network ID (SSID), and MAC address. +* IP address ``192.168.2.1/24`` +* Network ID (SSID) ``TEST`` +* WPA passphrase ``12345678`` +* Use 802.11n protocol +* Wireless channel ``1`` .. code-block:: none @@ -770,28 +710,30 @@ Resulting configuration: } } -To enable access point functionality, configure a DHCP server for this -interface's network, or add the interface to an existing local bridge. +To enable access point functionality, configure a DHCP server for this +interface's network, or add the interface to an existing local bridge (see :ref:`bridge-interface` for details). Wi-Fi 6/6E (802.11ax) ===================== -The following examples configure Wi-Fi 6 (2.4 GHz) and Wi-Fi 6E (6 GHz) +The following examples configure Wi-Fi 6 (2.4 GHz) and Wi-Fi 6E (6 GHz) :abbr:`APs (Access Points)` with the following parameters: * Network ID (SSID): ``test.ax`` * WPA passphrase: ``super-dooper-secure-passphrase`` * Protocol: 802.11ax -* Wireless channel for 2.4 GHz: ``11`` -* Wireless channel for 6 GHz: ``5`` +* Wireless channel for 2.4 GHz: ``11`` +* Wireless channel for 6 GHz: ``5`` Example configuration: Wi-Fi 6 at 2.4 GHz ------------------------------------------ +------------------------------------------ You may expect real throughput around 10 MB/s or higher in crowded areas. +.. stop_vyoslinter + .. code-block:: none set system wireless country-code de @@ -822,6 +764,8 @@ You may expect real throughput around 10 MB/s or higher in crowded areas. set interfaces wireless wlan0 type access-point commit +.. start_vyoslinter + Resulting configuration: .. code-block:: none @@ -879,13 +823,14 @@ Resulting configuration: } Example configuration: Wi-Fi 6E at 6 GHz ----------------------------------------- +----------------------------------------- -You may expect real throughput between 50 MB/s and 150 MB/s, depending on -obstructions from walls, water, metal, or other materials with high -electromagnetic damping at 6 GHz. +You may expect real throughput between 50 MB/s and 150 MB/s, depending on +obstructions from walls, water, metal, or other materials +with high electromagnetic damping at 6 GHz. Best results are achieved +with the AP being in the same room and in line-of-sight. -Best results are achieved when the AP is in the same room and in line of sight. +.. stop_vyoslinter .. code-block:: none @@ -913,6 +858,8 @@ Best results are achieved when the AP is in the same room and in line of sight. set interfaces wireless wlan0 stationary-ap commit +.. start_vyoslinter + Resulting configuration: .. code-block:: none @@ -968,10 +915,8 @@ Resulting configuration: Intel AX200 =========== -The Intel AX200 card does not operate out of the box in ``access-point`` mode. - -You can still enable :abbr:`AP (Access Point)` functionality on this hardware -by applying the following configuration: +The Intel AX200 card does not work out of the box in AP mode. You can +still put this card into AP mode using the following configuration: .. stop_vyoslinter .. code-block:: none -- cgit v1.2.3