Setting up a VyOS router for your homelab gives you enterprise-grade networking with open-source flexibility. In this post, we’ll cover the essential steps to install and configure VyOS for a more secure and efficient network.
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 offers powerful routing, firewalling, making it an excellent choice for homelabbers who want more than what consumer routers can provide. In this post, we’ll walk you through the essential steps to install and configure VyOS, so you can build a more secure and efficient network tailored to your needs.
Installation
Note: VyOS rolling release images are built from the latest development code, incorporating the newest changes from maintainers and community contributors. While they receive automated testing to ensure they boot and load configurations, they may include experimental features, bugs, and compatibility issues. As a result, they are not recommended for production use.
VyOS can run on various diffrent platforms. Both baremetal as well als cloud platforms. In this guide we will use the “bare metal” installation inside of a VM.
After you download the latests version, boot from the image using the appropriate method for your platform (USB, virtual machine, or PXE).
Once the image loads, log in with the default credentials (vyos/vyos). In operational mode, run install image and follow the wizard. It will guide you through partitioning the disk and configuring the root password. After installation, remove the live USB or CD and reboot the system.
Operational modes
VyOS has two main operational modes: Operational Mode and Configuration Mode. Understanding these modes is key to managing and configuring the system effectively.
- Operational Mode: This is the default mode when you log in. It’s used for monitoring, troubleshooting, and running system commands. Here, you can check interfaces, view logs, test connectivity, and restart services. Commands in this mode do not change the system’s configuration
- Configuration Mode: This mode is used to modify the system’s settings. To enter configuration mode
We need to enter configuration mode to configure our initial setup.
1configureLAN
We’ll configure the LAN ports to establish a network connection for all your devices. This will ensure that both your homelab and internet access are set up properly, providing seamless connectivity throughout your network.
Bridge Interface
We’ll create a bridge interface, allowing us to combine all the ports into a single network. This will enable seamless communication between all your devices on the same network.
1set interfaces bridge br0
2set interfaces bridge br0 description LAN bridge
3set interfaces bridge br0 address 192.168.1.1/24
4set interfaces bridge br0 member interface eth0
5commit; saveIn this setup I only have one interface in the bridge. You repeat the interfaces bridge br0 member interface eth0 command for every interface you want to be part of the bridge.
You can check the bridge with the command run show bridge br0
1admin@BR01:~$ run show interfaces bridge
2Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
3Interface IP Address S/L Description
4--------- ---------- --- -----------
5br0 192.168.1.1/24 u/u When in Configuration Mode, you normally can’t run operational commands like show. However, you can use run before the command to execute it without leaving Configuration Mode.
DHCP
Now, we’ll set up a DHCP server to automatically assign IP addresses to all the devices connected to your network.
1set service dhcp-server shared-network-name LAN authoritative
2set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 lease 86400
3set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option default-router 192.168.1.1
4set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 option name-server 192.168.1.1
5set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 range 0 start 192.168.1.100
6set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 range 0 stop 192.168.1.200
7set service dhcp-server shared-network-name LAN subnet 192.168.1.0/24 subnet-id 1
8commit; saveTo view active leases from connected clients, use the command: run show dhcp server leases
1admin@BR01:~$ run show dhcp server leases
2IP Address MAC address State Lease start Lease expiration Remaining Pool Hostname Origin
3------------- ----------------- ------- ------------------------- ------------------------- ----------- ------ ----------- --------
4192.168.1.100 bc:24:11:82:b2:20 active 2025-03-19 17:31:03+00:00 2025-03-20 17:31:03+00:00 23:41:55 LAN ubuntu-test local
5192.168.1.101 bc:24:11:89:c8:77 active 2025-03-19 17:36:13+00:00 2025-03-20 17:36:13+00:00 23:47:05 LAN ubuntu-test localWAN
As a next step we will configure our WAN internet connection. As we need this interface for the next steps we will configure it first. In my case I use a VLAN (vif) interface with DHCP, as it is required by my ISP.
Be sure to replace the placeholder variables [inside brackets] with values specific to your setup.
1set interfaces ethernet [YOUR_ETHERNET_INTERFACE] vif [VLAN_ID] address dhcp
2set interfaces ethernet [YOUR_ETHERNET_INTERFACE] vif [VLAN_ID] description WAN-Interface
3commit; save1set interfaces ethernet eth1 address dhcp
2set interfaces ethernet eth1 description WAN-Interface
3commit; save1set interfaces ethernet [YOUR_ETHERNET_INTERFACE] vif [VLAN_ID] description WAN-Interface
2set interfaces pppoe pppoe0 authentication username [YOUR_USERNAME]
3set interfaces pppoe pppoe0 authentication password [YOUR_PASSWORD]
4set interfaces pppoe pppoe0 source-interface [YOUR_ETHERNET_INTERFACE].[VLAN_ID]
5set interfaces pppoe pppoe0 default-route auto
6set interfaces pppoe pppoe0 mtu 1492
7set interfaces pppoe pppoe0 description WAN-Interface
8commit;save1set interfaces pppoe pppoe0 authentication username [YOUR_USERNAME]
2set interfaces pppoe pppoe0 authentication password [YOUR_PASSWORD]
3set interfaces pppoe pppoe0 source-interface [YOUR_ETHERNET_INTERFACE]
4set interfaces pppoe pppoe0 default-route auto
5set interfaces pppoe pppoe0 mtu 1492
6set interfaces pppoe pppoe0 description WAN-Interface
7commit; save1set interfaces ethernet [YOUR_ETHERNET_INTERFACE] description WAN-Interface
2set interfaces ethernet [YOUR_ETHERNET_INTERFACE] address [YOUR_STATIC_IP]/[PREFIX_LENGTH]
3set interfaces ethernet [YOUR_ETHERNET_INTERFACE] mtu 1500
4set protocols static route 0.0.0.0/0 next-hop [YOUR_GATEWAY_IP]
5set system name-server [PRIMARY_DNS]
6set system name-server [SECONDARY_DNS]
7commit; saveAfter the commit we can check if the routing table is correct. There should be a at least an 0.0.0.0 route in the table.
1admin@BR01# run show ip route
2Codes: K - kernel route, C - connected, L - local, S - static,
3 R - RIP, O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,
4 T - Table, v - VNC, V - VNC-Direct, A - Babel, F - PBR,
5 f - OpenFabric, t - Table-Direct,
6 > - selected route, * - FIB route, q - queued, r - rejected, b - backup
7 t - trapped, o - offload failure
8
9S>* 0.0.0.0/0 [210/0] via 85.146.118.xx, eth1.300, weight 1, 00:00:16
10C>* 85.146.118.xx/25 is directly connected, eth1.300, weight 1, 00:00:17
11K * 85.146.118.xx/25 [0/0] is directly connected, eth1.300, weight 1, 00:00:17
12L>* 85.146.118.xx/32 is directly connected, eth1.300, weight 1, 00:00:17
13C>* 192.168.1.0/24 is directly connected, br0, weight 1, 00:07:15
14L>* 192.168.1.1/32 is directly connected, br0, weight 1, 00:07:15Firewall
In VyOS (and most firewall systems using Netfilter/iptables), traffic filtering is managed through three main chains: INPUT, OUTPUT, and FORWARD. Understanding these chains is crucial for configuring firewall rules effectively.
Input Chain
This controls incoming traffic destined for the VyOS router itself. For example, SSH access to the router or web management interfaces would be filtered by the INPUT chain.
1set firewall ipv4 input filter rule 10 action 'accept'
2set firewall ipv4 input filter rule 10 state 'established'
3set firewall ipv4 input filter rule 10 state 'related'
4set firewall ipv4 input filter rule 10 inbound-interface name [YOUR_INTERFACE]
5set firewall ipv4 input filter rule 10 description 'Allow Return traffic destined to the router'
6set firewall ipv4 input filter rule 1000 action 'accept'
7set firewall ipv4 input filter rule 1000 description 'Allow all traffic from LAN interface'
8set firewall ipv4 input filter rule 1000 inbound-interface name br0
9set firewall ipv4 input filter default-action drop
10commit; saveOutput Chain
This manages traffic originating from the VyOS router. If the router itself makes outbound requests (such as NTP synchronization or software updates), they are processed through the OUTPUT chain.
1set firewall ipv4 output filter default-action accept
2commit; saveForward Chain
This handles traffic passing through the router but not directed to or from it. If VyOS is acting as a router between networks, the FORWARD chain determines which packets are allowed to pass between them.
1set firewall ipv4 forward filter rule 20 action 'accept'
2set firewall ipv4 forward filter rule 20 description 'Allow Return traffic through the router'
3set firewall ipv4 forward filter rule 20 state 'established'
4set firewall ipv4 forward filter rule 20 state 'related'
5set firewall ipv4 forward filter rule 20 inbound-interface name [YOUR_INTERFACE]
6set firewall ipv4 forward filter rule 1000 action 'accept'
7set firewall ipv4 forward filter rule 1000 description 'Allow all traffic from LAN interface'
8set firewall ipv4 forward filter rule 1000 inbound-interface name br0
9set firewall ipv4 forward filter default-action drop
10commit; saveDNS
By default, VyOS doesn’t function as a DNS proxy. To enable DNS forwarding from client devices to your upstream DNS servers, you’ll need to configure the following settings:
1set service dns forwarding allow-from '192.168.1.0/24'
2set service dns forwarding listen-address '192.168.1.1'
3set service dns forwarding system
4set system name-server [YOUR_UPSTREAM_DNS_SERVER]
5commit; saveThis configuration:
- Allows DNS requests from devices in the 192.168.1.0/24 subnet
- Sets your VyOS router (192.168.1.1) as the listening address for DNS requests
- Enables system-wide DNS forwarding
- Forwards requests to your specified upstream DNS server
Remember to replace [YOUR_UPSTREAM_DNS_SERVER] with the actual IP address of your preferred DNS server.
NAT
We’ll now set up a NAT rule to translate all outgoing traffic from your local network to your public IP address. This will enable devices in your homelab to access the internet using the router’s public IP, ensuring proper routing and security for all outgoing connections.
1set nat source rule 10 description 'Enable NAT on WAN-Interface'
2set nat source rule 10 outbound-interface name [YOUR_INTERFACE]
3set nat source rule 10 translation address 'masquerade'
4commit; saveSystem
Hostname
It’s a good idea to set the Hostname of the system to something that is easily identifiable. I will call mine BR01
1set system host-name BR01
2commit; saveNTP
By default, VyOS acts as an NTP server for clients. This is usually unnecessary for home use, so it’s best to disable it.
1delete service ntp allow-client
2commit; saveVyOS defaults to NTP servers in the US, Germany, and Singapore (AWS). For better accuracy, use servers closer to your location. I’ll be using NL-based servers from pool.ntp.org since I’m located in the Netherlands.
1delete service ntp server time1.vyos.net
2delete service ntp server time2.vyos.net
3delete service ntp server time3.vyos.net
4set service ntp server 0.nl.pool.ntp.org
5set service ntp server 1.nl.pool.ntp.org
6set service ntp server 2.nl.pool.ntp.org
7set service ntp server 3.nl.pool.ntp.org
8set system time-zone Europe/Amsterdam
9commit; saveUser
For security best practices, it’s recommended to remove the default vyos user and create a new one with administrative privileges. Even thought the command suggest that the password will be saved in plaintext, when committing the changes the system will encrypt it by default.
1set system login user admin authentication plaintext-password admin
2commit; savechange admin to your username and password.
Now login with your new user account to make sure everything works. After that delete the vyos user account.
1delete system login user vyos
2commit; saveNow your VyOS router is fully configured and ready to power your homelab! 🎉 With a secure and efficient network in place, you can focus on building and exploring your homelab projects. Happy networking! 🤝
