diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_include/common-references.txt | 4 | ||||
| m--------- | docs/_include/vyos-1x | 0 | ||||
| -rw-r--r-- | docs/changelog/1.3.rst | 94 | ||||
| -rw-r--r-- | docs/configuration/service/ssh.rst | 2 | ||||
| -rw-r--r-- | docs/contributing/build-vyos.rst | 13 | ||||
| -rw-r--r-- | docs/contributing/development.rst | 10 | ||||
| -rw-r--r-- | docs/index.rst | 3 | ||||
| -rw-r--r-- | docs/testing.rst | 207 |
8 files changed, 314 insertions, 19 deletions
diff --git a/docs/_include/common-references.txt b/docs/_include/common-references.txt index de4f76e7..a921ec67 100644 --- a/docs/_include/common-references.txt +++ b/docs/_include/common-references.txt @@ -5,5 +5,7 @@ .. _Phabricator: https://phabricator.vyos.net/ .. _802.1ad: https://en.wikipedia.org/wiki/IEEE_802.1ad .. _802.1q: https://en.wikipedia.org/wiki/IEEE_802.1Q +.. _`VyOS CI`: https://ci.vyos.net +.. _vyos-build: https://github.com/vyos/vyos-build -.. start_vyoslinter
\ No newline at end of file +.. start_vyoslinter diff --git a/docs/_include/vyos-1x b/docs/_include/vyos-1x -Subproject f83a5125735bb2f63e4d98e1b264eb689a2ef00 +Subproject d5ac2419296142d015684a8e3f7e5eb9f387d1b diff --git a/docs/changelog/1.3.rst b/docs/changelog/1.3.rst index ec00a1e3..225eba65 100644 --- a/docs/changelog/1.3.rst +++ b/docs/changelog/1.3.rst @@ -8,6 +8,91 @@ _ext/releasenotes.py +2021-08-15 +========== + +* :vytask:`T3756` (default): VyOS generates invalid QR code for wireguard clients +* :vytask:`T3275` (default): Disable conntrack helpers by default + + +2021-08-14 +========== + +* :vytask:`T3745` (feature): op-mode IPSec show vpn ipse sa sorting +* :vytask:`T1083` (feature): Implement "--persistent" option to NAT rules +* :vytask:`T521` (bug): Network services may fail if vyatta-router.service startup takes longer than a few seconds + + +2021-08-13 +========== + +* :vytask:`T3740` (bug): HTTPs API breaks when the address is IPv6 +* :vytask:`T3734` (bug): Move EVPN VRF up in FRR config + + +2021-08-12 +========== + +* :vytask:`T3731` (bug): verify_accel_ppp_base_service return wrong config error for SSP +* :vytask:`T3405` (feature): PPPoE server unit-cache +* :vytask:`T2432` (default): dhcpd: Can't create new lease file: Permission denied +* :vytask:`T3746` (feature): Inform users logging into the system about a pending reboot +* :vytask:`T3744` (default): Dns forwarding statistics formatting missing a new line + + +2021-08-10 +========== + +* :vytask:`T3730` (bug): op-mode conntrack-sync miss some functions + + +2021-08-09 +========== + +* :vytask:`T1501` (bug): VPN Commit Errors + + +2021-08-08 +========== + +* :vytask:`T2027` (bug): get_config_dict is failing when the configuration section is empty/missing +* :vytask:`T169` (feature): Image install should put correct serial console device in created grub menuentry + + +2021-08-07 +========== + +* :vytask:`T548` (feature): BGP IPv6 multipath support + + +2021-08-06 +========== + +* :vytask:`T3196` (bug): No NAT translations showing up +* :vytask:`T1153` (bug): VyOS 1.2.0RC10, RAID-1, fresh install, unable to save config + + +2021-08-05 +========== + +* :vytask:`T696` (feature): Rewrite conntrack sync to XML + + +2021-08-04 +========== + +* :vytask:`T3704` (feature): Add ability to interact with Areca RAID adapers +* :vytask:`T320` (default): ospf does not redistribute connected routes associated with virtuan tunnel interfaces + + +2021-08-02 +========== + +* :vytask:`T2623` (bug): Creating sit tunnel fails with “Can not set “local” for tunnel sit tun1 at tunnel creation” +* :vytask:`T2161` (default): snmpd cannot start if ipv6 disabled +* :vytask:`T3601` (default): Error in ssh keys for vmware cloud-init if ssh keys is left empty. + + 2021-08-01 ========== @@ -129,12 +214,6 @@ * :vytask:`T3632` (bug): policy: route-map: unable to configure route-target / site-of-origin -2021-06-18 -========== - -* :vytask:`T3634` (feature): Add op command option for ping for do not fragment bit to be set - - 2021-06-17 ========== @@ -672,7 +751,7 @@ 2021-02-16 ========== -* :vytask:`T3318` (feature): Update Linux Kernel to v5.4.135 / 5.10.53 +* :vytask:`T3318` (feature): Update Linux Kernel to v5.4.140 / 5.10.58 2021-02-14 @@ -1757,7 +1836,6 @@ * :vytask:`T1486` (bug): Unknown LLDP version reported to peers * :vytask:`T1414` (enhancment): equuleus: buster: 10-unmountfs.chroot fail under apply * :vytask:`T1076` (bug): SSH: make configuration (sshd_config) volatile and store it to /run -* :vytask:`T770` (bug): Bonded interfaces get updated with incorrect hw-id in config. * :vytask:`T2724` (feature): Support for IPv6 Toolset * :vytask:`T2323` (bug): LLDP: "show lldp neighbors detail" returns warnings when service is not configured * :vytask:`T1754` (bug): DHCPv6 client is impossible to restart diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst index 94249766..24881186 100644 --- a/docs/configuration/service/ssh.rst +++ b/docs/configuration/service/ssh.rst @@ -139,7 +139,7 @@ Operation Your identification has been saved in /config/auth/id_rsa_rpki. Your public key has been saved in /config/auth/id_rsa_rpki.pub. The key fingerprint is: - SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q cpo@LR1.wue3 + SHA256:XGv2PpdOzVCzpmEzJZga8hTRq7B/ZYL3fXaioLFLS5Q vyos@vyos The key's randomart image is: +---[RSA 2048]----+ | oo | diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index cb97e418..935f73b5 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -95,9 +95,9 @@ The container can also be built directly from source: $ docker build -t vyos/vyos-build:crux docker # For VyOS 1.2 $ docker build -t vyos/vyos-build:current docker # For rolling release -.. note:: Since VyOS has switched to Debian (10) Buster in its ``current`` - branch, you will require individual container for `current` and `crux` - builds. +.. note:: Since VyOS has switched to Debian (11) Bullseye in its ``current`` + branch, you will require individual container for `current`, `equuleus` and + `crux` builds. Tips and Tricks --------------- @@ -129,6 +129,13 @@ per release train (`current` or `crux`) - container. Add the following to your Now you are prepared with two new aliases ``vybld`` and ``vybld_crux`` to spawn your development containers in your current working directory. +.. note:: Some VyOS packages (namely vyos-1x) come with build-time tests which + verify some of the internal library calls that they work as expected. Those + tests are carried out through the Python Unittest module. If you wan't to + build the ``vyos-1x`` package (which is our main development package) you need + to start your Docker container using the following argument: + ``--sysctl net.ipv6.conf.lo.disable_ipv6=0``, otherwise those tests will fail. + .. _build_native: Native Build diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index cf274a33..591deedf 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -295,7 +295,7 @@ device if you happen to be a crazy scientist. conf = config else: conf = Config() - + # Base path to CLI nodes base = ['...', '...'] # Convert the VyOS config to an abstract internal representation @@ -320,7 +320,7 @@ device if you happen to be a crazy scientist. c = get_config() verify(c) generate(c) - apply(c) + apply(c) except ConfigError as e: print(e) sys.exit(1) @@ -685,9 +685,9 @@ Migrating old CLI Continuous Integration ====================== -VyOS makes use of Jenkins_ as our Continuous Integration (CI) service. Our CI -server is publicly accessible here: https://ci.vyos.net. You can get a brief -overview of all required components shipped in a VyOS ISO. +VyOS makes use of Jenkins_ as our Continuous Integration (CI) service. Our +`VyOS CI`_ server is publicly accessible here: https://ci.vyos.net. You can get +a brief overview of all required components shipped in a VyOS ISO. To build our modules we utilize a CI/CD Pipeline script. Each and every VyOS component comes with it's own ``Jenkinsfile`` which is (more or less) a copy. diff --git a/docs/index.rst b/docs/index.rst index 574a2c49..f81adfc8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,7 +20,7 @@ VyOS User Guide installation/index quick-start cli - + .. toctree:: :maxdepth: 2 :includehidden: @@ -41,6 +41,7 @@ VyOS User Guide contributing/index debugging + testing documentation coverage copyright diff --git a/docs/testing.rst b/docs/testing.rst new file mode 100644 index 00000000..d5df9d59 --- /dev/null +++ b/docs/testing.rst @@ -0,0 +1,207 @@ +.. _testing: + +####### +Testing +####### + +One of the major advantages introduced in VyOS 1.3 is an autmated test framework. +When assembling an ISO image multiple things can go wrong badly and publishing +a faulty ISO makes no sense. The user is disappointed by the quality of the image +and the developers get flodded with bug reports over and over again. + +As the VyOS documentation is not only for users but also for the developers - +and we keep no secret documentation - this section describes how the automated +testing works. + +Jenkins CI +========== + +Our `VyOS CI`_ system is based on Jenkins and builds all our required packages +for VyOS 1.2 to 1.4. In addition to the package build, there is the vyos-build +Job which builds and tests the VyOS ISO image which is published after a +successfull test drive. + +We differentiate in two independent tests, which are both run in parallel by +two separate QEmu instances which are launched via ``make test`` and ``make +testc`` from within the vyos-build_ repository. + +Smoketests +========== + +Smoketests executes predefined VyOS CLI commands and checks if the desired +daemon/service configuration is rendert - that is how to put it "short". + +When and ISO image is assembled by the `VyOS CI`_, the ``BUILD_SMOKETEST`` +parameter is enabled by default, which will extend the ISO configuration line +with the following packages: + +.. code-block:: python + + def CUSTOM_PACKAGES = '' + if (params.BUILD_SMOKETESTS) + CUSTOM_PACKAGES = '--custom-package vyos-1x-smoketest' + +So if you plan to build your own custom ISO image and wan't to make use of our +smoketests, ensure that you have the `vyos-1x-smoketest` package installed. + +The ``make test`` command from the vyos-build_ repository will launch a new +QEmu instance and the ISO image is first installed to the virtual harddisk. + +After its first boot into the newly installed system the main Smoketest script +is executed, it can be found here: `/usr/bin/vyos-smoketest` + +The script only searches for executable "test-cases" under +``/usr/libexec/vyos/tests/smoke/cli/`` and executes them one by one. + +.. note:: As Smoketests will alter the system configuration and you are logged + in remote you may loose your connection to the system. + +Manual Smoketest Run +-------------------- + +On the other hand - as each test is contain in its own file - one can always +execute a single Smoketest by hand by simply running the Python test scripts. + +Example: + +.. code-block:: none + + vyos@vyos:~$ /usr/libexec/vyos/tests/smoke/cli/test_protocols_bgp.py + test_bgp_01_simple (__main__.TestProtocolsBGP) ... ok + test_bgp_02_neighbors (__main__.TestProtocolsBGP) ... ok + test_bgp_03_peer_groups (__main__.TestProtocolsBGP) ... ok + test_bgp_04_afi_ipv4 (__main__.TestProtocolsBGP) ... ok + test_bgp_05_afi_ipv6 (__main__.TestProtocolsBGP) ... ok + test_bgp_06_listen_range (__main__.TestProtocolsBGP) ... ok + test_bgp_07_l2vpn_evpn (__main__.TestProtocolsBGP) ... ok + test_bgp_08_zebra_route_map (__main__.TestProtocolsBGP) ... ok + test_bgp_09_distance_and_flowspec (__main__.TestProtocolsBGP) ... ok + test_bgp_10_vrf_simple (__main__.TestProtocolsBGP) ... ok + test_bgp_11_confederation (__main__.TestProtocolsBGP) ... ok + test_bgp_12_v6_link_local (__main__.TestProtocolsBGP) ... ok + test_bgp_13_solo (__main__.TestProtocolsBGP) ... ok + + ---------------------------------------------------------------------- + Ran 13 tests in 348.191s + + OK + +Interface based tests +--------------------- + +Our smoketests not only test daemons and serives, but also check if what we +configure for an interface works. Thus there is a common base classed named: +``base_interfaces_test.py`` which holds all the common code that an interface +supports and is tested. + +Those common tests consists out of: + +* Add one or more IP addresses +* DHCP client and DHCPv6 prefix delegation +* MTU size +* IP and IPv6 options +* Port description +* Port disable +* VLANs (QinQ and regular 802.1q) +* ... + +.. note:: When you are working on interface configuration and you also wan't to + test if the Smoketests pass you would normally loose the remote SSH connection + to your :abbr:`DUT (Device Under Test)`. To handle this issue, some of the + interface based tests can be called with an environment variable beforehand + to limit the number of interfaces used in the test. By default all interface + e.g. all Ethernet interfaces are used. + +.. code-block:: none + + vyos@vyos:~$ TEST_ETH="eth1 eth2" /usr/libexec/vyos/tests/smoke/cli/test_interfaces_bonding.py + test_add_multiple_ip_addresses (__main__.BondingInterfaceTest) ... ok + test_add_single_ip_address (__main__.BondingInterfaceTest) ... ok + test_bonding_hash_policy (__main__.BondingInterfaceTest) ... ok + test_bonding_lacp_rate (__main__.BondingInterfaceTest) ... ok + test_bonding_min_links (__main__.BondingInterfaceTest) ... ok + test_bonding_remove_member (__main__.BondingInterfaceTest) ... ok + test_dhcpv6_client_options (__main__.BondingInterfaceTest) ... ok + test_dhcpv6pd_auto_sla_id (__main__.BondingInterfaceTest) ... ok + test_dhcpv6pd_manual_sla_id (__main__.BondingInterfaceTest) ... ok + test_interface_description (__main__.BondingInterfaceTest) ... ok + test_interface_disable (__main__.BondingInterfaceTest) ... ok + test_interface_ip_options (__main__.BondingInterfaceTest) ... ok + test_interface_ipv6_options (__main__.BondingInterfaceTest) ... ok + test_interface_mtu (__main__.BondingInterfaceTest) ... ok + test_ipv6_link_local_address (__main__.BondingInterfaceTest) ... ok + test_mtu_1200_no_ipv6_interface (__main__.BondingInterfaceTest) ... ok + test_span_mirror (__main__.BondingInterfaceTest) ... ok + test_vif_8021q_interfaces (__main__.BondingInterfaceTest) ... ok + test_vif_8021q_lower_up_down (__main__.BondingInterfaceTest) ... ok + test_vif_8021q_mtu_limits (__main__.BondingInterfaceTest) ... ok + test_vif_8021q_qos_change (__main__.BondingInterfaceTest) ... ok + test_vif_s_8021ad_vlan_interfaces (__main__.BondingInterfaceTest) ... ok + test_vif_s_protocol_change (__main__.BondingInterfaceTest) ... ok + + ---------------------------------------------------------------------- + Ran 23 tests in 244.694s + + OK + +This will limit the `bond` interface test to only make use of `eth1` and `eth2` +as member ports. + +Config Load Tests +================= + +The other part of our tests are called "config load tests". The config load tests +will load - one after another - arbitrary configuration files to test if the +configuration migration scripts work as designed and that a given set of +functionality still can be loaded with a fresh VyOS ISO image. + +The configurations are all derived from production systems and can not only act +as a testcase but also as reference if one wants to enable a certain feature. +The configurations can be found here: +https://github.com/vyos/vyos-1x/tree/current/smoketest/configs + +The entire test is controlled by the main wrapper script ``/usr/bin/vyos-configtest`` +which behaves in the same way as the main smoketest script. It scans the folder +for potential configuration files and issues a ``load`` command one after another. + +Manual config load test +----------------------- + +One is not bound to load all configurations one after another but can also load +individual test configurations on his own. + +.. code-block:: none + + vyos@vyos:~$ configure + load[edit] + + vyos@vyos# load /usr/libexec/vyos/tests/config/ospf-small + Loading configuration from '/usr/libexec/vyos/tests/config/ospf-small' + Load complete. Use 'commit' to make changes effective. + [edit] + vyos@vyos# compare + [edit interfaces ethernet eth0] + -hw-id 00:50:56:bf:c5:6d + [edit interfaces ethernet eth1] + +duplex auto + -hw-id 00:50:56:b3:38:c5 + +speed auto + [edit interfaces] + -ethernet eth2 { + - hw-id 00:50:56:b3:9c:1d + -} + -vti vti1 { + - address 192.0.2.1/30 + -} + ... + + vyos@vyos# commit + vyos@vyos# + +.. note:: Some of the configurations have preconditions which need to be met. + Those most likely include generation of crypographic keys before the config + can be applied - you will get a commit error otherwise. If you are interested + how those preconditions are fulfilled check the vyos-build_ repository and + the ``scripts/check-qemu-install`` file. + +.. include:: /_include/common-references.txt |