From 88957530a3e174bfc61e8358cb2b28fd8f1fbbb6 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 18:46:21 +0300 Subject: feat: import MyST swap mechanism + content for sagitta (replaces #1886) Replaces the broken #1886 with a fresh, properly-converted MyST set for the sagitta (1.4.x) docs, mirroring what landed for circinus via #1897. This PR: - Re-imports 210 md-*.md files for sagitta. Source: ran the pipelines rst-to-myst converter (chrisjsewell/rst-to-myst v0.4.0, with pandoc fallback) on sagittas RST. Post-processed via the pipelines postprocess stage (10 ordered fixes for blanks, admonitions, label hyphens, pandoc artifacts, structural blanks, linter markers). Compared to the broken #1886 content (which was left over from an earlier stage-1-only run): zero raw `
` remnants. - For 23 stems where sagittas RST is byte-identical with currents RST (mostly stable policy/protocol pages and the 404 page), reuses currents already-validated md-*.md content rather than re-converting. - Drops cli and installation/cloud/aws from sagittas swap set: their RST has SEVERE/4 "Title level inconsistent" errors that crash rst-to-myst; they need an independent RST-source fix and are kept as RST-only for now. - Adds the per-page swap mechanism: scripts/swap_sources.py, scripts/import_myst.py, the matching tests under tests/, _swap.txt with 210 stems, _ext/vyos.py MyST renderer fallback, Makefile swap-wrapped targets, .readthedocs.yml swap pre/post hooks. - Adds 187 .webp images and removes 235 superseded .jpg/.png/.jpeg static assets; flips html_logo to vyos-logo.webp. - Adds the MyST swap-related blocks to docs/conf.py only: myst_enable_extensions, myst_fence_as_directive, md-*.md exclude patterns, _swap_exclude.txt reader, _prefer_webp and _copy_md_sources setup hooks. github_version fallback set to 'sagitta' to match the branch (parallel to currents 'current' and circinuss 'circinus'). Deliberately excluded (per user direction): - llms.txt and sphinx-llms-txt / sphinx-sitemap config: these will land separately for sagitta via #1870 plus a new sagitta-specific llms.txt template PR. The conf.py here does not pull those extensions in, so the build does not depend on the new pip packages. Verification before pushing: - 210 md-*.md = 210 _swap.txt stems = 210 RST siblings on sagitta (1:1:1). - 0 files contain raw `
vyos:1.4-rolling-202111281249 /sbin/init +$ docker exec -ti vyos su - vyos +``` + +You can execute `docker stop vyos` when you are finished with the container. diff --git a/docs/installation/virtual/md-eve-ng.md b/docs/installation/virtual/md-eve-ng.md new file mode 100644 index 00000000..3e32e61f --- /dev/null +++ b/docs/installation/virtual/md-eve-ng.md @@ -0,0 +1,5 @@ +# EVE-NG + +## References + + diff --git a/docs/installation/virtual/md-gns3.md b/docs/installation/virtual/md-gns3.md new file mode 100644 index 00000000..d903c9a4 --- /dev/null +++ b/docs/installation/virtual/md-gns3.md @@ -0,0 +1,187 @@ +(vyos-on-gns3)= + +# Running on GNS3 + +Sometimes you may want to test VyOS in a lab environment. +[GNS3](http://www.gns3.com) is a network emulation software you +might use for it. + +This guide will provide the necessary steps for installing +and setting up VyOS on GNS3. + +## Requirements + +The following items are required: + +- A VyOS installation image (.iso file). You + can find how to get it on the {ref}`installation` page +- A working GNS3 installation. For further information see the + [GNS3 documentation](https://docs.gns3.com/). + +(vm-setup)= + +## VM setup + +First, a virtual machine (VM) for the VyOS installation must be created +in GNS3. + +Go to the GNS3 **File** menu, click **New template** and choose select +**Manually create a new Template**. + +:::{figure} /_static/images/gns3-01.png +::: + +Select **Quemu VMs** and then click on the `New` button. + +:::{figure} /_static/images/gns3-02.png +::: + +Write a name for your VM, for instance "VyOS", and click `Next`. + +:::{figure} /_static/images/gns3-03.png +::: + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click `Next`. + +:::{figure} /_static/images/gns3-04.png +::: + +Select **telnet** as your console type and click `Next`. + +:::{figure} /_static/images/gns3-05.png +::: + +Select **New image** for the base disk image of your VM and click +`Create`. + +:::{figure} /_static/images/gns3-06.png +::: + +Use the defaults in the **Binary and format** window and click +`Next`. + +:::{figure} /_static/images/gns3-07.png +::: + +Use the defaults in the **Qcow2 options** window and click `Next`. + +:::{figure} /_static/images/gns3-08.png +::: + +Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu +image creator**. + +:::{figure} /_static/images/gns3-09.png +::: + +Click `Finish` to end the **New QEMU VM template** wizard. + +:::{figure} /_static/images/gns3-10.png +::: + +Now the VM settings have to be edited. + +Being again at the **Preferences** window, having **Qemu VMs** +selected and having our new VM selected, click the `Edit` button. + +:::{figure} /_static/images/gns3-11.png +::: + +In the **General settings** tab of your **QEMU VM template +configuration**, do the following: + +- Click on the `Browse...` button to choose the **Symbol** you want to + have representing your VM. +- In **Category** select in which group you want to find your VM. +- Set the **Boot priority** to **CD/DVD-ROM**. + +:::{figure} /_static/images/gns3-12.png +::: + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +:::{figure} /_static/images/gns3-13.png +::: + +At the **CD/DVD** tab click on `Browse...` and locate the VyOS image +you want to install. + +:::{figure} /_static/images/gns3-14.png +::: + +:::{note} +You probably will want to accept to copy the .iso file to your +default image directory when you are asked. +::: + +In the **Network** tab, set **0** as the number of adapters, set the +**Name format** to **eth\{0}** and the **Type** to **Paravirtualized +Network I/O (virtio-net-pci)**. + +:::{figure} /_static/images/gns3-15.png +::: + +In the **Advanced** tab, unmark the checkbox **Use as a linked base +VM** and click `OK`, which will save and close the **QEMU VM template +configuration** window. + +:::{figure} /_static/images/gns3-16.png +::: + +At the general **Preferences** window, click `OK` to save and close. + +:::{figure} /_static/images/gns3-17.png +::: + +(vyos-installation)= + +## VyOS installation + +- Create a new project. +- Drag the newly created VyOS VM into it. +- Start the VM. +- Open a console. + The console should show the system booting. It will ask for the login + credentials, you are at the VyOS live system. +- {ref}`Install VyOS ` + as normal (that is, using the `install image` command). +- After a successful installation, shutdown the VM with the `poweroff` + command. +- **Delete the VM** from the GNS3 project. + +The *VyOS-hda.qcow2* file now contains a working VyOS image and can be +used as a template. But it still needs some fixes before we can deploy +VyOS in our labs. + +(vyos-vm-configuration)= + +## VyOS VM configuration + +To turn the template into a working VyOS machine, further steps are +necessary as outlined below: + +**General settings** tab: Set the boot priority to **HDD** + +:::{figure} /_static/images/gns3-20.png +::: + +**CD/DVD** tab: Unmount the installation image file by clearing the +**Image** entry field. + +:::{figure} /_static/images/gns3-21.png +::: + +Set the number of required network adapters, for example **4**. + +:::{figure} /_static/images/gns3-215.png +::: + +**Advanced** settings tab: Mark the checkbox **Use as a linked +base VM** and click `OK` to save the changes. + +:::{figure} /_static/images/gns3-22.png +::: + +The VyOS VM is now ready to be deployed. diff --git a/docs/installation/virtual/md-index.md b/docs/installation/virtual/md-index.md new file mode 100644 index 00000000..12ac179e --- /dev/null +++ b/docs/installation/virtual/md-index.md @@ -0,0 +1,13 @@ +# Running VyOS in Virtual Environments + +```{eval-rst} +.. toctree:: + :caption: Content + + libvirt + proxmox + vmware + gns3 + eve-ng + docker +``` diff --git a/docs/installation/virtual/md-libvirt.md b/docs/installation/virtual/md-libvirt.md new file mode 100644 index 00000000..5acefd43 --- /dev/null +++ b/docs/installation/virtual/md-libvirt.md @@ -0,0 +1,171 @@ +(libvirt)= + +# Running on Libvirt Qemu/KVM + +Libvirt is an open-source API, daemon and management tool for managing platform +virtualization. There are several ways to deploy VyOS on libvirt kvm. +Use Virt-manager and native CLI. In an example we will be use use 4 gigabytes +of memory, 2 cores CPU and default network virbr0. + +## CLI + +### Deploy from ISO + +Create VM name `vyos_r1`. You must specify the path to the `ISO` image, +the disk `qcow2` will be created automatically. The `default` network is +the virtual network (type Virtio) created by the hypervisor with NAT. + +```none +$ virt-install -n vyos_r1 \ + --ram 4096 \ + --vcpus 2 \ + --cdrom /var/lib/libvirt/images/vyos.iso \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ + --noautoconsole +``` + +Connect to VM with command `virsh console vyos_r1` + +```none +$ virsh console vyos_r1 + +Connected to domain vyos_r1 +Escape character is ^] + +vyos login: vyos +Password: + +vyos@vyos:~$ install image +``` + +After installation - exit from the console using the key combination +`Ctrl + ]` and reboot the system. + +### Deploy from qcow2 + +The convenience of using {abbr}`KVM (Kernel-based Virtual Machine)` +images is that they don't need to be installed. +Download predefined VyOS.qcow2 image for `KVM` + +```none +curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 +``` + +Create VM with `import` qcow2 disk option. + +```none +$ virt-install -n vyos_r2 \ + --ram 4096 \ + --vcpus 2 \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ + --import \ + --noautoconsole +``` + +Connect to VM with command `virsh console vyos_r2` + +```none +$ virsh console vyos_r2 + +Connected to domain vyos_r2 +Escape character is ^] + +vyos login: vyos +Password: + +vyos@vyos:~$ +``` + +The system is fully operational. + +## Virt-manager + +The virt-manager application is a desktop user interface for managing virtual +machines through libvirt. On the linux open +{abbr}`VMM (Virtual Machine Manager)`. + +(libvirt-virt-manager-iso)= + +### Deploy from ISO + +1. Open {abbr}`VMM (Virtual Machine Manager)` and Create a new + {abbr}`VM (Virtual Machine)` +2. Choose `Local install media` (ISO) + +:::{figure} /_static/images/virt-libvirt-01.png +::: + +3. Choose path to iso vyos.iso. Operating System can be any Debian based. + +:::{figure} /_static/images/virt-libvirt-02.png +::: + +4. Choose Memory and CPU + +:::{figure} /_static/images/virt-libvirt-03.png +::: + +5. Disk size + +:::{figure} /_static/images/virt-libvirt-04.png +::: + +6. Name of VM and network selection + +:::{figure} /_static/images/virt-libvirt-05.png +::: + +7. Then you will be taken to the console. + +:::{figure} /_static/images/virt-libvirt-06.png +::: + +(libvirt-virt-manager-qcow2)= + +### Deploy from qcow2 + +Download predefined VyOS.qcow2 image for `KVM` + +```none +curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 +``` + +1. Open {abbr}`VMM (Virtual Machine Manager)` and Create a new + {abbr}`VM (Virtual Machine)` +2. Choose `Import existing disk` image + +:::{figure} /_static/images/virt-libvirt-qc-01.png +::: + +3. Choose the path to the image `vyos_kvm.qcow2` that was previously + downloaded . Operation System can be any Debian based. + +:::{figure} /_static/images/virt-libvirt-qc-02.png +::: + +4. Choose Memory and CPU + +:::{figure} /_static/images/virt-libvirt-03.png +::: + +5. Name of VM and network selection + +:::{figure} /_static/images/virt-libvirt-05.png +::: + +6. Then you will be taken to the console. + +:::{figure} /_static/images/virt-libvirt-qc-03.png +::: diff --git a/docs/installation/virtual/md-proxmox.md b/docs/installation/virtual/md-proxmox.md new file mode 100644 index 00000000..cad22137 --- /dev/null +++ b/docs/installation/virtual/md-proxmox.md @@ -0,0 +1,45 @@ +(proxmox)= + +# Running on Proxmox + +Proxmox is an open-source platform for virtualization. Please visit + to see how to get a qcow2 image that can be imported +into Proxmox. + +## Deploy VyOS from CLI with qcow2 image + +1. Copy the qcow2 image to a temporary directory on the Proxmox server. +2. The commands below assume that virtual machine ID 200 is unused and that the user wants the disk stored in a storage pool called `local-lvm`. + +```none +$ qm create 200 --name vyos2 --memory 2048 --net0 virtio,bridge=vmbr0 +$ qm importdisk 200 /path/to/image/vyos-1.2.8-proxmox-2G.qcow2 local-lvm +$ qm set 200 --virtio0 local-lvm:vm-200-disk-0 +$ qm set 200 --boot order=virtio0 +``` + +3. Optionally, the user can attach a CDROM with an ISO as a cloud-init data source. The below command assumes the ISO has been uploaded to the `local` storage pool with the name `seed.iso`. + +```none +$ qm set 200 --ide2 media=cdrom,file=local:iso/seed.iso +``` + +4. Start the virtual machine in the proxmox GUI or CLI using `qm start 200`. + +## Deploy VyOS from CLI with rolling release ISO + +1. Download the rolling release iso from . Non-subscribers can always get the LTS release by building it from source. Instructions can be found in the {ref}`build` section of this manual. VyOS source code repository is available . +2. Prepare VM for installation from ISO media. The commands below assume that your iso is available in a storage pool 'local', that you want it to have a VM ID '200' and want to create a new disk on storage pool 'local-lvm' of size 15GB. + +```none +qm create 200 --name vyos --memory 2048 --net0 virtio,bridge=vmbr0 --ide2 media=cdrom,file=local:iso/live-image-amd64.hybrid.iso --virtio0 local-lvm:15 +``` + +3. Start the VM using the command `qm start 200` or using the start button located in the proxmox GUI. +4. Using the proxmox webGUI, open the virtual console for your newly created vm. Login username/password is `vyos/vyos`. +5. Once booted into the live system, type `install image` into the command line and follow the prompts to install VyOS to the virtual drive. +6. After installation has completed, remove the installation iso using the GUI or `qm set 200 --ide2 none`. +7. Reboot the virtual machine using the GUI or `qm reboot 200`. + +Visit for more information about the download +and installation of this hypervisor. diff --git a/docs/installation/virtual/md-vmware.md b/docs/installation/virtual/md-vmware.md new file mode 100644 index 00000000..0338067c --- /dev/null +++ b/docs/installation/virtual/md-vmware.md @@ -0,0 +1,39 @@ +(vyosonvmware)= + +# Running on VMware ESXi + +## ESXi 5.5 or later + +.ova files are available for supporting users, and a VyOS can also be stood up +using a generic Linux instance, and attaching the bootable ISO file and +installing from the ISO using the normal process around `install image`. + +:::{NOTE} +There have been previous documented issues with GRE/IPSEC tunneling +using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been +advised. +::: + +### Memory Contention Considerations + +When the underlying ESXi host is approaching ~92% memory utilisation it will +start the balloon process in a 'soft' state to start reclaiming memory from +guest operating systems. This causes an artificial pressure using the vmmemctl +driver on memory usage on the virtual guest. As VyOS by default does not have +a swap file, this vmmemctl pressure is unable to force processes to move in +memory data to the paging file, and blindly consumes memory forcing the +virtual guest into a low memory state with no way to escape. The balloon +can expand to 65% of guest allocated memory, so a VyOS guest running >35% of +memory usage, can encounter an out of memory situation, and trigger the kernel +oom_kill process. At this point a weighted lottery favouring memory hungry +processes will be run with the unlucky winner being terminated by the kernel. + +It is advised that VyOS routers are configured in a resource group with +adequate memory reservations so that ballooning is not inflicted on +virtual VyOS guests. + +### References + + + + -- cgit v1.2.3