From 4b36114e053ee11d0cb264a1e4cfe4692d78f194 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 14:40:28 +0300 Subject: Add incremental RST-to-MyST swap mechanism (#1857) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: add swap_sources.py for incremental RST-to-MyST migration Pre-build swap/restore script that renames md-{name}.md → {name}.md before Sphinx builds and restores after. Includes state tracking, exclude file generation, collision detection, and partial-failure rollback. 10 tests cover all specified behaviors plus rollback path. Co-Authored-By: Claude Sonnet 4.6 * feat: add import_myst.py for importing MyST files from myst/* branches Adds scripts/import_myst.py with import_page, git_show, list_myst_files, list_rst_files, and do_import. Imported files are written as md-{name}.md alongside existing RST files; importing is decoupled from swap activation. Adds tests/test_import_myst.py covering single-page write, identical-skip, warn-on-different-without-force, force-overwrite, and nested-path creation. All 5 tests pass on Python 3.9. Co-Authored-By: Claude Sonnet 4.6 * feat: add MyST swap exclude patterns and directive config to conf.py 🤖 Generated by [robots](https://vyos.io) * feat: add swap-wrapped rendering targets to Makefile 🤖 Generated by [robots](https://vyos.io) * feat: add swap pre/post build hooks for ReadTheDocs 🤖 Generated by [robots](https://vyos.io) * feat: add empty _swap.txt, remove atexit from swap script The atexit handler in --swap mode caused immediate restore on process exit, breaking standalone usage. Makefile trap and RTD post_build handle restore reliably. 🤖 Generated by [robots](https://vyos.io) * feat: activate quick-start as MyST canary via swap mechanism Imports docs/md-quick-start.md from origin/myst/current and adds quick-start to docs/_swap.txt. Validates the swap pipeline end-to-end on one page: import_myst pulls the MD via git show, swap_sources renames md-quick-start.md to quick-start.md, sphinx-build renders quick-start.html with zero MD-specific warnings, and restore reverses the rename cleanly. 🤖 Generated by [robots](https://vyos.io) * feat: activate 106 visual-validated canaries via swap Imports 105 MD files (plus quick-start already present) from origin/myst/current and adds them to docs/_swap.txt. The selection is the BackstopJS visual-passers cohort: pages with <5% rendered diff vs the live RST docs at docs.vyos.io/en/latest/, filtered to those with an RST counterpart on current and no cmdincludemd usage (template-format reconciliation pending). Local sphinx-build with all 106 swapped: succeeded with 100 warnings (vs 95 baseline). The 5 new warnings are all undefined cross-reference labels, not build failures: - contributing/development.md (missing 'coding-guidelines') - operation/upgrade-recovery.md (3 missing 'how_it_works' / 'cancelling_recovery') - vpp/configuration/dataplane/{buffers,memory,unix}.md (missing 'vpp_config_dataplane_*' labels) Source list: ~/.claude/projects/-Users-vybot-GitHub-vyos-documentation/docs/2026-04-29-myst-conversion-audit/visual-passers-under-5pct.txt BackstopJS report: claude/gifted-hertz-74b9f9 worktree (visual-compare/), 2026-04-23 vs vyos--1838.org.readthedocs.build. 🤖 Generated by [robots](https://vyos.io) * fix: re-import 4 canary md-*.md files with xref label fixes Re-imports the dash-form-corrected versions of: - contributing/md-development.md (added (coding-guidelines)= anchor) - operation/md-upgrade-recovery.md (3 ref renames: how_it_works / cancelling_recovery -> dash form) - vpp/configuration/dataplane/md-buffers.md (vpp_config_dataplane_physmem -> vpp-config-dataplane-physmem) - vpp/configuration/dataplane/md-unix.md (vpp_config_dataplane_interface_rx_mode -> vpp-config-dataplane-interface-rx-mode) Source: origin/myst/current commit 59fbe3ea. Verified locally: clean swap-build no longer reports any of the 5 target labels (1 of 6 — vpp-config-hugepages — remains because system.md isn't in the canary swap list; that anchor lives there). 🤖 Generated by [robots](https://vyos.io) * fix: re-add 4 canary md-*.md files deleted by 242b334a Commit 242b334a accidentally staged deletions instead of modifications because the working tree had unprefixed *.md files left over from an incomplete swap-restore cycle. Re-imports the same 4 files from origin/myst/current with the xref label fixes applied: - contributing/md-development.md — (coding-guidelines)= anchor - operation/md-upgrade-recovery.md — how_it_works → how-it-works, cancelling_recovery → cancelling-recovery - vpp/configuration/dataplane/md-buffers.md — vpp_config_dataplane_physmem → vpp-config-dataplane-physmem - vpp/configuration/dataplane/md-unix.md — vpp_config_dataplane_interface_rx_mode → vpp-config-dataplane-interface-rx-mode Source: origin/myst/current commit 59fbe3ea. 🤖 Generated by [robots](https://vyos.io) * fix: resolve remaining xref label gaps in swap-active build Three small additions clear the cross-reference warnings tied to underscore-vs-dash label form mismatches and the vpp-config-hugepages reference that previously needed system.md in the canary set. - system.rst: add .. _vpp-config-hugepages: alongside the existing underscore label so memory.md references resolve regardless of whether system.md is swap-active. - md-lcp.md: add (vpp_config_dataplane_lcp_ignore-kernel-routes)= alongside dash form (carries upstream from myst/current 079fa786). - md-memory.md: add (vpp_config_dataplane_memory)= alongside dash form (also from myst/current 079fa786). Local clean swap-build with 106 canaries: before: 305 warnings, 8 undefined-label entries in our scope after: 300 warnings, 0 undefined-label entries in our scope Remaining undefined-label warnings (release-notes, prepare_commit) are in documentation.rst and unrelated to the canary swap mechanism. 🤖 Generated by [robots](https://vyos.io) * fix: re-add md-lcp.md and md-memory.md (deleted by 870c9e7e) Same disaster pattern as 242b334a: a swap-restore cycle left unprefixed *.md files in the working tree, and the subsequent git add staged deletions instead of modifications. Restoring the two affected md-*.md files from origin/myst/current 079fa786 (which has the dual underscore+dash anchors needed for the swap-active build). 🤖 Generated by [robots](https://vyos.io) * feat: expand canaries to 114; refresh 3 with cfgcmd body fix Adds 8 new visual-validated canaries from the post-cfgcmd-fix BackstopJS run (2026-04-29): - configuration/policy/as-path-list - configuration/policy/community-list - configuration/policy/extcommunity-list - configuration/policy/large-community-list - configuration/policy/local-route - configuration/policy/prefix-list - configuration/service/salt-minion - configuration/system/updates Refreshes 3 existing canaries whose MD content changed via the cfgcmd/opcmd single-line body fix on myst/current fc19ab5c: - configuration/firewall/global-options - configuration/firewall/groups - configuration/policy/route All 11 sourced from origin/myst/current. Net: 106 -> 114 canaries. 🤖 Generated by [robots](https://vyos.io) * fix: re-import md-cloud-init.md (block 3 fix from myst/current) 🤖 Generated by [robots](https://vyos.io) * feat(swap): import .md files and webp transition from myst/current Selective import from origin/myst/current (cf9c9b34): - Add/update 255 .md files (full MyST conversion plus webp ref updates) - Delete 175 PNG/JPG from docs/_static/images (webp twins already present) - Delete 5 autotest topology.png (webp twins already present) Preserved on swap (untouched): - All .rst files (incremental swap pattern) - conf.py, _ext/, _include/*.txt, .gitignore - 115 canary md-*.md files - 7 superpowers/specs/*.md design docs - Logos vyos-logo.png / vyos-logo-icon.png (referenced by conf.py) 🤖 Generated by [robots](https://vyos.io) * chore(swap): remove canary md-*.md files and docs/superpowers - Remove 115 canary md-*.md files (incremental swap helpers no longer needed) - Remove 8 files under docs/superpowers (project planning/design docs that shouldn't ship in the documentation tree) 🤖 Generated by [robots](https://vyos.io) * docs: address Copilot review feedback on imported MyST pages Fix issues flagged by Copilot review on PR #1857 (the same content lives in myst/current as the canonical source): Real bugs: - site-2-site-cisco.md: replace curly quote (U+2019) with ASCII apostrophe - rsa-keys.md: fix typo "key-pair nam>>" → "key-pair name>" - vmware.md: lowercase admonition directive (:::{NOTE} → :::{note}) - vpp/configuration/nat/index.md: remove blank line inside {include} fence Grammar: - vpp/configuration/interfaces/loopback.md: "bounded" → "bound" - vpp/configuration/sflow.md: "VyOS support" → "VyOS supports" - vpp/requirements.md: "bypass" → "bypasses" - vpp/configuration/dataplane/interface.md: "configures" → "configure" CI linter (IP addresses): - nmp.md: wrap 8.8.8.8 example with stop/start_vyoslinter - lac-lns.md: wrap LNS config block (contains 8.8.8.8) - wan-load-balancing.md: wrap whole file (illustrative non-RFC IPs) - policy/examples.md: replace 192.0.1.1 with RFC 5737 192.0.2.1 🤖 Generated by [robots](https://vyos.io) * fix(swap): address Copilot review feedback on swap infrastructure Category D — drop obsolete canary mechanism settings: - conf.py: remove '**/md-*.md' from exclude_patterns (no canaries left) - Makefile: replace malformed '*/_build/*' with '$(BUILDDIR)/**' and drop the '*/md-*' ignore (canary files no longer exist) Category C — script robustness: - import_myst.py: * list_myst_files() now raises SystemExit on git ls-tree failure instead of silently returning [] (would have masked typo'd --source refs) * list_rst_files() skips _build/ when scanning for .rst stems * import_page() rejects stems containing '..' or absolute paths and re-checks that the resolved destination stays under docs_dir * --dry-run uses a separate "would_import" counter; summary line now distinguishes dry-run from actual imports - swap_sources.py: * parse_swap_list() reads with explicit encoding='utf-8' * do_restore() validates state file version + entry shape before renaming files; raises with actionable message on corruption * State file reads/writes use explicit encoding='utf-8' throughout _swap.txt: - Wrap long comment line to satisfy 80-character doc-linter limit 🤖 Generated by [robots](https://vyos.io) * refactor(swap): rename imported .md files to md- prefix for swap mechanism Restore the canary file naming convention that swap_sources.py expects: the imported MyST pages now live as docs//md-.md alongside the existing docs//.rst, so swap_sources.py --swap can rename them into place at build time. - 254 .md files renamed (every page with a matching .rst counterpart) - 2 MyST-only pages left at their final names (no .rst exists, no swap needed): docs/copyright.md, docs/automation/terraform/terraformvyos.md All 114 stems listed in docs/_swap.txt now have a corresponding md-.md source file ready to swap in. 🤖 Generated by [robots](https://vyos.io) * docs: address CodeRabbit review feedback on imported MyST pages Fix issues flagged by CodeRabbit on PR #1857. All issues are pre-existing in the upstream RST docs and inherited by the MyST conversion. Real bugs: - inter-vrf-routing-vrf-lite.md: invalid IPv6 next-hop "2001:db8::*" → "2001:db8::1" - ipsec-pa-route-based.md: vendor mislabel "Cisco" → "Palo Alto" (header on line 39 and "Monitoring on Cisco side" section heading) - bgp-ipv6-unnumbered.md: AS number mismatch between configuration and verification output for both routers (Router A: 65020 → 64496; Router B: 65021 → 64499) - qos.md: class 30 used "match ADDRESS20" instead of ADDRESS30 — broke the documented pattern (classes 10/20/30 → ADDRESS10/20/30) Security: - OpenVPN_with_LDAP.md: redact full PEM private key material from the three "set pki ... private key '...'" lines and from the embedded OpenVPN client block; replace with / ...REDACTED... placeholders. Public certificates retained. 🤖 Generated by [robots](https://vyos.io) * feat(swap): default to serving MyST for all swapped pages Replace the previously-curated 114-stem _swap.txt with the full set of 254 imported md-prefixed pages, so MD is served by default at build time. To revert any specific page back to RST, remove its stem from _swap.txt (or comment it out). 🤖 Generated by [robots](https://vyos.io) * fix(ext): handle RST fallback in CmdInclude when _renderer absent `cmdincludemd` is in `myst_fence_as_directive`, so MyST routes fence blocks through `render_fence → render_restructuredtext → MockRSTParser`. In that path `self.state` is a plain docutils Body with no `_renderer`, crashing the build. Fall back to `nested_parse` when `_renderer` is unavailable so the directive works in both MyST and RST/MockRSTParser contexts. 🤖 Generated by [robots](https://vyos.io) * feat(conf): copy .md sources into HTML output for plain-text serving Adds a build-finished hook that mirrors every .md file from the Sphinx source tree into the HTML output directory verbatim, making unrendered MyST sources accessible alongside HTML renders at the same URL path. 🤖 Generated by [robots](https://vyos.io) * docs: address review feedback from PR #1857 Fix conversion artifacts, typos, grammar errors, and technical inaccuracies flagged by automated code review (Copilot + CodeRabbit). Infrastructure: add root-level md-*.md exclusion to conf.py, fix sphinx-autobuild ignore globs in Makefile. Content: fix curly quotes, invalid Go panic() calls, shell quoting in cURL examples, incorrect firewall command paths, typos across 22 documentation files, remove duplicate sections. 🤖 Generated by [robots](https://vyos.io) --------- Co-authored-by: Claude Sonnet 4.6 --- docs/installation/virtual/md-docker.md | 72 ++++++++++++ docs/installation/virtual/md-eve-ng.md | 14 +++ docs/installation/virtual/md-gns3.md | 191 ++++++++++++++++++++++++++++++++ docs/installation/virtual/md-index.md | 16 +++ docs/installation/virtual/md-libvirt.md | 186 +++++++++++++++++++++++++++++++ docs/installation/virtual/md-proxmox.md | 80 +++++++++++++ docs/installation/virtual/md-vmware.md | 38 +++++++ 7 files changed, 597 insertions(+) create mode 100644 docs/installation/virtual/md-docker.md create mode 100644 docs/installation/virtual/md-eve-ng.md create mode 100644 docs/installation/virtual/md-gns3.md create mode 100644 docs/installation/virtual/md-index.md create mode 100644 docs/installation/virtual/md-libvirt.md create mode 100644 docs/installation/virtual/md-proxmox.md create mode 100644 docs/installation/virtual/md-vmware.md (limited to 'docs/installation/virtual') diff --git a/docs/installation/virtual/md-docker.md b/docs/installation/virtual/md-docker.md new file mode 100644 index 00000000..3489b94a --- /dev/null +++ b/docs/installation/virtual/md-docker.md @@ -0,0 +1,72 @@ +--- +lastproofread: '2026-02-02' +--- + +(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 +lightweight mechanism for both testing and packet routing for container +workloads. + +## IPv6 support for Docker + +VyOS requires an IPv6-enabled Docker network. Currently Linux distributions +do not enable Docker IPv6 support by default. You can enable IPv6 support in +two ways. + +### Method 1: Create a docker network with IPv6 support + +Here's an example using the `macvlan` driver. + +```none +docker network create --ipv6 -d macvlan -o parent=eth0 --subnet 2001:db8::/64 --subnet 192.0.2.0/24 mynet +``` + + +### Method 2: Add IPv6 support to the Docker daemon + +Edit /etc/docker/daemon.json to set the `ipv6` key to `true` and specify +the `fixed-cidr-v6` to your desired IPv6 subnet. + +```none +{ + "ipv6": true, + "fixed-cidr-v6": "2001:db8::/64" +} +``` + +Reload the Docker configuration. + +```none +$ sudo systemctl reload docker +``` + + +## Deploy container from ISO + +Download the ISO you want to base the container on. In this example, +the ISO is `vyos-1.4-rolling-202308240020-amd64.iso`. If you +created a custom IPv6-enabled network, include it as the `--net` parameter +to `docker run`. + +```none +$ mkdir vyos && cd vyos +$ curl -o vyos-1.4-rolling-202308240020-amd64.iso https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.4-rolling-202308240020/vyos-1.4-rolling-202308240020-amd64.iso +$ mkdir 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 +$ sudo tar -C unsquashfs -c . | docker import - vyos:1.4-rolling-202111281249 +$ sudo umount rootfs +$ cd .. +$ sudo rm -rf vyos +$ docker run -d --rm --name vyos --privileged -v /lib/modules:/lib/modules \ +> vyos:1.4-rolling-202111281249 /sbin/init +$ docker exec -ti vyos su - vyos +``` + +To stop the container, run `docker stop vyos`. diff --git a/docs/installation/virtual/md-eve-ng.md b/docs/installation/virtual/md-eve-ng.md new file mode 100644 index 00000000..1ee1c016 --- /dev/null +++ b/docs/installation/virtual/md-eve-ng.md @@ -0,0 +1,14 @@ +--- +lastproofread: '2026-02-02' +--- + +# EVE-NG + +:::{note} +This page is a stub and needs expansion. Contributions +welcome via the [VyOS documentation repository](https://github.com/vyos/vyos-documentation). +::: + +## References + + diff --git a/docs/installation/virtual/md-gns3.md b/docs/installation/virtual/md-gns3.md new file mode 100644 index 00000000..e4cb49c0 --- /dev/null +++ b/docs/installation/virtual/md-gns3.md @@ -0,0 +1,191 @@ +--- +lastproofread: '2026-02-02' +--- + +(vyos-on-gns3)= + +# Run VyOS on GNS3 + +You may want to test VyOS in a lab environment. +[GNS3](http://www.gns3.com) is a network emulation software that you +can use for this purpose. + +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 select +**Manually create a new Template**. + +:::{figure} /_static/images/gns3-01.webp +::: + +Select **Qemu VMs** and then click the `New` button. + +:::{figure} /_static/images/gns3-02.webp +::: + +Write a name for your VM, such as "VyOS", and click `Next`. + +:::{figure} /_static/images/gns3-03.webp +::: + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click `Next`. + +:::{figure} /_static/images/gns3-04.webp +::: + +Select **telnet** as your console type and click `Next`. + +:::{figure} /_static/images/gns3-05.webp +::: + +Select **New image** for the base disk image of your VM and click +`Create`. + +:::{figure} /_static/images/gns3-06.webp +::: + +Use the defaults in the **Binary and format** window and click +`Next`. + +:::{figure} /_static/images/gns3-07.webp +::: + +Use the defaults in the **Qcow2 options** window and click `Next`. + +:::{figure} /_static/images/gns3-08.webp +::: + +Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu +image creator**. + +:::{figure} /_static/images/gns3-09.webp +::: + +Click `Finish` to end the **New QEMU VM template** wizard. + +:::{figure} /_static/images/gns3-10.webp +::: + +Now you need to edit the VM settings. + +In the **Preferences** window, with **Qemu VMs** selected and your new VM +selected, click the `Edit` button. + +:::{figure} /_static/images/gns3-11.webp +::: + +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.webp +::: + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +:::{figure} /_static/images/gns3-13.webp +::: + +At the **CD/DVD** tab click on `Browse...` and locate the VyOS image +you want to install. + +:::{figure} /_static/images/gns3-14.webp +::: + +:::{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 the number of adapters to **0**, set the +**Name format** to **eth\{0}**, and set the **Type** to **Paravirtualized +Network I/O (virtio-net-pci)**. + +:::{figure} /_static/images/gns3-15.webp +::: + +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.webp +::: + +At the general **Preferences** window, click `OK` to save and close. + +:::{figure} /_static/images/gns3-17.webp +::: + +(vyos-installation)= + +## VyOS installation + +- Create a new project. +- Drag the newly created VyOS VM into it. +- Start the VM. +- Open a console. + The console displays the system booting. It prompts for login + credentials. You're now at the VyOS live system. +- {ref}`Install VyOS ` + as normal (that is, using the `install image` command). +- After successful installation, shut down 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.webp +::: + +**CD/DVD** tab: Clear the **Image** entry field to unmount the installation +image. + +:::{figure} /_static/images/gns3-21.webp +::: + +Set the number of required network adapters. For example, set it to **4**. + +:::{figure} /_static/images/gns3-215.webp +::: + +**Advanced** settings tab: Check the **Use as a linked +base VM** checkbox and click `OK` to save the changes. + +:::{figure} /_static/images/gns3-22.webp +::: + +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..97579129 --- /dev/null +++ b/docs/installation/virtual/md-index.md @@ -0,0 +1,16 @@ +--- +lastproofread: '2026-02-02' +--- + +# Virtual Environments + +```{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..0a21a97a --- /dev/null +++ b/docs/installation/virtual/md-libvirt.md @@ -0,0 +1,186 @@ +--- +lastproofread: '2026-02-02' +--- + +(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: +using Virt-Manager or the native CLI. This example uses 4 gigabytes +of memory, 2 CPU cores, and the 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-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 the VM with the 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 the console using the key combination +`Ctrl + ]` and reboot the system. + +### Deploy from qcow2 + +The benefit of using {abbr}`KVM (Kernel-based Virtual Machine)` +images is that they don't require installation. +Download the predefined VyOS `.qcow2` image. + +```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-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 the VM with the command `virsh console vyos_r2` + +```none +$ virsh console vyos_r2 + +Connected to domain vyos_r2 +Escape character is ^] + +vyos login: vyos +Password: + +vyos@vyos:~$ +``` + +If you cannot access the login screen, the KVM console may be set as the +default boot option. + +Open a secondary session and run this command to reboot the VM: + +```none +$ virsh reboot vyos_r2 +``` + +Then go to the first session where you opened the console. +Select `VyOS 1.4.x for QEMU (Serial console)` and press `Enter`. + +The system is fully operational. + +## Virt-Manager + +The Virt-Manager application is a desktop user interface for managing virtual +machines through libvirt. On Linux, open the +{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.webp +::: + +3. Choose the path to the VyOS ISO image. Select any Debian-based operating + system. + +:::{figure} /_static/images/virt-libvirt-02.webp +::: + +4. Choose Memory and CPU + +:::{figure} /_static/images/virt-libvirt-03.webp +::: + +5. Disk size + +:::{figure} /_static/images/virt-libvirt-04.webp +::: + +6. Name of VM and network selection + +:::{figure} /_static/images/virt-libvirt-05.webp +::: + +7. Then the system will be taken to the console. + +:::{figure} /_static/images/virt-libvirt-06.webp +::: + +(libvirt-virt-manager-qcow2)= + +### Deploy from qcow2 + +Download the predefined VyOS `.qcow2` image. + +```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.webp +::: + +3. Choose the path to the `vyos_kvm.qcow2` image that you downloaded. + Select any Debian-based operating system. + +:::{figure} /_static/images/virt-libvirt-qc-02.webp +::: + +4. Choose Memory and CPU + +:::{figure} /_static/images/virt-libvirt-03.webp +::: + +5. Name of VM and network selection + +:::{figure} /_static/images/virt-libvirt-05.webp +::: + +6. Then the system will be taken to the console. + +:::{figure} /_static/images/virt-libvirt-qc-03.webp +::: diff --git a/docs/installation/virtual/md-proxmox.md b/docs/installation/virtual/md-proxmox.md new file mode 100644 index 00000000..6b959341 --- /dev/null +++ b/docs/installation/virtual/md-proxmox.md @@ -0,0 +1,80 @@ +--- +lastproofread: '2026-02-02' +--- + +(proxmox)= + +# Running on Proxmox + +Proxmox is an open-source platform for virtualization. + +## Deploy VyOS from CLI with qcow2 image + +1. Download the `.qcow2` image from . + Official images are available to users with a valid subscription. + +2. Copy the `.qcow2` image to a temporary directory on the Proxmox server. + +3. The following commands assume that virtual machine (VM) ID `200` is unused + and that the imported disk will be stored in a storage pool named `local-lvm`. + + > ```none + > $ qm create 200 --name vyos --memory 4096 --net0 virtio,bridge=vmbr0 + > $ qm importdisk 200 /var/lib/vz/images/vyos--proxmox-amd64.qcow2 local-lvm + > $ qm set 200 --virtio0 local-lvm:vm-200-disk-0 + > $ qm set 200 --boot order=virtio0 + > ``` + +4. When using a `qcow2` image on Proxmox, the system + **does not include any preconfigured user accounts**. + You must define a user account using **Cloud-Init** before the + first boot. Otherwise, login access is not possible. + + Attach a Cloud-Init data source to the VM. For example, using + `local-lvm` storage: + + ```bash + $ qm set 200 --ide2 local-lvm:cloudinit + ``` + + Alternatively, add a Cloud-Init drive using the Proxmox GUI: + + 1. Open the VM and navigate to **Hardware** + 2. Click **Add** → **CloudInit Drive** + 3. Select a storage (for example, `local-lvm`) + 4. Click **Add** + +5. Start the virtual machine using the Proxmox GUI or by running `qm start 200`. + +## Deploy VyOS from CLI with rolling release ISO + +1. Download the rolling release ISO from + . +2. Prepare the VM for ISO installation. + The commands below assume that the ISO image is available in the + `local` storage, a VM ID `200` is unused, and a 15GB disk will be + created on storage pool `local-lvm`. + +```none +qm create 200 --name vyos --memory 4096 \ +--net0 virtio,bridge=vmbr0 \ +--scsihw virtio-scsi-pci \ +--scsi0 local-lvm:15 \ +--ide2 local:iso/vyos-.iso,media=cdrom \ +--boot order=ide2 +``` + +3. Start the VM using `qm start 200` or by clicking the **Start** + button in the Proxmox GUI. +4. In the Proxmox GUI, open the virtual console for your new VM. + The login username and password are `vyos`/`vyos`. +5. After booting into the live system, type `install image` and follow + the prompts to install VyOS to the virtual drive. +6. After installation completes, remove the installation ISO using the + GUI or run `qm set 200 --ide2 none`, then set the boot device + with `qm set 200 --boot order=scsi0`. +7. Reboot the virtual machine using the GUI or run `qm reboot 200`. + +For more information about downloading and installing Proxmox, visit +. + diff --git a/docs/installation/virtual/md-vmware.md b/docs/installation/virtual/md-vmware.md new file mode 100644 index 00000000..66278ae9 --- /dev/null +++ b/docs/installation/virtual/md-vmware.md @@ -0,0 +1,38 @@ +--- +lastproofread: '2026-02-02' +--- + +(vyosonvmware)= + +# Running on VMware ESXi + +## ESXi 5.5 or later + +`.ova` files are available for supporting users. You can also set up VyOS +using a generic Linux instance by attaching the bootable ISO file and +installing using the `install image` command. + +:::{note} +Previous issues have been documented with GRE/IPSEC tunneling +using the E1000 adapter on VyOS guests. Use the VMXNET3 adapter instead. +::: + +### Memory Contention Considerations + +When the underlying ESXi host reaches approximately 92% memory utilization, +it begins the balloon process to reclaim memory from guest operating systems. +This creates artificial memory pressure through the `vmmemctl` driver. Because +VyOS does not have a swap file by default, this pressure cannot move memory +data to a paging file. Instead, it consumes memory and forces the guest into +a low memory state with no recovery option. The balloon can expand to 65% of +guest allocated memory, so a VyOS guest using more than 35% of memory can +encounter an out-of-memory situation and trigger the kernel `oom_kill` +process. The `oom_kill` process then terminates memory-hungry processes. + +To prevent ballooning, configure VyOS routers in a resource group with +adequate memory reservations. + +### References + + + -- cgit v1.2.3