Boyang Yan

VyOS

13 min read

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

  • RAM: 2.00G
  • Precessors: 2
  • Hard Disk: 8G

Proxmox PCI passthrough

How to get PCI ID

root@server5:~# ethtool -i eno3
driver: igb
version: 6.14.11-3-pve
firmware-version: 1.67, 0x800010eb, 22.5.7
expansion-rom-version:
bus-info: 0000:09:00.0
supports-statistics: yes
supports-test: yes
supports-eeprom-access: yes
supports-register-dump: yes
supports-priv-flags: yes

Look for the bus-info line

bus-info: 0000:09:00.0

When should you enable “All Functions”?

  • ✅ Enable “All Functions” if:
    • The NIC has multiple functions (you see .0, .1, … in lspci), and
    • They are in the same IOMMU group, or the documentation recommends keeping them together.
    • You want the VM to fully own that physical card.
  • ❌ You can leave it unchecked if:
    • The card is simple (only .0), or
    • You intentionally want only one function (e.g., only one port) in the VM and keep the others on the host (but then watch IOMMU group warnings from Proxmox).

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.1.5/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.

  • Show bridge info

    bridge link

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

NOTE: In VyOS the priority for a VRRP group must be in the VRRP-standard range:

  • 1–254 are valid priorities
  • 0 is “shut down this VRRP instance”
  • 255 is reserved for the VRRP owner and usually not allowed to be set arbitrarily

Verify VRRP status

show vrrp

Configure conntrack-sync

add a sync-group that references this VRRP group

configure
set high-availability vrrp sync-group SYNC member 'LAN'
commit
save

Do that on both routers (same name SYNC, same member LAN).

delete system conntrack modules

Conntrack helper modules are enabled by default, but they tend to cause more problems than they’re worth in complex networks. You can disable all of them at one go.

vyos@vyos:~$ configure
[edit]
vyos@vyos# delete system conntrack modules
vyos@vyos# commit
vyos@vyos# save
vyos@vyos# exit

Configure conntrack-sync (on both routers)

configure
 
# Which protocols to sync
set service conntrack-sync accept-protocol 'tcp'
set service conntrack-sync accept-protocol 'udp'
set service conntrack-sync accept-protocol 'icmp'
 
# Tie conntrack-sync failover to your VRRP sync-group
set service conntrack-sync failover-mechanism vrrp sync-group 'SYNC'
 
# Interface used to send/receive sync packets
# (here we use LAN eth0 – good enough for lab; in production you’d often use a dedicated VLAN)
set service conntrack-sync interface 'eth0'
 
# Multicast group for sync traffic (default example from docs)
set service conntrack-sync mcast-group '225.0.0.50'
 
# Optional but nice:
set service conntrack-sync event-listen-queue-size '8'
set service conntrack-sync sync-queue-size '8'
set service conntrack-sync startup-resync
 
commit
save

NOTE: If you’d rather use unicast instead of multicast:

  • On R1: set service conntrack-sync interface eth0 peer 192.168.1.2
  • On R2: set service conntrack-sync interface eth0 peer 192.168.1.1
  • (and do not set mcast-group.)
configure
delete service conntrack-sync mcast-group
commit
save

Make sure conntrack is actually used

Conntrack is automatically enabled if you have any NAT or stateful firewall rules. You can verify:

run show conntrack table ipv4

You should see some entries (TCP/UDP flows).

Verify that conntrack sync is working

On both routers (operational mode, not in configure):

run show conntrack-sync status

You want to see something like:

  • sync-interface : eth0
  • failover-mechanism : vrrp [sync-group SYNC]

Then check statistics:

run show conntrack-sync statistics
  • On the master: active flows should appear in the internal cache.
  • On the backup: the same number of flows should appear in the external cache.

DHCP/Domain Name Service (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'

Setting Domain Name Service (DNS) client

On VyOS, the “DNS client” just means which DNS servers VyOS itself uses to resolve domain names (for ping, apt, curl, etc.)

configure
 
# Add one or more DNS servers
set system name-server 192.168.1.21
set system name-server 192.168.1.22
 
# Optional: set a default search domain
set system domain-name example.com
set system domain-search example.com
 
commit
save

Check what’s configured:

show system name-server
exit

Test

ping google.com
dig @1.1.1.1 vyos.io

VyOS Publishing and exposing ports (options)

Do this on each gateway so the LAN’s PC/VM always sees the gateway’s own IP as the source and replies to it.

  • NAT (Network Address Translation) = rewriting IP headers. Two directions:
    • SNAT: change the source address/port (usually on egress).
    • DNAT: change the destination address/port (usually on ingress).
    • Masquerade = a special kind of SNAT that automatically uses the egress interface’s current IP. It’s perfect when your WAN gets a dynamic address (DHCP/PPPoE) because it adapts if the IP changes or the link bounces.
    • PAT (Port Address Translation): the common case where NAT also rewrites ports so many inside hosts can share one public IP. VyOS SNAT/masquerade do this by default.

Show NAT rules

show nat source rules
show nat destination rules

Show the live translation table

show nat source translations
show nat destination translations

Show interfaces

show interfaces

DNAT Setting

configure
# DNAT: forward TCP/8006 from WAN to the 192.168.1.12:8006
set nat destination rule 8006 description 'wlan0:8006 → 192.168.1.12:8006 (PVE)'
set nat destination rule 8006 inbound-interface name 'wlan0' # e.g., <wan-if>
 
set nat destination rule 8006 destination port 8006
set nat destination rule 8006 protocol tcp
set nat destination rule 8006 translation address 192.168.1.12
set nat destination rule 8006 translation port 8006
commit; save

SNAT Setting

configure
# SNAT (hairpin for symmetry): make the 192.168.1.12 (server2) see current gateway 192.168.1.3
set nat source rule 8006 description '192.168.1.12:8006 (PVE) -> wlan0:8006'
set nat source rule 8006 outbound-interface name 'eth0'         # e.g., <lan-if>
 
set nat source rule 8006 destination address 192.168.1.12
set nat source rule 8006 protocol tcp
set nat source rule 8006 destination port 8006
set nat source rule 8006 translation address 192.168.1.3  # Gateway IP
commit; save

Firewall

If you run a WAN input firewall, allow TCP/8006 to the gateway (the DNAT will hand it to the server2 (PVE)): https://docs.vyos.io/en/latest/quick-start.html#firewall

configure
# WAN firewall (allow the forwarded traffic)
set firewall ipv4 name WAN_IN default-action drop
set firewall ipv4 name WAN_IN rule 10 action accept
set firewall ipv4 name WAN_IN rule 10 state established enable
set firewall ipv4 name WAN_IN rule 10 state related enable
 
set firewall ipv4 name WAN_IN rule 20 description 'Allow PVE 8006 DNAT'
set firewall ipv4 name WAN_IN rule 20 action accept
set firewall ipv4 name WAN_IN rule 20 protocol tcp
set firewall ipv4 name WAN_IN rule 20 destination address 192.168.1.12
set firewall ipv4 name WAN_IN rule 20 destination port 8006
 
# Attach WAN_IN to wlan0 (wireless interface)
# set interfaces <wan-type> <wan-if> firewall in name WAN_IN   # e.g., 'wireless wlan0' or 'ethernet eth0'
set interfaces wireless wlan0 firewall in name wlan0
 
commit
save

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

Optional: hairpin for LAN clients using the WAN IP

If machines on 192.168.1.0/24 will reach the service via the gateway’s WAN IP (not the VM IP), add a second DNAT for hairpin:

# On gw1 (repeat on gw2 with its WAN IP if needed)
set nat destination rule 11435 description 'Hairpin 8006 LAN->WANIP -> VM'
set nat destination rule 11435 inbound-interface <lan-if>
set nat destination rule 11435 protocol tcp
set nat destination rule 11435 destination address <gw1-wan-ip>
set nat destination rule 11435 destination port 8006
set nat destination rule 11435 translation address 192.168.1.3 # LAN Clients IP
set nat destination rule 11435 translation port 8006
commit; save

Hairpin NAT (aka NAT loopback or U-turn NAT) lets a host inside your LAN reach a service that you’ve published on the gateway’s WAN IP, even though the server is also inside the LAN.

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

Graph View

Backlinks