Merge branch 'master' of github.com:vyos/vyos-documentation into localazy-3

2025-10-26 08:41:46 +01:00 · 2023-08-27 21:04:56 +02:00 · 2023-08-27 21:04:56 +02:00 · 355b459f22
commit 355b459f22
parent abd23045bc 02aafc3df3
17 changed files with 2468 additions and 589 deletions
--- a/README.md
+++ b/README.md
@ -1,7 +1,6 @@
-Starting with VyOS 1.2 (`crux`) our documentation is being migrated from the old wiki
-to ReadTheDocs. Documentation can be accessed via the following URL: https://docs.vyos.io
+Starting with VyOS 1.2 (`crux`) our documentation is hosted on ReadTheDocs at https://docs.vyos.io

-Our old WiKi can still be accessed from the
+Our old wiki with documentation from the VyOS 1.1.x and early 1.2.0 era can still be accessed via the
 [Wayback Machine](https://web.archive.org/web/20200225171529/https://wiki.vyos.net/wiki/Main_Page)

 # Build
@ -28,7 +27,7 @@ largest. There are 88 of them, here's the
 * 1.4.x: `sagitta` (Arrow)
 * ...

-### sphinx
+### Sphinx
 Debian requires some extra steps for
 installing `sphinx`, `sphinx-autobuild` and `sphinx-rtd-theme` packages:

@ -100,18 +99,16 @@ $ docker run --rm -it -p 8000:8000 -v "$(pwd)":/vyos -w /vyos/docs -e \

 ### Test the docs

-Discuss in this Phabricator task: [T1731](https://vyos.dev/T1731)
-
-To test all files run:
+To test all files, run:

 ```bash
 $ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \
  -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation vale .
 ```

-to test a specific file (e.g. `clustering.rst`)
+to test a specific file (e.g. `quick-start.rst`)

 ```bash
 $ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) \
-  -e GOSU_GID=$(id -g) vyos/vyos-documentation vale clustering.rst
+  -e GOSU_GID=$(id -g) vyos/vyos-documentation vale quick-start.rst
 ```
--- a/docs/_include/interface-ipv6.txt
+++ b/docs/_include/interface-ipv6.txt
@ -67,6 +67,34 @@

  .. hint:: MSS value = MTU - 40 (IPv6 header) - 20 (TCP header), resulting in
    1432 bytes on a 1492 byte MTU.
-  
-  Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to 
+
+  Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to
  automatically set the proper value.
+
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} ipv6 accept-dad <1-3>
+
+  Whether to accept DAD (Duplicate Address Detection).
+
+  - 0: Disable DAD
+  - 1: Enable DAD (default)
+  - 2: Enable DAD, and disable IPv6 operation if MAC-based duplicate link-local address has been found.
+
+  Example:
+
+  .. code-block:: none
+
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ipv6 accept-dad 2
+
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} ipv6 dup-addr-detect-transmits <n>
+
+  The amount of Duplicate Address Detection probes to send.
+
+  Default: 1
+
+  Example:
+
+  .. code-block:: none
+
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ipv6 dup-addr-detect-transmits 5
--- a/docs/_include/interface-per-client-thread.txt
+++ b/docs/_include/interface-per-client-thread.txt
@ -0,0 +1,14 @@
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} per-client-thread
+
+  Provides a per-device control to enable/disable the threaded mode for
+  all the NAPI instances of the given network device, without the need for
+  a device up/down.
+
+  If CLI option is not specified, this feature is disabled.
+
+  Example:
+
+  .. code-block:: none
+
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} per-client-thread
--- a/docs/_include/vyos-1x
+++ b/docs/_include/vyos-1x
@ -1 +1 @@
-Subproject commit 1a44d8607f715934f2c03f28a9bf547321b26ed8
+Subproject commit ffb798b4678f3b1bd0a40cc42b1f0477470346dc
--- a/docs/changelog/1.3.rst
+++ b/docs/changelog/1.3.rst
@ -8,6 +8,38 @@
   _ext/releasenotes.py


+2023-08-20
+==========
+
+* :vytask:`T5470` ``(bug): wlan: can not disable interface if SSID is not configured``
+
+
+2023-08-17
+==========
+
+* :vytask:`T5486` ``(bug): Service dns dynamic cannot pass the smoketest``
+* :vytask:`T5223` ``(bug): tunnel key doesn't clear``
+
+
+2023-08-15
+==========
+
+* :vytask:`T5273` ``(default): Add op mode commands for displaying certificate details and fingerprints``
+* :vytask:`T5270` ``(default): Make OpenVPN `tls dh-params` optional``
+
+
+2023-08-10
+==========
+
+* :vytask:`T5329` ``(bug): Wireguard interface as GRE tunnel source causes configuration error on boot``
+
+
+2023-08-06
+==========
+
+* :vytask:`T3424` ``(default): PPPoE IA-PD doesn't work in VRF``
+
+
 2023-07-24
 ==========

--- a/docs/changelog/1.4.rst
+++ b/docs/changelog/1.4.rst
@ -8,6 +8,148 @@
   _ext/releasenotes.py


+2023-08-20
+==========
+
+* :vytask:`T5470` ``(bug): wlan: can not disable interface if SSID is not configured``
+
+
+2023-08-18
+==========
+
+* :vytask:`T5488` ``(bug): System conntrack ignore does not take any effect``
+
+
+2023-08-17
+==========
+
+* :vytask:`T4202` ``(bug): NFT: Zone policies fail to apply when "l2tp+" is in the interface list``
+* :vytask:`T5409` ``(feature): Add 'set interfaces wireguard wgX threaded'``
+* :vytask:`T5476` ``(feature): netplug: replace Perl helper scripts with a Python equivalent``
+* :vytask:`T5223` ``(bug): tunnel key doesn't clear``
+* :vytask:`T5490` ``(feature): login: add missing regex for home direcotry and radius server key``
+
+
+2023-08-16
+==========
+
+* :vytask:`T5483` ``(bug): Residual dhcp-server test file causing zabbix-agent smoketest to fail``
+
+
+2023-08-15
+==========
+
+* :vytask:`T5293` ``(feature): Support for Floating Rules (Global Firewall-Rules that are automatically applied before all other Zone Rules)``
+* :vytask:`T5273` ``(default): Add op mode commands for displaying certificate details and fingerprints``
+* :vytask:`T5270` ``(default): Make OpenVPN `tls dh-params` optional``
+
+
+2023-08-14
+==========
+
+* :vytask:`T5477` ``(bug): op-mode pki.py should use Config for defaults``
+* :vytask:`T5461` ``(feature): Improve rootfs directory variable``
+* :vytask:`T5457` ``(feature): Add environmental variable pointing to current rootfs directory``
+* :vytask:`T5440` ``(bug): Restore pre/postconfig scripts if user deleted them``
+* :vytask:`T5436` ``(bug): vyos-preconfig-bootup.script is missing``
+
+
+2023-08-12
+==========
+
+* :vytask:`T5467` ``(bug): ospf(v3): removing an interface from the OSPF process does not clear FRR configuration``
+
+
+2023-08-11
+==========
+
+* :vytask:`T5465` ``(feature): adjust-mss: config migration fails if applied to a VLAN or Q-in-Q interface``
+* :vytask:`T2665` ``(bug): vyos.xml.defaults for tag nodes``
+* :vytask:`T5434` ``(enhancment): Replace remaining calls of vyos.xml library``
+* :vytask:`T5319` ``(enhancment): Remove remaining workarounds for incorrect defaults``
+* :vytask:`T5464` ``(feature): ipv6: add support for per-interface dad (duplicate address detection) setting``
+
+
+2023-08-10
+==========
+
+* :vytask:`T5416` ``(bug): Ignoring "ipsec match-none" for firewall``
+* :vytask:`T5329` ``(bug): Wireguard interface as GRE tunnel source causes configuration error on boot``
+
+
+2023-08-09
+==========
+
+* :vytask:`T5452` ``(bug): Uncaught error in generate_cache during vyos-1x build``
+* :vytask:`T5443` ``(enhancment): Add merge_defaults as Config method``
+* :vytask:`T5435` ``(enhancment): Expose utility function for default values at path``
+
+
+2023-08-07
+==========
+
+* :vytask:`T5406` ``(bug): "update webproxy blacklists" fails when vrf is being configured``
+* :vytask:`T5302` ``(bug): QoS class with multiple matches generates one filter rule but expects several rules``
+* :vytask:`T5266` ``(bug): QoS- HTB error when match with  a dscp parameter for queue-type 'priority'``
+* :vytask:`T5071` ``(bug): QOS-Rewrite: DSCP match missing``
+
+
+2023-08-06
+==========
+
+* :vytask:`T5420` ``(feature): nftables - upgrade to latest 1.0.8``
+* :vytask:`T3424` ``(default): PPPoE IA-PD doesn't work in VRF``
+* :vytask:`T5445` ``(feature): dyndns: add possibility to specify update interval (timeout)``
+
+
+2023-08-05
+==========
+
+* :vytask:`T5291` ``(bug): vyatta-cfg-cmd-wrapper missing ${vyos_libexec_dir} variable``
+* :vytask:`T5290` ``(bug): Failing commits for SR-IOV interfaces using ixgbevf driver due to change speed/duplex settings``
+* :vytask:`T5439` ``(bug): Upgrade to FRR version 9.0 added new daemons which must be adjusted``
+
+
+2023-08-04
+==========
+
+* :vytask:`T5427` ``(bug): Change migration script len arguments checking``
+
+
+2023-08-03
+==========
+
+* :vytask:`T5301` ``(bug): NTP: chrony only allows one bind address``
+* :vytask:`T5154` ``(bug): Chrony - multiple listen addresses``
+
+
+2023-08-02
+==========
+
+* :vytask:`T5374` ``(feature): Ability to set 24-hour time format``
+* :vytask:`T5350` ``(bug): Confusing warning message when committing VRRP config``
+* :vytask:`T5430` ``(bug): bridge: vxlan interfaces are not listed as bridgable in completion helpers``
+* :vytask:`T5429` ``(bug): vxlan: source-interface is not honored and throws config error``
+* :vytask:`T5415` ``(feature): Upgrade FRR to version 9.0``
+* :vytask:`T5422` ``(feature): Support LXD Agent``
+
+
+2023-08-01
+==========
+
+* :vytask:`T5399` ``(bug): "show ntp" fails when vrf is being configured``
+* :vytask:`T5346` ``(bug): MPLS sysctl not persistent for L2TP interfaces``
+* :vytask:`T5343` ``(feature): BGP peer group VPNv4 & VPNv6 Address Family Support``
+* :vytask:`T5339` ``(feature): Geneve interface - option to use IPv4 as inner protocol``
+* :vytask:`T5335` ``(bug): ISIS: error when loading config from file``
+
+
+2023-07-31
+==========
+
+* :vytask:`T5421` ``(feature): Add arg to completion helper 'list_interfaces' to filter out vlan subinterfaces``
+
+
 2023-07-29
 ==========

--- a/docs/configuration/firewall/general-legacy.rst
+++ b/docs/configuration/firewall/general-legacy.rst
--- a/docs/configuration/firewall/general.rst
+++ b/docs/configuration/firewall/general.rst
--- a/docs/configuration/firewall/index.rst
+++ b/docs/configuration/firewall/index.rst
@ -2,9 +2,23 @@
 Firewall
 ########

+Starting from VyOS 1.4-rolling-202308040557, a new firewall structure
+can be found on all vyos installations. Documentation for most new firewall
+cli can be found here:
+
 .. toctree::
   :maxdepth: 1
   :includehidden:

   general
+
+Also, for those who haven't updated to newer version, legacy documentation is
+still present and valid for all sagitta version prior to VyOS
+1.4-rolling-202308040557:
+
+.. toctree::
+   :maxdepth: 1
+   :includehidden:
+
+   general-legacy
   zone
--- a/docs/configuration/firewall/zone.rst
+++ b/docs/configuration/firewall/zone.rst
@ -6,6 +6,10 @@
 Zone Based Firewall
 ###################

+.. note:: **Important note:**
+   This documentation is valid only for VyOS Sagitta prior to
+   1.4-rolling-YYYYMMDDHHmm
+
 In zone-based policy, interfaces are assigned to zones, and inspection policy
 is applied to traffic moving between the zones and acted on according to
 firewall rules. A Zone is a group of interfaces that have similar functions or
--- a/docs/configuration/interfaces/macsec.rst
+++ b/docs/configuration/interfaces/macsec.rst
@ -44,6 +44,30 @@ MACsec options
  A physical interface is required to connect this MACsec instance to. Traffic
  leaving this interface will now be authenticated/encrypted.

+Static Keys
+-----------
+Static :abbr:`SAK (Secure Authentication Key)` mode can be configured manually on each
+device wishing to use MACsec. Keys must be set statically on all devices for traffic
+to flow properly. Key rotation is dependent on the administrator updating all keys
+manually across connected devices. Static SAK mode can not be used with MKA.
+
+.. cfgcmd:: set interfaces macsec <interface> security static key <key>
+
+  Set the device's transmit (TX) key. This key must be a hex string that is 16-bytes 
+  (GCM-AES-128) or 32-bytes (GCM-AES-256).
+
+.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> mac <mac address>
+
+  Set the peer's MAC address
+
+.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> key <key>
+
+  Set the peer's key used to receive (RX) traffic
+
+.. cfgcmd:: set interfaces macsec <interface> security static peer <peer> disable
+
+  Disable the peer configuration
+
 Key Management
 --------------

@ -188,3 +212,28 @@ the unencrypted but authenticated content.
          0x0070:  3031 3233 3435 3637 87d5 eed3 3a39 d52b  01234567....:9.+
          0x0080:  a282 c842 5254 ef28                      ...BRT.(

+**R1 Static Key**
+
+.. code-block:: none
+
+  set interfaces macsec macsec1 address '192.0.2.1/24'
+  set interfaces macsec macsec1 address '2001:db8::1/64'
+  set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+  set interfaces macsec macsec1 security encrypt
+  set interfaces macsec macsec1 security static key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
+  set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:02
+  set interfaces macsec macsec1 security static peer R2 key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
+  set interfaces macsec macsec1 source-interface 'eth1'
+
+**R2 Static Key**
+
+.. code-block:: none
+
+  set interfaces macsec macsec1 address '192.0.2.2/24'
+  set interfaces macsec macsec1 address '2001:db8::2/64'
+  set interfaces macsec macsec1 security cipher 'gcm-aes-128'
+  set interfaces macsec macsec1 security encrypt
+  set interfaces macsec macsec1 security static key 'eadcc0aa9cf203f3ce651b332bd6e6c7'
+  set interfaces macsec macsec1 security static peer R2 mac 00:11:22:33:44:01
+  set interfaces macsec macsec1 security static peer R2 key 'ddd6f4a7be4d8bbaf88b26f10e1c05f7'
+  set interfaces macsec macsec1 source-interface 'eth1'
--- a/docs/configuration/interfaces/wireguard.rst
+++ b/docs/configuration/interfaces/wireguard.rst
@ -183,6 +183,10 @@ traffic.
  The command :opcmd:`show interfaces wireguard wg01 public-key` will then show the
  public key, which needs to be shared with the peer.

+.. cmdinclude:: /_include/interface-per-client-thread.txt
+   :var0: wireguard
+   :var1: wg01
+
 **remote side - commands**

 .. code-block:: none
--- a/docs/configuration/interfaces/wireless.rst
+++ b/docs/configuration/interfaces/wireless.rst
@ -122,6 +122,10 @@ Wireless options
  * ``station`` - Connects to another access point
  * ``monitor`` - Passively monitor all packets on the frequency/channel

+.. cmdinclude:: /_include/interface-per-client-thread.txt
+   :var0: wireless
+   :var1: wlan0
+
 PPDU
 ----

@ -304,6 +308,7 @@ default physical device (``phy0``) is used.

  set interfaces wireless wlan0 type station
  set interfaces wireless wlan0 address dhcp
+  set interfaces wireless wlan0 country-code de
  set interfaces wireless wlan0 ssid Test
  set interfaces wireless wlan0 security wpa passphrase '12345678'

@ -315,6 +320,7 @@ Resulting in
    [...]
    wireless wlan0 {
      address dhcp
+      country-code de
      security {
        wpa {
          passphrase "12345678"
@ -350,6 +356,7 @@ The WAP in this example has the following characteristics:
 .. code-block:: none

  set interfaces wireless wlan0 address '192.168.2.1/24'
+  set interfaces wireless wlan0 country-code de
  set interfaces wireless wlan0 type access-point
  set interfaces wireless wlan0 channel 1
  set interfaces wireless wlan0 mode n
@ -367,6 +374,7 @@ Resulting in
    [...]
    wireless wlan0 {
          address 192.168.2.1/24
+          country-code de
          channel 1
          mode n
          security {
@ -385,11 +393,6 @@ Resulting in
          type access-point
      }
  }
-  system {
-    [...]
-    wifi-regulatory-domain DE
-  }
-

 VLAN
 ====
--- a/docs/configuration/nat/nat44.rst
+++ b/docs/configuration/nat/nat44.rst
@ -283,6 +283,32 @@ Example of redirection:

  set nat destination rule 10 translation redirect port 22

+NAT Load Balance
+----------------
+
+Advanced configuration can be used in order to apply source or destination NAT,
+and within a single rule, be able to define multiple translated addresses,
+so NAT balances the translations among them.
+
+NAT Load Balance uses an algorithm that generates a hash and based on it, then
+it applies corresponding translation. This hash can be generated randomly, or 
+can use data from the ip header: source-address, destination-address,
+source-port and/or destination-port. By default, it will generate the hash
+randomly.
+
+When defining the translated address, called ``backends``, a ``weight`` must
+be configured. This lets the user define load balance distribution according
+to their needs. Them sum of all the weights defined for the backends should
+be equal to 100. In oder words, the weight defined for the backend is the
+percentage of the connections that will receive such backend.
+
+.. cfgcmd:: set nat [source | destination] rule <rule> load-balance hash
+   [source-address | destination-address | source-port | destination-port
+   | random]
+.. cfgcmd:: set nat [source | destination] rule <rule> load-balance backend
+  <x.x.x.x> weight <1-100>
+
+
 Configuration Examples
 ======================

@ -602,6 +628,40 @@ provide access to their internal resources, and require that a
 connecting organisation translate all traffic to the service provider
 network to a source address provided by the ASP.

+Load Balance
+------------
+Here we provide two examples on how to apply NAT Load Balance.
+
+First scenario: apply destination NAT for all HTTP traffic comming through
+interface eth0, and user 4 backends. First backend should received 30% of
+the request, second backend should get 20%, third 15% and the fourth 35%
+We will use source and destination address for hash generation.
+
+.. code-block:: none
+
+  set nat destination rule 10 inbound-interface eth0
+  set nat destination rule 10 protocol tcp
+  set nat destination rule 10 destination port 80
+  set nat destination rule 10 load-balance hash source-address
+  set nat destination rule 10 load-balance hash destination-address
+  set nat destination rule 10 laod-balance backend 198.51.100.101 weight 30
+  set nat destination rule 10 laod-balance backend 198.51.100.102 weight 20
+  set nat destination rule 10 laod-balance backend 198.51.100.103 weight 15
+  set nat destination rule 10 laod-balance backend 198.51.100.104 weight 35
+
+Second scenario: apply source NAT for all outgoing connections from
+LAN 10.0.0.0/8, using 3 public addresses and equal distribution.
+We will generate the hash randomly.
+
+.. code-block:: none
+
+  set nat source rule 10 outbound-interface eth0
+  set nat source rule 10 source address 10.0.0.0/8
+  set nat source rule 10 load-balance hash random
+  set nat source rule 10 load-balance backend 192.0.2.251 weight 33
+  set nat source rule 10 load-balance backend 192.0.2.252 weight 33
+  set nat source rule 10 load-balance backend 192.0.2.253 weight 34
+
 Example Network
 ^^^^^^^^^^^^^^^

--- a/docs/configuration/service/dns.rst
+++ b/docs/configuration/service/dns.rst
@ -251,6 +251,12 @@ Configuration
   Configure optional TTL value on the given resource record. This defaults to
   600 seconds.

+.. cfgcmd:: set service dns dynamic timeout <60-3600>
+
+   Specify timeout / update interval to check if IP address changed.
+
+   This defaults to 300 seconds.
+
 .. _dns:dynmaic_example:

 Example
--- a/docs/configuration/vrf/index.rst
+++ b/docs/configuration/vrf/index.rst
@ -424,6 +424,14 @@ address-family.
   unicast VRF to VPN. If the value specified is auto, the label value is
   automatically assigned from a pool maintained.

+.. cfgcmd:: set vrf name <name> protocols bgp address-family
+            <ipv4-unicast|ipv6-unicast> label vpn allocation-mode per-nexthop
+
+   Select how labels are allocated in the given VRF. By default, the per-vrf 
+   mode is selected, and one label is used for all prefixes from the VRF. The 
+   per-nexthop will use a unique label for all prefixes that are reachable via 
+   the same nexthop.
+
 .. cfgcmd:: set vrf name <name> protocols bgp address-family
            <ipv4-unicast|ipv6-unicast> route-map vpn <import|export>
            [route-map <name>]
@ -444,6 +452,13 @@ address-family.
   derived and should not be specified explicitly for either the source or
   destination VRF’s.

+.. cfgcmd:: set vrf name <name> protocols bgp interface <interface> mpls
+            forwarding
+
+   It is possible to permit BGP install VPN prefixes without transport labels.
+   This configuration will install VPN prefixes originated from an e-bgp session,
+   and with the next-hop directly connected.
+
 .. _l3vpn-vrf example operation:

 Operation
--- a/docs/installation/virtual/docker.rst
+++ b/docs/installation/virtual/docker.rst
@ -49,7 +49,7 @@ Deploy container from ISO
 =========================

 Download the ISO on which you want to base the container. In this example, 
-the name of the ISO is ``vyos-1.4-rolling-202111281249-amd64.iso``. If you
+the name of the ISO is ``vyos-1.4-rolling-202308240020-amd64.iso``. If you
 created a custom IPv6-enabled network, the ``docker run`` command below
 will require that this network be included as the ``--net`` parameter to
 ``docker run``.
@ -57,9 +57,10 @@ will require that this network be included as the ``--net`` parameter to
 .. code-block:: none

  $ mkdir vyos && cd vyos
-  $ cp ~/vyos-1.4-rolling-202111281249-amd64.iso .
+  $ curl -o vyos-1.4-rolling-202308240020-amd64.iso https://github.com/vyos/vyos-rolling-night
+ly-builds/releases/download/1.4-rolling-202308240020/vyos-1.4-rolling-202308240020-amd64.iso
  $ mkdir rootfs
-  $ sudo mount -o loop vyos-1.4-rolling-202111281249-amd64.iso rootfs
+  $ sudo mount -o loop vyos-1.4-rolling-202308240020-amd64.iso rootfs
  $ sudo apt-get install -y squashfs-tools
  $ mkdir unsquashfs
  $ sudo unsquashfs -f -d unsquashfs/ rootfs/live/filesystem.squashfs