VyOS is a linux-based CLI-only router distribution. It is designed to act as a router appliance, offering complex enterprise-grade routing and switching features to any user for free.
It is based on a modifed Debian base, so can run anywhere Debian would run. It is suitable for both physical installations - prefered for production border firewalls - as well as virtual installs - good for testing and VM-only networking.
This guide will document the steps required to take a clean VyOS install and set up the basic functions required to use it as a router at the edge of a test or residential network, including NAT, port forwarding, DHCP client function for the external IP, DHCP server functions for internal networking. With these functions, you can replace any standard consumer edge router with a far more powerful and secure device.
Further information can be found in the VyOS user’s guide
For the initial install, boot from the bootable media, and login with username and password of “vyos.”
From there, run command
install image and follow the prompts.
vyos@vyos:~$ install image
When complete, reboot.
As with other unix systems and networking equipment, there are multiple security contexts with greater or lesser privilege.
To enter “edit” mode on vyos, which allows configuration to be edited, not just read,
vyos@vyos:~$ configure  vyos@vyos#
configure mode, the
 tag will be displayed on each shell prompt,
as well as the
$ turning into a
#, which is used to seperate a root shell from
a nonroot shell.
When you are complete with changes, type
commit. This will take the configuration
changes you have made and make them live.
Workflow with Save command
IMPORTANT: when you finish your configuration session, it is critical to run the
from a configuration shell context.
This stores the current committed configuration to the startup config. Running
commit writes the
current config to memory, while running
save writes it to the startup.
The general workflow of a configuration session should look like:
vyos@vyos:~$ configure vyos@vyos# [your configuration commands] vyos@vyos# [your configuration commands] vyos@vyos# commit vyos@vyos# save vyos@vyos# exit
Similarly, you can specify a paramater on where to save the file, if you don’t want to store to the startup config. This can also be used for backups of the current running config. Try any one of these commands below.
vyos@vyos# save /local/file/path/config.conf vyos@vyos# save scp://email@example.com/path/to/file.config vyos@vyos# save ftp://firstname.lastname@example.org/path/to/file.config vyos@vyos# save tftp://remote.host/router.config
The first step in any system build is setting the hostname.
vyos@vyos# set system host-name [fw01] vyos@vyos# set system domain-name [corp.example.com] vyos@vyos# commit
Now, we’ll set the system’s timezone. After typing the command, press
multiple times to see the options, and select yours by continuing to type.
vyos@vyos# set system time-zone [TAB]
During installation, you set a password for the
vyos user. You can
add additional users using the following two commands. The user
is being created with the following details:
- username: jsmith
- Full name: John Smith
- Password: mypassword
vyos@vyos# set system login user jsmith full-name "John Smith" vyos@vyos# set system login user jsmith authentication plaintext-password mypassword
Additionally, you can delete users (such as the default
vyos user, which is
recommended) by running the following command. Note that you can not delete
the currently logged in user. Below, we’ll delete the default user after
adding our own.
Note: you will need to log out and login as your new user
you can delete the default user.
vyos@vyos# delete system login user vyos
Passwords are insecure for SSH login - the best practice is to use SSH public/ private key pairs.
To specify a key for a user, use command below.
 vyos@vyos# set system login user [username] authentication public-keys '[key-name-string]' key "AAAAB3Nz...." vyos@vyos# set system login user [username] authentication public-keys '[key-name-string]' type ssh-rsa
Most router configurations feature a singlular outside/wan interface, and one or more inside interfaces for various features.
Begin by enumeration the interfaces on the system.
vyos@vyos# show interfaces
The system then lists all the interfaces and their mac addresses.
Then, we will set up the interfaces we found. We’ll set up one outside interface with DHCP, and one inner interface with an IP, a configuration suitable for a standard residential or small business network.
Setup the external DHCP WAN interface:
vyos@vyos# set interfaces ethernet eth0 address dhcp vyos@vyos# set interfaces ethernet eth0 description 'OUTSIDE'
Setup the static inside LAN interface:
vyos@vyos# set interfaces ethernet eth1 address '192.168.0.1/24' vyos@vyos# set interfaces ethernet eth1 description 'INSIDE'
Finally, set the DNS server for the router.
vyos@vyos# set system name-server 184.108.40.206 vyos@vyos# set system name-server 220.127.116.11
Next, you can enable SSH. The command below starts SSH listening on all the router’s IPs.
vyos@vyos# set service ssh port 22
NOTE: this also exposes SSH access on the public OUTSIDE interface. Use with caution. Adding firewall rules to limit to internal use only is recommended.
Internal NAT (src nat)
By default, VyOS only routes packets. Additional setup is required to allow
multiple devices to share a public IP on the WAN connection (
Set the following configuration. Replace
eth0 with your OUTSIDE interface,
source address IP with your device’s INSIDE IP.
vyos@vyos# set nat source rule 100 outbound-interface 'eth0' vyos@vyos# set nat source rule 100 source address '192.168.0.0/24' vyos@vyos# set nat source rule 100 translation address masquerade
DHCP Server for Internal Clients
VyOS can act as a DHCP server if you wish.
Set the basic config for the DHCP clients.
LAN is an arbitrary string naming the DHCP instance.
vyos@vyos# set service dhcp-server shared-network-name 'LAN' authoritative vyos@vyos# set service dhcp-server shared-network-name 'LAN' subnet 192.168.0.0/24 default-router 192.168.0.1 vyos@vyos# set service dhcp-server shared-network-name 'LAN' subnet 192.168.0.0/24 dns-server 192.168.0.1 vyos@vyos# set service dhcp-server shared-network-name 'LAN' subnet 192.168.0.0/24 lease 1800 vyos@vyos# set service dhcp-server shared-network-name 'LAN' subnet 192.168.0.0/24 range 0 start 192.168.0.100 vyos@vyos# set service dhcp-server shared-network-name 'LAN' subnet 192.168.0.0/24 range 0 stop 192.168.0.200
Setup DNS forwarder
VyOS can be set up to be a DNS forwarder, including caching. This allows clients to query the VyOS device for DNS, and it can pass on requests to public DNS servers.
Replace the interface with your INSIDE interface.
vyos@vyos# set service dns forwarding system vyos@vyos# set service dns forwarding listen-address '192.168.0.1' vyos@vyos# set service dns forwarding allow-from '192.168.0.0/24'
You’re now configured! Switch your network interfaces and test to ensure it works as expected!