diff options
| author | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-10 17:23:58 +0300 |
|---|---|---|
| committer | Yuriy Andamasov <yuriy@vyos.io> | 2026-05-10 17:23:58 +0300 |
| commit | b6ff49dc4873e370083205d2f12bb2eb3894c7bc (patch) | |
| tree | 70adcc0335887a92ac99f6e20b64bc8192461412 /docs/installation | |
| parent | 1d5a918294f65de399da012ab5f9b6cea224f474 (diff) | |
| download | vyos-documentation-b6ff49dc4873e370083205d2f12bb2eb3894c7bc.tar.gz vyos-documentation-b6ff49dc4873e370083205d2f12bb2eb3894c7bc.zip | |
chore: remove RST swap mechanism, archive rst-*.rst under docs/_rst_legacy/
The swap mechanism (RST-as-fallback for migrated MD pages) is dormant —
docs/_rst_overrides.txt has been empty since the MyST flip trio
(#1899/#1900/#1901) landed. The mechanism's surface area is dead weight
and the rst-*.rst shadows scattered across the source tree cause
Context7's parser to misclassify the project as RST.
Sibling PR on rolling: yuriy/remove-rst-swap-mechanism
Changes:
- Move 253 rst-*.rst shadow files into docs/_rst_legacy/ preserving
subdirectory structure. They remain in the repo for reference; Sphinx
excludes the folder via exclude_patterns.
- Strip swap_sources.py invocation from docs/Makefile.
- Strip jobs: pre_build/post_build block from .readthedocs.yml.
- Strip rst-*.rst exclude entry and the _md_exclude.txt loader from
docs/conf.py; replace with a single _rst_legacy exclude.
- Delete scripts/swap_sources.py, tests/test_swap_sources.py,
docs/_rst_overrides.txt.
- Update AGENTS.md: drop the "RST override mechanism" section and the
test-runner snippet for the deleted test.
Verified: sphinx-build -b html with --keep-going produces identical
warning set (68 unique), identical sitemap entry count (267), identical
llms.txt entry count (22), zero rst-* URLs in any artifact.
🤖 Generated by [robots](https://vyos.io)
Diffstat (limited to 'docs/installation')
| -rw-r--r-- | docs/installation/cloud/rst-aws.rst | 166 | ||||
| -rw-r--r-- | docs/installation/cloud/rst-azure.rst | 84 | ||||
| -rw-r--r-- | docs/installation/cloud/rst-gcp.rst | 59 | ||||
| -rw-r--r-- | docs/installation/cloud/rst-index.rst | 11 | ||||
| -rw-r--r-- | docs/installation/cloud/rst-oracle.rst | 18 | ||||
| -rw-r--r-- | docs/installation/rst-bare-metal.rst | 632 | ||||
| -rw-r--r-- | docs/installation/rst-image.rst | 112 | ||||
| -rw-r--r-- | docs/installation/rst-index.rst | 27 | ||||
| -rw-r--r-- | docs/installation/rst-install.rst | 475 | ||||
| -rw-r--r-- | docs/installation/rst-secure-boot.rst | 192 | ||||
| -rw-r--r-- | docs/installation/rst-update.rst | 96 | ||||
| -rw-r--r-- | docs/installation/virtual/rst-docker.rst | 75 | ||||
| -rw-r--r-- | docs/installation/virtual/rst-eve-ng.rst | 16 | ||||
| -rw-r--r-- | docs/installation/virtual/rst-gns3.rst | 177 | ||||
| -rw-r--r-- | docs/installation/virtual/rst-index.rst | 15 | ||||
| -rw-r--r-- | docs/installation/virtual/rst-libvirt.rst | 186 | ||||
| -rw-r--r-- | docs/installation/virtual/rst-proxmox.rst | 71 | ||||
| -rw-r--r-- | docs/installation/virtual/rst-vmware.rst | 41 |
18 files changed, 0 insertions, 2453 deletions
diff --git a/docs/installation/cloud/rst-aws.rst b/docs/installation/cloud/rst-aws.rst deleted file mode 100644 index 2901b6d1..00000000 --- a/docs/installation/cloud/rst-aws.rst +++ /dev/null @@ -1,166 +0,0 @@ -: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**. - -.. figure:: /_static/images/cloud-aws-01.png - -2. Search for "VyOS" in the Marketplace. - -.. figure:: /_static/images/cloud-aws-02.png - -3. Choose the instance type. The recommended minimum is ``m3.medium``. - -.. figure:: /_static/images/cloud-aws-03.png - -4. Configure the instance for your requirements. Select the number of - instances, network, and subnet. - -.. figure:: /_static/images/cloud-aws-04.png - -5. Configure additional storage. You can remove the additional storage - ``/dev/sdb``. The root device will be ``/dev/xvda``. You can skip this step. - -.. figure:: /_static/images/cloud-aws-05.png - -6. Configure the security group. We recommend configuring SSH access - only from specific sources, or you can permit any IP address (the default). - -.. figure:: /_static/images/cloud-aws-06.png - -7. Select the SSH key pair and click **Launch Instances**. - -.. figure:: /_static/images/cloud-aws-07.png - -8. Note your public IP address. - -.. figure:: /_static/images/cloud-aws-08.png - -9. Connect to the instance using your SSH key. - - .. 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. - - .. 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. - - .. code-block:: none - - $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c ssm:<your-configuration-name> - - 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``. - - .. 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. - - .. 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. - -.. stop_vyoslinter -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/>`__. - -.. start_vyoslinter -Configuration Example -^^^^^^^^^^^^^^^^^^^^^ - -Configure the AWS GWLB service with the following commands: - -.. code-block:: 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' - -.. stop_vyoslinter -References ----------- -- https://console.aws.amazon.com/ -- https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/create-iam-roles-for-cloudwatch-agent.html -- https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance-fleet.html -- https://aws.amazon.com/blogs/networking-and-content-delivery/how-to-integrate-linux-instances-with-aws-gateway-load-balancer/ - -.. start_vyoslinter diff --git a/docs/installation/cloud/rst-azure.rst b/docs/installation/cloud/rst-azure.rst deleted file mode 100644 index 77d00814..00000000 --- a/docs/installation/cloud/rst-azure.rst +++ /dev/null @@ -1,84 +0,0 @@ -: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**. - -.. figure:: /_static/images/cloud-azure-01.png - -3. Search for "VyOS" in the marketplace and choose the appropriate - subscription. - -.. figure:: /_static/images/cloud-azure-02.png - -4. Generate new SSH key pair or use existing. - -.. figure:: /_static/images/cloud-azure-03.png - -5. Configure the network, subnet, and public IP. Or use the defaults. - -.. figure:: /_static/images/cloud-azure-04.png - -6. Click **Review + create**. Your deployment completes in a few seconds. - -.. figure:: /_static/images/cloud-azure-05.png - -7. Select your new VM and note your public IP address. - -.. figure:: /_static/images/cloud-azure-06.png - -8. Connect to the instance with your SSH key. - - .. 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 ----------- -https://azure.microsoft.com diff --git a/docs/installation/cloud/rst-gcp.rst b/docs/installation/cloud/rst-gcp.rst deleted file mode 100644 index f6b6732b..00000000 --- a/docs/installation/cloud/rst-gcp.rst +++ /dev/null @@ -1,59 +0,0 @@ -: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: - - .. code-block:: 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.png - - - Click **Add item**, paste your public SSH key, and click **Save**. - -.. figure:: /_static/images/cloud-gcp-02.png - - -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.png - -5. After a few seconds, select your **instance**. - -.. figure:: /_static/images/cloud-gcp-04.png - -6. Note your external IP address. - -.. figure:: /_static/images/cloud-gcp-05.png - -7. Connect to the instance using the SSH key you generated in step 1. - - .. code-block:: none - - ssh -i ~/.ssh/vyos_gcp vyos@203.0.113.3 - vyos@vyos-r1-vm:~$ - -References ----------- -https://console.cloud.google.com/ diff --git a/docs/installation/cloud/rst-index.rst b/docs/installation/cloud/rst-index.rst deleted file mode 100644 index 18d525ac..00000000 --- a/docs/installation/cloud/rst-index.rst +++ /dev/null @@ -1,11 +0,0 @@ -################## -Cloud Environments -################## - -.. toctree:: - :caption: Content - - aws - azure - gcp - oracle diff --git a/docs/installation/cloud/rst-oracle.rst b/docs/installation/cloud/rst-oracle.rst deleted file mode 100644 index f5e03329..00000000 --- a/docs/installation/cloud/rst-oracle.rst +++ /dev/null @@ -1,18 +0,0 @@ -:lastproofread: 2026-02-09 - -###### -Oracle -###### - -.. note:: This page is a stub and needs expansion. - Contributions welcome via the - VyOS `documentation repository`_. - -.. _documentation repository: https://github.com/vyos/vyos-documentation - -.. stop_vyoslinter -References ----------- -https://www.oracle.com/cloud/ -https://docs.oracle.com/en/cloud/paas/developer-cloud-classic/csdcc/deploy-application.html -.. start_vyoslinter diff --git a/docs/installation/rst-bare-metal.rst b/docs/installation/rst-bare-metal.rst deleted file mode 100644 index be5f9342..00000000 --- a/docs/installation/rst-bare-metal.rst +++ /dev/null @@ -1,632 +0,0 @@ -.. _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.jpg - :scale: 25 % - :alt: CSE-505-203B Back - -.. figure:: /_static/images/1u_vyos_front.jpg - :scale: 25 % - :alt: CSE-505-203B Front - -.. figure:: /_static/images/1u_vyos_front_open_1.jpg - :scale: 25 % - :alt: CSE-505-203B Open 1 - -.. figure:: /_static/images/1u_vyos_front_open_2.jpg - :scale: 25 % - :alt: CSE-505-203B Open 2 - -.. figure:: /_static/images/1u_vyos_front_open_3.jpg - :scale: 25 % - :alt: CSE-505-203B Open 3 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_1.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 1 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_2.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 2 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_3.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 3 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_4.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open - - -.. _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. - -.. stop_vyoslinter -.. code-block:: 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] - -.. start_vyoslinter - -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. - -.. code-block:: 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: - -.. code-block:: 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.jpg - :scale: 25 % - :alt: APU4 rack closed - -.. figure:: /_static/images/apu4_rack_2.jpg - :scale: 25 % - :alt: APU4 rack front - -.. figure:: /_static/images/apu4_rack_3.jpg - :scale: 25 % - :alt: APU4 rack module #1 - -.. figure:: /_static/images/apu4_rack_4.jpg - :scale: 25 % - :alt: APU4 rack module #2 - -.. figure:: /_static/images/apu4_rack_5.jpg - :scale: 25 % - :alt: APU4 rack module #3 with PSU - -VyOS custom print -""""""""""""""""" - -.. figure:: /_static/images/apu4_rack_vyos_print.jpg - :scale: 25 % - :alt: APU4 custom VyOS powder coat - -Desktop / Bench Top -^^^^^^^^^^^^^^^^^^^ - -.. figure:: /_static/images/apu4_desk_1.jpg - :scale: 25 % - :alt: APU4 desktop closed - -.. figure:: /_static/images/apu4_desk_2.jpg - :scale: 25 % - :alt: APU4 desktop closed - -.. figure:: /_static/images/apu4_desk_3.jpg - :scale: 25 % - :alt: APU4 desktop back - -.. figure:: /_static/images/apu4_desk_4.jpg - :scale: 25 % - :alt: APU4 desktop back - -.. _Rufus: https://rufus.ie/ - -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.jpg - -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.jpg - -.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Back.jpg - -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.png - -.. figure:: ../_static/images/gowin-02.png - -.. figure:: ../_static/images/gowin-03.png - -.. figure:: ../_static/images/gowin-04.png - -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. - -.. code-block:: 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. - -.. code-block:: 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. - -.. code-block:: 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 --------- - -.. code-block:: 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] - -.. code-block:: 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: - -.. code-block:: none - - interfaces { - wwan wwan0 { - address "dhcp" - apn "YOUR-APN-GOES-HERE" - } - } - -For more information please refer to chapter: :ref:`wwan-interface` diff --git a/docs/installation/rst-image.rst b/docs/installation/rst-image.rst deleted file mode 100644 index 5b473e78..00000000 --- a/docs/installation/rst-image.rst +++ /dev/null @@ -1,112 +0,0 @@ -: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: - -.. code-block:: 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/rst-index.rst b/docs/installation/rst-index.rst deleted file mode 100644 index 5ba89755..00000000 --- a/docs/installation/rst-index.rst +++ /dev/null @@ -1,27 +0,0 @@ -: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:: - :maxdepth: 2 - :caption: Content - - install - virtual/index - cloud/index - bare-metal - update - image - secure-boot diff --git a/docs/installation/rst-install.rst b/docs/installation/rst-install.rst deleted file mode 100644 index 80e4a5f6..00000000 --- a/docs/installation/rst-install.rst +++ /dev/null @@ -1,475 +0,0 @@ -: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 https://support.vyos.io/ 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.png - -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 -https://github.com/vyos/vyos-build. - -Rolling Release ---------------- - -Everyone can download bleeding-edge VyOS rolling images from: -https://downloads.vyos.io/ - -.. 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: https://vyos.net/get/nightly-builds/ - - -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: - -.. code-block:: 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: - -.. code-block:: 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. - - -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. - -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: - -.. code-block:: 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: - -.. code-block:: none - - vyos@vyos# show service tftp-server - directory /config/tftpboot - listen-address 192.168.1.50 - -Example of the contents of the TFTP server: - -.. code-block:: 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: - -.. code-block:: 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://<address_of_your_HTTP_server>/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. - - -.. stop_vyoslinter - -.. _SYSLINUX: http://www.syslinux.org/ -.. _balenaEtcher: https://www.balena.io/etcher/ -.. _Rufus: https://rufus.ie/ -.. _many others: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems -.. _configuration: https://wiki.syslinux.org/wiki/index.php?title=Config -.. _default: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration -.. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html -.. _article: https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913 - -.. start_vyoslinter diff --git a/docs/installation/rst-secure-boot.rst b/docs/installation/rst-secure-boot.rst deleted file mode 100644 index 1dd6713b..00000000 --- a/docs/installation/rst-secure-boot.rst +++ /dev/null @@ -1,192 +0,0 @@ -: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: - -.. code-block:: 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.png - :alt: Disable UEFI secure boot - -Proceed with the standard VyOS :ref:`installation <permanent_installation>` on -your system. Instead of the final ``reboot`` command, enroll the -:abbr:`MOK (Machine Owner Key)`. - -.. code-block:: 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.png - :alt: Disable UEFI secure boot - -Select ``Enroll MOK`` - -.. figure:: /_static/images/uefi_secureboot_03.png - :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.png - :alt: Disable UEFI secure boot - -.. figure:: /_static/images/uefi_secureboot_05.png - :alt: Disable UEFI secure boot - -Now you need to enter the password you defined previously. - -.. figure:: /_static/images/uefi_secureboot_06.png - :alt: Disable UEFI secure boot - -Now reboot and re-enable UEFI Secure Boot. - -.. figure:: /_static/images/uefi_secureboot_07.png - :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: - -.. code-block:: none - - vyos@vyos:~$ show secure-boot - SecureBoot enabled - -.. code-block:: none - - vyos@vyos:~$ show log kernel | match Secure - Oct 08 19:15:41 kernel: Secure boot enabled - -.. code-block:: 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: - -.. code-block:: 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. - -.. stop_vyoslinter - -https://patchwork.kernel.org/project/linux-integrity/patch/20210218220011.67625-5-nayna@linux.ibm.com/ - -.. start_vyoslinter - -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: - -.. code-block:: 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/rst-update.rst b/docs/installation/rst-update.rst deleted file mode 100644 index 967f494b..00000000 --- a/docs/installation/rst-update.rst +++ /dev/null @@ -1,96 +0,0 @@ -: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 <url | path> | [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: - -.. code:: - - copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 - - -Example -""""""" - -.. code-block:: 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. - -.. code-block:: none - - vyos@vyos:~$ add system image latest - -.. stop_vyoslinter -.. 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: - - https://raw.githubusercontent.com/vyos/vyos-nightly-build/refs/heads/current/version.json - -.. start_vyoslinter - -.. hint:: You can access the latest Rolling Release for AMD64 from a web - browser at: - - https://vyos.net/get/nightly-builds/ - -After rebooting, verify the version you're running using the -:opcmd:`show version` command. diff --git a/docs/installation/virtual/rst-docker.rst b/docs/installation/virtual/rst-docker.rst deleted file mode 100644 index 282e4e63..00000000 --- a/docs/installation/virtual/rst-docker.rst +++ /dev/null @@ -1,75 +0,0 @@ -: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. - -.. code-block:: 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. - -.. code-block:: none - - { - "ipv6": true, - "fixed-cidr-v6": "2001:db8::/64" - } - -Reload the Docker configuration. - -.. code-block:: 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``. - -.. code-block:: 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/rst-eve-ng.rst b/docs/installation/virtual/rst-eve-ng.rst deleted file mode 100644 index 0dd07db8..00000000 --- a/docs/installation/virtual/rst-eve-ng.rst +++ /dev/null @@ -1,16 +0,0 @@ -:lastproofread: 2026-02-02 - -###### -EVE-NG -###### - -.. note:: This page is a stub and needs expansion. - Contributions welcome via the - VyOS `documentation repository`_. - -.. _documentation repository: https://github.com/vyos/vyos-documentation - -References -========== - -https://www.eve-ng.net/
\ No newline at end of file diff --git a/docs/installation/virtual/rst-gns3.rst b/docs/installation/virtual/rst-gns3.rst deleted file mode 100644 index 31bb6887..00000000 --- a/docs/installation/virtual/rst-gns3.rst +++ /dev/null @@ -1,177 +0,0 @@ -: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.png - -Select **Qemu VMs** and then click the ``New`` button. - -.. figure:: /_static/images/gns3-02.png - -Write a name for your VM, such as "VyOS", and click ``Next``. - -.. figure:: /_static/images/gns3-03.png - -Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM -and click ``Next``. - -.. figure:: /_static/images/gns3-04.png - -Select **telnet** as your console type and click ``Next``. - -.. figure:: /_static/images/gns3-05.png - -Select **New image** for the base disk image of your VM and click -``Create``. - -.. figure:: /_static/images/gns3-06.png - -Use the defaults in the **Binary and format** window and click -``Next``. - -.. figure:: /_static/images/gns3-07.png - -Use the defaults in the **Qcow2 options** window and click ``Next``. - -.. figure:: /_static/images/gns3-08.png - -Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu -image creator**. - -.. figure:: /_static/images/gns3-09.png - -Click ``Finish`` to end the **New QEMU VM template** wizard. - -.. figure:: /_static/images/gns3-10.png - -Now 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.png - -In the **General settings** tab of your **QEMU VM template -configuration**, do the following: - -* Click on the ``Browse...`` button to choose the **Symbol** you want to - have representing your VM. -* In **Category** select in which group you want to find your VM. -* Set the **Boot priority** to **CD/DVD-ROM**. - -.. figure:: /_static/images/gns3-12.png - -At the **HDD** tab, change the Disk interface to **sata** to speed up -the boot process. - -.. figure:: /_static/images/gns3-13.png - -At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image -you want to install. - -.. figure:: /_static/images/gns3-14.png - -.. note:: You probably will want to accept to copy the .iso file to your - default image directory when you are asked. - -In the **Network** tab, set 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.png - -In the **Advanced** tab, unmark the checkbox **Use as a linked base -VM** and click ``OK``, which will save and close the **QEMU VM template -configuration** window. - -.. figure:: /_static/images/gns3-16.png - -At the general **Preferences** window, click ``OK`` to save and close. - -.. figure:: /_static/images/gns3-17.png - - -.. _vyos_installation: - -VyOS installation ------------------ - -* Create a new project. -* Drag the newly created VyOS VM into it. -* Start the VM. -* Open a console. - The console displays the system booting. It prompts for login - credentials. You're now at the VyOS live system. -* :ref:`Install VyOS <installation>` - 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.png - -**CD/DVD** tab: Clear the **Image** entry field to unmount the installation -image. - -.. figure:: /_static/images/gns3-21.png - -Set the number of required network adapters. For example, set it to **4**. - -.. figure:: /_static/images/gns3-215.png - -**Advanced** settings tab: Check the **Use as a linked -base VM** checkbox and click ``OK`` to save the changes. - -.. figure:: /_static/images/gns3-22.png - -The VyOS VM is now ready to be deployed. - diff --git a/docs/installation/virtual/rst-index.rst b/docs/installation/virtual/rst-index.rst deleted file mode 100644 index e1a3caf5..00000000 --- a/docs/installation/virtual/rst-index.rst +++ /dev/null @@ -1,15 +0,0 @@ -:lastproofread: 2026-02-02 - -#################### -Virtual Environments -#################### - -.. toctree:: - :caption: Content - - libvirt - proxmox - vmware - gns3 - eve-ng - docker diff --git a/docs/installation/virtual/rst-libvirt.rst b/docs/installation/virtual/rst-libvirt.rst deleted file mode 100644 index 20b3ff1a..00000000 --- a/docs/installation/virtual/rst-libvirt.rst +++ /dev/null @@ -1,186 +0,0 @@ -: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. - -.. code-block:: 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`` - -.. code-block:: 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. - -.. code-block:: none - - curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 - -Create VM with ``import`` qcow2 disk option. - -.. code-block:: 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`` - -.. code-block:: 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: - -.. code-block:: 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.png - -3. Choose the path to the VyOS ISO image. Select any Debian-based operating - system. - -.. figure:: /_static/images/virt-libvirt-02.png - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.png - -5. Disk size - -.. figure:: /_static/images/virt-libvirt-04.png - -6. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.png - -7. Then the system will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-06.png - -.. _libvirt:virt-manager_qcow2: - -Deploy from qcow2 ------------------ - -Download the predefined VyOS ``.qcow2`` image. - -.. code-block:: none - - curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 - - -1. Open :abbr:`VMM (Virtual Machine Manager)` and create a new - :abbr:`VM (Virtual Machine)` - -2. Choose ``Import existing disk`` image - -.. figure:: /_static/images/virt-libvirt-qc-01.png - -3. Choose the path to the ``vyos_kvm.qcow2`` image that you downloaded. - Select any Debian-based operating system. - -.. figure:: /_static/images/virt-libvirt-qc-02.png - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.png - -5. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.png - -6. Then the system will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-qc-03.png - - - diff --git a/docs/installation/virtual/rst-proxmox.rst b/docs/installation/virtual/rst-proxmox.rst deleted file mode 100644 index 070627aa..00000000 --- a/docs/installation/virtual/rst-proxmox.rst +++ /dev/null @@ -1,71 +0,0 @@ -:lastproofread: 2026-02-02 - -.. _proxmox: - -****************** -Running on Proxmox -****************** - -Proxmox is an open-source platform for virtualization. Visit -https://vyos.io to download a ``.qcow2`` image that you can import into -Proxmox. - -Deploy VyOS from CLI with qcow2 image -===================================== - -1. Copy the ``.qcow2`` image to a temporary directory on the Proxmox server. -2. The commands assume virtual machine ID 200 is unused and you want - the disk stored in a storage pool named `local-lvm`. - -.. code-block:: none - - $ qm create 200 --name vyos2 --memory 2048 --net0 virtio,bridge=vmbr0 - $ qm importdisk 200 /path/to/image/vyos-1.2.8-proxmox-2G.qcow2 local-lvm - $ qm set 200 --virtio0 local-lvm:vm-200-disk-0 - $ qm set 200 --boot order=virtio0 - -3. You can optionally attach a CDROM with an ISO as a cloud-init data - source. The command assumes the ISO is uploaded to the `local` - storage pool as `seed.iso`. - -.. code-block:: none - - $ qm set 200 --ide2 media=cdrom,file=local:iso/seed.iso - -4. Start the virtual machine using the Proxmox GUI or run ``qm start 200``. - - - -Deploy VyOS from CLI with rolling release ISO -============================================= - -1. Download the rolling release ISO from - https://vyos.net/get/nightly-builds/. Non-subscribers can use the - LTS release by building from source. For instructions, see the - :ref:`build` section. The VyOS source code repository - is available at https://github.com/vyos/vyos-build. -2. Prepare the VM for ISO installation. The commands assume your ISO is - in storage pool 'local', you want VM ID '200', and you want to create - a new 15GB disk on storage pool 'local-lvm'. - -.. code-block:: none - - qm create 200 --name vyos --memory 2048 --net0 virtio,bridge=vmbr0 --ide2 media=cdrom,file=local:iso/live-image-amd64.hybrid.iso --virtio0 local-lvm:15 - -3. Start the VM using ``qm start 200`` or the start button in the - Proxmox GUI. -4. Open the virtual console for your VM using the Proxmox web GUI. - Login username and password are both ``vyos``. -5. Once booted 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``. -7. Reboot the virtual machine using the GUI or run ``qm reboot 200``. - - - - - -For more information about downloading and installing Proxmox, visit -https://www.proxmox.com/en/. - diff --git a/docs/installation/virtual/rst-vmware.rst b/docs/installation/virtual/rst-vmware.rst deleted file mode 100644 index e18ea4c8..00000000 --- a/docs/installation/virtual/rst-vmware.rst +++ /dev/null @@ -1,41 +0,0 @@ -: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
-----------
-
-.. stop_vyoslinter
-
-https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html
-
-.. start_vyoslinter
\ No newline at end of file |