diff options
Diffstat (limited to 'docs/installation')
| -rw-r--r-- | docs/installation/cloud/md-aws.md | 188 | ||||
| -rw-r--r-- | docs/installation/cloud/md-azure.md | 98 | ||||
| -rw-r--r-- | docs/installation/cloud/md-gcp.md | 61 | ||||
| -rw-r--r-- | docs/installation/cloud/md-index.md | 10 | ||||
| -rw-r--r-- | docs/installation/cloud/md-oracle.md | 17 | ||||
| -rw-r--r-- | docs/installation/md-bare-metal.md | 626 | ||||
| -rw-r--r-- | docs/installation/md-image.md | 113 | ||||
| -rw-r--r-- | docs/installation/md-index.md | 30 | ||||
| -rw-r--r-- | docs/installation/md-install.md | 466 | ||||
| -rw-r--r-- | docs/installation/md-secure-boot.md | 194 | ||||
| -rw-r--r-- | docs/installation/md-update.md | 105 | ||||
| -rw-r--r-- | docs/installation/virtual/md-docker.md | 72 | ||||
| -rw-r--r-- | docs/installation/virtual/md-eve-ng.md | 14 | ||||
| -rw-r--r-- | docs/installation/virtual/md-gns3.md | 191 | ||||
| -rw-r--r-- | docs/installation/virtual/md-index.md | 16 | ||||
| -rw-r--r-- | docs/installation/virtual/md-libvirt.md | 186 | ||||
| -rw-r--r-- | docs/installation/virtual/md-proxmox.md | 80 | ||||
| -rw-r--r-- | docs/installation/virtual/md-vmware.md | 38 |
18 files changed, 2505 insertions, 0 deletions
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:<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`. + +```{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 + +- <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/> + 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 + +<https://azure.microsoft.com> 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 + +<https://console.cloud.google.com/> 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 + +<https://www.oracle.com/cloud/> + +<https://docs.oracle.com/en/cloud/paas/developer-cloud-classic/csdcc/deploy-application.html> + 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 <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.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 +<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: + +```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://<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. + +[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]: <https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems> +[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 <permanent_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. + +<https://patchwork.kernel.org/project/linux-integrity/patch/20210218220011.67625-5-nayna@linux.ibm.com/> + +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 \<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: + +```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: + +<https://raw.githubusercontent.com/vyos/vyos-nightly-build/refs/heads/current/version.json> +::: + +:::{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/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 + +<https://www.eve-ng.net/> 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 <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.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 <https://support.vyos.io/>. + 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-<version>-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 + <https://vyos.net/get/nightly-builds/>. +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-<version>.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 +<https://www.proxmox.com/en/>. + 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 + +<https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html> + |