diff options
Diffstat (limited to 'docs/configuration')
| -rw-r--r-- | docs/configuration/interfaces/bridge.rst | 7 | ||||
| -rw-r--r-- | docs/configuration/interfaces/geneve.rst | 2 | ||||
| -rw-r--r-- | docs/configuration/interfaces/openvpn.rst | 80 | ||||
| -rw-r--r-- | docs/configuration/interfaces/vxlan.rst | 20 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wireguard.rst | 12 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wireless.rst | 24 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wwan.rst | 10 |
7 files changed, 79 insertions, 76 deletions
diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst index e69a6e26..5e79107b 100644 --- a/docs/configuration/interfaces/bridge.rst +++ b/docs/configuration/interfaces/bridge.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-06-30 +:lastproofread: 2024-07-04 .. _bridge-interface: @@ -155,9 +155,8 @@ VLAN Options native-vlan <vlan-id> Set the native VLAN ID flag of the interface. When a data packet without a - VLAN tag enters the port, the data packet will be forced to add a tag of a - specific vlan id. When the vlan id flag flows out, the tag of the vlan id - will be stripped + VLAN tag enters the port, the data packet will have a specific vlan id added + to it. When the packet flows out, the native vlan tag will be stripped. Example: Set `eth0` member port to be native VLAN 2 diff --git a/docs/configuration/interfaces/geneve.rst b/docs/configuration/interfaces/geneve.rst index 1e8b8096..a0a46a95 100644 --- a/docs/configuration/interfaces/geneve.rst +++ b/docs/configuration/interfaces/geneve.rst @@ -16,7 +16,7 @@ entirely. GENEVE is designed to support network virtualization use cases, where tunnels are typically established to act as a backplane between the virtual switches residing in hypervisors, physical switches, or middleboxes or other appliances. -An arbitrary IP network can be used as an underlay although Clos networks - A +An arbitrary IP network can be used as an underlay through Clos networks - A technique for composing network fabrics larger than a single switch while maintaining non-blocking bandwidth across connection points. ECMP is used to divide traffic across the multiple links and switches that constitute the diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index fb85f4bf..1dfe1fc5 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -1,4 +1,4 @@ -:lastproofread: 2021-07-05 +:lastproofread: 2024-07-04 .. _openvpn: @@ -9,8 +9,8 @@ OpenVPN Traditionally hardware routers implement IPsec exclusively due to relative ease of implementing it in hardware and insufficient CPU power for doing encryption in software. Since VyOS is a software router, this is less of a -concern. OpenVPN has been widely used on UNIX platform for a long time and is -a popular option for remote access VPN, though it's also capable of +concern. OpenVPN has been widely used on the UNIX platform for a long time and +is a popular option for remote access VPN, though it's also capable of site-to-site connections. Advantages of OpenVPN are: @@ -45,14 +45,15 @@ remains a relatively obscure feature, and many router appliances still don't support it. However, it's very useful for quickly setting up tunnels between routers. -As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates. +As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or +x.509 certificates. -The pre-shared key mode is deprecated and will be removed from future OpenVPN versions, -so VyOS will have to remove support for that option as well. The reason is that using pre-shared keys -is significantly less secure than using TLS. +The pre-shared key mode is deprecated and will be removed from future OpenVPN +versions, so VyOS will have to remove support for that option as well. The +reason is that using pre-shared keys is significantly less secure than using TLS. -We'll configure OpenVPN using self-signed certificates, and then discuss the legacy -pre-shared key mode. +We'll configure OpenVPN using self-signed certificates, and then discuss the +legacy pre-shared key mode. In both cases, we will use the following settings: @@ -168,10 +169,11 @@ Remote Configuration: Pre-shared keys =============== -Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI was to use pre-shared keys. -That option is still available but it is deprecated and will be removed in the future. -However, if you need to set up a tunnel to an older VyOS version or a system with older OpenVPN, -you need to still need to know how to use it. +Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI was to use +pre-shared keys. That option is still available but it is deprecated and will +be removed in the future. However, if you need to set up a tunnel to an older +VyOS version or a system with older OpenVPN, you need to still need to know how +to use it. First, you need to generate a key by running ``run generate pki openvpn shared-secret install <name>`` from configuration mode. You can use any name, we will use ``s2s``. @@ -311,11 +313,11 @@ not come up. Firewall policy can also be applied to the tunnel interface for `local`, `in`, and `out` directions and functions identically to ethernet interfaces. -If making use of multiple tunnels, OpenVPN must have a way to distinguish -between different tunnels aside from the pre-shared-key. This is either by -referencing IP address or port number. One option is to dedicate a public IP -to each tunnel. Another option is to dedicate a port number to each tunnel -(e.g. 1195,1196,1197...). +If you're making use of multiple tunnels, OpenVPN must have a way to +distinguish between different tunnels aside from the pre-shared-key. This is +done either by referencing IP addresses or port numbers. One option is to +dedicate a public IP to each tunnel. Another option is to dedicate a port +number to each tunnel (e.g. 1195,1196,1197...). OpenVPN status can be verified using the `show openvpn` operational commands. See the built-in help for a complete list of options. @@ -327,7 +329,7 @@ Server Multi-client server is the most popular OpenVPN mode on routers. It always uses x.509 authentication and therefore requires a PKI setup. Refer this topic :ref:`configuration/pki/index:pki` to generate a CA certificate, -a server certificate and key, a certificate revocation list, a Diffie-Hellman +a server certificate and key, a certificate revocation list, and a Diffie-Hellman key exchange parameters file. You do not need client certificates and keys for the server setup. @@ -340,14 +342,14 @@ all client subnets belong to 10.23.0.0/20. All clients need access to the 192.168.0.0/16 network. First we need to specify the basic settings. 1194/UDP is the default. The -``persistent-tunnel`` option is recommended, it prevents the TUN/TAP device from -closing on connection resets or daemon reloads. +``persistent-tunnel`` option is recommended, as it prevents the TUN/TAP device +from closing on connection resets or daemon reloads. .. note:: Using **openvpn-option -reneg-sec** can be tricky. This option is - used to renegotiate data channel after n seconds. When used at both server - and client, the lower value will trigger the renegotiation. If you set it to - 0 on one side of the connection (to disable it), the chosen value on the - other side will determine when the renegotiation will occur. + used to renegotiate data channel after n seconds. When used on both the + server and client, the lower value will trigger the renegotiation. If you + set it to 0 on one side of the connection (to disable it), the chosen value + on the other side will determine when the renegotiation will occur. .. code-block:: none @@ -357,7 +359,7 @@ closing on connection resets or daemon reloads. set interfaces openvpn vtun10 protocol udp Then we need to generate, add and specify the names of the cryptographic materials. -Each of the install command should be applied to the configuration and commited +Each of the install commands should be applied to the configuration and commited before using under the openvpn interface configuration. .. code-block:: none @@ -392,7 +394,7 @@ installing that route on clients. set interfaces openvpn vtun10 server push-route 192.168.0.0/16 set interfaces openvpn vtun10 server subnet 10.23.1.0/24 -Since it's a HQ and branch offices setup, we will want all clients to have +Since it's a HQ with branch offices setup, we will want all clients to have fixed addresses and we will route traffic to specific subnets through them. We need configuration for each client to achieve this. @@ -413,9 +415,9 @@ internally, so we need to create a route to the 10.23.0.0/20 network ourselves: set protocols static route 10.23.0.0/20 interface vtun10 Additionally, each client needs a copy of ca cert and its own client key and -cert files. The files are plaintext so they may be copied either manually from the CLI. -Client key and cert files should be signed with the proper ca cert and generated on the -server side. +cert files. The files are plaintext so they may be copied manually from the CLI. +Client key and cert files should be signed with the proper ca cert and generated +on the server side. HQ's router requires the following steps to generate crypto materials for the Branch 1: @@ -570,12 +572,12 @@ example: Client ****** -VyOS can not only act as an OpenVPN site-to-site or server for multiple clients. -You can indeed also configure any VyOS OpenVPN interface as an OpenVPN client -connecting to a VyOS OpenVPN server or any other OpenVPN server. +VyOS can not only act as an OpenVPN site-to-site or server for multiple clients +but you can also configure any VyOS OpenVPN interface as an OpenVPN client that +connects to a VyOS OpenVPN server or any other OpenVPN server. -Given the following example we have one VyOS router acting as OpenVPN server -and another VyOS router acting as OpenVPN client. The server also pushes a +Given the following example we have one VyOS router acting as an OpenVPN server +and another VyOS router acting as an OpenVPN client. The server also pushes a static client IP address to the OpenVPN client. Remember, clients are identified using their CN attribute in the SSL certificate. @@ -754,7 +756,7 @@ between kernel and user space for encryption and packet handling. As a result, the processing of each packet becomes more efficient, potentially leveraging hardware encryption offloading support available in the kernel. -.. note:: OpenVPN DCO is not full OpenVPN features supported , is currently +.. note:: OpenVPN DCO is not a fully supported OpenVPN feature, and is currently considered experimental. Furthermore, there are certain OpenVPN features and use cases that remain incompatible with DCO. To get a comprehensive understanding of the limitations associated with DCO, refer to the list of @@ -770,9 +772,9 @@ DCO support is a per-tunnel option and it is not automatically enabled by default for new or upgraded tunnels. Existing tunnels will continue to function as they have in the past. -DCO can be enabled for both new and existing tunnels,VyOS adds an option in each -tunnel configuration where we can enable this function .The current best -practice is to create a new tunnel with DCO to minimize the chance of problems +DCO can be enabled for both new and existing tunnels. VyOS adds an option in +each tunnel configuration where we can enable this function. The current best +practice is to create a new tunnel with DCO to minimize the chance of problems with existing clients. .. cfgcmd:: set interfaces openvpn <name> offload dco diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst index af00fdec..39901f53 100644 --- a/docs/configuration/interfaces/vxlan.rst +++ b/docs/configuration/interfaces/vxlan.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-01-26 +:lastproofread: 2024-07-04 .. _vxlan-interface: @@ -103,8 +103,8 @@ Unicast .. cfgcmd:: set interfaces vxlan <interface> remote <address> - IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the - remote IPv4/IPv6 address can set directly. + IPv4/IPv6 remote address of the VXLAN tunnel. An alternative to multicast, + the remote IPv4/IPv6 address can be set directly. Multicast ^^^^^^^^^ @@ -117,7 +117,7 @@ Multicast .. cfgcmd:: set interfaces vxlan <interface> group <address> - Multicast group address for VXLAN interface. VXLAN tunnels can be built + Multicast group address for the VXLAN interface. VXLAN tunnels can be built either via Multicast or via Unicast. Both IPv4 and IPv6 multicast is possible. @@ -132,7 +132,7 @@ the same broadcast domain. Let's assume PC4 on Leaf2 wants to ping PC5 on Leaf3. Instead of setting Leaf3 as our remote end manually, Leaf2 encapsulates the packet into a UDP-packet and -sends it to its designated multicast-address via Spine1. When Spine1 receives +sends it to its' designated multicast-address via Spine1. When Spine1 receives this packet it forwards it to all other leaves who has joined the same multicast-group, in this case Leaf3. When Leaf3 receives the packet it forwards it, while at the same time learning that PC4 is reachable behind Leaf2, because @@ -188,8 +188,8 @@ Example The setup is this: Leaf2 - Spine1 - Leaf3 -Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a -VyOS router running 1.2. +Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 are each +VyOS routers running 1.2. This topology was built using GNS3. @@ -282,8 +282,8 @@ traffic from. set interfaces vxlan vxlan242 source-interface 'eth0' set interfaces vxlan vxlan242 vni '242' -As you can see, Leaf2 and Leaf3 configuration is almost identical. There are -lots of commands above, I'll try to into more detail below, command +As you can see, the Leaf2 and Leaf3 configurations are almost identical. There +are lots of commands above, I'll try to go into more detail below. Command descriptions are placed under the command boxes: .. code-block:: none @@ -339,7 +339,7 @@ that behavior is available using the above command. Unicast VXLAN ============= -Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can be +Alternatively to multicast, the remote IPv4 address of the VXLAN tunnel can be set directly. Let's change the Multicast example from above: .. code-block:: none diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst index 885720e1..db2ff2c7 100644 --- a/docs/configuration/interfaces/wireguard.rst +++ b/docs/configuration/interfaces/wireguard.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-01-26 +:lastproofread: 2024-07-04 .. _wireguard: @@ -30,7 +30,7 @@ Generate Keypair .. opcmd:: generate pki wireguard key-pair - It generates the keypair, which includes the public and private parts. + Generates the keypair, which includes the public and private parts. The key is not stored on the system - only a keypair is generated. .. code-block:: none @@ -41,7 +41,7 @@ Generate Keypair .. opcmd:: generate pki wireguard key-pair install interface <interface> - Generates a keypair, which includes the public and private parts, and build + Generates a keypair, which includes the public and private parts, and builds a configuration command to install this key to ``interface``. .. code-block:: none @@ -101,8 +101,8 @@ Optional .. opcmd:: generate pki wireguard preshared-key install interface <interface> peer <peer> An additional layer of symmetric-key crypto can be used on top of the - asymmetric crypto. This command automatically creates for you the required - CLI command to install this PSK for a given peer. + asymmetric crypto. This command automatically creates the required CLI + command to install this PSK for a given peer. This is optional. @@ -409,7 +409,7 @@ the VyOS CLI. connect to ``interface`` on this router. The public key from the specified interface is automatically extracted and embedded into the configuration. - The command also generates a configuration snipped which can be copy/pasted + The command also generates a configuration snippet which can be copy/pasted into the VyOS CLI if needed. The supplied ``<name>`` on the CLI will become the peer name in the snippet. diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index d93e983e..695866a0 100644 --- a/docs/configuration/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-01-26 +:lastproofread: 2024-07-04 .. _wireless-interface: @@ -6,20 +6,20 @@ WLAN/WIFI - Wireless LAN ######################## -:abbr:`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless -support (commonly referred to as Wi-Fi) by means of compatible hardware. If -your hardware supports it, VyOS supports multiple logical wireless interfaces +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. There are three modes of operation for a wireless interface: -* :abbr:`WAP (Wireless Access-Point)` provides network access to connecting +* :abbr:`WAP (Wireless Access-Point)` mode provides network access to connecting stations if the physical hardware supports acting as a WAP -* A station acts as a Wi-Fi client accessing the network through an available +* Station mode acts as a Wi-Fi client accessing the network through an available WAP -* Monitor, the system passively monitors any kind of wireless traffic +* Monitor mode lets the system passively monitor wireless traffic If the system detects an unconfigured wireless device, it will be automatically added the configuration tree, specifying any detected settings (for example, @@ -67,7 +67,7 @@ Wireless options .. cfgcmd:: set interfaces wireless <interface> disable-broadcast-ssid Send empty SSID in beacons and ignore probe request frames that do not specify - full SSID, i.e., require stations to know SSID. + full SSID, i.e., require stations to know the SSID. .. cfgcmd:: set interfaces wireless <interface> expunge-failing-stations @@ -126,10 +126,12 @@ Wireless options .. cfgcmd:: set interfaces wireless <interface> reduce-transmit-power <number> - Add Power Constraint element to Beacon and Probe Response frames. + Adds the Power Constraint information element to Beacon and Probe Response + frames. - This option adds Power Constraint element when applicable and Country element - is added. Power Constraint element is required by Transmit Power Control. + 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. Valid values are 0..255. diff --git a/docs/configuration/interfaces/wwan.rst b/docs/configuration/interfaces/wwan.rst index 98890158..00f927bb 100644 --- a/docs/configuration/interfaces/wwan.rst +++ b/docs/configuration/interfaces/wwan.rst @@ -1,4 +1,4 @@ -:lastproofread: 2023-01-27 +:lastproofread: 2024-07-04 .. _wwan-interface: @@ -320,11 +320,11 @@ The following hardware modules have been tested successfully in an Firmware Update *************** -All available WWAN cards have a build in, reprogrammable firmware. Most of the -vendors provide a regular update to the firmware used in the baseband chip. +All available WWAN cards have a built-in, reprogrammable firmware. Most vendors +provide regular updates to firmware used in the baseband chip. -As VyOS makes use of the QMI interface to connect to the WWAN modem cards, also -the firmware can be reprogrammed. +As VyOS makes use of the QMI interface to connect to the WWAN modem cards, the +firmware can be reprogrammed. 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 |