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
Role | Hostname | LAN IP | Floating IP | WAN Interface | LAN Interface | vrid |
---|---|---|---|---|---|---|
Primary VyOS | vyos-1 | 192.168.1.2/24 | 192.168.1.4/24 | wlan0 | eth0 | 4 |
Secondary VyOS | vyos-2 | 192.168.1.3/24 | 192.168.1.4/24 | wlan0 | eth0 | 4 |
- 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
- stp enables the spanning tree protocol (stp) to prevent loops.
- Assign an IP address to the bridge for LAN gateway access.
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)