Pre-requires

Introduction

VyOS is an open source network operating system Linux distribution based on Debian.

VyOS provides a free routing platform that competes directly with other commercially available solutions from well-known network providers. Because VyOS is run on standard amd64 systems, it can be used as a router and firewall platform for cloud deployments. VyOS can also be optimized to achieve routing at 100Gbps.

Features

Routing and Protocols

Monitoring

High Availability and Load Balancing

  • VRRP for IPv4 and IPv6, ability to execute custom health checks and transition scripts

Two VyOS routers to create a high availability gateway Example

Scenario Overview

RoleHostnameLAN IPFloating IPWAN InterfaceLAN Interfacevrid
Primary VyOSvyos-1192.168.1.2/24192.168.1.4/24wlan0eth04
Secondary VyOSvyos-2192.168.1.3/24192.168.1.4/24wlan0eth04
  • Floating IP: 192.168.1.4

This is what LAN clients use as their default gateway. It automatically moves between vyos-1 and vyos-2 depending on availability.

  • LAN Subnet: 192.168.1.0/24
  • WAN Interface: wlan0 (connected to Wi-Fi)
  • LAN Interface: eth0 (wired)

Installation on Proxmox VE

Downloading VyOS rolling release

https://vyos.net/get/nightly-builds/ https://docs.vyos.io/en/latest/installation/virtual/proxmox.html https://vyos.net/get/

Installation

https://docs.vyos.io/en/latest/installation/install.html#live-installation https://docs.vyos.io/en/latest/installation/install.html#permanent-installation

In order to proceed with a permanent installation: Log into the VyOS live system (use the default credentials: vyos, vyos) Run the install image command and follow the wizard

Before you start

list all of interfaces

show interfaces

NAT gateway

https://docs.vyos.io/en/latest/quick-start.html

Configuration Mode

By default, VyOS is in operational mode, and the command prompt displays a $. To configure VyOS, you will need to enter configuration mode, resulting in the command prompt displaying a #, as demonstrated below:

vyos@vyos$ configure
vyos@vyos#

Interface Configuration

Your outside/WAN interface will be eth0. It will receive its interface address via DHCP. Your internal/LAN interface will be eth1, eth2. It will use a static IP address of 192.168.0.1/24.

Outside/WAN

set interfaces ethernet eth0 address dhcp
set interfaces ethernet eth0 description 'OUTSIDE'

NOTE: if is wifi, please please use the steps below

Create a WPA Supplicant Config for Open Hidden Wi-Fi

Edit or create the config file:

sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

Add the following:

ctrl_interface=/var/run/wpa_supplicant
update_config=1
 
network={
    ssid="YourHiddenSSID"
    scan_ssid=1
    key_mgmt=NONE
}

Explanation:

  • ssid → The exact name of your hidden Wi-Fi.
  • scan_ssid=1 → Required for hidden networks so that wpa_supplicant actively scans for it.
  • key_mgmt=NONE → Specifies an open network with no password.

Connect Using WPA Supplicant

Run wpa_supplicant in the background:

sudo wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant.conf

-B → Run in background. -i wlan0 → Replace wlan0 with your actual interface name. -c → Path to your config file.

Get an IP Address Since the Wi-Fi has no password, you still need to obtain an IP from DHCP:

sudo dhclient wlan0

NOTE: when we reboot the system, wpa_supplicant and dhclient will gone. Solution: VyOS provides a built-in hook script that runs automatically after the system applies its configuration at boot. add below to file - /config/scripts/vyos-postconfig-bootup.script:

sudo wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant.conf
sudo dhclient wlan0

Verify your IP:

ip addr show wlan0

Auto-Connect at Boot

sudo systemctl enable wpa_supplicant@wlan0.service
sudo systemctl start wpa_supplicant@wlan0.service
show interfaces wireless info

Use this command to view operational status and wireless-specific information about all wireless interfaces.

If you have more than one port for LAN, please follow below create a bridge and add interfaces to the bridge. If only one interface for LAN jump to next section.

Multiple-ports for LAN

Create a Bridge Interface

Start by creating a bridge interface (e.g., br0) to aggregate your LAN ports:

set interfaces bridge br0 description 'LAN bridge'
set interfaces bridge br0 stp
set interfaces bridge br0 address 192.168.0.1/24

Add LAN Interfaces to the Bridge

Assuming your LAN interfaces are eth1, and eth2, add them to the bridge:

set interfaces bridge br0 member interface eth1
set interfaces bridge br0 member interface eth2

This configuration treats the specified interfaces as switch ports, allowing devices connected to them to communicate within the same LAN.

Single port for LAN

Primary

configure
set interfaces ethernet eth0 description 'LAN'
set interfaces ethernet eth0 address '192.168.1.2/24'
commit; save

Secondary

configure
set interfaces ethernet eth0 description 'LAN'
set interfaces ethernet eth0 address '192.168.1.3/24'
commit; save

Configure NAT (masquerade) LAN→WAN

Primary (replace WAN_IF as appropriate)

configure
set nat source rule 10 description 'NAT LAN to WAN'
set nat source rule 10 outbound-interface name 'WAN_IF'
set nat source rule 10 source address '192.168.1.0/24'
set nat source rule 10 translation address 'masquerade'
commit; save

Secondary (replace WAN_IF as appropriate)

configure
set nat source rule 10 description 'NAT LAN to WAN'
set nat source rule 10 outbound-interface name 'WAN_IF'
set nat source rule 10 source address '192.168.1.0/24'
set nat source rule 10 translation address 'masquerade'
commit; save

VRRP HA

https://docs.vyos.io/en/latest/configuration/highavailability/

Key VRRP Settings

  • Virtual Address: 192.168.1.4 → The floating IP for LAN clients
  • Group Name: LAN
  • Priority:
    • Higher = preferred master
    • Primary uses 200
    • Secondary uses 100
  • Preempt - Preemption is enabled by default:
    • Ensures the primary regains master status when it comes back online.

Primary (higher priority)

configure
set high-availability vrrp group LAN interface 'eth0'
set high-availability vrrp group LAN vrid '4'
set high-availability vrrp group LAN address '192.168.1.4/24'
set high-availability vrrp group LAN priority '200'
set high-availability vrrp group LAN advertise-interval '1'
commit
save

Secondary (lower priority)

configure
set high-availability vrrp group LAN interface 'eth0'
set high-availability vrrp group LAN vrid '4'
set high-availability vrrp group LAN address '192.168.1.4/24'
set high-availability vrrp group LAN priority '100'
set high-availability vrrp group LAN advertise-interval '1'
commit
save

Verify VRRP status

run show vrrp

DHCP/DNS quick-start

The following settings will configure DHCP and DNS services on your internal/LAN network, where VyOS will act as the default gateway and DNS server.

  • The default gateway and DNS recursor address will be 192.168.0.1/24
  • The address range 192.168.0.2/24 - 192.168.0.8/24 will be reserved for static assignments
  • DHCP clients will be assigned IP addresses within the range of 192.168.0.9 - 192.168.0.254 and have a domain name of internal-network
  • DHCP leases will hold for one day (86400 seconds)
  • VyOS will serve as a full DNS recursor, replacing the need to utilize Google, Cloudflare, or other public DNS servers (which is good for privacy)
  • Only hosts from your internal/LAN network can use the DNS recursor
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 option default-router '192.168.0.1'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 option name-server '192.168.0.1'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 option domain-name 'vyos.net'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 lease '86400'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 start '192.168.0.9'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 range 0 stop '192.168.0.254'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 subnet-id '1'
 
set service dns forwarding cache-size '0'
set service dns forwarding listen-address '192.168.0.1'
set service dns forwarding allow-from '192.168.0.0/24'

Firewall

https://docs.vyos.io/en/latest/quick-start.html#firewall

Commit and Save

After every configuration change, you need to apply the changes by using the following command:

commit

Once your configuration works as expected, you can save it permanently by using the following command:

save

WWAN - Wireless Wide-Area-Network

https://docs.vyos.io/en/stable/configuration/interfaces/wwan.html

Supported LTE cards

  • 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)
  • Huawei ME909s-120 miniPCIe card (LTE)

Supported WIFI cards

VyOS is based on Debian (depends on the version, like 1.3 → Debian 10 “Buster”), so Wi-Fi card compatibility is similar to Debian Linux. These chipsets are usually your safest bet:

Atheros AR9xxx series (ath9k)

✅ Fully open-source drivers ✅ Stable and well-supported in Debian Works in both AP and client mode Good for hostapd (if you’re trying to make VyOS a Wi-Fi AP)

Reference List

  1. https://docs.vyos.io/en/sagitta/
  2. https://forum.vyos.io/t/article-vyos-for-home-use/14715
  3. https://akyriako.medium.com/configure-vyos-as-a-software-based-router-for-your-home-labs-private-networks-a0f4529f0b99
  4. https://en.wikipedia.org/wiki/VyOS