From 5d6fa52b8985f8068314aba26878a1d7d5cb84e5 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 20:42:32 +0300 Subject: feat: flip swap mechanism — MD as primary, RST as override (Phase 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is the first of three phases inverting the per-page swap mechanism so MD becomes the canonical primary and RST becomes the rare override. Phase 1 — file renames + conf.py exclude_patterns flip only: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 254 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 254 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty comment-only since no pages need the RST fallback right now - conf.py exclude_patterns flipped: rst-*.rst is now excluded by default instead of md-*.md - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce these names; for now no swap script runs because overrides list is empty) Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py with inverted rename direction, delete scripts/import_myst.py + tests, and update tests/test_swap_sources.py for the new semantics. Phase 3 will be the cleanup pass and ready-for-review flip. Generated by robots https://vyos.io --- docs/installation/bare-metal.md | 626 +++++++++++++++++++++++++++++ docs/installation/bare-metal.rst | 633 ------------------------------ docs/installation/cloud/aws.md | 188 +++++++++ docs/installation/cloud/aws.rst | 166 -------- docs/installation/cloud/azure.md | 98 +++++ docs/installation/cloud/azure.rst | 84 ---- docs/installation/cloud/gcp.md | 61 +++ docs/installation/cloud/gcp.rst | 59 --- docs/installation/cloud/index.md | 10 + docs/installation/cloud/index.rst | 11 - docs/installation/cloud/md-aws.md | 188 --------- docs/installation/cloud/md-azure.md | 98 ----- docs/installation/cloud/md-gcp.md | 61 --- docs/installation/cloud/md-index.md | 10 - docs/installation/cloud/md-oracle.md | 17 - docs/installation/cloud/oracle.md | 17 + docs/installation/cloud/oracle.rst | 16 - docs/installation/cloud/rst-aws.rst | 166 ++++++++ docs/installation/cloud/rst-azure.rst | 84 ++++ docs/installation/cloud/rst-gcp.rst | 59 +++ docs/installation/cloud/rst-index.rst | 11 + docs/installation/cloud/rst-oracle.rst | 16 + docs/installation/image.md | 113 ++++++ docs/installation/image.rst | 112 ------ docs/installation/index.md | 30 ++ docs/installation/index.rst | 27 -- docs/installation/install.md | 466 ++++++++++++++++++++++ docs/installation/install.rst | 475 ---------------------- docs/installation/md-bare-metal.md | 626 ----------------------------- docs/installation/md-image.md | 113 ------ docs/installation/md-index.md | 30 -- docs/installation/md-install.md | 466 ---------------------- docs/installation/md-secure-boot.md | 194 --------- docs/installation/md-update.md | 105 ----- docs/installation/rst-bare-metal.rst | 633 ++++++++++++++++++++++++++++++ docs/installation/rst-image.rst | 112 ++++++ docs/installation/rst-index.rst | 27 ++ docs/installation/rst-install.rst | 475 ++++++++++++++++++++++ docs/installation/rst-secure-boot.rst | 192 +++++++++ docs/installation/rst-update.rst | 97 +++++ docs/installation/secure-boot.md | 194 +++++++++ docs/installation/secure-boot.rst | 192 --------- docs/installation/update.md | 105 +++++ docs/installation/update.rst | 97 ----- docs/installation/virtual/docker.md | 72 ++++ docs/installation/virtual/docker.rst | 75 ---- docs/installation/virtual/eve-ng.md | 14 + docs/installation/virtual/eve-ng.rst | 14 - docs/installation/virtual/gns3.md | 191 +++++++++ docs/installation/virtual/gns3.rst | 177 --------- docs/installation/virtual/index.md | 16 + docs/installation/virtual/index.rst | 15 - docs/installation/virtual/libvirt.md | 186 +++++++++ docs/installation/virtual/libvirt.rst | 186 --------- docs/installation/virtual/md-docker.md | 72 ---- docs/installation/virtual/md-eve-ng.md | 14 - docs/installation/virtual/md-gns3.md | 191 --------- docs/installation/virtual/md-index.md | 16 - docs/installation/virtual/md-libvirt.md | 186 --------- docs/installation/virtual/md-proxmox.md | 80 ---- docs/installation/virtual/md-vmware.md | 38 -- docs/installation/virtual/proxmox.md | 80 ++++ docs/installation/virtual/proxmox.rst | 91 ----- docs/installation/virtual/rst-docker.rst | 75 ++++ docs/installation/virtual/rst-eve-ng.rst | 14 + docs/installation/virtual/rst-gns3.rst | 177 +++++++++ docs/installation/virtual/rst-index.rst | 15 + docs/installation/virtual/rst-libvirt.rst | 186 +++++++++ docs/installation/virtual/rst-proxmox.rst | 91 +++++ docs/installation/virtual/rst-vmware.rst | 41 ++ docs/installation/virtual/vmware.md | 38 ++ docs/installation/virtual/vmware.rst | 41 -- 72 files changed, 4976 insertions(+), 4976 deletions(-) create mode 100644 docs/installation/bare-metal.md delete mode 100644 docs/installation/bare-metal.rst create mode 100644 docs/installation/cloud/aws.md delete mode 100644 docs/installation/cloud/aws.rst create mode 100644 docs/installation/cloud/azure.md delete mode 100644 docs/installation/cloud/azure.rst create mode 100644 docs/installation/cloud/gcp.md delete mode 100644 docs/installation/cloud/gcp.rst create mode 100644 docs/installation/cloud/index.md delete mode 100644 docs/installation/cloud/index.rst delete mode 100644 docs/installation/cloud/md-aws.md delete mode 100644 docs/installation/cloud/md-azure.md delete mode 100644 docs/installation/cloud/md-gcp.md delete mode 100644 docs/installation/cloud/md-index.md delete mode 100644 docs/installation/cloud/md-oracle.md create mode 100644 docs/installation/cloud/oracle.md delete mode 100644 docs/installation/cloud/oracle.rst create mode 100644 docs/installation/cloud/rst-aws.rst create mode 100644 docs/installation/cloud/rst-azure.rst create mode 100644 docs/installation/cloud/rst-gcp.rst create mode 100644 docs/installation/cloud/rst-index.rst create mode 100644 docs/installation/cloud/rst-oracle.rst create mode 100644 docs/installation/image.md delete mode 100644 docs/installation/image.rst create mode 100644 docs/installation/index.md delete mode 100644 docs/installation/index.rst create mode 100644 docs/installation/install.md delete mode 100644 docs/installation/install.rst delete mode 100644 docs/installation/md-bare-metal.md delete mode 100644 docs/installation/md-image.md delete mode 100644 docs/installation/md-index.md delete mode 100644 docs/installation/md-install.md delete mode 100644 docs/installation/md-secure-boot.md delete mode 100644 docs/installation/md-update.md create mode 100644 docs/installation/rst-bare-metal.rst create mode 100644 docs/installation/rst-image.rst create mode 100644 docs/installation/rst-index.rst create mode 100644 docs/installation/rst-install.rst create mode 100644 docs/installation/rst-secure-boot.rst create mode 100644 docs/installation/rst-update.rst create mode 100644 docs/installation/secure-boot.md delete mode 100644 docs/installation/secure-boot.rst create mode 100644 docs/installation/update.md delete mode 100644 docs/installation/update.rst create mode 100644 docs/installation/virtual/docker.md delete mode 100644 docs/installation/virtual/docker.rst create mode 100644 docs/installation/virtual/eve-ng.md delete mode 100644 docs/installation/virtual/eve-ng.rst create mode 100644 docs/installation/virtual/gns3.md delete mode 100644 docs/installation/virtual/gns3.rst create mode 100644 docs/installation/virtual/index.md delete mode 100644 docs/installation/virtual/index.rst create mode 100644 docs/installation/virtual/libvirt.md delete mode 100644 docs/installation/virtual/libvirt.rst delete mode 100644 docs/installation/virtual/md-docker.md delete mode 100644 docs/installation/virtual/md-eve-ng.md delete mode 100644 docs/installation/virtual/md-gns3.md delete mode 100644 docs/installation/virtual/md-index.md delete mode 100644 docs/installation/virtual/md-libvirt.md delete mode 100644 docs/installation/virtual/md-proxmox.md delete mode 100644 docs/installation/virtual/md-vmware.md create mode 100644 docs/installation/virtual/proxmox.md delete mode 100644 docs/installation/virtual/proxmox.rst create mode 100644 docs/installation/virtual/rst-docker.rst create mode 100644 docs/installation/virtual/rst-eve-ng.rst create mode 100644 docs/installation/virtual/rst-gns3.rst create mode 100644 docs/installation/virtual/rst-index.rst create mode 100644 docs/installation/virtual/rst-libvirt.rst create mode 100644 docs/installation/virtual/rst-proxmox.rst create mode 100644 docs/installation/virtual/rst-vmware.rst create mode 100644 docs/installation/virtual/vmware.md delete mode 100644 docs/installation/virtual/vmware.rst (limited to 'docs/installation') diff --git a/docs/installation/bare-metal.md b/docs/installation/bare-metal.md new file mode 100644 index 00000000..27525ae4 --- /dev/null +++ b/docs/installation/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 passively 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 around 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/bare-metal.rst b/docs/installation/bare-metal.rst deleted file mode 100644 index 5b6f24a4..00000000 --- a/docs/installation/bare-metal.rst +++ /dev/null @@ -1,633 +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 `_ so far on this -motherboard). - -Pictures --------- - -.. figure:: /_static/images/1u_vyos_back.* - :scale: 25 % - :alt: CSE-505-203B Back - -.. figure:: /_static/images/1u_vyos_front.* - :scale: 25 % - :alt: CSE-505-203B Front - -.. figure:: /_static/images/1u_vyos_front_open_1.* - :scale: 25 % - :alt: CSE-505-203B Open 1 - -.. figure:: /_static/images/1u_vyos_front_open_2.* - :scale: 25 % - :alt: CSE-505-203B Open 2 - -.. figure:: /_static/images/1u_vyos_front_open_3.* - :scale: 25 % - :alt: CSE-505-203B Open 3 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_1.* - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 1 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_2.* - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 2 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_3.* - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 3 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_4.* - :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.* - :scale: 25 % - :alt: APU4 rack closed - -.. figure:: /_static/images/apu4_rack_2.* - :scale: 25 % - :alt: APU4 rack front - -.. figure:: /_static/images/apu4_rack_3.* - :scale: 25 % - :alt: APU4 rack module #1 - -.. figure:: /_static/images/apu4_rack_4.* - :scale: 25 % - :alt: APU4 rack module #2 - -.. figure:: /_static/images/apu4_rack_5.* - :scale: 25 % - :alt: APU4 rack module #3 with PSU - -VyOS custom print -""""""""""""""""" - -.. figure:: /_static/images/apu4_rack_vyos_print.* - :scale: 25 % - :alt: APU4 custom VyOS powder coat - -Desktop / Bench Top -^^^^^^^^^^^^^^^^^^^ - -.. figure:: /_static/images/apu4_desk_1.* - :scale: 25 % - :alt: APU4 desktop closed - -.. figure:: /_static/images/apu4_desk_2.* - :scale: 25 % - :alt: APU4 desktop closed - -.. figure:: /_static/images/apu4_desk_3.* - :scale: 25 % - :alt: APU4 desktop back - -.. figure:: /_static/images/apu4_desk_4.* - :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.* - -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 `_. - -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.* - -.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Back.* - -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.* - -.. figure:: ../_static/images/gowin-02.* - -.. figure:: ../_static/images/gowin-03.* - -.. figure:: ../_static/images/gowin-04.* - -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/cloud/aws.md b/docs/installation/cloud/aws.md new file mode 100644 index 00000000..de5da3aa --- /dev/null +++ b/docs/installation/cloud/aws.md @@ -0,0 +1,188 @@ +--- +lastproofread: '2026-02-06' +--- + +# Amazon AWS + +## Deploy VM + +Deploy VyOS on Amazon {abbr}`AWS (Amazon Web Services)`. + +1. Click **Instances** and then click **Launch Instance**. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-01.webp +``` + +2. Search for "VyOS" in the Marketplace. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-02.webp +``` + +3. Choose the instance type. The recommended minimum is `m3.medium`. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-03.webp +``` + +4. Configure the instance for your requirements. Select the number of + instances, network, and subnet. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-04.webp +``` + +5. Configure additional storage. You can remove the additional storage + `/dev/sdb`. The root device will be `/dev/xvda`. You can skip this step. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-05.webp +``` + +6. Configure the security group. We recommend configuring SSH access + only from specific sources, or you can permit any IP address (the default). + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-06.webp +``` + +7. Select the SSH key pair and click **Launch Instances**. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-07.webp +``` + +8. Note your public IP address. + +```{eval-rst} +.. figure:: /_static/images/cloud-aws-08.webp +``` + +9. Connect to the instance using your SSH key. + +```{eval-rst} + + .. code-block:: none + + ssh -i ~/.ssh/amazon.pem vyos@203.0.113.3 + vyos@ip-192-0-2-10:~$ +``` + + +## Amazon CloudWatch Agent Usage + +To use the Amazon CloudWatch agent, configure it in the Amazon Systems Manager +Parameter Store. For instructions on creating a configuration, see +{ref}`configuration_creation`. + +1. Create an {abbr}`IAM (Identity and Access Management)` role for the + {abbr}`EC2 (Elastic Compute Cloud)` instance to access CloudWatch service, + and name it CloudWatchAgentServerRole. The role should contain two default + policies: `CloudWatchAgentServerPolicy` and + `AmazonSSMManagedInstanceCore`. +2. Attach the created role to your VyOS {abbr}`EC2 (Elastic Compute Cloud)` + instance. +3. Ensure the amazon-cloudwatch-agent package is installed. + +```{eval-rst} + + .. code-block:: none + + $ sudo apt list --installed | grep amazon-cloudwatch-agent + + .. note:: The amazon-cloudwatch-agent package is normally included in + VyOS 1.3.3+ and 1.4+ +``` + +4. Retrieve an existing CloudWatch Agent configuration from the + {abbr}`SSM (Systems Manager)` Parameter Store. + +```{eval-rst} + + .. code-block:: none + + $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c ssm: + + This step also enables systemd service and runs it. + + .. note:: The VyOS platform-specific scripts feature is under development. + Thus, this step should be repeated manually after changing system image + (:doc:`/installation/update`) +``` + +(configuration_creation)= + +### CloudWatch SSM Configuration creation + +Creating the Amazon Cloudwatch Agent Configuration in Amazon +{abbr}`SSM (Systems Manager)` Parameter Store. + +1. Create an {abbr}`IAM (Identity and Access Management)` role for your + {abbr}`EC2 (Elastic Compute Cloud)` instance to access the CloudWatch + service. Name it `CloudWatchAgentAdminRole`. The role must contain at + least two policies: `CloudWatchAgentAdminPolicy` and + `AmazonSSMManagedInstanceCore`. + +```{eval-rst} + + .. note:: CloudWatchAgentServerRole is too permissive and should be used only + for + creating and deploying a single configuration. After step 3, we recommend + replacing the ``CloudWatchAgentAdminRole`` with the + ``CloudWatchAgentServerRole``. +``` + +2. Run the CloudWatch configuration wizard. + +```{eval-rst} + + .. code-block:: none + + $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard +``` + +3. When prompted, enter "yes" to the question "Do you want to store the + config in the SSM parameter store?". + +## AWS Gateway Load Balancer + +VyOS supports the AWS Gateway Load Balancer (GWLB) tunnel handler (`gwlbtun`), +which enables VyOS to act as an inspection or processing target for GWLB. GWLB +uses Geneve encapsulation with custom metadata to deliver traffic to VyOS for +packet filtering, shaping, deep packet inspection, NAT, or other traffic +manipulation functions. The tunnel handler automatically creates Linux tunnel +interfaces (`gwi-*` for ingress and `gwo-*` for egress) per endpoint, +allowing you to use standard Linux utilities like iptables, tc, and netfilter +to implement your inspection or processing logic. This enables VyOS to serve as +a centralized appliance for traffic inspection in your AWS infrastructure, +supporting both single-endpoint (1-arm) and multi-endpoint (2-arm) deployment +modes. + +For more information about integrating with AWS Gateway Load Balancer, see +the following article from AWS: +[How to integrate Linux instances with AWS Gateway Load Balancer](https://aws.amazon.com/blogs/networking-and-content-delivery/how-to-integrate-linux-instances-with-aws-gateway-load-balancer/). + +### Configuration Example + +Configure the AWS GWLB service with the following commands: + +```none +set service aws glb script on-create '/config/scripts/glb-create.sh' +set service aws glb script on-destroy '/config/scripts/glb-destroy.sh' +set service aws glb status format 'simple' +set service aws glb status port '8282' +set service aws glb threads tunnel '4' +set service aws glb threads tunnel-affinity '1-2' +set service aws glb threads udp '4' +set service aws glb threads udp-affinity '0-3' +``` + + +## References + +- +- +- +- + diff --git a/docs/installation/cloud/aws.rst b/docs/installation/cloud/aws.rst deleted file mode 100644 index 89f4a152..00000000 --- a/docs/installation/cloud/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.* - -2. Search for "VyOS" in the Marketplace. - -.. figure:: /_static/images/cloud-aws-02.* - -3. Choose the instance type. The recommended minimum is ``m3.medium``. - -.. figure:: /_static/images/cloud-aws-03.* - -4. Configure the instance for your requirements. Select the number of - instances, network, and subnet. - -.. figure:: /_static/images/cloud-aws-04.* - -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.* - -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.* - -7. Select the SSH key pair and click **Launch Instances**. - -.. figure:: /_static/images/cloud-aws-07.* - -8. Note your public IP address. - -.. figure:: /_static/images/cloud-aws-08.* - -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: - - 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 `__. - -.. 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/azure.md b/docs/installation/cloud/azure.md new file mode 100644 index 00000000..24b7b166 --- /dev/null +++ b/docs/installation/cloud/azure.md @@ -0,0 +1,98 @@ +--- +lastproofread: '2026-02-09' +--- + +# Azure + +## Deploy VM + +Deploy VyOS on Azure. + +1. Go to Azure services and click **Add new Virtual machine**. +2. Choose a VM name, resource group, and region, then click **Browse all public + and private images**. + +```{eval-rst} +.. figure:: /_static/images/cloud-azure-01.webp +``` + +3. Search for "VyOS" in the marketplace and choose the appropriate + subscription. + +```{eval-rst} +.. figure:: /_static/images/cloud-azure-02.webp +``` + +4. Generate new SSH key pair or use existing. + +```{eval-rst} +.. figure:: /_static/images/cloud-azure-03.webp +``` + +5. Configure the network, subnet, and public IP. Or use the defaults. + +```{eval-rst} +.. figure:: /_static/images/cloud-azure-04.webp +``` + +6. Click **Review + create**. Your deployment completes in a few seconds. + +```{eval-rst} +.. figure:: /_static/images/cloud-azure-05.webp +``` + +7. Select your new VM and note your public IP address. + +```{eval-rst} +.. figure:: /_static/images/cloud-azure-06.webp +``` + +8. Connect to the instance with your SSH key. + +```{eval-rst} + + .. code-block:: none + + ssh -i ~/.ssh/vyos_azure vyos@203.0.113.3 + vyos@vyos-doc-r1:~$ +``` + + +## Add interface + +If your instance was deployed with one **eth0** (`WAN`) interface and you +want to add another, you must shut down the instance. To add a new interface, +such as **eth1** (`LAN`), attach it in the Azure portal and then restart the +instance. + +:::{note} +Azure doesn't allow you to attach an interface while the instance is +running. +::: + +## Absorbing Routes + +If you're using the VM as a router, you can use a route table to absorb some or +all traffic from your virtual network (VNET) with your LAN interface. + +1. Create a route table and navigate to **Configuration**. +2. Add one or more routes for the networks you want to route through the VyOS + VM. For **Next hop type**, select **Virtual Appliance** and set the **Next + Hop Address** to the VyOS `LAN` interface. + +:::{note} +To create a default route for VMs on the subnet, use +**Address Prefix** `0.0.0.0/0`. For a typical edge device configuration, +configure masquerade NAT on the `WAN` interface. +::: + +## Serial Console + +VyOS includes serial console support by default. However, if you replace the +`config.boot` file and reboot, ensure this configuration is present: + +`set system console device ttyS0 speed '9600'` + +## References + + diff --git a/docs/installation/cloud/azure.rst b/docs/installation/cloud/azure.rst deleted file mode 100644 index f77c9bee..00000000 --- a/docs/installation/cloud/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.* - -3. Search for "VyOS" in the marketplace and choose the appropriate - subscription. - -.. figure:: /_static/images/cloud-azure-02.* - -4. Generate new SSH key pair or use existing. - -.. figure:: /_static/images/cloud-azure-03.* - -5. Configure the network, subnet, and public IP. Or use the defaults. - -.. figure:: /_static/images/cloud-azure-04.* - -6. Click **Review + create**. Your deployment completes in a few seconds. - -.. figure:: /_static/images/cloud-azure-05.* - -7. Select your new VM and note your public IP address. - -.. figure:: /_static/images/cloud-azure-06.* - -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/gcp.md b/docs/installation/cloud/gcp.md new file mode 100644 index 00000000..828312cd --- /dev/null +++ b/docs/installation/cloud/gcp.md @@ -0,0 +1,61 @@ +--- +lastproofread: '2026-02-09' +--- + +# Google Cloud Platform + +## Deploy VM + +To deploy VyOS on Google Cloud Platform (GCP): + +1. Generate an SSH key pair of type **ssh-rsa** on the host that will connect + to VyOS. + + Example: + + ```none + ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" + ``` + +:::{note} +The SSH key comment must begin with `vyos@` because that's the +default VyOS user. GCP uses this value to set the username on the instance. +::: + +2. Open the GCP Console and navigate to **Metadata**. Select **SSH Keys** and + click **Edit**. + +:::{figure} /_static/images/cloud-gcp-01.webp +Click **Add item**, paste your public SSH key, and click **Save**. +::: + +:::{figure} /_static/images/cloud-gcp-02.webp +::: + +3. Search for "VyOS" in the Marketplace. +4. Configure the deployment name, zone, and machine type, then click **Deploy**. + +:::{figure} /_static/images/cloud-gcp-03.webp +::: + +5. After a few seconds, select your **instance**. + +:::{figure} /_static/images/cloud-gcp-04.webp +::: + +6. Note your external IP address. + +:::{figure} /_static/images/cloud-gcp-05.webp +::: + +7. Connect to the instance using the SSH key you generated in step 1. + +```none +ssh -i ~/.ssh/vyos_gcp vyos@203.0.113.3 +vyos@vyos-r1-vm:~$ +``` + + +## References + + diff --git a/docs/installation/cloud/gcp.rst b/docs/installation/cloud/gcp.rst deleted file mode 100644 index 7d70e007..00000000 --- a/docs/installation/cloud/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.* - - - Click **Add item**, paste your public SSH key, and click **Save**. - -.. figure:: /_static/images/cloud-gcp-02.* - - -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.* - -5. After a few seconds, select your **instance**. - -.. figure:: /_static/images/cloud-gcp-04.* - -6. Note your external IP address. - -.. figure:: /_static/images/cloud-gcp-05.* - -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/index.md b/docs/installation/cloud/index.md new file mode 100644 index 00000000..cf7d447d --- /dev/null +++ b/docs/installation/cloud/index.md @@ -0,0 +1,10 @@ +# Cloud Environments + +```{toctree} +:caption: Content + +aws +azure +gcp +oracle +``` diff --git a/docs/installation/cloud/index.rst b/docs/installation/cloud/index.rst deleted file mode 100644 index 18d525ac..00000000 --- a/docs/installation/cloud/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -################## -Cloud Environments -################## - -.. toctree:: - :caption: Content - - aws - azure - gcp - oracle diff --git a/docs/installation/cloud/md-aws.md b/docs/installation/cloud/md-aws.md deleted file mode 100644 index de5da3aa..00000000 --- a/docs/installation/cloud/md-aws.md +++ /dev/null @@ -1,188 +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**. - -```{eval-rst} -.. figure:: /_static/images/cloud-aws-01.webp -``` - -2. Search for "VyOS" in the Marketplace. - -```{eval-rst} -.. figure:: /_static/images/cloud-aws-02.webp -``` - -3. Choose the instance type. The recommended minimum is `m3.medium`. - -```{eval-rst} -.. figure:: /_static/images/cloud-aws-03.webp -``` - -4. Configure the instance for your requirements. Select the number of - instances, network, and subnet. - -```{eval-rst} -.. figure:: /_static/images/cloud-aws-04.webp -``` - -5. Configure additional storage. You can remove the additional storage - `/dev/sdb`. The root device will be `/dev/xvda`. You can skip this step. - -```{eval-rst} -.. figure:: /_static/images/cloud-aws-05.webp -``` - -6. Configure the security group. We recommend configuring SSH access - only from specific sources, or you can permit any IP address (the default). - -```{eval-rst} -.. figure:: /_static/images/cloud-aws-06.webp -``` - -7. Select the SSH key pair and click **Launch Instances**. - -```{eval-rst} -.. figure:: /_static/images/cloud-aws-07.webp -``` - -8. Note your public IP address. - -```{eval-rst} -.. figure:: /_static/images/cloud-aws-08.webp -``` - -9. Connect to the instance using your SSH key. - -```{eval-rst} - - .. code-block:: none - - ssh -i ~/.ssh/amazon.pem vyos@203.0.113.3 - vyos@ip-192-0-2-10:~$ -``` - - -## Amazon CloudWatch Agent Usage - -To use the Amazon CloudWatch agent, configure it in the Amazon Systems Manager -Parameter Store. For instructions on creating a configuration, see -{ref}`configuration_creation`. - -1. Create an {abbr}`IAM (Identity and Access Management)` role for the - {abbr}`EC2 (Elastic Compute Cloud)` instance to access CloudWatch service, - and name it CloudWatchAgentServerRole. The role should contain two default - policies: `CloudWatchAgentServerPolicy` and - `AmazonSSMManagedInstanceCore`. -2. Attach the created role to your VyOS {abbr}`EC2 (Elastic Compute Cloud)` - instance. -3. Ensure the amazon-cloudwatch-agent package is installed. - -```{eval-rst} - - .. code-block:: none - - $ sudo apt list --installed | grep amazon-cloudwatch-agent - - .. note:: The amazon-cloudwatch-agent package is normally included in - VyOS 1.3.3+ and 1.4+ -``` - -4. Retrieve an existing CloudWatch Agent configuration from the - {abbr}`SSM (Systems Manager)` Parameter Store. - -```{eval-rst} - - .. code-block:: none - - $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c ssm: - - This step also enables systemd service and runs it. - - .. note:: The VyOS platform-specific scripts feature is under development. - Thus, this step should be repeated manually after changing system image - (:doc:`/installation/update`) -``` - -(configuration_creation)= - -### CloudWatch SSM Configuration creation - -Creating the Amazon Cloudwatch Agent Configuration in Amazon -{abbr}`SSM (Systems Manager)` Parameter Store. - -1. Create an {abbr}`IAM (Identity and Access Management)` role for your - {abbr}`EC2 (Elastic Compute Cloud)` instance to access the CloudWatch - service. Name it `CloudWatchAgentAdminRole`. The role must contain at - least two policies: `CloudWatchAgentAdminPolicy` and - `AmazonSSMManagedInstanceCore`. - -```{eval-rst} - - .. note:: CloudWatchAgentServerRole is too permissive and should be used only - for - creating and deploying a single configuration. After step 3, we recommend - replacing the ``CloudWatchAgentAdminRole`` with the - ``CloudWatchAgentServerRole``. -``` - -2. Run the CloudWatch configuration wizard. - -```{eval-rst} - - .. code-block:: none - - $ sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-config-wizard -``` - -3. When prompted, enter "yes" to the question "Do you want to store the - config in the SSM parameter store?". - -## AWS Gateway Load Balancer - -VyOS supports the AWS Gateway Load Balancer (GWLB) tunnel handler (`gwlbtun`), -which enables VyOS to act as an inspection or processing target for GWLB. GWLB -uses Geneve encapsulation with custom metadata to deliver traffic to VyOS for -packet filtering, shaping, deep packet inspection, NAT, or other traffic -manipulation functions. The tunnel handler automatically creates Linux tunnel -interfaces (`gwi-*` for ingress and `gwo-*` for egress) per endpoint, -allowing you to use standard Linux utilities like iptables, tc, and netfilter -to implement your inspection or processing logic. This enables VyOS to serve as -a centralized appliance for traffic inspection in your AWS infrastructure, -supporting both single-endpoint (1-arm) and multi-endpoint (2-arm) deployment -modes. - -For more information about integrating with AWS Gateway Load Balancer, see -the following article from AWS: -[How to integrate Linux instances with AWS Gateway Load Balancer](https://aws.amazon.com/blogs/networking-and-content-delivery/how-to-integrate-linux-instances-with-aws-gateway-load-balancer/). - -### Configuration Example - -Configure the AWS GWLB service with the following commands: - -```none -set service aws glb script on-create '/config/scripts/glb-create.sh' -set service aws glb script on-destroy '/config/scripts/glb-destroy.sh' -set service aws glb status format 'simple' -set service aws glb status port '8282' -set service aws glb threads tunnel '4' -set service aws glb threads tunnel-affinity '1-2' -set service aws glb threads udp '4' -set service aws glb threads udp-affinity '0-3' -``` - - -## References - -- -- -- -- - diff --git a/docs/installation/cloud/md-azure.md b/docs/installation/cloud/md-azure.md deleted file mode 100644 index 24b7b166..00000000 --- a/docs/installation/cloud/md-azure.md +++ /dev/null @@ -1,98 +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**. - -```{eval-rst} -.. figure:: /_static/images/cloud-azure-01.webp -``` - -3. Search for "VyOS" in the marketplace and choose the appropriate - subscription. - -```{eval-rst} -.. figure:: /_static/images/cloud-azure-02.webp -``` - -4. Generate new SSH key pair or use existing. - -```{eval-rst} -.. figure:: /_static/images/cloud-azure-03.webp -``` - -5. Configure the network, subnet, and public IP. Or use the defaults. - -```{eval-rst} -.. figure:: /_static/images/cloud-azure-04.webp -``` - -6. Click **Review + create**. Your deployment completes in a few seconds. - -```{eval-rst} -.. figure:: /_static/images/cloud-azure-05.webp -``` - -7. Select your new VM and note your public IP address. - -```{eval-rst} -.. figure:: /_static/images/cloud-azure-06.webp -``` - -8. Connect to the instance with your SSH key. - -```{eval-rst} - - .. code-block:: none - - ssh -i ~/.ssh/vyos_azure vyos@203.0.113.3 - vyos@vyos-doc-r1:~$ -``` - - -## Add interface - -If your instance was deployed with one **eth0** (`WAN`) interface and you -want to add another, you must shut down the instance. To add a new interface, -such as **eth1** (`LAN`), attach it in the Azure portal and then restart the -instance. - -:::{note} -Azure doesn't allow you to attach an interface while the instance is -running. -::: - -## Absorbing Routes - -If you're using the VM as a router, you can use a route table to absorb some or -all traffic from your virtual network (VNET) with your LAN interface. - -1. Create a route table and navigate to **Configuration**. -2. Add one or more routes for the networks you want to route through the VyOS - VM. For **Next hop type**, select **Virtual Appliance** and set the **Next - Hop Address** to the VyOS `LAN` interface. - -:::{note} -To create a default route for VMs on the subnet, use -**Address Prefix** `0.0.0.0/0`. For a typical edge device configuration, -configure masquerade NAT on the `WAN` interface. -::: - -## Serial Console - -VyOS includes serial console support by default. However, if you replace the -`config.boot` file and reboot, ensure this configuration is present: - -`set system console device ttyS0 speed '9600'` - -## References - - diff --git a/docs/installation/cloud/md-gcp.md b/docs/installation/cloud/md-gcp.md deleted file mode 100644 index 828312cd..00000000 --- a/docs/installation/cloud/md-gcp.md +++ /dev/null @@ -1,61 +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: - - ```none - ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" - ``` - -:::{note} -The SSH key comment must begin with `vyos@` because that's the -default VyOS user. GCP uses this value to set the username on the instance. -::: - -2. Open the GCP Console and navigate to **Metadata**. Select **SSH Keys** and - click **Edit**. - -:::{figure} /_static/images/cloud-gcp-01.webp -Click **Add item**, paste your public SSH key, and click **Save**. -::: - -:::{figure} /_static/images/cloud-gcp-02.webp -::: - -3. Search for "VyOS" in the Marketplace. -4. Configure the deployment name, zone, and machine type, then click **Deploy**. - -:::{figure} /_static/images/cloud-gcp-03.webp -::: - -5. After a few seconds, select your **instance**. - -:::{figure} /_static/images/cloud-gcp-04.webp -::: - -6. Note your external IP address. - -:::{figure} /_static/images/cloud-gcp-05.webp -::: - -7. Connect to the instance using the SSH key you generated in step 1. - -```none -ssh -i ~/.ssh/vyos_gcp vyos@203.0.113.3 -vyos@vyos-r1-vm:~$ -``` - - -## References - - diff --git a/docs/installation/cloud/md-index.md b/docs/installation/cloud/md-index.md deleted file mode 100644 index cf7d447d..00000000 --- a/docs/installation/cloud/md-index.md +++ /dev/null @@ -1,10 +0,0 @@ -# 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 deleted file mode 100644 index f8cee52c..00000000 --- a/docs/installation/cloud/md-oracle.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -lastproofread: '2026-02-09' ---- - -# Oracle - -:::{note} -This page is a stub and needs expansion. Contributions -welcome via the [VyOS documentation repository](https://github.com/vyos/vyos-documentation). -::: - -## References - - - - - diff --git a/docs/installation/cloud/oracle.md b/docs/installation/cloud/oracle.md new file mode 100644 index 00000000..f8cee52c --- /dev/null +++ b/docs/installation/cloud/oracle.md @@ -0,0 +1,17 @@ +--- +lastproofread: '2026-02-09' +--- + +# Oracle + +:::{note} +This page is a stub and needs expansion. Contributions +welcome via the [VyOS documentation repository](https://github.com/vyos/vyos-documentation). +::: + +## References + + + + + diff --git a/docs/installation/cloud/oracle.rst b/docs/installation/cloud/oracle.rst deleted file mode 100644 index d71d8039..00000000 --- a/docs/installation/cloud/oracle.rst +++ /dev/null @@ -1,16 +0,0 @@ -:lastproofread: 2026-02-09 - -###### -Oracle -###### - -.. note:: This page is a stub and needs expansion. Contributions - welcome via the `VyOS documentation repository - `_. - -.. 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/cloud/rst-aws.rst b/docs/installation/cloud/rst-aws.rst new file mode 100644 index 00000000..89f4a152 --- /dev/null +++ b/docs/installation/cloud/rst-aws.rst @@ -0,0 +1,166 @@ +: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.* + +2. Search for "VyOS" in the Marketplace. + +.. figure:: /_static/images/cloud-aws-02.* + +3. Choose the instance type. The recommended minimum is ``m3.medium``. + +.. figure:: /_static/images/cloud-aws-03.* + +4. Configure the instance for your requirements. Select the number of + instances, network, and subnet. + +.. figure:: /_static/images/cloud-aws-04.* + +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.* + +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.* + +7. Select the SSH key pair and click **Launch Instances**. + +.. figure:: /_static/images/cloud-aws-07.* + +8. Note your public IP address. + +.. figure:: /_static/images/cloud-aws-08.* + +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: + + 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 `__. + +.. 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 new file mode 100644 index 00000000..f77c9bee --- /dev/null +++ b/docs/installation/cloud/rst-azure.rst @@ -0,0 +1,84 @@ +: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.* + +3. Search for "VyOS" in the marketplace and choose the appropriate + subscription. + +.. figure:: /_static/images/cloud-azure-02.* + +4. Generate new SSH key pair or use existing. + +.. figure:: /_static/images/cloud-azure-03.* + +5. Configure the network, subnet, and public IP. Or use the defaults. + +.. figure:: /_static/images/cloud-azure-04.* + +6. Click **Review + create**. Your deployment completes in a few seconds. + +.. figure:: /_static/images/cloud-azure-05.* + +7. Select your new VM and note your public IP address. + +.. figure:: /_static/images/cloud-azure-06.* + +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 new file mode 100644 index 00000000..7d70e007 --- /dev/null +++ b/docs/installation/cloud/rst-gcp.rst @@ -0,0 +1,59 @@ +: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.* + + + Click **Add item**, paste your public SSH key, and click **Save**. + +.. figure:: /_static/images/cloud-gcp-02.* + + +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.* + +5. After a few seconds, select your **instance**. + +.. figure:: /_static/images/cloud-gcp-04.* + +6. Note your external IP address. + +.. figure:: /_static/images/cloud-gcp-05.* + +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 new file mode 100644 index 00000000..18d525ac --- /dev/null +++ b/docs/installation/cloud/rst-index.rst @@ -0,0 +1,11 @@ +################## +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 new file mode 100644 index 00000000..d71d8039 --- /dev/null +++ b/docs/installation/cloud/rst-oracle.rst @@ -0,0 +1,16 @@ +:lastproofread: 2026-02-09 + +###### +Oracle +###### + +.. note:: This page is a stub and needs expansion. Contributions + welcome via the `VyOS documentation repository + `_. + +.. 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/image.md b/docs/installation/image.md new file mode 100644 index 00000000..a0fc89d4 --- /dev/null +++ b/docs/installation/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/image.rst b/docs/installation/image.rst deleted file mode 100644 index 5b473e78..00000000 --- a/docs/installation/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/index.md b/docs/installation/index.md new file mode 100644 index 00000000..4256aa9b --- /dev/null +++ b/docs/installation/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/index.rst b/docs/installation/index.rst deleted file mode 100644 index 5ba89755..00000000 --- a/docs/installation/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/install.md b/docs/installation/install.md new file mode 100644 index 00000000..532bdc0c --- /dev/null +++ b/docs/installation/install.md @@ -0,0 +1,466 @@ +--- +lastproofread: '2026-01-26' +--- + +(installation)= + +# Installation + +VyOS installation requires a VyOS .iso file. This file is a live installation +image that you can use to boot a live VyOS system. From there, you can proceed +with a permanent installation on a hard drive or other storage device. + +:::{list-table} Comparison of VyOS image releases +:header-rows: 1 +:widths: 15 35 15 25 15 15 + +* - Release Type + - Description + - Release Cycle + - Intended Use + - Access to Images + - Access to Source + +* - Nightly (Current) + - Automatically built from the current branch. Always up to date + with cutting edge development but guaranteed to contain bugs. + - Every night + - Developing VyOS, testing new features, experimenting. + - Everyone + - Everyone + +* - Stream + - VyOS Stream serves as a technology preview and a quality gate + for the upcoming LTS release. Allows everyone to try new features + and check if they work well or need improvements. + - Every quarter + - Non-critical production environments, preparing for the LTS + release. + - Everyone + - Everyone + +* - Release Candidate + - Rather stable. All development focuses on testing and hunting + down remaining bugs following the feature freeze. + - Irregularly until EPA comes out + - Labs, small offices and non-critical production systems backed + by a high-availability setup. + - Everyone + - Everyone + +* - Early Production Access + - Highly stable with no known bugs. Needs to be tested repeatedly + under different conditions before it can become the final + release. + - Irregularly until LTS comes out + - Non-critical production environments, preparing for the LTS + release. + - Everyone + - Everyone + +* - Long-Term Support + - Guaranteed to be stable and carefully maintained for several + years after the release. No features are introduced but security + updates are released in a timely manner. + - Every major version + - Large-scale enterprise networks, internet service providers, + critical production environments that call for minimum downtime. + - Subscribers, contributors, non-profits, emergency services, + academic institutions + - Subscribers, contributors, non-profits, emergency services, + academic institutions +::: + +## Hardware requirements + +The minimum system requirements for VyOS are 4 GB RAM and 10 GB storage. +Depending on your use case, you might need additional RAM and CPU resources. + +## Download + +### Registered Subscribers + +Registered subscribers can log into to access +a variety of different downloads via the "Downloads" link. These +downloads include LTS (Long-Term Support), the associated hot-fix releases, +early public access releases, pre-built VM images, as well as device +specific installation ISOs. See this [article] for more information on +downloads. + +:::{note} +The `.qcow2` image provided for Proxmox deployment can also be +used to deploy VyOS on KVM environments. This image includes cloud-init +support. See {ref}`cloud-init` for more information. +::: + +:::{figure} /_static/images/vyosnew-downloads.webp +::: + +### Building from source + +Subscribers can download the source code for the LTS release from the +"Downloads" link. Non-subscribers can access the source code for the +Rolling release. For instructions, see the {ref}`build` section. The +VyOS source code repository is available at +. + +### Rolling Release + +Everyone can download bleeding-edge VyOS rolling images from: + + +:::{note} +Rolling releases contain the latest enhancements and fixes. +This means there may be new bugs. If you encounter a bug, follow the +guide at {ref}`bug_report`. We depend on your feedback to improve VyOS. +::: + +The following link contains the most recent VyOS builds for AMD64 +systems from the `current` branch: + +### Download Verification + +LTS images are signed with the VyOS lead package maintainer's private key. +You can verify the authenticity of the package using the official public key +and Minisign. + +(minisign-verification)= + +#### Minisign verification + +VyOS uses [Minisign](https://github.com/jedisct1/minisign) for release +signing. Minisign is a tool for signing files and verifying signatures. + +OpenBSD introduced signify in 2015. Minisign is an alternative +implementation of the same protocol, available for Windows, macOS, and +most GNU/Linux distributions. Minisign is portable, lightweight, and +uses the Ed25519 public-key signature system. + +{vytask}`T2108` switched the validation system to prefer Minisign over GPG keys. + +To verify a VyOS image starting with VyOS `1.3.0-rc6`, run: + +```none +$ minisign -V -P RWSIhkR/dkM2DSaBRniv/bbbAf8hmDqdbOEmgXkf1RxRoxzodgKcDyGq -m vyos-1.5-rolling-202409250007-generic-amd64.iso vyos-1.5-rolling-202409250007-generic-amd64.iso.minisig + +Signature and comment signature verified +Trusted comment: timestamp:1727223408 file:vyos-1.5-rolling-202409250007-generic-amd64.iso hashed +``` + +During an image upgrade, VyOS runs the following command: + +```none +$ minisign -V -p /usr/share/vyos/keys/vyos-release.minisign.pub -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig +Signature and comment signature verified +Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso +``` + +:::{note} +Starting with version `1.4.3`, VyOS uses Minisign exclusively. +If you see an unexpected verification error, update your system to version +`1.4.2` first. Support for GnuPG signatures has been +removed ({vytask}`T7301`). +::: + +(live_installation)= + +## Live installation + +:::{note} +To permanently install VyOS, you must first complete a live +installation. +::: + +You can test VyOS without installing it on your hard drive. **Using your +downloaded VyOS .iso file, you can create a bootable USB drive to boot +into a fully functional VyOS system**. After testing it, you can start a +{ref}`permanent_installation` on your hard drive or power off your system +and remove the USB drive. + +```{eval-rst} +If you have a GNU/Linux system, you can create a bootable VyOS USB drive using +the ``dd`` command: + + 1. Open your terminal emulator. + + 2. Find the device name of your USB drive (use the ``lsblk`` command). + + 3. Unmount the USB drive. Replace ``X`` with your device letter and keep the + asterisk (*) to unmount all partitions. + + .. code-block:: none + + $ umount /dev/sdX* + + 1. Write the image (your VyOS .iso file) to the USB drive. Use the device + name (for example, ``/dev/sdb``), not the partition name + (for example, ``/dev/sdb1``). + + **Warning**: This will destroy all data on the USB drive! + + .. code-block:: none + + # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync + + 1. Wait for the operation to complete (bytes copied). On some systems, this + may take more than one minute. + + 2. Once ``dd`` has finished, pull the USB drive out and plug it into + the powered-off computer where you want to install (or test) VyOS. + + 3. Power on the computer and ensure it boots from the USB drive + (you may need to select the boot device or change boot settings). + + 4. When VyOS finishes loading, sign in using the default credentials + (login: ``vyos``, password: ``vyos``). +``` + +If you encounter issues with this method, prefer a different operating +system, or want a GUI program, you can use other tools to create a +bootable USB drive, such as [balenaEtcher] (GNU/Linux, macOS, and Windows), +[Rufus] (Windows), and [many others]. Follow their instructions to create +a bootable USB drive from an `.iso` file. + +:::{hint} +The default username and password for the live system is *vyos*. +::: + +(permanent_installation)= + +## Permanent installation + +:::{note} +Before a permanent installation, VyOS requires a +{ref}`live_installation`. +::: + +Unlike general-purpose Linux distributions, VyOS uses "image installation", +which mimics the user experience of traditional hardware routers and allows +you to keep multiple VyOS versions installed simultaneously. This lets you +switch to a previous version if something breaks or misbehaves after an +image upgrade. + +Each version is contained in its own squashfs image mounted in a union +filesystem along with a directory for mutable data such as configurations, +keys, and custom scripts. + +```{eval-rst} +In order to proceed with a permanent installation: + + 1. Sign in to the VyOS live system using the default credentials + (login: ``vyos``, password: ``vyos``). + + 2. Run the ``install image`` command and follow the wizard: + + .. code-block:: none + + vyos@vyos:~$ install image + Welcome to VyOS installation! + This command will install VyOS to your permanent storage. + Would you like to continue? [y/N] y + What would you like to name this image? (Default: 2025.09.17-0018-rolling) + Please enter a password for the "vyos" user: + Please confirm password for the "vyos" user: + What console should be used by default? (K: KVM, S: Serial)? (Default: S) + Probing disks + 1 disk(s) found + The following disks were found: + Drive: /dev/vda (10.0 GB) + Which one should be used for installation? (Default: /dev/vda) + Installation will delete all data on the drive. Continue? [y/N] y + Searching for data from previous installations + No previous installation found + Would you like to use all the free space on the drive? [Y/n] Y + Creating partition table... + The following config files are available for boot: + 1: /opt/vyatta/etc/config/config.boot + 2: /opt/vyatta/etc/config.boot.default + Which file would you like as boot config? (Default: 1) + Creating temporary directories + Mounting new partitions + Creating a configuration file + Copying system image files + Installing GRUB configuration files + Installing GRUB to the drive + Cleaning up + Unmounting target filesystems + Removing temporary files + The image installed successfully; please reboot now. + + + 3. After installation completes, remove the live USB drive or CD. + + 4. Reboot the system. + + .. code-block:: none + + vyos@vyos:~$ reboot + Proceed with reboot? (Yes/No) [No] Yes + + You will boot now into a permanent VyOS system. +``` + +## PXE Boot + +You can also install VyOS using PXE, a more complex installation method that +allows you to deploy VyOS over the network. + +**Requirements** + +- A machine (client) with a PXE-enabled NIC. +- {ref}`dhcp-server` +- {ref}`tftp-server` +- Webserver (HTTP). Optional, but speeds up installation. +- VyOS ISO image (do not use images prior to VyOS `1.2.3`). +- Files *pxelinux.0* and *ldlinux.c32* from the + [Syslinux distribution](https://kernel.org/pub/linux/utils/boot/syslinux/). + +### Configuration + +#### Step 1: DHCP + +Configure a DHCP server to provide the client with: + +- An IP address +- The TFTP server address (DHCP option 66), sometimes referred to as the + *boot server* +- The *bootfile name* (DHCP option 67): *pxelinux.0* + +In this example we configured an existent VyOS as the DHCP server: + +```none +vyos@vyos# show service dhcp-server + shared-network-name mydhcp { + subnet 192.168.1.0/24 { + option { + bootfile-name pxelinux.0 + bootfile-server 192.168.1.50 + default-router 192.168.1.50 + } + range 0 { + start 192.168.1.70 + stop 192.168.1.100 + } + subnet-id 1 + } + } +``` + +(install_from_tftp)= + +#### Step 2: TFTP + +Configure a TFTP server to serve the following: + +- The *pxelinux.0* file from the Syslinux distribution +- The *ldlinux.c32* file from the Syslinux distribution +- The VyOS kernel you want to deploy (*vmlinuz* file from the + */live* directory in the extracted ISO file) +- The VyOS initial ramdisk (*initrd.img* file from the */live* directory + in the extracted ISO file). Do not use an empty (0 bytes) initrd.img + file; the correct file may have a longer name. +- A directory named *pxelinux.cfg* containing the configuration file. + By default, the VyOS configuration file is named [default]. + +In the example you configured your existent VyOS as the TFTP server too: + +```none +vyos@vyos# show service tftp-server + directory /config/tftpboot + listen-address 192.168.1.50 +``` + +Example of the contents of the TFTP server: + +```none +vyos@vyos# ls -hal /config/tftpboot/ +total 29M +drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . +drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. +-r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos +-rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 +-rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 +drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg +-r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz + +vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg +total 12K +drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . +drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. +-rw-r--r-- 1 root root 191 Oct 14 01:10 default +``` + +Example of simple (no menu) configuration file: + +```none +vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default +DEFAULT VyOS123 + +LABEL VyOS123 + KERNEL vmlinuz + APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs +``` + + +#### Step 3: HTTP + +You also need to provide the *filesystem.squashfs* file. Because this is a +large file and TFTP is slow, you can send it through HTTP to speed up the +transfer. In our example, we do this—see the configuration file above. + +1. Start a web server. You can use one like + [Python's SimpleHTTPServer] to serve the `filesystem.squashfs` file. + The file is in the `/live` directory of the extracted ISO file. +2. Edit the {ref}`install_from_tftp` configuration file to show the correct + URL: `fetch=http:///filesystem.squashfs`. + +:::{note} +Do not rename the *filesystem.squashfs* file. If you're working with +different versions, create different directories instead. +::: + +3. restart the TFTP service. If you're using VyOS as your TFTP server, restart + the service with `sudo service tftpd-hpa restart`. + +:::{note} +Ensure the directories and files on both the TFTP and HTTP servers +have the correct permissions for the booting clients to access them. +::: + +### Client Boot + +Finally, power on your PXE-enabled clients. They will automatically receive an +IP address from the DHCP server and boot into VyOS live using files from the +TFTP and HTTP servers. + +Once finished you will be able to proceed with the `install image` +command as in a regular VyOS installation. + +## Known Issues + +This is a list of known issues that can arise during installation. + +### Black screen on install + +GRUB redirects all output to a serial port to facilitate installation +on headless hosts. On some hardware that lacks a serial port, this causes +a hard lockup and displays a black screen after you select the +`Live system` option from the installation image. + +The workaround is to press `e` when the boot menu appears and edit the +GRUB boot options. Specifically, remove the: + +`console=ttyS0,115200` + +option, and type CTRL-X to boot. + +Installation can then continue as outlined above. + +[article]: https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913 +[balenaetcher]: https://www.balena.io/etcher/ +[configuration]: https://wiki.syslinux.org/wiki/index.php?title=Config +[default]: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration +[many others]: +[python's simplehttpserver]: https://docs.python.org/2/library/simplehttpserver.html +[rufus]: https://rufus.ie/ +[syslinux]: http://www.syslinux.org/ diff --git a/docs/installation/install.rst b/docs/installation/install.rst deleted file mode 100644 index 7b38a06b..00000000 --- a/docs/installation/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.* - -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 `__ 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 `_. - -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:///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/md-bare-metal.md b/docs/installation/md-bare-metal.md deleted file mode 100644 index 27525ae4..00000000 --- a/docs/installation/md-bare-metal.md +++ /dev/null @@ -1,626 +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.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 passively 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 around 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 deleted file mode 100644 index a0fc89d4..00000000 --- a/docs/installation/md-image.md +++ /dev/null @@ -1,113 +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: - -```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 deleted file mode 100644 index 4256aa9b..00000000 --- a/docs/installation/md-index.md +++ /dev/null @@ -1,30 +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} -: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 deleted file mode 100644 index 532bdc0c..00000000 --- a/docs/installation/md-install.md +++ /dev/null @@ -1,466 +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 to access -a variety of different downloads via the "Downloads" link. These -downloads include LTS (Long-Term Support), the associated hot-fix releases, -early public access releases, pre-built VM images, as well as device -specific installation ISOs. See this [article] for more information on -downloads. - -:::{note} -The `.qcow2` image provided for Proxmox deployment can also be -used to deploy VyOS on KVM environments. This image includes cloud-init -support. See {ref}`cloud-init` for more information. -::: - -:::{figure} /_static/images/vyosnew-downloads.webp -::: - -### Building from source - -Subscribers can download the source code for the LTS release from the -"Downloads" link. Non-subscribers can access the source code for the -Rolling release. For instructions, see the {ref}`build` section. The -VyOS source code repository is available at -. - -### Rolling Release - -Everyone can download bleeding-edge VyOS rolling images from: - - -:::{note} -Rolling releases contain the latest enhancements and fixes. -This means there may be new bugs. If you encounter a bug, follow the -guide at {ref}`bug_report`. We depend on your feedback to improve VyOS. -::: - -The following link contains the most recent VyOS builds for AMD64 -systems from the `current` branch: - -### Download Verification - -LTS images are signed with the VyOS lead package maintainer's private key. -You can verify the authenticity of the package using the official public key -and Minisign. - -(minisign-verification)= - -#### Minisign verification - -VyOS uses [Minisign](https://github.com/jedisct1/minisign) for release -signing. Minisign is a tool for signing files and verifying signatures. - -OpenBSD introduced signify in 2015. Minisign is an alternative -implementation of the same protocol, available for Windows, macOS, and -most GNU/Linux distributions. Minisign is portable, lightweight, and -uses the Ed25519 public-key signature system. - -{vytask}`T2108` switched the validation system to prefer Minisign over GPG keys. - -To verify a VyOS image starting with VyOS `1.3.0-rc6`, run: - -```none -$ minisign -V -P RWSIhkR/dkM2DSaBRniv/bbbAf8hmDqdbOEmgXkf1RxRoxzodgKcDyGq -m vyos-1.5-rolling-202409250007-generic-amd64.iso vyos-1.5-rolling-202409250007-generic-amd64.iso.minisig - -Signature and comment signature verified -Trusted comment: timestamp:1727223408 file:vyos-1.5-rolling-202409250007-generic-amd64.iso hashed -``` - -During an image upgrade, VyOS runs the following command: - -```none -$ minisign -V -p /usr/share/vyos/keys/vyos-release.minisign.pub -m vyos-1.3.0-rc6-amd64.iso vyos-1.3.0-rc6-amd64.iso.minisig -Signature and comment signature verified -Trusted comment: timestamp:1629997936 file:vyos-1.3.0-rc6-amd64.iso -``` - -:::{note} -Starting with version `1.4.3`, VyOS uses Minisign exclusively. -If you see an unexpected verification error, update your system to version -`1.4.2` first. Support for GnuPG signatures has been -removed ({vytask}`T7301`). -::: - -(live_installation)= - -## Live installation - -:::{note} -To permanently install VyOS, you must first complete a live -installation. -::: - -You can test VyOS without installing it on your hard drive. **Using your -downloaded VyOS .iso file, you can create a bootable USB drive to boot -into a fully functional VyOS system**. After testing it, you can start a -{ref}`permanent_installation` on your hard drive or power off your system -and remove the USB drive. - -```{eval-rst} -If you have a GNU/Linux system, you can create a bootable VyOS USB drive using -the ``dd`` command: - - 1. Open your terminal emulator. - - 2. Find the device name of your USB drive (use the ``lsblk`` command). - - 3. Unmount the USB drive. Replace ``X`` with your device letter and keep the - asterisk (*) to unmount all partitions. - - .. code-block:: none - - $ umount /dev/sdX* - - 1. Write the image (your VyOS .iso file) to the USB drive. Use the device - name (for example, ``/dev/sdb``), not the partition name - (for example, ``/dev/sdb1``). - - **Warning**: This will destroy all data on the USB drive! - - .. code-block:: none - - # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync - - 1. Wait for the operation to complete (bytes copied). On some systems, this - may take more than one minute. - - 2. Once ``dd`` has finished, pull the USB drive out and plug it into - the powered-off computer where you want to install (or test) VyOS. - - 3. Power on the computer and ensure it boots from the USB drive - (you may need to select the boot device or change boot settings). - - 4. When VyOS finishes loading, sign in using the default credentials - (login: ``vyos``, password: ``vyos``). -``` - -If you encounter issues with this method, prefer a different operating -system, or want a GUI program, you can use other tools to create a -bootable USB drive, such as [balenaEtcher] (GNU/Linux, macOS, and Windows), -[Rufus] (Windows), and [many others]. Follow their instructions to create -a bootable USB drive from an `.iso` file. - -:::{hint} -The default username and password for the live system is *vyos*. -::: - -(permanent_installation)= - -## Permanent installation - -:::{note} -Before a permanent installation, VyOS requires a -{ref}`live_installation`. -::: - -Unlike general-purpose Linux distributions, VyOS uses "image installation", -which mimics the user experience of traditional hardware routers and allows -you to keep multiple VyOS versions installed simultaneously. This lets you -switch to a previous version if something breaks or misbehaves after an -image upgrade. - -Each version is contained in its own squashfs image mounted in a union -filesystem along with a directory for mutable data such as configurations, -keys, and custom scripts. - -```{eval-rst} -In order to proceed with a permanent installation: - - 1. Sign in to the VyOS live system using the default credentials - (login: ``vyos``, password: ``vyos``). - - 2. Run the ``install image`` command and follow the wizard: - - .. code-block:: none - - vyos@vyos:~$ install image - Welcome to VyOS installation! - This command will install VyOS to your permanent storage. - Would you like to continue? [y/N] y - What would you like to name this image? (Default: 2025.09.17-0018-rolling) - Please enter a password for the "vyos" user: - Please confirm password for the "vyos" user: - What console should be used by default? (K: KVM, S: Serial)? (Default: S) - Probing disks - 1 disk(s) found - The following disks were found: - Drive: /dev/vda (10.0 GB) - Which one should be used for installation? (Default: /dev/vda) - Installation will delete all data on the drive. Continue? [y/N] y - Searching for data from previous installations - No previous installation found - Would you like to use all the free space on the drive? [Y/n] Y - Creating partition table... - The following config files are available for boot: - 1: /opt/vyatta/etc/config/config.boot - 2: /opt/vyatta/etc/config.boot.default - Which file would you like as boot config? (Default: 1) - Creating temporary directories - Mounting new partitions - Creating a configuration file - Copying system image files - Installing GRUB configuration files - Installing GRUB to the drive - Cleaning up - Unmounting target filesystems - Removing temporary files - The image installed successfully; please reboot now. - - - 3. After installation completes, remove the live USB drive or CD. - - 4. Reboot the system. - - .. code-block:: none - - vyos@vyos:~$ reboot - Proceed with reboot? (Yes/No) [No] Yes - - You will boot now into a permanent VyOS system. -``` - -## PXE Boot - -You can also install VyOS using PXE, a more complex installation method that -allows you to deploy VyOS over the network. - -**Requirements** - -- A machine (client) with a PXE-enabled NIC. -- {ref}`dhcp-server` -- {ref}`tftp-server` -- Webserver (HTTP). Optional, but speeds up installation. -- VyOS ISO image (do not use images prior to VyOS `1.2.3`). -- Files *pxelinux.0* and *ldlinux.c32* from the - [Syslinux distribution](https://kernel.org/pub/linux/utils/boot/syslinux/). - -### Configuration - -#### Step 1: DHCP - -Configure a DHCP server to provide the client with: - -- An IP address -- The TFTP server address (DHCP option 66), sometimes referred to as the - *boot server* -- The *bootfile name* (DHCP option 67): *pxelinux.0* - -In this example we configured an existent VyOS as the DHCP server: - -```none -vyos@vyos# show service dhcp-server - shared-network-name mydhcp { - subnet 192.168.1.0/24 { - option { - bootfile-name pxelinux.0 - bootfile-server 192.168.1.50 - default-router 192.168.1.50 - } - range 0 { - start 192.168.1.70 - stop 192.168.1.100 - } - subnet-id 1 - } - } -``` - -(install_from_tftp)= - -#### Step 2: TFTP - -Configure a TFTP server to serve the following: - -- The *pxelinux.0* file from the Syslinux distribution -- The *ldlinux.c32* file from the Syslinux distribution -- The VyOS kernel you want to deploy (*vmlinuz* file from the - */live* directory in the extracted ISO file) -- The VyOS initial ramdisk (*initrd.img* file from the */live* directory - in the extracted ISO file). Do not use an empty (0 bytes) initrd.img - file; the correct file may have a longer name. -- A directory named *pxelinux.cfg* containing the configuration file. - By default, the VyOS configuration file is named [default]. - -In the example you configured your existent VyOS as the TFTP server too: - -```none -vyos@vyos# show service tftp-server - directory /config/tftpboot - listen-address 192.168.1.50 -``` - -Example of the contents of the TFTP server: - -```none -vyos@vyos# ls -hal /config/tftpboot/ -total 29M -drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . -drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. --r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos --rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 --rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 -drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg --r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz - -vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg -total 12K -drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . -drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. --rw-r--r-- 1 root root 191 Oct 14 01:10 default -``` - -Example of simple (no menu) configuration file: - -```none -vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default -DEFAULT VyOS123 - -LABEL VyOS123 - KERNEL vmlinuz - APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs -``` - - -#### Step 3: HTTP - -You also need to provide the *filesystem.squashfs* file. Because this is a -large file and TFTP is slow, you can send it through HTTP to speed up the -transfer. In our example, we do this—see the configuration file above. - -1. Start a web server. You can use one like - [Python's SimpleHTTPServer] to serve the `filesystem.squashfs` file. - The file is in the `/live` directory of the extracted ISO file. -2. Edit the {ref}`install_from_tftp` configuration file to show the correct - URL: `fetch=http:///filesystem.squashfs`. - -:::{note} -Do not rename the *filesystem.squashfs* file. If you're working with -different versions, create different directories instead. -::: - -3. restart the TFTP service. If you're using VyOS as your TFTP server, restart - the service with `sudo service tftpd-hpa restart`. - -:::{note} -Ensure the directories and files on both the TFTP and HTTP servers -have the correct permissions for the booting clients to access them. -::: - -### Client Boot - -Finally, power on your PXE-enabled clients. They will automatically receive an -IP address from the DHCP server and boot into VyOS live using files from the -TFTP and HTTP servers. - -Once finished you will be able to proceed with the `install image` -command as in a regular VyOS installation. - -## Known Issues - -This is a list of known issues that can arise during installation. - -### Black screen on install - -GRUB redirects all output to a serial port to facilitate installation -on headless hosts. On some hardware that lacks a serial port, this causes -a hard lockup and displays a black screen after you select the -`Live system` option from the installation image. - -The workaround is to press `e` when the boot menu appears and edit the -GRUB boot options. Specifically, remove the: - -`console=ttyS0,115200` - -option, and type CTRL-X to boot. - -Installation can then continue as outlined above. - -[article]: https://customers.support.vyos.com/servicedesk/customer/portal/1/article/159055913 -[balenaetcher]: https://www.balena.io/etcher/ -[configuration]: https://wiki.syslinux.org/wiki/index.php?title=Config -[default]: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration -[many others]: -[python's simplehttpserver]: https://docs.python.org/2/library/simplehttpserver.html -[rufus]: https://rufus.ie/ -[syslinux]: http://www.syslinux.org/ diff --git a/docs/installation/md-secure-boot.md b/docs/installation/md-secure-boot.md deleted file mode 100644 index ecbc432d..00000000 --- a/docs/installation/md-secure-boot.md +++ /dev/null @@ -1,194 +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: - -```bash -cd vyos-build -CA_DIR="data/certificates" -SHIM_CERT_NAME="vyos-dev-2025-shim" -VYOS_KERNEL_CERT_NAME="vyos-dev-2025-linux" - -openssl req -new -x509 -newkey rsa:4096 -keyout ${CA_DIR}/${SHIM_CERT_NAME}.key -out ${CA_DIR}/${SHIM_CERT_NAME}.der \ - -outform DER -days 36500 -subj "/CN=VyOS Networks Secure Boot CA/" -nodes -openssl x509 -inform der -in ${CA_DIR}/${SHIM_CERT_NAME}.der -out ${CA_DIR}/${SHIM_CERT_NAME}.pem - -openssl req -newkey rsa:4096 -sha256 -nodes -keyout ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.key \ - -out ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.csr -outform PEM -days 3650 \ - -subj "/CN=VyOS Networks Secure Boot Signer 2025 - linux/" -openssl x509 -req -in ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.csr -CA ${CA_DIR}/${SHIM_CERT_NAME}.pem \ - -CAkey ${CA_DIR}/${SHIM_CERT_NAME}.key -CAcreateserial -out ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.pem -days 3650 -sha256 -``` - - -## Installation - -As our version of `shim` is not signed by Microsoft we need to enroll the -previously generated {abbr}`MOK (Machine Owner Key)` to the system. - -First, disable UEFI Secure Boot for the installation. - -:::{figure} /_static/images/uefi_secureboot_01.webp -:alt: Disable UEFI secure boot -::: - -Proceed with the standard VyOS {ref}`installation ` on -your system. Instead of the final `reboot` command, enroll the -{abbr}`MOK (Machine Owner Key)`. - -```none -vyos@vyos:~$ install mok -input password: -input password again: -``` - -You can set the `input password` to any value you choose. You'll need this -password after reboot when MOK Manager launches to permanently install the keys. - -With the next reboot, MOK Manager will automatically launch - -:::{figure} /_static/images/uefi_secureboot_02.webp -:alt: Disable UEFI secure boot -::: - -Select `Enroll MOK` - -:::{figure} /_static/images/uefi_secureboot_03.webp -:alt: Disable UEFI secure boot -::: - -You can now view the key to be installed and continue with key installation. - -:::{figure} /_static/images/uefi_secureboot_04.webp -:alt: Disable UEFI secure boot -::: - -:::{figure} /_static/images/uefi_secureboot_05.webp -:alt: Disable UEFI secure boot -::: - -Now you need to enter the password you defined previously. - -:::{figure} /_static/images/uefi_secureboot_06.webp -:alt: Disable UEFI secure boot -::: - -Now reboot and re-enable UEFI Secure Boot. - -:::{figure} /_static/images/uefi_secureboot_07.webp -:alt: Disable UEFI secure boot -::: - -VyOS will now launch in UEFI Secure Boot mode. You can verify this by running -one of the following commands: - -```none -vyos@vyos:~$ show secure-boot -SecureBoot enabled -``` - -```none -vyos@vyos:~$ show log kernel | match Secure -Oct 08 19:15:41 kernel: Secure boot enabled -``` - -```none -vyos@vyos:~$ show version -Version: VyOS 1.5-secureboot -Release train: current -Release flavor: generic - -Built by: autobuild@vyos.net -Built on: Tue 08 Oct 2024 18:00 UTC -Build UUID: 5702ca38-e6f4-470f-b89e-ffc29baee474 -Build commit ID: 9eb61d3b6cf426 - -Architecture: x86_64 -Boot via: installed image -System type: KVM guest -Secure Boot: enabled <-- UEFI secure boot indicator - -Hardware vendor: QEMU -Hardware model: Standard PC (i440FX + PIIX, 1996) -Hardware S/N: -Hardware UUID: 1f6e7f5c-fb52-4c33-96c9-782fbea36436 - -Copyright: VyOS maintainers and contributors -``` - - -## Image Update - -:::{note} -Currently, there is no signed version of `shim` for VyOS. If you -want Secure Boot support, you can build a custom image with your own keys. -::: - -During image installation, you install your {abbr}`MOK (Machine Owner Key)` -into the UEFI variables to add trust to this key. After you re-enable Secure -Boot in UEFI, you can only boot into your signed image. - -You can no longer boot into a CI-generated rolling release because those -are not signed by a trusted party ({vytask}`T861` work in progress). This -also means you must sign all successor builds with the same key; otherwise, -you'll see this error: - -```none -error: bad shim signature -error: you need to load the kernel first -``` - - -## Linux Kernel - -In addition to Secure Boot support, VyOS uses ephemeral key signing of Linux -Kernel modules for an extra security layer in both Secure and non-Secure boot -images. - - - -When the CI system builds a Kernel package and required third-party modules, -it generates a temporary (ephemeral) key pair for signing the modules. The -public key is embedded in the Kernel binary to verify loaded modules. - -After the Kernel CI build completes, the generated key is discarded, meaning -we can no longer sign additional modules with that key. The Kernel configuration -also includes the option `CONFIG_MODULE_SIG_FORCE=y`, which enforces signature -verification for all modules. If you try to load an unsigned module, you'll -get this error: - -`insmod: ERROR: could not insert module malicious.ko: Key was rejected by -service` - -This prevents loading any malicious code after the image is assembled into the -Kernel as a module. You can disable this behavior on custom builds if needed. - -## Troubleshoot - -In most cases, if something goes wrong during system boot, you'll see this -error message: - -```none -error: bad shim signature -error: you need to load the kernel first -``` - -This error means the Machine Owner Key used to sign the Kernel is not trusted -by your UEFI. Install the MOK using the `install mok` command as described -above. diff --git a/docs/installation/md-update.md b/docs/installation/md-update.md deleted file mode 100644 index e8b5f912..00000000 --- a/docs/installation/md-update.md +++ /dev/null @@ -1,105 +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 \ | [latest] [vrf name] [username user [password pass]] - -Use this command to install a new system image. You can retrieve the -image from the web (``http://``, ``https://``) or from your local system. -For example: /tmp/vyos-1.2.3-amd64.iso. - - The ``add system image`` command also supports installing new VyOS versions - through an optional VRF. If the URL requires authentication, you can specify - an optional username and password on the command line, which will be passed - as "Basic-Auth" to the server. -``` - -If there isn't enough free disk space, the installation will be canceled. -To delete images, use the {opcmd}`delete system image` command. - - -VyOS associates configuration with each image, and each image has its own -unique configuration copy. This differs from traditional network routers where -the configuration is shared across all images. - - -:::{note} -If you have personal files such as scripts that you want to preserve -during the upgrade, store them in `/config` since this directory is always -copied to newly installed images. -::: - - -You can access files from a previous installation and copy them to your -current image if they were stored in the `/config` directory. Use the -{opcmd}`copy` command to do this. For example, to copy `/config/config.boot` -from the VyOS `1.2.1` image, run: - -```none -copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 -``` - - -#### Example - -```none -vyos@vyos:~$ add system image https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso -Trying to fetch ISO file from https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed -100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k -ISO download succeeded. -Checking for digital signature file... - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 -curl: (22) The requested URL returned error: 404 Not Found - -Unable to fetch digital signature file. -Do you want to continue without signature check? (yes/no) [yes] -Checking MD5 checksums of files on the ISO image...OK. -Done! - -What would you like to name this image? [vyos-1.3-rolling-201912201452]: - -OK. This image will be named: vyos-1.3-rolling-201912201452 -``` - -You can use `latest` option. It loads the latest available Rolling release. - -```none -vyos@vyos:~$ add system image latest -``` - -:::{note} -To use the `latest` option, "system update-check url" must be -configured appropriately for your installed release. - -For updates to the Rolling Release for AMD64, the following URL may be -used: - - -::: - -:::{hint} -You can access the latest Rolling Release for AMD64 from a web -browser at: - - -::: - -After rebooting, verify the version you're running using the -{opcmd}`show version` command. diff --git a/docs/installation/rst-bare-metal.rst b/docs/installation/rst-bare-metal.rst new file mode 100644 index 00000000..5b6f24a4 --- /dev/null +++ b/docs/installation/rst-bare-metal.rst @@ -0,0 +1,633 @@ +.. _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 `_ so far on this +motherboard). + +Pictures +-------- + +.. figure:: /_static/images/1u_vyos_back.* + :scale: 25 % + :alt: CSE-505-203B Back + +.. figure:: /_static/images/1u_vyos_front.* + :scale: 25 % + :alt: CSE-505-203B Front + +.. figure:: /_static/images/1u_vyos_front_open_1.* + :scale: 25 % + :alt: CSE-505-203B Open 1 + +.. figure:: /_static/images/1u_vyos_front_open_2.* + :scale: 25 % + :alt: CSE-505-203B Open 2 + +.. figure:: /_static/images/1u_vyos_front_open_3.* + :scale: 25 % + :alt: CSE-505-203B Open 3 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_1.* + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 1 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_2.* + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 2 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_3.* + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 3 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_4.* + :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.* + :scale: 25 % + :alt: APU4 rack closed + +.. figure:: /_static/images/apu4_rack_2.* + :scale: 25 % + :alt: APU4 rack front + +.. figure:: /_static/images/apu4_rack_3.* + :scale: 25 % + :alt: APU4 rack module #1 + +.. figure:: /_static/images/apu4_rack_4.* + :scale: 25 % + :alt: APU4 rack module #2 + +.. figure:: /_static/images/apu4_rack_5.* + :scale: 25 % + :alt: APU4 rack module #3 with PSU + +VyOS custom print +""""""""""""""""" + +.. figure:: /_static/images/apu4_rack_vyos_print.* + :scale: 25 % + :alt: APU4 custom VyOS powder coat + +Desktop / Bench Top +^^^^^^^^^^^^^^^^^^^ + +.. figure:: /_static/images/apu4_desk_1.* + :scale: 25 % + :alt: APU4 desktop closed + +.. figure:: /_static/images/apu4_desk_2.* + :scale: 25 % + :alt: APU4 desktop closed + +.. figure:: /_static/images/apu4_desk_3.* + :scale: 25 % + :alt: APU4 desktop back + +.. figure:: /_static/images/apu4_desk_4.* + :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.* + +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 `_. + +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.* + +.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Back.* + +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.* + +.. figure:: ../_static/images/gowin-02.* + +.. figure:: ../_static/images/gowin-03.* + +.. figure:: ../_static/images/gowin-04.* + +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 new file mode 100644 index 00000000..5b473e78 --- /dev/null +++ b/docs/installation/rst-image.rst @@ -0,0 +1,112 @@ +: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 new file mode 100644 index 00000000..5ba89755 --- /dev/null +++ b/docs/installation/rst-index.rst @@ -0,0 +1,27 @@ +: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 new file mode 100644 index 00000000..7b38a06b --- /dev/null +++ b/docs/installation/rst-install.rst @@ -0,0 +1,475 @@ +: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.* + +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 `__ 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 `_. + +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:///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 new file mode 100644 index 00000000..b0912f00 --- /dev/null +++ b/docs/installation/rst-secure-boot.rst @@ -0,0 +1,192 @@ +: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.* + :alt: Disable UEFI secure boot + +Proceed with the standard VyOS :ref:`installation ` on +your system. Instead of the final ``reboot`` command, enroll the +:abbr:`MOK (Machine Owner Key)`. + +.. 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.* + :alt: Disable UEFI secure boot + +Select ``Enroll MOK`` + +.. figure:: /_static/images/uefi_secureboot_03.* + :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.* + :alt: Disable UEFI secure boot + +.. figure:: /_static/images/uefi_secureboot_05.* + :alt: Disable UEFI secure boot + +Now you need to enter the password you defined previously. + +.. figure:: /_static/images/uefi_secureboot_06.* + :alt: Disable UEFI secure boot + +Now reboot and re-enable UEFI Secure Boot. + +.. figure:: /_static/images/uefi_secureboot_07.* + :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 new file mode 100644 index 00000000..81750dc1 --- /dev/null +++ b/docs/installation/rst-update.rst @@ -0,0 +1,97 @@ +:lastproofread: 2026-01-26 + +.. _update_vyos: + +########### +Update VyOS +########### + +New system images can be added using the :opcmd:`add system image` command. +This command extracts the image and prompts you to use the current system +configuration and SSH security keys, allowing the new image to boot with your +current configuration. + +.. note:: Only LTS releases are PGP-signed. + +.. opcmd:: add system image | [latest] [vrf name] + [username user [password pass]] + + Use this command to install a new system image. You can retrieve the + image from the web (``http://``, ``https://``) or from your local system. + For example: /tmp/vyos-1.2.3-amd64.iso. + + The ``add system image`` command also supports installing new VyOS versions + through an optional VRF. If the URL requires authentication, you can specify + an optional username and password on the command line, which will be passed + as "Basic-Auth" to the server. + +If there isn't enough free disk space, the installation will be canceled. +To delete images, use the :opcmd:`delete system image` command. + +VyOS associates configuration with each image, and each image has its own +unique configuration copy. This differs from traditional network routers where +the configuration is shared across all images. + +.. note:: If you have personal files such as scripts that you want to preserve + during the upgrade, store them in ``/config`` since this directory is always + copied to newly installed images. + +You can access files from a previous installation and copy them to your +current image if they were stored in the ``/config`` directory. Use the +:opcmd:`copy` command to do this. For example, to copy ``/config/config.boot`` +from the VyOS ``1.2.1`` image, run: + +.. 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/secure-boot.md b/docs/installation/secure-boot.md new file mode 100644 index 00000000..ecbc432d --- /dev/null +++ b/docs/installation/secure-boot.md @@ -0,0 +1,194 @@ +--- +lastproofread: '2026-01-26' +--- + +(secure-boot)= + +# Secure Boot + +Initial UEFI Secure Boot support is available ({vytask}`T861`). VyOS uses +`shim` from Debian 12 (Bookworm), which is properly signed by the UEFI +Secure Boot key from Microsoft. + +:::{note} +There is yet no signed version of `shim` for VyOS, thus we +provide no signed image for secure boot yet. If you are interested in +secure boot you can build an image on your own. +::: + +To generate a custom ISO with your own secure boot keys, run the following +commands prior to your ISO image build: + +```bash +cd vyos-build +CA_DIR="data/certificates" +SHIM_CERT_NAME="vyos-dev-2025-shim" +VYOS_KERNEL_CERT_NAME="vyos-dev-2025-linux" + +openssl req -new -x509 -newkey rsa:4096 -keyout ${CA_DIR}/${SHIM_CERT_NAME}.key -out ${CA_DIR}/${SHIM_CERT_NAME}.der \ + -outform DER -days 36500 -subj "/CN=VyOS Networks Secure Boot CA/" -nodes +openssl x509 -inform der -in ${CA_DIR}/${SHIM_CERT_NAME}.der -out ${CA_DIR}/${SHIM_CERT_NAME}.pem + +openssl req -newkey rsa:4096 -sha256 -nodes -keyout ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.key \ + -out ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.csr -outform PEM -days 3650 \ + -subj "/CN=VyOS Networks Secure Boot Signer 2025 - linux/" +openssl x509 -req -in ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.csr -CA ${CA_DIR}/${SHIM_CERT_NAME}.pem \ + -CAkey ${CA_DIR}/${SHIM_CERT_NAME}.key -CAcreateserial -out ${CA_DIR}/${VYOS_KERNEL_CERT_NAME}.pem -days 3650 -sha256 +``` + + +## Installation + +As our version of `shim` is not signed by Microsoft we need to enroll the +previously generated {abbr}`MOK (Machine Owner Key)` to the system. + +First, disable UEFI Secure Boot for the installation. + +:::{figure} /_static/images/uefi_secureboot_01.webp +:alt: Disable UEFI secure boot +::: + +Proceed with the standard VyOS {ref}`installation ` on +your system. Instead of the final `reboot` command, enroll the +{abbr}`MOK (Machine Owner Key)`. + +```none +vyos@vyos:~$ install mok +input password: +input password again: +``` + +You can set the `input password` to any value you choose. You'll need this +password after reboot when MOK Manager launches to permanently install the keys. + +With the next reboot, MOK Manager will automatically launch + +:::{figure} /_static/images/uefi_secureboot_02.webp +:alt: Disable UEFI secure boot +::: + +Select `Enroll MOK` + +:::{figure} /_static/images/uefi_secureboot_03.webp +:alt: Disable UEFI secure boot +::: + +You can now view the key to be installed and continue with key installation. + +:::{figure} /_static/images/uefi_secureboot_04.webp +:alt: Disable UEFI secure boot +::: + +:::{figure} /_static/images/uefi_secureboot_05.webp +:alt: Disable UEFI secure boot +::: + +Now you need to enter the password you defined previously. + +:::{figure} /_static/images/uefi_secureboot_06.webp +:alt: Disable UEFI secure boot +::: + +Now reboot and re-enable UEFI Secure Boot. + +:::{figure} /_static/images/uefi_secureboot_07.webp +:alt: Disable UEFI secure boot +::: + +VyOS will now launch in UEFI Secure Boot mode. You can verify this by running +one of the following commands: + +```none +vyos@vyos:~$ show secure-boot +SecureBoot enabled +``` + +```none +vyos@vyos:~$ show log kernel | match Secure +Oct 08 19:15:41 kernel: Secure boot enabled +``` + +```none +vyos@vyos:~$ show version +Version: VyOS 1.5-secureboot +Release train: current +Release flavor: generic + +Built by: autobuild@vyos.net +Built on: Tue 08 Oct 2024 18:00 UTC +Build UUID: 5702ca38-e6f4-470f-b89e-ffc29baee474 +Build commit ID: 9eb61d3b6cf426 + +Architecture: x86_64 +Boot via: installed image +System type: KVM guest +Secure Boot: enabled <-- UEFI secure boot indicator + +Hardware vendor: QEMU +Hardware model: Standard PC (i440FX + PIIX, 1996) +Hardware S/N: +Hardware UUID: 1f6e7f5c-fb52-4c33-96c9-782fbea36436 + +Copyright: VyOS maintainers and contributors +``` + + +## Image Update + +:::{note} +Currently, there is no signed version of `shim` for VyOS. If you +want Secure Boot support, you can build a custom image with your own keys. +::: + +During image installation, you install your {abbr}`MOK (Machine Owner Key)` +into the UEFI variables to add trust to this key. After you re-enable Secure +Boot in UEFI, you can only boot into your signed image. + +You can no longer boot into a CI-generated rolling release because those +are not signed by a trusted party ({vytask}`T861` work in progress). This +also means you must sign all successor builds with the same key; otherwise, +you'll see this error: + +```none +error: bad shim signature +error: you need to load the kernel first +``` + + +## Linux Kernel + +In addition to Secure Boot support, VyOS uses ephemeral key signing of Linux +Kernel modules for an extra security layer in both Secure and non-Secure boot +images. + + + +When the CI system builds a Kernel package and required third-party modules, +it generates a temporary (ephemeral) key pair for signing the modules. The +public key is embedded in the Kernel binary to verify loaded modules. + +After the Kernel CI build completes, the generated key is discarded, meaning +we can no longer sign additional modules with that key. The Kernel configuration +also includes the option `CONFIG_MODULE_SIG_FORCE=y`, which enforces signature +verification for all modules. If you try to load an unsigned module, you'll +get this error: + +`insmod: ERROR: could not insert module malicious.ko: Key was rejected by +service` + +This prevents loading any malicious code after the image is assembled into the +Kernel as a module. You can disable this behavior on custom builds if needed. + +## Troubleshoot + +In most cases, if something goes wrong during system boot, you'll see this +error message: + +```none +error: bad shim signature +error: you need to load the kernel first +``` + +This error means the Machine Owner Key used to sign the Kernel is not trusted +by your UEFI. Install the MOK using the `install mok` command as described +above. diff --git a/docs/installation/secure-boot.rst b/docs/installation/secure-boot.rst deleted file mode 100644 index b0912f00..00000000 --- a/docs/installation/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.* - :alt: Disable UEFI secure boot - -Proceed with the standard VyOS :ref:`installation ` on -your system. Instead of the final ``reboot`` command, enroll the -:abbr:`MOK (Machine Owner Key)`. - -.. 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.* - :alt: Disable UEFI secure boot - -Select ``Enroll MOK`` - -.. figure:: /_static/images/uefi_secureboot_03.* - :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.* - :alt: Disable UEFI secure boot - -.. figure:: /_static/images/uefi_secureboot_05.* - :alt: Disable UEFI secure boot - -Now you need to enter the password you defined previously. - -.. figure:: /_static/images/uefi_secureboot_06.* - :alt: Disable UEFI secure boot - -Now reboot and re-enable UEFI Secure Boot. - -.. figure:: /_static/images/uefi_secureboot_07.* - :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/update.md b/docs/installation/update.md new file mode 100644 index 00000000..e8b5f912 --- /dev/null +++ b/docs/installation/update.md @@ -0,0 +1,105 @@ +--- +lastproofread: '2026-01-26' +--- + +(update_vyos)= + +# Update VyOS + +New system images can be added using the {opcmd}`add system image` command. +This command extracts the image and prompts you to use the current system +configuration and SSH security keys, allowing the new image to boot with your +current configuration. + +:::{note} +Only LTS releases are PGP-signed. +::: + +```{opcmd} add system image \ | [latest] [vrf name] [username user [password pass]] + +Use this command to install a new system image. You can retrieve the +image from the web (``http://``, ``https://``) or from your local system. +For example: /tmp/vyos-1.2.3-amd64.iso. + + The ``add system image`` command also supports installing new VyOS versions + through an optional VRF. If the URL requires authentication, you can specify + an optional username and password on the command line, which will be passed + as "Basic-Auth" to the server. +``` + +If there isn't enough free disk space, the installation will be canceled. +To delete images, use the {opcmd}`delete system image` command. + + +VyOS associates configuration with each image, and each image has its own +unique configuration copy. This differs from traditional network routers where +the configuration is shared across all images. + + +:::{note} +If you have personal files such as scripts that you want to preserve +during the upgrade, store them in `/config` since this directory is always +copied to newly installed images. +::: + + +You can access files from a previous installation and copy them to your +current image if they were stored in the `/config` directory. Use the +{opcmd}`copy` command to do this. For example, to copy `/config/config.boot` +from the VyOS `1.2.1` image, run: + +```none +copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 +``` + + +#### Example + +```none +vyos@vyos:~$ add system image https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso +Trying to fetch ISO file from https://s3.amazonaws.com/s3-us.vyos.io/rolling/current/vyos-1.4-rolling-202201120317-amd64.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k +ISO download succeeded. +Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 +curl: (22) The requested URL returned error: 404 Not Found + +Unable to fetch digital signature file. +Do you want to continue without signature check? (yes/no) [yes] +Checking MD5 checksums of files on the ISO image...OK. +Done! + +What would you like to name this image? [vyos-1.3-rolling-201912201452]: + +OK. This image will be named: vyos-1.3-rolling-201912201452 +``` + +You can use `latest` option. It loads the latest available Rolling release. + +```none +vyos@vyos:~$ add system image latest +``` + +:::{note} +To use the `latest` option, "system update-check url" must be +configured appropriately for your installed release. + +For updates to the Rolling Release for AMD64, the following URL may be +used: + + +::: + +:::{hint} +You can access the latest Rolling Release for AMD64 from a web +browser at: + + +::: + +After rebooting, verify the version you're running using the +{opcmd}`show version` command. diff --git a/docs/installation/update.rst b/docs/installation/update.rst deleted file mode 100644 index 81750dc1..00000000 --- a/docs/installation/update.rst +++ /dev/null @@ -1,97 +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 | [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/docker.md b/docs/installation/virtual/docker.md new file mode 100644 index 00000000..3489b94a --- /dev/null +++ b/docs/installation/virtual/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/docker.rst b/docs/installation/virtual/docker.rst deleted file mode 100644 index d62c011b..00000000 --- a/docs/installation/virtual/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/eve-ng.md b/docs/installation/virtual/eve-ng.md new file mode 100644 index 00000000..1ee1c016 --- /dev/null +++ b/docs/installation/virtual/eve-ng.md @@ -0,0 +1,14 @@ +--- +lastproofread: '2026-02-02' +--- + +# EVE-NG + +:::{note} +This page is a stub and needs expansion. Contributions +welcome via the [VyOS documentation repository](https://github.com/vyos/vyos-documentation). +::: + +## References + + diff --git a/docs/installation/virtual/eve-ng.rst b/docs/installation/virtual/eve-ng.rst deleted file mode 100644 index f3db28fe..00000000 --- a/docs/installation/virtual/eve-ng.rst +++ /dev/null @@ -1,14 +0,0 @@ -:lastproofread: 2026-02-02 - -###### -EVE-NG -###### - -.. note:: This page is a stub and needs expansion. Contributions - welcome via the `VyOS documentation repository - `_. - -References -========== - -https://www.eve-ng.net/ \ No newline at end of file diff --git a/docs/installation/virtual/gns3.md b/docs/installation/virtual/gns3.md new file mode 100644 index 00000000..e4cb49c0 --- /dev/null +++ b/docs/installation/virtual/gns3.md @@ -0,0 +1,191 @@ +--- +lastproofread: '2026-02-02' +--- + +(vyos-on-gns3)= + +# Run VyOS on GNS3 + +You may want to test VyOS in a lab environment. +[GNS3](http://www.gns3.com) is a network emulation software that you +can use for this purpose. + +This guide will provide the necessary steps for installing +and setting up VyOS on GNS3. + +## Requirements + +The following items are required: + +- A VyOS installation image (.iso file). You + can find how to get it on the {ref}`installation` page +- A working GNS3 installation. For further information see the + [GNS3 documentation](https://docs.gns3.com/). + +(vm-setup)= + +## VM setup + +First, a virtual machine (VM) for the VyOS installation must be created +in GNS3. + +Go to the GNS3 **File** menu, click **New template**, and select +**Manually create a new Template**. + +:::{figure} /_static/images/gns3-01.webp +::: + +Select **Qemu VMs** and then click the `New` button. + +:::{figure} /_static/images/gns3-02.webp +::: + +Write a name for your VM, such as "VyOS", and click `Next`. + +:::{figure} /_static/images/gns3-03.webp +::: + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click `Next`. + +:::{figure} /_static/images/gns3-04.webp +::: + +Select **telnet** as your console type and click `Next`. + +:::{figure} /_static/images/gns3-05.webp +::: + +Select **New image** for the base disk image of your VM and click +`Create`. + +:::{figure} /_static/images/gns3-06.webp +::: + +Use the defaults in the **Binary and format** window and click +`Next`. + +:::{figure} /_static/images/gns3-07.webp +::: + +Use the defaults in the **Qcow2 options** window and click `Next`. + +:::{figure} /_static/images/gns3-08.webp +::: + +Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu +image creator**. + +:::{figure} /_static/images/gns3-09.webp +::: + +Click `Finish` to end the **New QEMU VM template** wizard. + +:::{figure} /_static/images/gns3-10.webp +::: + +Now you need to edit the VM settings. + +In the **Preferences** window, with **Qemu VMs** selected and your new VM +selected, click the `Edit` button. + +:::{figure} /_static/images/gns3-11.webp +::: + +In the **General settings** tab of your **QEMU VM template +configuration**, do the following: + +- Click on the `Browse...` button to choose the **Symbol** you want to + have representing your VM. +- In **Category** select in which group you want to find your VM. +- Set the **Boot priority** to **CD/DVD-ROM**. + +:::{figure} /_static/images/gns3-12.webp +::: + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +:::{figure} /_static/images/gns3-13.webp +::: + +At the **CD/DVD** tab click on `Browse...` and locate the VyOS image +you want to install. + +:::{figure} /_static/images/gns3-14.webp +::: + +:::{note} +You probably will want to accept to copy the .iso file to your +default image directory when you are asked. +::: + +In the **Network** tab, set the number of adapters to **0**, set the +**Name format** to **eth\{0}**, and set the **Type** to **Paravirtualized +Network I/O (virtio-net-pci)**. + +:::{figure} /_static/images/gns3-15.webp +::: + +In the **Advanced** tab, unmark the checkbox **Use as a linked base +VM** and click `OK`, which will save and close the **QEMU VM template +configuration** window. + +:::{figure} /_static/images/gns3-16.webp +::: + +At the general **Preferences** window, click `OK` to save and close. + +:::{figure} /_static/images/gns3-17.webp +::: + +(vyos-installation)= + +## VyOS installation + +- Create a new project. +- Drag the newly created VyOS VM into it. +- Start the VM. +- Open a console. + The console displays the system booting. It prompts for login + credentials. You're now at the VyOS live system. +- {ref}`Install VyOS ` + as normal (that is, using the `install image` command). +- After successful installation, shut down the VM with the `poweroff` + command. +- **Delete the VM** from the GNS3 project. + +The *VyOS-hda.qcow2* file now contains a working VyOS image and can be +used as a template. But it still needs some fixes before we can deploy +VyOS in our labs. + +(vyos-vm-configuration)= + +## VyOS VM configuration + +To turn the template into a working VyOS machine, further steps are +necessary as outlined below: + +**General settings** tab: Set the boot priority to **HDD** + +:::{figure} /_static/images/gns3-20.webp +::: + +**CD/DVD** tab: Clear the **Image** entry field to unmount the installation +image. + +:::{figure} /_static/images/gns3-21.webp +::: + +Set the number of required network adapters. For example, set it to **4**. + +:::{figure} /_static/images/gns3-215.webp +::: + +**Advanced** settings tab: Check the **Use as a linked +base VM** checkbox and click `OK` to save the changes. + +:::{figure} /_static/images/gns3-22.webp +::: + +The VyOS VM is now ready to be deployed. diff --git a/docs/installation/virtual/gns3.rst b/docs/installation/virtual/gns3.rst deleted file mode 100644 index 2c0b5224..00000000 --- a/docs/installation/virtual/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 `__ 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 `__. - -.. _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.* - -Select **Qemu VMs** and then click the ``New`` button. - -.. figure:: /_static/images/gns3-02.* - -Write a name for your VM, such as "VyOS", and click ``Next``. - -.. figure:: /_static/images/gns3-03.* - -Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM -and click ``Next``. - -.. figure:: /_static/images/gns3-04.* - -Select **telnet** as your console type and click ``Next``. - -.. figure:: /_static/images/gns3-05.* - -Select **New image** for the base disk image of your VM and click -``Create``. - -.. figure:: /_static/images/gns3-06.* - -Use the defaults in the **Binary and format** window and click -``Next``. - -.. figure:: /_static/images/gns3-07.* - -Use the defaults in the **Qcow2 options** window and click ``Next``. - -.. figure:: /_static/images/gns3-08.* - -Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu -image creator**. - -.. figure:: /_static/images/gns3-09.* - -Click ``Finish`` to end the **New QEMU VM template** wizard. - -.. figure:: /_static/images/gns3-10.* - -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.* - -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.* - -At the **HDD** tab, change the Disk interface to **sata** to speed up -the boot process. - -.. figure:: /_static/images/gns3-13.* - -At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image -you want to install. - -.. figure:: /_static/images/gns3-14.* - -.. 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.* - -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.* - -At the general **Preferences** window, click ``OK`` to save and close. - -.. figure:: /_static/images/gns3-17.* - - -.. _vyos_installation: - -VyOS installation ------------------ - -* Create a new project. -* Drag the newly created VyOS VM into it. -* Start the VM. -* Open a console. - The console displays the system booting. It prompts for login - credentials. You're now at the VyOS live system. -* :ref:`Install VyOS ` - as normal (that is, using the ``install image`` command). - -* After successful installation, shut down the VM with the ``poweroff`` - command. - -* **Delete the VM** from the GNS3 project. - -The *VyOS-hda.qcow2* file now contains a working VyOS image and can be -used as a template. But it still needs some fixes before we can deploy -VyOS in our labs. - -.. _vyos_vm_configuration: - -VyOS VM configuration ---------------------- - -To turn the template into a working VyOS machine, further steps are -necessary as outlined below: - -**General settings** tab: Set the boot priority to **HDD** - -.. figure:: /_static/images/gns3-20.* - -**CD/DVD** tab: Clear the **Image** entry field to unmount the installation -image. - -.. figure:: /_static/images/gns3-21.* - -Set the number of required network adapters. For example, set it to **4**. - -.. figure:: /_static/images/gns3-215.* - -**Advanced** settings tab: Check the **Use as a linked -base VM** checkbox and click ``OK`` to save the changes. - -.. figure:: /_static/images/gns3-22.* - -The VyOS VM is now ready to be deployed. - diff --git a/docs/installation/virtual/index.md b/docs/installation/virtual/index.md new file mode 100644 index 00000000..97579129 --- /dev/null +++ b/docs/installation/virtual/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/index.rst b/docs/installation/virtual/index.rst deleted file mode 100644 index e1a3caf5..00000000 --- a/docs/installation/virtual/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/libvirt.md b/docs/installation/virtual/libvirt.md new file mode 100644 index 00000000..0a21a97a --- /dev/null +++ b/docs/installation/virtual/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/libvirt.rst b/docs/installation/virtual/libvirt.rst deleted file mode 100644 index 7374e42c..00000000 --- a/docs/installation/virtual/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.* - -3. Choose the path to the VyOS ISO image. Select any Debian-based operating - system. - -.. figure:: /_static/images/virt-libvirt-02.* - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.* - -5. Disk size - -.. figure:: /_static/images/virt-libvirt-04.* - -6. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.* - -7. Then the system will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-06.* - -.. _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.* - -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.* - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.* - -5. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.* - -6. Then the system will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-qc-03.* - - - diff --git a/docs/installation/virtual/md-docker.md b/docs/installation/virtual/md-docker.md deleted file mode 100644 index 3489b94a..00000000 --- a/docs/installation/virtual/md-docker.md +++ /dev/null @@ -1,72 +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. - -```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 deleted file mode 100644 index 1ee1c016..00000000 --- a/docs/installation/virtual/md-eve-ng.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -lastproofread: '2026-02-02' ---- - -# EVE-NG - -:::{note} -This page is a stub and needs expansion. Contributions -welcome via the [VyOS documentation repository](https://github.com/vyos/vyos-documentation). -::: - -## References - - diff --git a/docs/installation/virtual/md-gns3.md b/docs/installation/virtual/md-gns3.md deleted file mode 100644 index e4cb49c0..00000000 --- a/docs/installation/virtual/md-gns3.md +++ /dev/null @@ -1,191 +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.webp -::: - -Select **Qemu VMs** and then click the `New` button. - -:::{figure} /_static/images/gns3-02.webp -::: - -Write a name for your VM, such as "VyOS", and click `Next`. - -:::{figure} /_static/images/gns3-03.webp -::: - -Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM -and click `Next`. - -:::{figure} /_static/images/gns3-04.webp -::: - -Select **telnet** as your console type and click `Next`. - -:::{figure} /_static/images/gns3-05.webp -::: - -Select **New image** for the base disk image of your VM and click -`Create`. - -:::{figure} /_static/images/gns3-06.webp -::: - -Use the defaults in the **Binary and format** window and click -`Next`. - -:::{figure} /_static/images/gns3-07.webp -::: - -Use the defaults in the **Qcow2 options** window and click `Next`. - -:::{figure} /_static/images/gns3-08.webp -::: - -Set the disk size to 2000 MiB, and click `Finish` to end the **Quemu -image creator**. - -:::{figure} /_static/images/gns3-09.webp -::: - -Click `Finish` to end the **New QEMU VM template** wizard. - -:::{figure} /_static/images/gns3-10.webp -::: - -Now you need to edit the VM settings. - -In the **Preferences** window, with **Qemu VMs** selected and your new VM -selected, click the `Edit` button. - -:::{figure} /_static/images/gns3-11.webp -::: - -In the **General settings** tab of your **QEMU VM template -configuration**, do the following: - -- Click on the `Browse...` button to choose the **Symbol** you want to - have representing your VM. -- In **Category** select in which group you want to find your VM. -- Set the **Boot priority** to **CD/DVD-ROM**. - -:::{figure} /_static/images/gns3-12.webp -::: - -At the **HDD** tab, change the Disk interface to **sata** to speed up -the boot process. - -:::{figure} /_static/images/gns3-13.webp -::: - -At the **CD/DVD** tab click on `Browse...` and locate the VyOS image -you want to install. - -:::{figure} /_static/images/gns3-14.webp -::: - -:::{note} -You probably will want to accept to copy the .iso file to your -default image directory when you are asked. -::: - -In the **Network** tab, set the number of adapters to **0**, set the -**Name format** to **eth\{0}**, and set the **Type** to **Paravirtualized -Network I/O (virtio-net-pci)**. - -:::{figure} /_static/images/gns3-15.webp -::: - -In the **Advanced** tab, unmark the checkbox **Use as a linked base -VM** and click `OK`, which will save and close the **QEMU VM template -configuration** window. - -:::{figure} /_static/images/gns3-16.webp -::: - -At the general **Preferences** window, click `OK` to save and close. - -:::{figure} /_static/images/gns3-17.webp -::: - -(vyos-installation)= - -## VyOS installation - -- Create a new project. -- Drag the newly created VyOS VM into it. -- Start the VM. -- Open a console. - The console displays the system booting. It prompts for login - credentials. You're now at the VyOS live system. -- {ref}`Install VyOS ` - as normal (that is, using the `install image` command). -- After successful installation, shut down the VM with the `poweroff` - command. -- **Delete the VM** from the GNS3 project. - -The *VyOS-hda.qcow2* file now contains a working VyOS image and can be -used as a template. But it still needs some fixes before we can deploy -VyOS in our labs. - -(vyos-vm-configuration)= - -## VyOS VM configuration - -To turn the template into a working VyOS machine, further steps are -necessary as outlined below: - -**General settings** tab: Set the boot priority to **HDD** - -:::{figure} /_static/images/gns3-20.webp -::: - -**CD/DVD** tab: Clear the **Image** entry field to unmount the installation -image. - -:::{figure} /_static/images/gns3-21.webp -::: - -Set the number of required network adapters. For example, set it to **4**. - -:::{figure} /_static/images/gns3-215.webp -::: - -**Advanced** settings tab: Check the **Use as a linked -base VM** checkbox and click `OK` to save the changes. - -:::{figure} /_static/images/gns3-22.webp -::: - -The VyOS VM is now ready to be deployed. diff --git a/docs/installation/virtual/md-index.md b/docs/installation/virtual/md-index.md deleted file mode 100644 index 97579129..00000000 --- a/docs/installation/virtual/md-index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -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 deleted file mode 100644 index 0a21a97a..00000000 --- a/docs/installation/virtual/md-libvirt.md +++ /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. - -```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 deleted file mode 100644 index 6b959341..00000000 --- a/docs/installation/virtual/md-proxmox.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -lastproofread: '2026-02-02' ---- - -(proxmox)= - -# Running on Proxmox - -Proxmox is an open-source platform for virtualization. - -## Deploy VyOS from CLI with qcow2 image - -1. Download the `.qcow2` image from . - Official images are available to users with a valid subscription. - -2. Copy the `.qcow2` image to a temporary directory on the Proxmox server. - -3. The following commands assume that virtual machine (VM) ID `200` is unused - and that the imported disk will be stored in a storage pool named `local-lvm`. - - > ```none - > $ qm create 200 --name vyos --memory 4096 --net0 virtio,bridge=vmbr0 - > $ qm importdisk 200 /var/lib/vz/images/vyos--proxmox-amd64.qcow2 local-lvm - > $ qm set 200 --virtio0 local-lvm:vm-200-disk-0 - > $ qm set 200 --boot order=virtio0 - > ``` - -4. When using a `qcow2` image on Proxmox, the system - **does not include any preconfigured user accounts**. - You must define a user account using **Cloud-Init** before the - first boot. Otherwise, login access is not possible. - - Attach a Cloud-Init data source to the VM. For example, using - `local-lvm` storage: - - ```bash - $ qm set 200 --ide2 local-lvm:cloudinit - ``` - - Alternatively, add a Cloud-Init drive using the Proxmox GUI: - - 1. Open the VM and navigate to **Hardware** - 2. Click **Add** → **CloudInit Drive** - 3. Select a storage (for example, `local-lvm`) - 4. Click **Add** - -5. Start the virtual machine using the Proxmox GUI or by running `qm start 200`. - -## Deploy VyOS from CLI with rolling release ISO - -1. Download the rolling release ISO from - . -2. Prepare the VM for ISO installation. - The commands below assume that the ISO image is available in the - `local` storage, a VM ID `200` is unused, and a 15GB disk will be - created on storage pool `local-lvm`. - -```none -qm create 200 --name vyos --memory 4096 \ ---net0 virtio,bridge=vmbr0 \ ---scsihw virtio-scsi-pci \ ---scsi0 local-lvm:15 \ ---ide2 local:iso/vyos-.iso,media=cdrom \ ---boot order=ide2 -``` - -3. Start the VM using `qm start 200` or by clicking the **Start** - button in the Proxmox GUI. -4. In the Proxmox GUI, open the virtual console for your new VM. - The login username and password are `vyos`/`vyos`. -5. After booting into the live system, type `install image` and follow - the prompts to install VyOS to the virtual drive. -6. After installation completes, remove the installation ISO using the - GUI or run `qm set 200 --ide2 none`, then set the boot device - with `qm set 200 --boot order=scsi0`. -7. Reboot the virtual machine using the GUI or run `qm reboot 200`. - -For more information about downloading and installing Proxmox, visit -. - diff --git a/docs/installation/virtual/md-vmware.md b/docs/installation/virtual/md-vmware.md deleted file mode 100644 index 66278ae9..00000000 --- a/docs/installation/virtual/md-vmware.md +++ /dev/null @@ -1,38 +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 - - - diff --git a/docs/installation/virtual/proxmox.md b/docs/installation/virtual/proxmox.md new file mode 100644 index 00000000..6b959341 --- /dev/null +++ b/docs/installation/virtual/proxmox.md @@ -0,0 +1,80 @@ +--- +lastproofread: '2026-02-02' +--- + +(proxmox)= + +# Running on Proxmox + +Proxmox is an open-source platform for virtualization. + +## Deploy VyOS from CLI with qcow2 image + +1. Download the `.qcow2` image from . + Official images are available to users with a valid subscription. + +2. Copy the `.qcow2` image to a temporary directory on the Proxmox server. + +3. The following commands assume that virtual machine (VM) ID `200` is unused + and that the imported disk will be stored in a storage pool named `local-lvm`. + + > ```none + > $ qm create 200 --name vyos --memory 4096 --net0 virtio,bridge=vmbr0 + > $ qm importdisk 200 /var/lib/vz/images/vyos--proxmox-amd64.qcow2 local-lvm + > $ qm set 200 --virtio0 local-lvm:vm-200-disk-0 + > $ qm set 200 --boot order=virtio0 + > ``` + +4. When using a `qcow2` image on Proxmox, the system + **does not include any preconfigured user accounts**. + You must define a user account using **Cloud-Init** before the + first boot. Otherwise, login access is not possible. + + Attach a Cloud-Init data source to the VM. For example, using + `local-lvm` storage: + + ```bash + $ qm set 200 --ide2 local-lvm:cloudinit + ``` + + Alternatively, add a Cloud-Init drive using the Proxmox GUI: + + 1. Open the VM and navigate to **Hardware** + 2. Click **Add** → **CloudInit Drive** + 3. Select a storage (for example, `local-lvm`) + 4. Click **Add** + +5. Start the virtual machine using the Proxmox GUI or by running `qm start 200`. + +## Deploy VyOS from CLI with rolling release ISO + +1. Download the rolling release ISO from + . +2. Prepare the VM for ISO installation. + The commands below assume that the ISO image is available in the + `local` storage, a VM ID `200` is unused, and a 15GB disk will be + created on storage pool `local-lvm`. + +```none +qm create 200 --name vyos --memory 4096 \ +--net0 virtio,bridge=vmbr0 \ +--scsihw virtio-scsi-pci \ +--scsi0 local-lvm:15 \ +--ide2 local:iso/vyos-.iso,media=cdrom \ +--boot order=ide2 +``` + +3. Start the VM using `qm start 200` or by clicking the **Start** + button in the Proxmox GUI. +4. In the Proxmox GUI, open the virtual console for your new VM. + The login username and password are `vyos`/`vyos`. +5. After booting into the live system, type `install image` and follow + the prompts to install VyOS to the virtual drive. +6. After installation completes, remove the installation ISO using the + GUI or run `qm set 200 --ide2 none`, then set the boot device + with `qm set 200 --boot order=scsi0`. +7. Reboot the virtual machine using the GUI or run `qm reboot 200`. + +For more information about downloading and installing Proxmox, visit +. + diff --git a/docs/installation/virtual/proxmox.rst b/docs/installation/virtual/proxmox.rst deleted file mode 100644 index d34be290..00000000 --- a/docs/installation/virtual/proxmox.rst +++ /dev/null @@ -1,91 +0,0 @@ -: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``. - - - .. code-block:: none - - $ qm create 200 --name vyos --memory 4096 --net0 virtio,bridge=vmbr0 - $ qm importdisk 200 /var/lib/vz/images/vyos--proxmox-amd64.qcow2 local-lvm - $ qm set 200 --virtio0 local-lvm:vm-200-disk-0 - $ qm set 200 --boot order=virtio0 - - -4. When using a ``qcow2`` image on Proxmox, the system - **does not include any preconfigured user accounts**. - You must define a user account using **Cloud-Init** before the - first boot. Otherwise, login access is not possible. - - Attach a Cloud-Init data source to the VM. For example, using - ``local-lvm`` storage: - - .. code-block:: bash - - $ qm set 200 --ide2 local-lvm:cloudinit - - Alternatively, add a Cloud-Init drive using the Proxmox GUI: - - #. Open the VM and navigate to **Hardware** - #. Click **Add** → **CloudInit Drive** - #. Select a storage (for example, ``local-lvm``) - #. 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`. - -.. code-block:: none - - qm create 200 --name vyos --memory 4096 \ - --net0 virtio,bridge=vmbr0 \ - --scsihw virtio-scsi-pci \ - --scsi0 local-lvm:15 \ - --ide2 local:iso/vyos-.iso,media=cdrom \ - --boot order=ide2 - -3. Start the VM using ``qm start 200`` or by clicking the **Start** - button in the Proxmox GUI. -4. In the Proxmox GUI, open the virtual console for your new VM. - The login username and password are ``vyos``/``vyos``. -5. After booting into the live system, type ``install image`` and follow - the prompts to install VyOS to the virtual drive. -6. After installation completes, remove the installation ISO using the - GUI or run ``qm set 200 --ide2 none``, then set the boot device - with ``qm set 200 --boot order=scsi0``. -7. Reboot the virtual machine using the GUI or run ``qm reboot 200``. - - - - - -For more information about downloading and installing Proxmox, visit -https://www.proxmox.com/en/. - diff --git a/docs/installation/virtual/rst-docker.rst b/docs/installation/virtual/rst-docker.rst new file mode 100644 index 00000000..d62c011b --- /dev/null +++ b/docs/installation/virtual/rst-docker.rst @@ -0,0 +1,75 @@ +: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 new file mode 100644 index 00000000..f3db28fe --- /dev/null +++ b/docs/installation/virtual/rst-eve-ng.rst @@ -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 + `_. + +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 new file mode 100644 index 00000000..2c0b5224 --- /dev/null +++ b/docs/installation/virtual/rst-gns3.rst @@ -0,0 +1,177 @@ +:lastproofread: 2026-02-02 + +.. _vyos-on-gns3: + +############### +Run VyOS on GNS3 +############### + +You may want to test VyOS in a lab environment. +`GNS3 `__ 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 `__. + +.. _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.* + +Select **Qemu VMs** and then click the ``New`` button. + +.. figure:: /_static/images/gns3-02.* + +Write a name for your VM, such as "VyOS", and click ``Next``. + +.. figure:: /_static/images/gns3-03.* + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click ``Next``. + +.. figure:: /_static/images/gns3-04.* + +Select **telnet** as your console type and click ``Next``. + +.. figure:: /_static/images/gns3-05.* + +Select **New image** for the base disk image of your VM and click +``Create``. + +.. figure:: /_static/images/gns3-06.* + +Use the defaults in the **Binary and format** window and click +``Next``. + +.. figure:: /_static/images/gns3-07.* + +Use the defaults in the **Qcow2 options** window and click ``Next``. + +.. figure:: /_static/images/gns3-08.* + +Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu +image creator**. + +.. figure:: /_static/images/gns3-09.* + +Click ``Finish`` to end the **New QEMU VM template** wizard. + +.. figure:: /_static/images/gns3-10.* + +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.* + +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.* + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +.. figure:: /_static/images/gns3-13.* + +At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image +you want to install. + +.. figure:: /_static/images/gns3-14.* + +.. 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.* + +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.* + +At the general **Preferences** window, click ``OK`` to save and close. + +.. figure:: /_static/images/gns3-17.* + + +.. _vyos_installation: + +VyOS installation +----------------- + +* Create a new project. +* Drag the newly created VyOS VM into it. +* Start the VM. +* Open a console. + The console displays the system booting. It prompts for login + credentials. You're now at the VyOS live system. +* :ref:`Install VyOS ` + as normal (that is, using the ``install image`` command). + +* After successful installation, shut down the VM with the ``poweroff`` + command. + +* **Delete the VM** from the GNS3 project. + +The *VyOS-hda.qcow2* file now contains a working VyOS image and can be +used as a template. But it still needs some fixes before we can deploy +VyOS in our labs. + +.. _vyos_vm_configuration: + +VyOS VM configuration +--------------------- + +To turn the template into a working VyOS machine, further steps are +necessary as outlined below: + +**General settings** tab: Set the boot priority to **HDD** + +.. figure:: /_static/images/gns3-20.* + +**CD/DVD** tab: Clear the **Image** entry field to unmount the installation +image. + +.. figure:: /_static/images/gns3-21.* + +Set the number of required network adapters. For example, set it to **4**. + +.. figure:: /_static/images/gns3-215.* + +**Advanced** settings tab: Check the **Use as a linked +base VM** checkbox and click ``OK`` to save the changes. + +.. figure:: /_static/images/gns3-22.* + +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 new file mode 100644 index 00000000..e1a3caf5 --- /dev/null +++ b/docs/installation/virtual/rst-index.rst @@ -0,0 +1,15 @@ +: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 new file mode 100644 index 00000000..7374e42c --- /dev/null +++ b/docs/installation/virtual/rst-libvirt.rst @@ -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. + +.. 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.* + +3. Choose the path to the VyOS ISO image. Select any Debian-based operating + system. + +.. figure:: /_static/images/virt-libvirt-02.* + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.* + +5. Disk size + +.. figure:: /_static/images/virt-libvirt-04.* + +6. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.* + +7. Then the system will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-06.* + +.. _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.* + +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.* + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.* + +5. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.* + +6. Then the system will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-qc-03.* + + + diff --git a/docs/installation/virtual/rst-proxmox.rst b/docs/installation/virtual/rst-proxmox.rst new file mode 100644 index 00000000..d34be290 --- /dev/null +++ b/docs/installation/virtual/rst-proxmox.rst @@ -0,0 +1,91 @@ +: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``. + + + .. code-block:: none + + $ qm create 200 --name vyos --memory 4096 --net0 virtio,bridge=vmbr0 + $ qm importdisk 200 /var/lib/vz/images/vyos--proxmox-amd64.qcow2 local-lvm + $ qm set 200 --virtio0 local-lvm:vm-200-disk-0 + $ qm set 200 --boot order=virtio0 + + +4. When using a ``qcow2`` image on Proxmox, the system + **does not include any preconfigured user accounts**. + You must define a user account using **Cloud-Init** before the + first boot. Otherwise, login access is not possible. + + Attach a Cloud-Init data source to the VM. For example, using + ``local-lvm`` storage: + + .. code-block:: bash + + $ qm set 200 --ide2 local-lvm:cloudinit + + Alternatively, add a Cloud-Init drive using the Proxmox GUI: + + #. Open the VM and navigate to **Hardware** + #. Click **Add** → **CloudInit Drive** + #. Select a storage (for example, ``local-lvm``) + #. 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`. + +.. code-block:: none + + qm create 200 --name vyos --memory 4096 \ + --net0 virtio,bridge=vmbr0 \ + --scsihw virtio-scsi-pci \ + --scsi0 local-lvm:15 \ + --ide2 local:iso/vyos-.iso,media=cdrom \ + --boot order=ide2 + +3. Start the VM using ``qm start 200`` or by clicking the **Start** + button in the Proxmox GUI. +4. In the Proxmox GUI, open the virtual console for your new VM. + The login username and password are ``vyos``/``vyos``. +5. After booting into the live system, type ``install image`` and follow + the prompts to install VyOS to the virtual drive. +6. After installation completes, remove the installation ISO using the + GUI or run ``qm set 200 --ide2 none``, then set the boot device + with ``qm set 200 --boot order=scsi0``. +7. Reboot the virtual machine using the GUI or run ``qm reboot 200``. + + + + + +For more information about downloading and installing Proxmox, visit +https://www.proxmox.com/en/. + diff --git a/docs/installation/virtual/rst-vmware.rst b/docs/installation/virtual/rst-vmware.rst new file mode 100644 index 00000000..e18ea4c8 --- /dev/null +++ b/docs/installation/virtual/rst-vmware.rst @@ -0,0 +1,41 @@ +: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 diff --git a/docs/installation/virtual/vmware.md b/docs/installation/virtual/vmware.md new file mode 100644 index 00000000..66278ae9 --- /dev/null +++ b/docs/installation/virtual/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 + + + diff --git a/docs/installation/virtual/vmware.rst b/docs/installation/virtual/vmware.rst deleted file mode 100644 index e18ea4c8..00000000 --- a/docs/installation/virtual/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 -- cgit v1.2.3