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/cloud/md-aws.md | 188 ++++++++++ docs/installation/cloud/md-azure.md | 98 +++++ docs/installation/cloud/md-gcp.md | 61 ++++ docs/installation/cloud/md-index.md | 10 + docs/installation/cloud/md-oracle.md | 17 + docs/installation/md-bare-metal.md | 626 ++++++++++++++++++++++++++++++++ docs/installation/md-image.md | 113 ++++++ docs/installation/md-index.md | 30 ++ docs/installation/md-install.md | 466 ++++++++++++++++++++++++ docs/installation/md-secure-boot.md | 194 ++++++++++ docs/installation/md-update.md | 105 ++++++ 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 ++ 18 files changed, 2505 insertions(+) create mode 100644 docs/installation/cloud/md-aws.md create mode 100644 docs/installation/cloud/md-azure.md create mode 100644 docs/installation/cloud/md-gcp.md create mode 100644 docs/installation/cloud/md-index.md create mode 100644 docs/installation/cloud/md-oracle.md create mode 100644 docs/installation/md-bare-metal.md create mode 100644 docs/installation/md-image.md create mode 100644 docs/installation/md-index.md create mode 100644 docs/installation/md-install.md create mode 100644 docs/installation/md-secure-boot.md create mode 100644 docs/installation/md-update.md 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') diff --git a/docs/installation/cloud/md-aws.md b/docs/installation/cloud/md-aws.md new file mode 100644 index 00000000..de5da3aa --- /dev/null +++ b/docs/installation/cloud/md-aws.md @@ -0,0 +1,188 @@ +--- +lastproofread: '2026-02-06' +--- + +# Amazon AWS + +## Deploy VM + +Deploy VyOS on Amazon {abbr}`AWS (Amazon Web Services)`. + +1. Click **Instances** and then click **Launch Instance**. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-01.webp +``` + +2. Search for "VyOS" in the Marketplace. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-02.webp +``` + +3. Choose the instance type. The recommended minimum is `m3.medium`. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-03.webp +``` + +4. Configure the instance for your requirements. Select the number of + instances, network, and subnet. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-04.webp +``` + +5. Configure additional storage. You can remove the additional storage + `/dev/sdb`. The root device will be `/dev/xvda`. You can skip this step. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-05.webp +``` + +6. Configure the security group. We recommend configuring SSH access + only from specific sources, or you can permit any IP address (the default). + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-06.webp +``` + +7. Select the SSH key pair and click **Launch Instances**. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-07.webp +``` + +8. Note your public IP address. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-08.webp +``` + +9. Connect to the instance using your SSH key. + +```{eval-rst} + + .. code-block:: none + + ssh -i ~/.ssh/amazon.pem vyos@203.0.113.3 + vyos@ip-192-0-2-10:~$ +``` + + +## Amazon CloudWatch Agent Usage + +To use the Amazon CloudWatch agent, configure it in the Amazon Systems Manager +Parameter Store. For instructions on creating a configuration, see +{ref}`configuration_creation`. + +1. Create an {abbr}`IAM (Identity and Access Management)` role for the + {abbr}`EC2 (Elastic Compute Cloud)` instance to access CloudWatch service, + and name it CloudWatchAgentServerRole. The role should contain two default + policies: `CloudWatchAgentServerPolicy` and + `AmazonSSMManagedInstanceCore`. +2. Attach the created role to your VyOS {abbr}`EC2 (Elastic Compute Cloud)` + instance. +3. Ensure the amazon-cloudwatch-agent package is installed. + +```{eval-rst} + + .. code-block:: none + + $ sudo apt list --installed | grep amazon-cloudwatch-agent + + .. note:: The amazon-cloudwatch-agent package is normally included in + VyOS 1.3.3+ and 1.4+ +``` + +4. Retrieve an existing CloudWatch Agent configuration from the + {abbr}`SSM (Systems Manager)` Parameter Store. + +```{eval-rst} + + .. code-block:: none + + $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c ssm: + + This step also enables systemd service and runs it. + + .. note:: The VyOS platform-specific scripts feature is under development. + Thus, this step should be repeated manually after changing system image + (:doc:`/installation/update`) +``` + +(configuration_creation)= + +### CloudWatch SSM Configuration creation + +Creating the Amazon Cloudwatch Agent Configuration in Amazon +{abbr}`SSM (Systems Manager)` Parameter Store. + +1. Create an {abbr}`IAM (Identity and Access Management)` role for your + {abbr}`EC2 (Elastic Compute Cloud)` instance to access the CloudWatch + service. Name it `CloudWatchAgentAdminRole`. The role must contain at + least two policies: `CloudWatchAgentAdminPolicy` and + `AmazonSSMManagedInstanceCore`. + +```{eval-rst} + + .. note:: CloudWatchAgentServerRole is too permissive and should be used only + for + creating and deploying a single configuration. After step 3, we recommend + replacing the ``CloudWatchAgentAdminRole`` with the + ``CloudWatchAgentServerRole``. +``` + +2. Run the CloudWatch configuration wizard. + +```{eval-rst} + + .. code-block:: none + + $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard +``` + +3. When prompted, enter "yes" to the question "Do you want to store the + config in the SSM parameter store?". + +## AWS Gateway Load Balancer + +VyOS supports the AWS Gateway Load Balancer (GWLB) tunnel handler (`gwlbtun`), +which enables VyOS to act as an inspection or processing target for GWLB. GWLB +uses Geneve encapsulation with custom metadata to deliver traffic to VyOS for +packet filtering, shaping, deep packet inspection, NAT, or other traffic +manipulation functions. The tunnel handler automatically creates Linux tunnel +interfaces (`gwi-*` for ingress and `gwo-*` for egress) per endpoint, +allowing you to use standard Linux utilities like iptables, tc, and netfilter +to implement your inspection or processing logic. This enables VyOS to serve as +a centralized appliance for traffic inspection in your AWS infrastructure, +supporting both single-endpoint (1-arm) and multi-endpoint (2-arm) deployment +modes. + +For more information about integrating with AWS Gateway Load Balancer, see +the following article from AWS: +[How to integrate Linux instances with AWS Gateway Load Balancer](https://aws.amazon.com/blogs/networking-and-content-delivery/how-to-integrate-linux-instances-with-aws-gateway-load-balancer/). + +### Configuration Example + +Configure the AWS GWLB service with the following commands: + +```none +set service aws glb script on-create '/config/scripts/glb-create.sh' +set service aws glb script on-destroy '/config/scripts/glb-destroy.sh' +set service aws glb status format 'simple' +set service aws glb status port '8282' +set service aws glb threads tunnel '4' +set service aws glb threads tunnel-affinity '1-2' +set service aws glb threads udp '4' +set service aws glb threads udp-affinity '0-3' +``` + + +## References + +- +- +- +- + diff --git a/docs/installation/cloud/md-azure.md b/docs/installation/cloud/md-azure.md new file mode 100644 index 00000000..24b7b166 --- /dev/null +++ b/docs/installation/cloud/md-azure.md @@ -0,0 +1,98 @@ +--- +lastproofread: '2026-02-09' +--- + +# Azure + +## Deploy VM + +Deploy VyOS on Azure. + +1. Go to Azure services and click **Add new Virtual machine**. +2. Choose a VM name, resource group, and region, then click **Browse all public + and private images**. + +```{eval-rst} +.. figure:: /_static/images/cloud-azure-01.webp +``` + +3. Search for "VyOS" in the marketplace and choose the appropriate + subscription. + +```{eval-rst} +.. figure:: /_static/images/cloud-azure-02.webp +``` + +4. Generate new SSH key pair or use existing. + +```{eval-rst} +.. figure:: /_static/images/cloud-azure-03.webp +``` + +5. Configure the network, subnet, and public IP. Or use the defaults. + +```{eval-rst} +.. figure:: /_static/images/cloud-azure-04.webp +``` + +6. Click **Review + create**. Your deployment completes in a few seconds. + +```{eval-rst} +.. figure:: /_static/images/cloud-azure-05.webp +``` + +7. Select your new VM and note your public IP address. + +```{eval-rst} +.. figure:: /_static/images/cloud-azure-06.webp +``` + +8. Connect to the instance with your SSH key. + +```{eval-rst} + + .. code-block:: none + + ssh -i ~/.ssh/vyos_azure vyos@203.0.113.3 + vyos@vyos-doc-r1:~$ +``` + + +## Add interface + +If your instance was deployed with one **eth0** (`WAN`) interface and you +want to add another, you must shut down the instance. To add a new interface, +such as **eth1** (`LAN`), attach it in the Azure portal and then restart the +instance. + +:::{note} +Azure doesn't allow you to attach an interface while the instance is +running. +::: + +## Absorbing Routes + +If you're using the VM as a router, you can use a route table to absorb some or +all traffic from your virtual network (VNET) with your LAN interface. + +1. Create a route table and navigate to **Configuration**. +2. Add one or more routes for the networks you want to route through the VyOS + VM. For **Next hop type**, select **Virtual Appliance** and set the **Next + Hop Address** to the VyOS `LAN` interface. + +:::{note} +To create a default route for VMs on the subnet, use +**Address Prefix** `0.0.0.0/0`. For a typical edge device configuration, +configure masquerade NAT on the `WAN` interface. +::: + +## Serial Console + +VyOS includes serial console support by default. However, if you replace the +`config.boot` file and reboot, ensure this configuration is present: + +`set system console device ttyS0 speed '9600'` + +## References + + diff --git a/docs/installation/cloud/md-gcp.md b/docs/installation/cloud/md-gcp.md new file mode 100644 index 00000000..828312cd --- /dev/null +++ b/docs/installation/cloud/md-gcp.md @@ -0,0 +1,61 @@ +--- +lastproofread: '2026-02-09' +--- + +# Google Cloud Platform + +## Deploy VM + +To deploy VyOS on Google Cloud Platform (GCP): + +1. Generate an SSH key pair of type **ssh-rsa** on the host that will connect + to VyOS. + + Example: + + ```none + ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" + ``` + +:::{note} +The SSH key comment must begin with `vyos@` because that's the +default VyOS user. GCP uses this value to set the username on the instance. +::: + +2. Open the GCP Console and navigate to **Metadata**. Select **SSH Keys** and + click **Edit**. + +:::{figure} /_static/images/cloud-gcp-01.webp +Click **Add item**, paste your public SSH key, and click **Save**. +::: + +:::{figure} /_static/images/cloud-gcp-02.webp +::: + +3. Search for "VyOS" in the Marketplace. +4. Configure the deployment name, zone, and machine type, then click **Deploy**. + +:::{figure} /_static/images/cloud-gcp-03.webp +::: + +5. After a few seconds, select your **instance**. + +:::{figure} /_static/images/cloud-gcp-04.webp +::: + +6. Note your external IP address. + +:::{figure} /_static/images/cloud-gcp-05.webp +::: + +7. Connect to the instance using the SSH key you generated in step 1. + +```none +ssh -i ~/.ssh/vyos_gcp vyos@203.0.113.3 +vyos@vyos-r1-vm:~$ +``` + + +## References + + diff --git a/docs/installation/cloud/md-index.md b/docs/installation/cloud/md-index.md new file mode 100644 index 00000000..cf7d447d --- /dev/null +++ b/docs/installation/cloud/md-index.md @@ -0,0 +1,10 @@ +# Cloud Environments + +```{toctree} +:caption: Content + +aws +azure +gcp +oracle +``` diff --git a/docs/installation/cloud/md-oracle.md b/docs/installation/cloud/md-oracle.md new file mode 100644 index 00000000..f8cee52c --- /dev/null +++ b/docs/installation/cloud/md-oracle.md @@ -0,0 +1,17 @@ +--- +lastproofread: '2026-02-09' +--- + +# Oracle + +:::{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/md-bare-metal.md b/docs/installation/md-bare-metal.md new file mode 100644 index 00000000..ed813545 --- /dev/null +++ b/docs/installation/md-bare-metal.md @@ -0,0 +1,626 @@ +(vyosonbaremetal)= + +# Bare Metal Deployment + +## Supermicro A2SDi (Atom C3000) + +I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. +Running VyOS on an UEFI only device is supported as of VyOS release 1.2. + +### Supermicro Shopping Cart + +- 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) +- 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) +- 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN + with Intel C3000 SoC 1GbE) +- 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) +- 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) +- 1x Supermicro MCP-320-81302-0B (optional FAN tray) + +### Optional (10GE) + +If you want to get additional ethernet ports or even 10GE connectivity +the following optional parts will be required: + +- 1x Supermicro RSC-RR1U-E8 (Riser Card) +- 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) + +Latest VyOS rolling releases boot without any problem on this board. You also +receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no +information about [OpenBMC](https://www.openbmc.org/) so far on this +motherboard). + +### Pictures + +:::{figure} /_static/images/1u_vyos_back.webp +:alt: CSE-505-203B Back +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front.webp +:alt: CSE-505-203B Front +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_open_1.webp +:alt: CSE-505-203B Open 1 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_open_2.webp +:alt: CSE-505-203B Open 2 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_open_3.webp +:alt: CSE-505-203B Open 3 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_10ge_open_1.webp +:alt: CSE-505-203B w/ 10GE Open 1 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_10ge_open_2.webp +:alt: CSE-505-203B w/ 10GE Open 2 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_10ge_open_3.webp +:alt: CSE-505-203B w/ 10GE Open 3 +:scale: 25 % +::: + +:::{figure} /_static/images/1u_vyos_front_10ge_open_4.webp +:alt: CSE-505-203B w/ 10GE Open +:scale: 25 % +::: + +(pc-engines-apu4)= + +## PC Engines APU4 + +As this platform seems to be quite common in terms of noise, cost, power and +performance it makes sense to write a small installation manual. + +This guide was developed using an APU4C4 board with the following specs: + +- AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI + support, 32K data + 32K instruction cache per core, shared 2MB L2 cache. +- 4 GB DDR3-1333 DRAM, with optional ECC support +- About 6 to 10W of 12V DC power depending on CPU load +- 2 miniPCI express (one with SIM socket for 3G modem). +- 4 Gigabit Ethernet channels using Intel i211AT NICs + +The board can be powered via 12V from the front or via a 5V onboard connector. + +(vyos-on-baremetal-apu4-shopping)= + +### APU4 Shopping Cart + +- 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM +- 1x Kingston SUV500MS/120G +- 1x VARIA Group Item 326745 19" dual rack for APU4 + +The 19" enclosure can accommodate up to two APU4 boards - there is a single and +dual front cover. + +#### Extension Modules + +##### WiFi + +Refer to {ref}`wireless-interface` for additional information, below listed +modules have been tested successfully on this Hardware platform: + +- Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1. +- Intel Corporation AX200 mini-PCIe WiFi module, only supported in mPCIe slot 1. + (see {ref}`wireless-interface-intel-ax200`) + +##### WWAN + +Refer to {ref}`wwan-interface` for additional information, below listed modules +have been tested successfully on this Hardware platform using VyOS 1.3 +(equuleus): + +- Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +- Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +- Huawei ME909u-521 miniPCIe card (LTE) + +### VyOS 1.4 (sagitta) + +Depending on the VyOS versions you intend to install there is a difference in +the serial port settings ({vytask}`T1327`). + +Create a bootable USB pendrive using e.g. [Rufus] on a Windows machine. + +Connect serial port to a PC through null modem cable (RXD / TXD crossed over). +Set terminal emulator to 115200 8N1. + +```none +PC Engines apu4 +coreboot build 20171130 +BIOS version v4.6.4 +4080 MB ECC DRAM +SeaBIOS (version rel-1.11.0.1-0-g90da88d) + +Press F10 key now for boot menu: + +Select boot device: + +1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes) +2. USB MSC Drive Generic Flash Disk 8.07 +3. Payload [memtest] +4. Payload [setup] +``` + +Now boot from the `USB MSC Drive Generic Flash Disk 8.07` media by pressing +`2`, the VyOS boot menu will appear, just wait 10 seconds or press `Enter` +to continue. + +```none +lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk +x VyOS - Boot Menu x +tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu +x Live system (amd64-vyos) x +x Live system (amd64-vyos fail-safe mode) x +x Live system (amd64-vyos) - Serial console x +x x +mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj +``` + +The image will be loaded and the last lines you will get will be: + +```none +Loading /live/vmlinuz... ok +Loading /live/initrd.img... +... +Welcome to VyOS - vyos ttyS0 + +vyos login: +``` + +You can now proceed with a regular image installation as described in +{ref}`installation`. + +(vyos-on-baremetal-apu4-pictures)= + +### Pictures + +:::{note} +Both device types operate without any moving parts and emit zero +noise. +::: + +#### Rack Mount + +:::{figure} /_static/images/apu4_rack_1.webp +:alt: APU4 rack closed +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_rack_2.webp +:alt: APU4 rack front +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_rack_3.webp +:alt: 'APU4 rack module #1' +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_rack_4.webp +:alt: 'APU4 rack module #2' +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_rack_5.webp +:alt: 'APU4 rack module #3 with PSU' +:scale: 25 % +::: + +##### VyOS custom print + +:::{figure} /_static/images/apu4_rack_vyos_print.webp +:alt: APU4 custom VyOS powder coat +:scale: 25 % +::: + +#### Desktop / Bench Top + +:::{figure} /_static/images/apu4_desk_1.webp +:alt: APU4 desktop closed +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_desk_2.webp +:alt: APU4 desktop closed +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_desk_3.webp +:alt: APU4 desktop back +:scale: 25 % +::: + +:::{figure} /_static/images/apu4_desk_4.webp +:alt: APU4 desktop back +:scale: 25 % +::: + +## Qotom Q355G4 + +The install on this Q355G4 box is pretty much plug and play. The port numbering +the OS does might differ from the labels on the outside, but the UEFI firmware +has a port blink test built in with MAC addresses so you can very quickly +identify which is which. MAC labels are on the inside as well, and this test +can be done from VyOS or plain Linux too. Default settings in the UEFI will +make it boot, but depending on your installation wishes (i.e. storage type, +boot type, console type) you might want to adjust them. This Qotom company +seems to be the real OEM/ODM for many other relabelling companies like +Protectli. + +### Hardware + +There are a number of other options, but they all seem to be close to Intel +reference designs, with added features like more serial ports, more network +interfaces and the likes. Because they don't deviate too much from standard +designs all the hardware is well-supported by mainline. It accepts one LPDDR3 +SO-DIMM, but chances are that if you need more than that, you'll also want +something even beefier than an i5. There are options for antenna holes, and SIM +slots, so you could in theory add an LTE/Cell modem (not tested so far). + +The chassis is a U-shaped alu extrusion with removable I/O plates and removable +bottom plate. Cooling is completely passive with a heatsink on the SoC with +internal and external fins, a flat interface surface, thermal pad on top of +that, which then directly attaches to the chassis, which has fins as well. It +comes with mounting hardware and rubber feet, so you could place it like a +desktop model or mount it on a VESA mount, or even wall mount it with the +provided mounting plate. The closing plate doubles as internal 2.5" mounting +place for an HDD or SSD, and comes supplied with a small SATA cable and SATA +power cable. + +Power supply is a 12VDC barrel jack, and included switching power supply, which +is why SATA power regulation is on-board. Internally it has a NUC-board-style +on-board 12V input header as well, the molex locking style. + +There are WDT options and auto-boot on power enable, which is great for remote +setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled +in enforcement mode, which is good but also means no coreboot option), yet has +most options available to configure (so it's not locked out like most firmwares +are). + +An external RS232 serial port is available, internally a GPIO header as well. +It does have Realtek based audio on board for some reason, but you can disable +that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS +mode and HDMI BIOS mode depends on what is connected at startup; it goes into +serial mode if you disconnect HDMI and plug in serial, in all other cases it's +HDMI mode. + +## Partaker i5 + +:::{figure} ../_static/images/600px-Partaker-i5.webp +::: + +I believe this is actually the same hardware as the Protectli. I purchased it +in June 2018. It came pre-loaded with pfSense. + +[Manufacturer product page](http://www.inctel.com.cn/product/detail/338.html). + +### Installation + +- Write VyOS ISO to USB drive of some sort +- Plug in VGA, power, USB keyboard, and USB drive +- Press "SW" button on the front (this is the power button; I don't know what + "SW" is supposed to mean). +- Begin rapidly pressing delete on the keyboard. The boot prompt is very quick, + but with a few tries you should be able to get into the BIOS. +- Chipset > South Bridge > USB Configuration: set XHCI to Disabled and USB 2.0 + (EHCI) to Enabled. Without doing this, the USB drive won't boot. +- Boot to the VyOS installer and install as usual. + +Warning the interface labels on my device are backwards; the left-most "LAN4" +port is eth0 and the right-most "LAN1" port is eth3. + +## Acrosser AND-J190N1 + +:::{figure} ../_static/images/480px-Acrosser_ANDJ190N1_Front.webp +::: + +:::{figure} ../_static/images/480px-Acrosser_ANDJ190N1_Back.webp +::: + +This microbox network appliance was build to create OpenVPN bridges. It can +saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN + +You may have to add your own RAM and HDD/SSD. There is no VGA connector. But +Acrosser provides a DB25 adapter for the VGA header on the motherboard (not +used). + +### BIOS Settings: + +First thing you want to do is getting a more user friendly console to configure +BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead. + +For practical issues change speed from 115200 to 9600. 9600 is the default +speed at which both linux kernel and VyOS will reconfigure the serial port +when loading. + +Connect to serial (115200bps). Power on the appliance and press Del in the +console when requested to enter BIOS settings. + +Advanced > Serial Port Console Redirection > Console Redirection Settings: + +- Terminal Type : VT100+ +- Bits per second : 9600 + +Save, reboot and change serial speed to 9600 on your client. + +Some options have to be changed for VyOS to boot correctly. With XHCI enabled +the installer can’t access the USB key. Enable EHCI instead. + +Reboot into BIOS, Chipset > South Bridge > USB Configuration: + +- Disable XHCI +- Enable USB 2.0 (EHCI) Support + +Perform Image installation using `install image` CLI command. + +(gowin-gw-fn-1ur1-10g)= + +## Gowin GW-FN-1UR1-10G + +A platform utilizing an Intel Alder Lake-N100 CPU with 6M cache, TDP 6W. +Onboard LPDDR5 16GB RAM and 128GB eMMC (can be used for image installation). + +The appliance comes with 2 * 2.5GbE Intel I226-V and 3 * 1GbE Intel I210 +where one supports IEEE802.3at PoE+ (Typical 30W). + +In addition there is a Mellanox ConnectX-3 2\* 10GbE SFP+ NIC available. + +**NOTE:** This is the entry level platform. Other derivates exists with +i3-N305 CPU and 2x 25GbE! + +### Gowin Shopping Cart + +- 1x Gowin GW-FN-1UR1-10G +- 2x 128GB M.2 NVMe SSDs + +### Optional (WiFi + WWAN) + +- 1x MediaTek 7921E M.2 NGFF WIFI module (not tested as this currently leads to + a Kernel crash) +- 1x HP LT4120 Snapdragon X5 LTE WWAN module + +### Pictures + +:::{figure} ../_static/images/gowin-01.webp +::: + +:::{figure} ../_static/images/gowin-02.webp +::: + +:::{figure} ../_static/images/gowin-03.webp +::: + +:::{figure} ../_static/images/gowin-04.webp +::: + +### Cooling + +The device itself is passivly cooled, whereas the power supply has an active fan. +Even if the main processor is powered off, the power supply fan is operating and +the entire chassis draws 7.5W. During operation the chassis drew arround 38W. + +### BIOS Settings + +No settings needed to be altered, everything worked out of the box! + +### Installation + +The system provides a regular RS232 console port using 115200,8n1 setting which +is sufficient to install VyOS from a USB pendrive. + +### First Boot + +Please note that there is a weirdness on the network interface mapping. +The interface \<-> MAC mapping is going upwards but the NICs are placed +somehow swapped on the mainboard/MACs programmed in a swapped order. + +See interface description for more detailed mapping. + +```none +vyos@vyos:~$ show interfaces +Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down +Interface IP Address MAC VRF MTU S/L Description +----------- -------------- ----------------- ------- ----- ----- ------------- +eth0 - 00:f0:cb:00:00:99 default 1500 u/D Intel I226-V - Front eth2 +eth1 - 00:f0:cb:00:00:9a default 1500 u/D Intel I226-V - Front eth1 +eth2 - 00:f0:cb:00:00:9b default 1500 u/D Intel I210 - Front eth4 +eth3 - 00:f0:cb:00:00:9c default 1500 u/D Intel I210 - Front eth3 +eth4 - 00:f0:cb:00:00:9d default 1500 u/D Intel I210 - Front POE +eth5 - 00:02:c9:00:00:30 default 1500 u/D Mellanox ConnectX-3 - SFP2 +eth6 - 00:02:c9:00:00:31 default 1500 u/D Mellanox ConnectX-3 - SFP1 +lo 127.0.0.1/8 00:00:00:00:00:00 default 65536 u/u + ::1/128 +wwan0 - d2:39:76:8e:05:12 default 1500 A/D +``` + + +#### VyOS 1.4 (sagitta) + +Connect serial port to a PC through a USB \<-> RJ45 console cable. Set terminal +emulator to 115200 8N1. You can also perform the installation using VGA or HDMI +ports. + +In this example I choose to install VyOS as RAID-1 on both NVMe drives. However, +a previous installation on the 128GB eMMC storage worked without any issues, +too. + +```none +Welcome to VyOS - vyos ttyS0 +vyos login: +``` + +Perform Image installation using `install image` CLI command. This installation +uses two 128GB NVMe disks setup as RAID1. + +```none +Welcome to VyOS! + + β”Œβ”€β”€ ┐ + . VyOS 1.4.0 + β”” β”€β”€β”˜ sagitta + +* Support portal: https://support.vyos.io +* Documentation: https://docs.vyos.io/en/sagitta +* Project news: https://blog.vyos.io +* Bug reports: https://vyos.dev + +You can change this banner using "set system login banner post-login" command. + +VyOS is a free software distribution that includes multiple components, +you can check individual component licenses under /usr/share/doc/*/copyright +Use of this pre-built image is governed by the EULA you can find in +/usr/share/vyos/EULA + +vyos@vyos:~$ install image + +Welcome to VyOS installation! +This command will install VyOS to your permanent storage. +Would you like to continue? [y/N] y + +What would you like to name this image? (Default: 1.4.0) + +Please enter a password for the "vyos" user: +Please confirm password for the "vyos" user: + +What console should be used by default? (K: KVM, S: Serial)? (Default: S) + +Probing disks +4 disk(s) found +Would you like to configure RAID-1 mirroring? [Y/n] y + +The following disks were found: + /dev/sda (14.4 GB) + /dev/mmcblk0 (116.5 GB) +Would you like to configure RAID-1 mirroring on them? [Y/n] n + +Would you like to choose two disks for RAID-1 mirroring? [Y/n] y +Disks available: + 1: /dev/sda (14.4 GB) + 2: /dev/mmcblk0 (116.5 GB) + 3: /dev/nvme1n1 (119.2 GB) + 4: /dev/nvme0n1 (119.2 GB) +Select first disk: 3 + +Remaining disks: + 1: /dev/sda (14.4 GB) + 2: /dev/mmcblk0 (116.5 GB) + 3: /dev/nvme0n1 (119.2 GB) +Select second disk: 3 + +Installation will delete all data on both drives. Continue? [y/N] y + +Searching for data from previous installations +No previous installation found +Creating partitions on /dev/nvme1n1 +Creating partition table... +Creating partitions on /dev/nvme0n1 +Creating partition table... +Creating RAID array +Updating initramfs +Creating filesystem on RAID array +The following config files are available for boot: + 1: /opt/vyatta/etc/config/config.boot + 2: /opt/vyatta/etc/config.boot.default + +Which file would you like as boot config? (Default: 1) +Creating temporary directories +Mounting new partitions +Creating a configuration file +Copying system image files +Installing GRUB configuration files +Installing GRUB to the drives +Cleaning up +Unmounting target filesystems +Removing temporary files +The image installed successfully; please reboot now. +``` + + +### Hardware + +```none +vyos@vyos:~$ lspci +00:00.0 Host bridge: Intel Corporation Device 461c +00:02.0 VGA compatible controller: Intel Corporation Alder Lake-N [UHD Graphics] +00:0a.0 Signal processing controller: Intel Corporation Platform Monitoring Technology (rev 01) +00:0d.0 USB controller: Intel Corporation Device 464e +00:14.0 USB controller: Intel Corporation Device 54ed +00:14.2 RAM memory: Intel Corporation Device 54ef +00:15.0 Serial bus controller: Intel Corporation Device 54e8 +00:16.0 Communication controller: Intel Corporation Device 54e0 +00:1a.0 SD Host controller: Intel Corporation Device 54c4 +00:1c.0 PCI bridge: Intel Corporation Device 54b8 +00:1c.2 PCI bridge: Intel Corporation Device 54ba +00:1c.3 PCI bridge: Intel Corporation Device 54bb +00:1c.6 PCI bridge: Intel Corporation Device 54be +00:1d.0 PCI bridge: Intel Corporation Device 54b0 +00:1f.0 ISA bridge: Intel Corporation Device 5481 +00:1f.4 SMBus: Intel Corporation Device 54a3 +00:1f.5 Serial bus controller: Intel Corporation Device 54a4 +01:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +02:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +03:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) +04:00.0 Ethernet controller: Intel Corporation Ethernet Controller I226-V (rev 04) +05:00.0 Network controller: MEDIATEK Corp. MT7922 802.11ax PCI Express Wireless Network Adapter +06:00.0 SATA controller: ASMedia Technology Inc. Device 0622 (rev 01) +07:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:00.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:02.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:06.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +08:0e.0 PCI bridge: ASMedia Technology Inc. Device 1806 (rev 01) +09:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) +0a:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) +0b:00.0 Ethernet controller: Intel Corporation I210 Gigabit Network Connection (rev 03) +0d:00.0 Non-Volatile memory controller: Device 1ed0:2283 +0f:00.0 Non-Volatile memory controller: Device 1ed0:2283 +11:00.0 Ethernet controller: Mellanox Technologies MT27500 Family [ConnectX-3] +``` + +```none +vyos@vyos:~$ lsusb +Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub +Bus 003 Device 005: ID 0e8d:c616 MediaTek Inc. Wireless_Device +Bus 003 Device 003: ID 413c:2113 Dell Computer Corp. KB216 Wired Keyboard +Bus 003 Device 004: ID 03f0:9d1d HP, Inc HP lt4120 Snapdragon X5 LTE +Bus 003 Device 002: ID 05e3:0610 Genesys Logic, Inc. Hub +Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub +Bus 002 Device 002: ID 05e3:0620 Genesys Logic, Inc. GL3523 Hub +Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub +Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub +``` + + +#### WWAN + +The LTE module can be enabled as simple as this config snippet: + +```none +interfaces { + wwan wwan0 { + address "dhcp" + apn "YOUR-APN-GOES-HERE" + } +} +``` + +For more information please refer to chapter: {ref}`wwan-interface` + +[rufus]: https://rufus.ie/ diff --git a/docs/installation/md-image.md b/docs/installation/md-image.md new file mode 100644 index 00000000..a0fc89d4 --- /dev/null +++ b/docs/installation/md-image.md @@ -0,0 +1,113 @@ +--- +lastproofread: '2026-01-26' +--- + +(image-mgmt)= + +# Image Management + +VyOS uses an image-based installation that creates a directory for each image +on the storage device you select during installation. + +The boot device has the following directory structure: + +```none +/ +/boot +/boot/grub +/boot/2025.07.16-0020-rolling.squashfs +``` + +The image directory contains the system kernel, a compressed root filesystem +image, and a directory for persistent storage (such as configuration). During +boot, the system extracts the OS image into memory and mounts the appropriate +live-rw subdirectories to provide persistent storage for system configuration. + +This process ensures that the system always boots to a known working state, +since the OS image is fixed and non-persistent. You can also install multiple +VyOS releases on the same storage device. You can manually select the image at +boot if needed, but the system boots the default image by default. + +```{opcmd} show system image + +List all available system images which can be booted on the current system. + +:::{code-block} none +vyos@vyos:~$ show system image +Name Default boot Running +----------------------- -------------- --------- +2025.07.16-0020-rolling Yes Yes +1.4.1 +1.4.0 +::: +``` +```{opcmd} delete system image [image-name] + + Delete unused images from the system. You can specify an optional image name + to delete. Use the {opcmd}`show system image` command to list available + images. + + :::{code-block} none + vyos@vyos:~$ delete system image + The following images are installed: + 1: 2025.07.16-0020-rolling (running) (default boot) + 2: 1.4.1 + 3: 1.4.0 + Select an image to delete: 3 + Do you really want to delete the image 1.4.0? [y/N] y + The image "1.4.0" was successfully deleted + ::: +``` + + +```{opcmd} show version + +Show current system image version. + +:::{code-block} none +vyos@vyos:~$ show version +Version: VyOS 2025.07.16-0020-rolling +Release train: current +Release flavor: generic + +Built by: autobuild@vyos.net +Built on: Wed 16 Jul 2025 00:21 UTC +Build UUID: 20d432ee-6d55-4ebc-8462-46fe836246c9 +Build Commit ID: f7ce0d8a692f2d + +Architecture: x86_64 +Boot via: installed image +System type: KVM guest +Secure Boot: n/a (BIOS) + +Hardware vendor: QEMU +Hardware model: Standard PC (i440FX + PIIX, 1996) +Hardware S/N: +Hardware UUID: b9831d42-c1fe-b2bd-7d3d-49db9418f5c9 + +Copyright: VyOS maintainers and contributors +::: +``` + +## System rollback + +To roll back to a previous image, first view the available images by using the +{opcmd}`show system image` command, then select your image with the following +command: + +```{opcmd} set system image default-boot [image-name] + +Select the default boot image which will be started on the next boot +of the system. +``` + +Then reboot the system. + +:::{note} +VyOS automatically associates the configuration with each image, +so you don't need to manage this separately. Each image has its own unique +configuration copy. +::: + +If you have console access, you can also select the boot image by restarting +the system and using the GRUB menu at startup. diff --git a/docs/installation/md-index.md b/docs/installation/md-index.md new file mode 100644 index 00000000..4256aa9b --- /dev/null +++ b/docs/installation/md-index.md @@ -0,0 +1,30 @@ +--- +lastproofread: '2026-01-26' +--- + +# Installation and Image Management + +:::{note} +This information applies primarily to virtual installations: + +When installing VyOS, ensure that the MAC address you select for your NICs +is not a locally administered MAC address. Locally administered addresses are +distinguished from universally administered addresses by setting the +second-least-significant bit of the first octet to 1: + +Example: `02:00:00:00:00:01`, where the second-least-significant bit +(`02` in hexadecimal) is set to `1`. +::: + +```{toctree} +:caption: Content +:maxdepth: 2 + +install +virtual/index +cloud/index +bare-metal +update +image +secure-boot +``` diff --git a/docs/installation/md-install.md b/docs/installation/md-install.md new file mode 100644 index 00000000..532bdc0c --- /dev/null +++ b/docs/installation/md-install.md @@ -0,0 +1,466 @@ +--- +lastproofread: '2026-01-26' +--- + +(installation)= + +# Installation + +VyOS installation requires a VyOS .iso file. This file is a live installation +image that you can use to boot a live VyOS system. From there, you can proceed +with a permanent installation on a hard drive or other storage device. + +:::{list-table} Comparison of VyOS image releases +:header-rows: 1 +:widths: 15 35 15 25 15 15 + +* - Release Type + - Description + - Release Cycle + - Intended Use + - Access to Images + - Access to Source + +* - Nightly (Current) + - Automatically built from the current branch. Always up to date + with cutting edge development but guaranteed to contain bugs. + - Every night + - Developing VyOS, testing new features, experimenting. + - Everyone + - Everyone + +* - Stream + - VyOS Stream serves as a technology preview and a quality gate + for the upcoming LTS release. Allows everyone to try new features + and check if they work well or need improvements. + - Every quarter + - Non-critical production environments, preparing for the LTS + release. + - Everyone + - Everyone + +* - Release Candidate + - Rather stable. All development focuses on testing and hunting + down remaining bugs following the feature freeze. + - Irregularly until EPA comes out + - Labs, small offices and non-critical production systems backed + by a high-availability setup. + - Everyone + - Everyone + +* - Early Production Access + - Highly stable with no known bugs. Needs to be tested repeatedly + under different conditions before it can become the final + release. + - Irregularly until LTS comes out + - Non-critical production environments, preparing for the LTS + release. + - Everyone + - Everyone + +* - Long-Term Support + - Guaranteed to be stable and carefully maintained for several + years after the release. No features are introduced but security + updates are released in a timely manner. + - Every major version + - Large-scale enterprise networks, internet service providers, + critical production environments that call for minimum downtime. + - Subscribers, contributors, non-profits, emergency services, + academic institutions + - Subscribers, contributors, non-profits, emergency services, + academic institutions +::: + +## Hardware requirements + +The minimum system requirements for VyOS are 4 GB RAM and 10 GB storage. +Depending on your use case, you might need additional RAM and CPU resources. + +## Download + +### Registered Subscribers + +Registered subscribers can log into to access +a variety of different downloads via the "Downloads" link. These +downloads include LTS (Long-Term Support), the associated hot-fix releases, +early public access releases, pre-built VM images, as well as device +specific installation ISOs. See this [article] for more information on +downloads. + +:::{note} +The `.qcow2` image provided for Proxmox deployment can also be +used to deploy VyOS on KVM environments. This image includes cloud-init +support. See {ref}`cloud-init` for more information. +::: + +:::{figure} /_static/images/vyosnew-downloads.webp +::: + +### Building from source + +Subscribers can download the source code for the LTS release from the +"Downloads" link. Non-subscribers can access the source code for the +Rolling release. For instructions, see the {ref}`build` section. The +VyOS source code repository is available at +. + +### Rolling Release + +Everyone can download bleeding-edge VyOS rolling images from: + + +:::{note} +Rolling releases contain the latest enhancements and fixes. +This means there may be new bugs. If you encounter a bug, follow the +guide at {ref}`bug_report`. We depend on your feedback to improve VyOS. +::: + +The following link contains the most recent VyOS builds for AMD64 +systems from the `current` branch: + +### Download Verification + +LTS images are signed with the VyOS lead package maintainer's private key. +You can verify the authenticity of the package using the official public key +and Minisign. + +(minisign-verification)= + +#### Minisign verification + +VyOS uses [Minisign](https://github.com/jedisct1/minisign) for release +signing. Minisign is a tool for signing files and verifying signatures. + +OpenBSD introduced signify in 2015. Minisign is an alternative +implementation of the same protocol, available for Windows, macOS, and +most GNU/Linux distributions. Minisign is portable, lightweight, and +uses the Ed25519 public-key signature system. + +{vytask}`T2108` switched the validation system to prefer Minisign over GPG keys. + +To verify a VyOS image starting with VyOS `1.3.0-rc6`, run: + +```none +$ minisign -V -P RWSIhkR/dkM2DSaBRniv/bbbAf8hmDqdbOEmgXkf1RxRoxzodgKcDyGq -m vyos-1.5-rolling-202409250007-generic-amd64.iso vyos-1.5-rolling-202409250007-generic-amd64.iso.minisig + +Signature and comment signature verified +Trusted comment: timestamp:1727223408 file:vyos-1.5-rolling-202409250007-generic-amd64.iso hashed +``` + +During an image upgrade, VyOS runs the following command: + +```none +$ minisign -V -p /usr/share/vyos/keys/vyos-release.minisign.pub -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig +Signature and comment signature verified +Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso +``` + +:::{note} +Starting with version `1.4.3`, VyOS uses Minisign exclusively. +If you see an unexpected verification error, update your system to version +`1.4.2` first. Support for GnuPG signatures has been +removed ({vytask}`T7301`). +::: + +(live_installation)= + +## Live installation + +:::{note} +To permanently install VyOS, you must first complete a live +installation. +::: + +You can test VyOS without installing it on your hard drive. **Using your +downloaded VyOS .iso file, you can create a bootable USB drive to boot +into a fully functional VyOS system**. After testing it, you can start a +{ref}`permanent_installation` on your hard drive or power off your system +and remove the USB drive. + +```{eval-rst} +If you have a GNU/Linux system, you can create a bootable VyOS USB drive using +the ``dd`` command: + + 1. Open your terminal emulator. + + 2. Find the device name of your USB drive (use the ``lsblk`` command). + + 3. Unmount the USB drive. Replace ``X`` with your device letter and keep the + asterisk (*) to unmount all partitions. + + .. code-block:: none + + $ umount /dev/sdX* + + 1. Write the image (your VyOS .iso file) to the USB drive. Use the device + name (for example, ``/dev/sdb``), not the partition name + (for example, ``/dev/sdb1``). + + **Warning**: This will destroy all data on the USB drive! + + .. code-block:: none + + # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync + + 1. Wait for the operation to complete (bytes copied). On some systems, this + may take more than one minute. + + 2. Once ``dd`` has finished, pull the USB drive out and plug it into + the powered-off computer where you want to install (or test) VyOS. + + 3. Power on the computer and ensure it boots from the USB drive + (you may need to select the boot device or change boot settings). + + 4. When VyOS finishes loading, sign in using the default credentials + (login: ``vyos``, password: ``vyos``). +``` + +If you encounter issues with this method, prefer a different operating +system, or want a GUI program, you can use other tools to create a +bootable USB drive, such as [balenaEtcher] (GNU/Linux, macOS, and Windows), +[Rufus] (Windows), and [many others]. Follow their instructions to create +a bootable USB drive from an `.iso` file. + +:::{hint} +The default username and password for the live system is *vyos*. +::: + +(permanent_installation)= + +## Permanent installation + +:::{note} +Before a permanent installation, VyOS requires a +{ref}`live_installation`. +::: + +Unlike general-purpose Linux distributions, VyOS uses "image installation", +which mimics the user experience of traditional hardware routers and allows +you to keep multiple VyOS versions installed simultaneously. This lets you +switch to a previous version if something breaks or misbehaves after an +image upgrade. + +Each version is contained in its own squashfs image mounted in a union +filesystem along with a directory for mutable data such as configurations, +keys, and custom scripts. + +```{eval-rst} +In order to proceed with a permanent installation: + + 1. Sign in to the VyOS live system using the default credentials + (login: ``vyos``, password: ``vyos``). + + 2. Run the ``install image`` command and follow the wizard: + + .. code-block:: none + + vyos@vyos:~$ install image + Welcome to VyOS installation! + This command will install VyOS to your permanent storage. + Would you like to continue? [y/N] y + What would you like to name this image? (Default: 2025.09.17-0018-rolling) + Please enter a password for the "vyos" user: + Please confirm password for the "vyos" user: + What console should be used by default? (K: KVM, S: Serial)? (Default: S) + Probing disks + 1 disk(s) found + The following disks were found: + Drive: /dev/vda (10.0 GB) + Which one should be used for installation? (Default: /dev/vda) + Installation will delete all data on the drive. Continue? [y/N] y + Searching for data from previous installations + No previous installation found + Would you like to use all the free space on the drive? [Y/n] Y + Creating partition table... + The following config files are available for boot: + 1: /opt/vyatta/etc/config/config.boot + 2: /opt/vyatta/etc/config.boot.default + Which file would you like as boot config? (Default: 1) + Creating temporary directories + Mounting new partitions + Creating a configuration file + Copying system image files + Installing GRUB configuration files + Installing GRUB to the drive + Cleaning up + Unmounting target filesystems + Removing temporary files + The image installed successfully; please reboot now. + + + 3. After installation completes, remove the live USB drive or CD. + + 4. Reboot the system. + + .. code-block:: none + + vyos@vyos:~$ reboot + Proceed with reboot? (Yes/No) [No] Yes + + You will boot now into a permanent VyOS system. +``` + +## PXE Boot + +You can also install VyOS using PXE, a more complex installation method that +allows you to deploy VyOS over the network. + +**Requirements** + +- A machine (client) with a PXE-enabled NIC. +- {ref}`dhcp-server` +- {ref}`tftp-server` +- Webserver (HTTP). Optional, but speeds up installation. +- VyOS ISO image (do not use images prior to VyOS `1.2.3`). +- Files *pxelinux.0* and *ldlinux.c32* from the + [Syslinux distribution](https://kernel.org/pub/linux/utils/boot/syslinux/). + +### Configuration + +#### Step 1: DHCP + +Configure a DHCP server to provide the client with: + +- An IP address +- The TFTP server address (DHCP option 66), sometimes referred to as the + *boot server* +- The *bootfile name* (DHCP option 67): *pxelinux.0* + +In this example we configured an existent VyOS as the DHCP server: + +```none +vyos@vyos# show service dhcp-server + shared-network-name mydhcp { + subnet 192.168.1.0/24 { + option { + bootfile-name pxelinux.0 + bootfile-server 192.168.1.50 + default-router 192.168.1.50 + } + range 0 { + start 192.168.1.70 + stop 192.168.1.100 + } + subnet-id 1 + } + } +``` + +(install_from_tftp)= + +#### Step 2: TFTP + +Configure a TFTP server to serve the following: + +- The *pxelinux.0* file from the Syslinux distribution +- The *ldlinux.c32* file from the Syslinux distribution +- The VyOS kernel you want to deploy (*vmlinuz* file from the + */live* directory in the extracted ISO file) +- The VyOS initial ramdisk (*initrd.img* file from the */live* directory + in the extracted ISO file). Do not use an empty (0 bytes) initrd.img + file; the correct file may have a longer name. +- A directory named *pxelinux.cfg* containing the configuration file. + By default, the VyOS configuration file is named [default]. + +In the example you configured your existent VyOS as the TFTP server too: + +```none +vyos@vyos# show service tftp-server + directory /config/tftpboot + listen-address 192.168.1.50 +``` + +Example of the contents of the TFTP server: + +```none +vyos@vyos# ls -hal /config/tftpboot/ +total 29M +drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . +drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. +-r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos +-rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 +-rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 +drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg +-r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz + +vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg +total 12K +drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . +drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. +-rw-r--r-- 1 root root 191 Oct 14 01:10 default +``` + +Example of simple (no menu) configuration file: + +```none +vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default +DEFAULT VyOS123 + +LABEL VyOS123 + KERNEL vmlinuz + APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs +``` + + +#### Step 3: HTTP + +You also need to provide the *filesystem.squashfs* file. Because this is a +large file and TFTP is slow, you can send it through HTTP to speed up the +transfer. In our example, we do thisβ€”see the configuration file above. + +1. Start a web server. You can use one like + [Python's SimpleHTTPServer] to serve the `filesystem.squashfs` file. + The file is in the `/live` directory of the extracted ISO file. +2. Edit the {ref}`install_from_tftp` configuration file to show the correct + URL: `fetch=http:///filesystem.squashfs`. + +:::{note} +Do not rename the *filesystem.squashfs* file. If you're working with +different versions, create different directories instead. +::: + +3. restart the TFTP service. If you're using VyOS as your TFTP server, restart + the service with `sudo service tftpd-hpa restart`. + +:::{note} +Ensure the directories and files on both the TFTP and HTTP servers +have the correct permissions for the booting clients to access them. +::: + +### Client Boot + +Finally, power on your PXE-enabled clients. They will automatically receive an +IP address from the DHCP server and boot into VyOS live using files from the +TFTP and HTTP servers. + +Once finished you will be able to proceed with the `install image` +command as in a regular VyOS installation. + +## Known Issues + +This is a list of known issues that can arise during installation. + +### Black screen on install + +GRUB redirects all output to a serial port to facilitate installation +on headless hosts. On some hardware that lacks a serial port, this causes +a hard lockup and displays a black screen after you select the +`Live system` option from the installation image. + +The workaround is to press `e` when the boot menu appears and edit the +GRUB boot options. Specifically, remove the: + +`console=ttyS0,115200` + +option, and type CTRL-X to boot. + +Installation can then continue as outlined above. + +[article]: https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913 +[balenaetcher]: https://www.balena.io/etcher/ +[configuration]: https://wiki.syslinux.org/wiki/index.php?title=Config +[default]: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration +[many others]: +[python's simplehttpserver]: https://docs.python.org/2/library/simplehttpserver.html +[rufus]: https://rufus.ie/ +[syslinux]: http://www.syslinux.org/ diff --git a/docs/installation/md-secure-boot.md b/docs/installation/md-secure-boot.md new file mode 100644 index 00000000..ecbc432d --- /dev/null +++ b/docs/installation/md-secure-boot.md @@ -0,0 +1,194 @@ +--- +lastproofread: '2026-01-26' +--- + +(secure-boot)= + +# Secure Boot + +Initial UEFI Secure Boot support is available ({vytask}`T861`). VyOS uses +`shim` from Debian 12 (Bookworm), which is properly signed by the UEFI +Secure Boot key from Microsoft. + +:::{note} +There is yet no signed version of `shim` for VyOS, thus we +provide no signed image for secure boot yet. If you are interested in +secure boot you can build an image on your own. +::: + +To generate a custom ISO with your own secure boot keys, run the following +commands prior to your ISO image build: + +```bash +cd vyos-build +CA_DIR="data/certificates" +SHIM_CERT_NAME="vyos-dev-2025-shim" +VYOS_KERNEL_CERT_NAME="vyos-dev-2025-linux" + +openssl req -new -x509 -newkey rsa:4096 -keyout ${CA_DIR}/${SHIM_CERT_NAME}.key -out ${CA_DIR}/${SHIM_CERT_NAME}.der \ + -outform DER -days 36500 -subj "/CN=VyOS Networks Secure Boot CA/" -nodes +openssl x509 -inform der -in ${CA_DIR}/${SHIM_CERT_NAME}.der -out ${CA_DIR}/${SHIM_CERT_NAME}.pem + +openssl req -newkey rsa:4096 -sha256 -nodes -keyout ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.key \ + -out ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.csr -outform PEM -days 3650 \ + -subj "/CN=VyOS Networks Secure Boot Signer 2025 - linux/" +openssl x509 -req -in ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.csr -CA ${CA_DIR}/${SHIM_CERT_NAME}.pem \ + -CAkey ${CA_DIR}/${SHIM_CERT_NAME}.key -CAcreateserial -out ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.pem -days 3650 -sha256 +``` + + +## Installation + +As our version of `shim` is not signed by Microsoft we need to enroll the +previously generated {abbr}`MOK (Machine Owner Key)` to the system. + +First, disable UEFI Secure Boot for the installation. + +:::{figure} /_static/images/uefi_secureboot_01.webp +:alt: Disable UEFI secure boot +::: + +Proceed with the standard VyOS {ref}`installation ` on +your system. Instead of the final `reboot` command, enroll the +{abbr}`MOK (Machine Owner Key)`. + +```none +vyos@vyos:~$ install mok +input password: +input password again: +``` + +You can set the `input password` to any value you choose. You'll need this +password after reboot when MOK Manager launches to permanently install the keys. + +With the next reboot, MOK Manager will automatically launch + +:::{figure} /_static/images/uefi_secureboot_02.webp +:alt: Disable UEFI secure boot +::: + +Select `Enroll MOK` + +:::{figure} /_static/images/uefi_secureboot_03.webp +:alt: Disable UEFI secure boot +::: + +You can now view the key to be installed and continue with key installation. + +:::{figure} /_static/images/uefi_secureboot_04.webp +:alt: Disable UEFI secure boot +::: + +:::{figure} /_static/images/uefi_secureboot_05.webp +:alt: Disable UEFI secure boot +::: + +Now you need to enter the password you defined previously. + +:::{figure} /_static/images/uefi_secureboot_06.webp +:alt: Disable UEFI secure boot +::: + +Now reboot and re-enable UEFI Secure Boot. + +:::{figure} /_static/images/uefi_secureboot_07.webp +:alt: Disable UEFI secure boot +::: + +VyOS will now launch in UEFI Secure Boot mode. You can verify this by running +one of the following commands: + +```none +vyos@vyos:~$ show secure-boot +SecureBoot enabled +``` + +```none +vyos@vyos:~$ show log kernel | match Secure +Oct 08 19:15:41 kernel: Secure boot enabled +``` + +```none +vyos@vyos:~$ show version +Version: VyOS 1.5-secureboot +Release train: current +Release flavor: generic + +Built by: autobuild@vyos.net +Built on: Tue 08 Oct 2024 18:00 UTC +Build UUID: 5702ca38-e6f4-470f-b89e-ffc29baee474 +Build commit ID: 9eb61d3b6cf426 + +Architecture: x86_64 +Boot via: installed image +System type: KVM guest +Secure Boot: enabled <-- UEFI secure boot indicator + +Hardware vendor: QEMU +Hardware model: Standard PC (i440FX + PIIX, 1996) +Hardware S/N: +Hardware UUID: 1f6e7f5c-fb52-4c33-96c9-782fbea36436 + +Copyright: VyOS maintainers and contributors +``` + + +## Image Update + +:::{note} +Currently, there is no signed version of `shim` for VyOS. If you +want Secure Boot support, you can build a custom image with your own keys. +::: + +During image installation, you install your {abbr}`MOK (Machine Owner Key)` +into the UEFI variables to add trust to this key. After you re-enable Secure +Boot in UEFI, you can only boot into your signed image. + +You can no longer boot into a CI-generated rolling release because those +are not signed by a trusted party ({vytask}`T861` work in progress). This +also means you must sign all successor builds with the same key; otherwise, +you'll see this error: + +```none +error: bad shim signature +error: you need to load the kernel first +``` + + +## Linux Kernel + +In addition to Secure Boot support, VyOS uses ephemeral key signing of Linux +Kernel modules for an extra security layer in both Secure and non-Secure boot +images. + + + +When the CI system builds a Kernel package and required third-party modules, +it generates a temporary (ephemeral) key pair for signing the modules. The +public key is embedded in the Kernel binary to verify loaded modules. + +After the Kernel CI build completes, the generated key is discarded, meaning +we can no longer sign additional modules with that key. The Kernel configuration +also includes the option `CONFIG_MODULE_SIG_FORCE=y`, which enforces signature +verification for all modules. If you try to load an unsigned module, you'll +get this error: + +`insmod: ERROR: could not insert module malicious.ko: Key was rejected by +service` + +This prevents loading any malicious code after the image is assembled into the +Kernel as a module. You can disable this behavior on custom builds if needed. + +## Troubleshoot + +In most cases, if something goes wrong during system boot, you'll see this +error message: + +```none +error: bad shim signature +error: you need to load the kernel first +``` + +This error means the Machine Owner Key used to sign the Kernel is not trusted +by your UEFI. Install the MOK using the `install mok` command as described +above. diff --git a/docs/installation/md-update.md b/docs/installation/md-update.md new file mode 100644 index 00000000..e8b5f912 --- /dev/null +++ b/docs/installation/md-update.md @@ -0,0 +1,105 @@ +--- +lastproofread: '2026-01-26' +--- + +(update_vyos)= + +# Update VyOS + +New system images can be added using the {opcmd}`add system image` command. +This command extracts the image and prompts you to use the current system +configuration and SSH security keys, allowing the new image to boot with your +current configuration. + +:::{note} +Only LTS releases are PGP-signed. +::: + +```{opcmd} add system image \ | [latest] [vrf name] [username user [password pass]] + +Use this command to install a new system image. You can retrieve the +image from the web (``http://``, ``https://``) or from your local system. +For example: /tmp/vyos-1.2.3-amd64.iso. + + The ``add system image`` command also supports installing new VyOS versions + through an optional VRF. If the URL requires authentication, you can specify + an optional username and password on the command line, which will be passed + as "Basic-Auth" to the server. +``` + +If there isn't enough free disk space, the installation will be canceled. +To delete images, use the {opcmd}`delete system image` command. + + +VyOS associates configuration with each image, and each image has its own +unique configuration copy. This differs from traditional network routers where +the configuration is shared across all images. + + +:::{note} +If you have personal files such as scripts that you want to preserve +during the upgrade, store them in `/config` since this directory is always +copied to newly installed images. +::: + + +You can access files from a previous installation and copy them to your +current image if they were stored in the `/config` directory. Use the +{opcmd}`copy` command to do this. For example, to copy `/config/config.boot` +from the VyOS `1.2.1` image, run: + +```none +copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 +``` + + +#### Example + +```none +vyos@vyos:~$ add system image https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso +Trying to fetch ISO file from https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k +ISO download succeeded. +Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 +curl: (22) The requested URL returned error: 404 Not Found + +Unable to fetch digital signature file. +Do you want to continue without signature check? (yes/no) [yes] +Checking MD5 checksums of files on the ISO image...OK. +Done! + +What would you like to name this image? [vyos-1.3-rolling-201912201452]: + +OK. This image will be named: vyos-1.3-rolling-201912201452 +``` + +You can use `latest` option. It loads the latest available Rolling release. + +```none +vyos@vyos:~$ add system image latest +``` + +:::{note} +To use the `latest` option, "system update-check url" must be +configured appropriately for your installed release. + +For updates to the Rolling Release for AMD64, the following URL may be +used: + + +::: + +:::{hint} +You can access the latest Rolling Release for AMD64 from a web +browser at: + + +::: + +After rebooting, verify the version you're running using the +{opcmd}`show version` command. 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