Difference between revisions of "User Guide"

From VyOS Wiki
Jump to: navigation, search
(QoS and Traffic Policy)
 
(42 intermediate revisions by 12 users not shown)
Line 1: Line 1:
{{TOC right}}  
+
{{Migrate progress | url = https://vyos.readthedocs.io/en/latest/index.html }}
 +
 
 +
{{TOC right}}
  
 
The VyOS User Guide is focused on providing a general overview of the installation, configuration, and operation of the VyOS network operating system.
 
The VyOS User Guide is focused on providing a general overview of the installation, configuration, and operation of the VyOS network operating system.
 +
 +
(There is an alternative form of documentation on [https://vyos.readthedocs.io/en/latest/ readthedocs.io] which is generated from the sources at [https://github.com/vyos/vyos-documentation github/vyos/vyos-documentation])
  
 
== Introduction ==
 
== Introduction ==
  
VyOS is a Linux-based network operating system that provides software-based network routing, firewall, and VPN functionality.
+
VyOS is a Linux-based network operating system that provides software-based network routing, firewall, and VPN functionality.
  
 
The VyOS project was started in late 2013 as a community fork of the [http://en.wikipedia.org/wiki/GNU_General_Public_License GPL] portions of Vyatta Core 6.6R1 with the goal of maintaining a free and open source network operating system in response to the decision to discontinue the community edition of Vyatta. Here everyone loves learning, older managers and new users.
 
The VyOS project was started in late 2013 as a community fork of the [http://en.wikipedia.org/wiki/GNU_General_Public_License GPL] portions of Vyatta Core 6.6R1 with the goal of maintaining a free and open source network operating system in response to the decision to discontinue the community edition of Vyatta. Here everyone loves learning, older managers and new users.
Line 12: Line 16:
  
 
== Installation ==
 
== Installation ==
 +
 +
{{Main|Installation}}
  
 
The latest ISO image for VyOS can be downloaded at [http://www.vyos.net/ www.vyos.net].
 
The latest ISO image for VyOS can be downloaded at [http://www.vyos.net/ www.vyos.net].
Line 21: Line 27:
 
  Linux vyatta 3.3.8-1-amd64-vyatta #1 SMP Wed Oct 30 22:54:40 CET 2013 x86_64
 
  Linux vyatta 3.3.8-1-amd64-vyatta #1 SMP Wed Oct 30 22:54:40 CET 2013 x86_64
 
  Welcome to VyOS.
 
  Welcome to VyOS.
  This system is open-source software. The exact distribution terms for  
+
  This system is open-source software. The exact distribution terms for
  each module comprising the full system are described in the individual  
+
  each module comprising the full system are described in the individual
 
  files in /usr/share/doc/*/copyright.
 
  files in /usr/share/doc/*/copyright.
 
  Last login: Wed Dec 11 17:33:09 2013
 
  Last login: Wed Dec 11 17:33:09 2013
  vyos@vyos:~$  
+
  vyos@vyos:~$
  
 
Unlike general purpose Linux distributions, VyOS uses "image installation" that mimics the user experience of traditional hardware routers and allows you to keep multiple VyOS versions on the
 
Unlike general purpose Linux distributions, VyOS uses "image installation" that mimics the user experience of traditional hardware routers and allows you to keep multiple VyOS versions on the
Line 37: Line 43:
 
To install VyOS, run '''install image'''.
 
To install VyOS, run '''install image'''.
  
  vyos@vyos:~$ '''install image'''  
+
  vyos@vyos:~$ '''install image'''
 
  Welcome to the VyOS install program.  This script
 
  Welcome to the VyOS install program.  This script
 
  will walk you through the process of installing the
 
  will walk you through the process of installing the
Line 48: Line 54:
 
  or would you rather partition it manually with parted?  If
 
  or would you rather partition it manually with parted?  If
 
  you have already setup your partitions, you may skip this step
 
  you have already setup your partitions, you may skip this step
+
 
  Partition (Auto/Parted/Skip) [Auto]: '''[return]'''  
+
  Partition (Auto/Parted/Skip) [Auto]: '''[return]'''
+
 
 
  I found the following drives on your system:
 
  I found the following drives on your system:
 
   sda  2147MB
 
   sda  2147MB
+
 
+
 
 
  Install the image on? [sda]: '''[return]'''
 
  Install the image on? [sda]: '''[return]'''
+
 
 
  This will destroy all data on /dev/sda.
 
  This will destroy all data on /dev/sda.
 
  Continue? (Yes/No) [No]: '''Yes'''
 
  Continue? (Yes/No) [No]: '''Yes'''
+
 
 
  How big of a root partition should I create? (1000MB - 2147MB) [2147]MB: '''[return]'''
 
  How big of a root partition should I create? (1000MB - 2147MB) [2147]MB: '''[return]'''
+
 
 
  Creating filesystem on /dev/sda1: OK
 
  Creating filesystem on /dev/sda1: OK
 
  Done!
 
  Done!
 
  Mounting /dev/sda1...
 
  Mounting /dev/sda1...
  What would you like to name this image? [VyOS_999.hydrogen.11291501]:  
+
  What would you like to name this image? [VyOS_999.hydrogen.11291501]: '''[return]'''
 
  OK.  This image will be named: VyOS_999.hydrogen.11291501
 
  OK.  This image will be named: VyOS_999.hydrogen.11291501
 
  Copying squashfs image...
 
  Copying squashfs image...
Line 74: Line 80:
 
     /opt/vyatta/etc/config.boot.default
 
     /opt/vyatta/etc/config.boot.default
 
  Which one should I copy to sda? [/config/config.boot]: '''[return]'''
 
  Which one should I copy to sda? [/config/config.boot]: '''[return]'''
+
 
 
  Copying /config/config.boot to sda.
 
  Copying /config/config.boot to sda.
 
  Enter password for administrator account
 
  Enter password for administrator account
Line 82: Line 88:
 
  I found the following drives on your system:
 
  I found the following drives on your system:
 
   sda  2147MB
 
   sda  2147MB
+
 
+
 
 
  Which drive should GRUB modify the boot partition on? [sda]: '''[return]'''
 
  Which drive should GRUB modify the boot partition on? [sda]: '''[return]'''
+
 
 
  Setting up grub: OK
 
  Setting up grub: OK
 
  Done!
 
  Done!
  vyos@vyos:~$  
+
  vyos@vyos:~$
  
 
After the installation is complete, remove the Live CD and reboot the system:
 
After the installation is complete, remove the Live CD and reboot the system:
  
  vyos@vyos:~$ '''reboot'''  
+
  vyos@vyos:~$ '''reboot'''
 
  Proceed with reboot? (Yes/No) [No] '''Yes'''
 
  Proceed with reboot? (Yes/No) [No] '''Yes'''
 
  vyos@vyos:~$
 
  vyos@vyos:~$
  
 
== Using the Command-Line Interface ==
 
== Using the Command-Line Interface ==
 +
 +
{{Main|Command line interface}}
  
 
The VyOS CLI comprises an '''operational mode''' and a '''configuration mode'''.
 
The VyOS CLI comprises an '''operational mode''' and a '''configuration mode'''.
Line 106: Line 114:
 
For example typing '''sh''' followed by the '''[tab]''' key will complete to '''show'''.  Pressing '''[tab]''' a second time will display the possible sub-commands of the show command.
 
For example typing '''sh''' followed by the '''[tab]''' key will complete to '''show'''.  Pressing '''[tab]''' a second time will display the possible sub-commands of the show command.
  
  vyos@vyos:~$ '''s[tab]'''
+
  vyos@vyos:~$ s[tab]
  set  show
+
  set  show
 
  vyos@vyos:~$
 
  vyos@vyos:~$
  
 
Example showing possible show commands:
 
Example showing possible show commands:
  
  vyos@vyos:~$ '''show [tab]'''
+
  vyos@vyos:~$ show [tab]
 
  Possible completions:
 
  Possible completions:
 
   arp          Show Address Resolution Protocol (ARP) information
 
   arp          Show Address Resolution Protocol (ARP) information
Line 118: Line 126:
 
   cluster      Show clustering information
 
   cluster      Show clustering information
 
   configuration Show running configuration
 
   configuration Show running configuration
   conntrack    Show conntrack entries in the conntrack table  
+
   conntrack    Show conntrack entries in the conntrack table
 
   conntrack-sync
 
   conntrack-sync
 
                 Show connection syncing information
 
                 Show connection syncing information
Line 134: Line 142:
 
   host          Show host information
 
   host          Show host information
 
   incoming      Show ethernet input-policy information
 
   incoming      Show ethernet input-policy information
  : '''q'''
+
  : q
 
  vyos@vyos:~$
 
  vyos@vyos:~$
  
Line 140: Line 148:
  
 
When viewing in page mode the following commands are available:
 
When viewing in page mode the following commands are available:
* '''[q]''' key can be used to cancel output
+
* <code>[q]</code> key can be used to cancel output
* '''[space]''' will scroll down one page
+
* <code>[space]</code> will scroll down one page
* '''[b]''' will scroll back one page
+
* <code>[b]</code> will scroll back one page
* '''[return]''' will scroll down one line
+
* <code>[return]</code> will scroll down one line
* '''[up-arrow]''' and '''[down-arrow]''' will scroll up or down one line at a time respectively
+
* <code>[up-arrow]</code> and <code>[down-arrow]</code> will scroll up or down one line at a time respectively
* '''[left-arrow]''' and '''[right-arrow]''' can be used to scroll left or right in the event that the output has lines which exceed the terminal size.
+
* <code>[left-arrow]</code> and <code>[right-arrow]</code> can be used to scroll left or right in the event that the output has lines which exceed the terminal size.
  
 
To enter configuration mode use the '''configure''' command:
 
To enter configuration mode use the '''configure''' command:
  
  vyos@vyos:~$ '''configure'''
+
  vyos@vyos:~$ configure
 
  [edit]
 
  [edit]
 
  vyos@vyos:~#
 
  vyos@vyos:~#
Line 155: Line 163:
 
Note that the prompt changes from '''$''' to '''#'''.  To exit configuration mode, type '''exit'''.
 
Note that the prompt changes from '''$''' to '''#'''.  To exit configuration mode, type '''exit'''.
  
  vyos@vyos:~# '''exit'''
+
  vyos@vyos:~# exit
 
  exit
 
  exit
 
  vyos@vyos:~$
 
  vyos@vyos:~$
Line 167: Line 175:
 
Enter configuration mode:
 
Enter configuration mode:
  
  vyos@vyos$ '''configure'''
+
  vyos@vyos$ configure
 
  vyos@vyos#
 
  vyos@vyos#
  
 
Configure network interfaces:
 
Configure network interfaces:
  
  '''set interfaces ethernet eth0 address dhcp'''
+
  set interfaces ethernet eth0 address dhcp
  '''set interfaces ethernet eth0 description 'OUTSIDE''''
+
  set interfaces ethernet eth0 description 'OUTSIDE'
+
 
  '''set interfaces ethernet eth1 address '192.168.0.1/24''''
+
  set interfaces ethernet eth1 address '192.168.0.1/24'
  '''set interfaces ethernet eth1 description 'INSIDE''''
+
  set interfaces ethernet eth1 description 'INSIDE'
  
 
Enable SSH for remote management:
 
Enable SSH for remote management:
  
  '''set service ssh port '22''''
+
  set service ssh port '22'
  
 
Configure Source NAT for our "Inside" network.
 
Configure Source NAT for our "Inside" network.
  
  '''set nat source rule 100 outbound-interface 'eth0''''
+
  set nat source rule 100 outbound-interface 'eth0'
  '''set nat source rule 100 source address '192.168.0.0/24''''
+
  set nat source rule 100 source address '192.168.0.0/24'
  '''set nat source rule 100 translation address masquerade'''
+
  set nat source rule 100 translation address masquerade
  
 
Configure a DHCP Server:
 
Configure a DHCP Server:
  
'''set service dhcp-server disabled 'false''''
+
 
  '''set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 default-router '192.168.0.1''''
+
  set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 default-router '192.168.0.1'
  '''set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 dns-server '192.168.0.1''''
+
  set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 dns-server '192.168.0.1'
  '''set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 domain-name 'internal-network''''
+
  set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 domain-name 'internal-network'
  '''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 lease '86400'
  '''set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 start 192.168.0.9 stop '192.168.0.254''''
+
 
 +
>= 1.2.0
 +
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'
 +
 
 +
<= 1.1.8
 +
  set service dhcp-server disabled 'false'
 +
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 start 192.168.0.9 stop '192.168.0.254'
  
 
And a DNS forwarder:
 
And a DNS forwarder:
  
  '''set service dns forwarding cache-size '0''''
+
  set service dns forwarding cache-size '0'
  '''set service dns forwarding listen-on 'eth1''''
+
  set service dns forwarding listen-on 'eth1'
  '''set service dns forwarding name-server '8.8.8.8''''
+
  set service dns forwarding name-server '8.8.8.8'
  '''set service dns forwarding name-server '8.8.4.4''''
+
  set service dns forwarding name-server '8.8.4.4'
  
 
Add a set of firewall policies for our "Outside" interface:
 
Add a set of firewall policies for our "Outside" interface:
  
  '''set firewall name OUTSIDE-IN default-action 'drop''''
+
  set firewall name OUTSIDE-IN default-action 'drop'
  '''set firewall name OUTSIDE-IN rule 10 action 'accept''''
+
  set firewall name OUTSIDE-IN rule 10 action 'accept'
  '''set firewall name OUTSIDE-IN rule 10 state established 'enable''''
+
  set firewall name OUTSIDE-IN rule 10 state established 'enable'
  '''set firewall name OUTSIDE-IN rule 10 state related 'enable''''
+
  set firewall name OUTSIDE-IN rule 10 state related 'enable'
+
 
  '''set firewall name OUTSIDE-LOCAL default-action 'drop''''
+
  set firewall name OUTSIDE-LOCAL default-action 'drop'
  '''set firewall name OUTSIDE-LOCAL rule 10 action 'accept''''
+
  set firewall name OUTSIDE-LOCAL rule 10 action 'accept'
  '''set firewall name OUTSIDE-LOCAL rule 10 state established 'enable''''
+
  set firewall name OUTSIDE-LOCAL rule 10 state established 'enable'
  '''set firewall name OUTSIDE-LOCAL rule 10 state related 'enable''''
+
  set firewall name OUTSIDE-LOCAL rule 10 state related 'enable'
  '''set firewall name OUTSIDE-LOCAL rule 20 action 'accept''''
+
  set firewall name OUTSIDE-LOCAL rule 20 action 'accept'
  '''set firewall name OUTSIDE-LOCAL rule 20 icmp type-name 'echo-request''''
+
  set firewall name OUTSIDE-LOCAL rule 20 icmp type-name 'echo-request'
  '''set firewall name OUTSIDE-LOCAL rule 20 protocol 'icmp''''
+
  set firewall name OUTSIDE-LOCAL rule 20 protocol 'icmp'
  '''set firewall name OUTSIDE-LOCAL rule 20 state new 'enable''''
+
  set firewall name OUTSIDE-LOCAL rule 20 state new 'enable'
  '''set firewall name OUTSIDE-LOCAL rule 30 action 'drop''''
+
  set firewall name OUTSIDE-LOCAL rule 30 action 'drop'
  '''set firewall name OUTSIDE-LOCAL rule 30 destination port '22''''
+
  set firewall name OUTSIDE-LOCAL rule 30 destination port '22'
  '''set firewall name OUTSIDE-LOCAL rule 30 protocol 'tcp''''
+
  set firewall name OUTSIDE-LOCAL rule 30 protocol 'tcp'
  '''set firewall name OUTSIDE-LOCAL rule 30 recent count '4''''
+
  set firewall name OUTSIDE-LOCAL rule 30 recent count '4'
  '''set firewall name OUTSIDE-LOCAL rule 30 recent time '60''''
+
  set firewall name OUTSIDE-LOCAL rule 30 recent time '60'
  '''set firewall name OUTSIDE-LOCAL rule 30 state new 'enable''''
+
  set firewall name OUTSIDE-LOCAL rule 30 state new 'enable'
  '''set firewall name OUTSIDE-LOCAL rule 31 action 'accept''''
+
  set firewall name OUTSIDE-LOCAL rule 31 action 'accept'
  '''set firewall name OUTSIDE-LOCAL rule 31 destination port '22''''
+
  set firewall name OUTSIDE-LOCAL rule 31 destination port '22'
  '''set firewall name OUTSIDE-LOCAL rule 31 protocol 'tcp''''
+
  set firewall name OUTSIDE-LOCAL rule 31 protocol 'tcp'
  '''set firewall name OUTSIDE-LOCAL rule 31 state new 'enable''''
+
  set firewall name OUTSIDE-LOCAL rule 31 state new 'enable'
  
 
Apply the firewall policies:
 
Apply the firewall policies:
  
  '''set interfaces ethernet eth0 firewall in name 'OUTSIDE-IN''''
+
  set interfaces ethernet eth0 firewall in name 'OUTSIDE-IN'
  '''set interfaces ethernet eth0 firewall local name 'OUTSIDE-LOCAL''''
+
  set interfaces ethernet eth0 firewall local name 'OUTSIDE-LOCAL'
  
 
Commit changes, save the configuration, and exit configuration mode:
 
Commit changes, save the configuration, and exit configuration mode:
  
  vyos@vyos# '''commit'''
+
  vyos@vyos# commit
  vyos@vyos# '''save'''
+
  vyos@vyos# save
 
  Saving configuration to '/config/config.boot'...
 
  Saving configuration to '/config/config.boot'...
 
  Done
 
  Done
  vyos@vyos# '''exit'''
+
 
 +
  vyos@vyos# exit
 
  vyos@vyos$
 
  vyos@vyos$
  
Line 250: Line 266:
 
The current configuration can be viewed using the '''show configuration''' command.
 
The current configuration can be viewed using the '''show configuration''' command.
  
  vyos@vyos:~$ '''show configuration'''
+
  vyos@vyos:~$ show configuration
 
  interfaces {
 
  interfaces {
 
     ethernet eth0 {
 
     ethernet eth0 {
Line 287: Line 303:
 
         }
 
         }
 
         server 2.pool.ntp.org {
 
         server 2.pool.ntp.org {
        }
 
    }
 
    package {
 
        repository community {
 
            components main
 
            distribution hydrogen
 
            url http://packages.vyos.net/vyos
 
 
         }
 
         }
 
     }
 
     }
Line 307: Line 316:
 
     }
 
     }
 
  }
 
  }
  vyos@vyos:~$  
+
  vyos@vyos:~$
  
 
Because configuration changes are made using '''set''' and '''delete''' commands, the commands to generate the active configuration can also be displayed using the '''show configuration commands''' command.
 
Because configuration changes are made using '''set''' and '''delete''' commands, the commands to generate the active configuration can also be displayed using the '''show configuration commands''' command.
  
  vyos@vyos:~$ '''show configuration commands'''
+
  vyos@vyos:~$ show configuration commands
 
  set interfaces ethernet eth0 address 'dhcp'
 
  set interfaces ethernet eth0 address 'dhcp'
 
  set interfaces ethernet eth0 hw-id '00:0c:29:44:3b:0f'
 
  set interfaces ethernet eth0 hw-id '00:0c:29:44:3b:0f'
Line 323: Line 332:
 
  set system ntp server '1.pool.ntp.org'
 
  set system ntp server '1.pool.ntp.org'
 
  set system ntp server '2.pool.ntp.org'
 
  set system ntp server '2.pool.ntp.org'
set system package repository community components 'main'
 
set system package repository community distribution 'stable'
 
set system package repository community url 'http://packages.vyos.net/vyos'
 
 
  set system syslog global facility all level 'notice'
 
  set system syslog global facility all level 'notice'
 
  set system syslog global facility protocols level 'debug'
 
  set system syslog global facility protocols level 'debug'
  vyos@vyos:~$  
+
  vyos@vyos:~$
  
 
Configuration changes made do not take effect until committed using the '''commit''' command in configuration mode.
 
Configuration changes made do not take effect until committed using the '''commit''' command in configuration mode.
  
  vyos@vyos# '''commit'''
+
  vyos@vyos# commit
 
  [edit]
 
  [edit]
  vyos@vyos# '''exit'''
+
 
 +
  vyos@vyos# exit
 
  Warning: configuration changes have not been saved.
 
  Warning: configuration changes have not been saved.
exit
+
 
 
  vyos@vyos:~$
 
  vyos@vyos:~$
  
 
In order to preserve configuration changes upon reboot, the configuration must also be saved once applied.  This is done using the '''save''' command in configuration mode.
 
In order to preserve configuration changes upon reboot, the configuration must also be saved once applied.  This is done using the '''save''' command in configuration mode.
  
  vyos@vyos# '''save'''
+
  vyos@vyos# save
 
  Saving configuration to '/config/config.boot'...
 
  Saving configuration to '/config/config.boot'...
 
  Done
 
  Done
Line 349: Line 356:
 
The '''show''' command within configuration mode will show the current configuration indicating line changes with a '''+''' for additions and a '''-''' for deletions.
 
The '''show''' command within configuration mode will show the current configuration indicating line changes with a '''+''' for additions and a '''-''' for deletions.
  
  vyos@vyos:~$ '''configure'''
+
  vyos@vyos:~$ configure
 
  [edit]
 
  [edit]
  vyos@vyos# '''show interfaces'''   
+
 
  ethernet eth0 {
+
  vyos@vyos# show interfaces
      address dhcp
+
  ethernet eth0 {
      hw-id 00:0c:29:44:3b:0f
+
      address dhcp
  }
+
      hw-id 00:0c:29:44:3b:0f
  loopback lo {
+
  }
  }
+
  loopback lo {
 +
  }
 
  [edit]
 
  [edit]
  vyos@vyos# '''set interfaces ethernet eth0 description 'OUTSIDE''''
+
 
 +
  vyos@vyos# set interfaces ethernet eth0 description 'OUTSIDE'
 
  [edit]
 
  [edit]
  vyos@vyos# show interfaces  
+
  vyos@vyos# show interfaces
 
   ethernet eth0 {
 
   ethernet eth0 {
 
       address dhcp
 
       address dhcp
  '''+'''   description OUTSIDE
+
  +    description OUTSIDE
 
       hw-id 00:0c:29:44:3b:0f
 
       hw-id 00:0c:29:44:3b:0f
 
   }
 
   }
Line 374: Line 383:
 
Configuration mode can not be exited while uncommitted changes exist.  To exit configuration mode without applying changes, the '''exit discard''' command can be used.
 
Configuration mode can not be exited while uncommitted changes exist.  To exit configuration mode without applying changes, the '''exit discard''' command can be used.
  
  vyos@vyos# '''exit''' 
+
  vyos@vyos# exit
 
  Cannot exit: configuration modified.
 
  Cannot exit: configuration modified.
 
  Use 'exit discard' to discard the changes and exit.
 
  Use 'exit discard' to discard the changes and exit.
 
  [edit]
 
  [edit]
  vyos@vyos# '''exit discard'''
+
  vyos@vyos# exit discard
 
  exit
 
  exit
  vyos@vyos:~$  
+
  vyos@vyos:~$
  
 
VyOS also maintains backups of previous configurations.  To compare configuration revisions in configuration mode, use the '''compare''' command:
 
VyOS also maintains backups of previous configurations.  To compare configuration revisions in configuration mode, use the '''compare''' command:
  
  vyos@vyos# '''compare [tab]'''
+
  vyos@vyos# compare [tab]
 
  Possible completions:
 
  Possible completions:
 
   <Enter> Compare working & active configurations
 
   <Enter> Compare working & active configurations
Line 390: Line 399:
 
   <N> Compare working with revision N
 
   <N> Compare working with revision N
 
   <N> <M> Compare revision N with M
 
   <N> <M> Compare revision N with M
+
 
 
   Revisions:
 
   Revisions:
 
     0 2013-12-17 20:01:37 root by boot-config-loader
 
     0 2013-12-17 20:01:37 root by boot-config-loader
Line 403: Line 412:
 
     9 2013-12-12 15:42:07 root by boot-config-loader
 
     9 2013-12-12 15:42:07 root by boot-config-loader
 
     10 2013-12-12 15:42:06 root by init
 
     10 2013-12-12 15:42:06 root by init
+
 
     
+
 
 
  [edit]
 
  [edit]
 
  vyos@vyos#
 
  vyos@vyos#
Line 410: Line 419:
 
You can rollback configuration using the '''rollback''' command, however this command will currently trigger a system reboot.
 
You can rollback configuration using the '''rollback''' command, however this command will currently trigger a system reboot.
  
  vyos@vyos# '''compare 1'''
+
  vyos@vyos# compare 1
 
  [edit system]
 
  [edit system]
 
  >host-name vyos-1
 
  >host-name vyos-1
 
  [edit]
 
  [edit]
  vyos@vyos# '''rollback 1'''
+
  vyos@vyos# rollback 1
 
  Proceed with reboot? [confirm][y]
 
  Proceed with reboot? [confirm][y]
+
 
 
  Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013):
 
  Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013):
+
 
 
  The system is going down for reboot NOW!
 
  The system is going down for reboot NOW!
 
  [edit]
 
  [edit]
Line 426: Line 435:
 
VyOS also supports saving and loading configuration remotely using SCP, FTP, or TFTP.
 
VyOS also supports saving and loading configuration remotely using SCP, FTP, or TFTP.
  
  vyos@vyos# '''save [tab]'''
+
  vyos@vyos# save [tab]
 
  Possible completions:
 
  Possible completions:
 
   <Enter>      Save to system config file
 
   <Enter>      Save to system config file
Line 434: Line 443:
 
   tftp://<host>/<file>      Save to file on remote machine
 
   tftp://<host>/<file>      Save to file on remote machine
  
  vyos@vyos# '''save tftp://192.168.0.100/vyos-test.config.boot'''
+
  vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot
 
  Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'...
 
  Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'...
 
  ######################################################################## 100.0%
 
  ######################################################################## 100.0%
 
  Done
 
  Done
 
  
 
== Network Interfaces ==
 
== Network Interfaces ==
Line 444: Line 452:
 
Configured interfaces on a VyOS system can be displayed using the '''show interfaces''' command.
 
Configured interfaces on a VyOS system can be displayed using the '''show interfaces''' command.
  
  vyos@vyos:~$ '''show interfaces'''           
+
  vyos@vyos:~$ show interfaces
 
  Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
 
  Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
 
  Interface        IP Address                        S/L  Description
 
  Interface        IP Address                        S/L  Description
 
  ---------        ----------                        ---  -----------
 
  ---------        ----------                        ---  -----------
  eth0            172.16.51.129/24                  u/u  OUTSIDE  
+
  eth0            172.16.51.129/24                  u/u  OUTSIDE
  eth1            192.168.0.1/24                    u/u  INSIDE  
+
  eth1            192.168.0.1/24                    u/u  INSIDE
  lo              127.0.0.1/8                      u/u
+
  lo              127.0.0.1/8                      u/u
 
                   ::1/128
 
                   ::1/128
  vyos@vyos:~$  
+
  vyos@vyos:~$
  
 
A specific interface can be shown using the '''show interfaces <type> <name>''' command.
 
A specific interface can be shown using the '''show interfaces <type> <name>''' command.
  
  vyos@vyos:~$ '''show interfaces ethernet eth0'''
+
  vyos@vyos:~$ show interfaces ethernet eth0
 
  eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000
 
  eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000
 
     link/ether 00:0c:29:44:3b:0f brd ff:ff:ff:ff:ff:ff
 
     link/ether 00:0c:29:44:3b:0f brd ff:ff:ff:ff:ff:ff
 
     inet 172.16.51.129/24 brd 172.16.51.255 scope global eth0
 
     inet 172.16.51.129/24 brd 172.16.51.255 scope global eth0
     inet6 fe80::20c:29ff:fe44:3b0f/64 scope link  
+
     inet6 fe80::20c:29ff:fe44:3b0f/64 scope link
 
         valid_lft forever preferred_lft forever
 
         valid_lft forever preferred_lft forever
 
     Description: OUTSIDE
 
     Description: OUTSIDE
+
 
 
     RX:  bytes    packets    errors    dropped    overrun      mcast
 
     RX:  bytes    packets    errors    dropped    overrun      mcast
 
         274397      3064          0          0          0          0
 
         274397      3064          0          0          0          0
Line 472: Line 480:
 
Each interface can be configured with a description and address.
 
Each interface can be configured with a description and address.
  
  '''set interfaces ethernet eth0 description 'OUTSIDE''''
+
  set interfaces ethernet eth0 description 'OUTSIDE'
  '''set interfaces ethernet eth0 address 'dhcp''''
+
  set interfaces ethernet eth0 address 'dhcp'
  
 
Different network interfaces provide type-specific configuration.  Ethernet interfaces, for example, allow the configuration of speed and duplex.
 
Different network interfaces provide type-specific configuration.  Ethernet interfaces, for example, allow the configuration of speed and duplex.
Line 480: Line 488:
  
 
=== Ethernet Interfaces ===
 
=== Ethernet Interfaces ===
 +
 +
{{Main|Ethernet#Ethernet_Interfaces}}
  
 
Ethernet interfaces allow for the configuration of speed, duplex, and hw-id (MAC address).  Below is an example configuration:
 
Ethernet interfaces allow for the configuration of speed, duplex, and hw-id (MAC address).  Below is an example configuration:
  
  '''set interfaces ethernet eth1 address '192.168.0.1/24''''
+
  set interfaces ethernet eth1 address '192.168.0.1/24'
  '''set interfaces ethernet eth1 description 'INSIDE''''
+
  set interfaces ethernet eth1 description 'INSIDE'
  '''set interfaces ethernet eth1 duplex 'auto''''
+
  set interfaces ethernet eth1 duplex 'auto'
  '''set interfaces ethernet eth1 speed 'auto''''
+
  set interfaces ethernet eth1 speed 'auto'
  
 
Resulting in:
 
Resulting in:
Line 499: Line 509:
 
     }
 
     }
  
In addition, Ethernet interfaces provide the extended operational commands '''show interfaces ethernet <name> physical''' and '''show interfaces ethernet <name> statistics'''.  Statistics available are driver dependent.
+
set interfaces ethernet eth1 disable
 +
 
 +
Will disable an existing interface.
  
  vyos@vyos:~$ '''show interfaces ethernet eth0 physical'''
+
 
 +
In addition, Ethernet interfaces provide the extended operational commands '''show interfaces ethernet <name> physical''' and '''show interfaces ethernet <name> statistics'''.  Statistics available are driver dependent.
 +
 
 +
  vyos@vyos:~$ show interfaces ethernet eth0 physical
 
  Settings for eth0:
 
  Settings for eth0:
 
         Supported ports: [ TP ]
 
         Supported ports: [ TP ]
         Supported link modes:  10baseT/Half 10baseT/Full  
+
         Supported link modes:  10baseT/Half 10baseT/Full
                                 100baseT/Half 100baseT/Full  
+
                                 100baseT/Half 100baseT/Full
                                 1000baseT/Full  
+
                                 1000baseT/Full
 
         Supports auto-negotiation: Yes
 
         Supports auto-negotiation: Yes
         Advertised link modes:  10baseT/Half 10baseT/Full  
+
         Advertised link modes:  10baseT/Half 10baseT/Full
                                 100baseT/Half 100baseT/Full  
+
                                 100baseT/Half 100baseT/Full
                                 1000baseT/Full  
+
                                 1000baseT/Full
 
         Advertised pause frame use: No
 
         Advertised pause frame use: No
 
         Advertised auto-negotiation: Yes
 
         Advertised auto-negotiation: Yes
Line 526: Line 541:
 
  driver: e1000
 
  driver: e1000
 
  version: 7.3.21-k8-NAPI
 
  version: 7.3.21-k8-NAPI
  firmware-version:  
+
  firmware-version:
 
  bus-info: 0000:02:01.0
 
  bus-info: 0000:02:01.0
vyos@vyos:~$
+
 
  vyos@vyos:~$ '''show interfaces ethernet eth0 statistics'''
+
  vyos@vyos:~$ show interfaces ethernet eth0 statistics
 
  NIC statistics:
 
  NIC statistics:
 
       rx_packets: 3530
 
       rx_packets: 3530
 
       tx_packets: 2179
 
       tx_packets: 2179
  [...]  
+
  [...]
  
 
=== VLAN Sub-Interfaces (802.1Q) ===
 
=== VLAN Sub-Interfaces (802.1Q) ===
Line 539: Line 554:
 
802.1Q VLAN interfaces are represented as virtual sub-interfaces in VyOS.  The term used for this is '''vif'''.  Configuration of a tagged sub-interface is accomplished using the configuration command '''set interfaces ethernet <name> vif <vlan-id>'''.
 
802.1Q VLAN interfaces are represented as virtual sub-interfaces in VyOS.  The term used for this is '''vif'''.  Configuration of a tagged sub-interface is accomplished using the configuration command '''set interfaces ethernet <name> vif <vlan-id>'''.
  
  '''set interfaces ethernet eth1 vif 100 description 'VLAN 100''''
+
  set interfaces ethernet eth1 vif 100 description 'VLAN 100'
  '''set interfaces ethernet eth1 vif 100 address '192.168.100.1/24''''
+
  set interfaces ethernet eth1 vif 100 address '192.168.100.1/24'
  
 
Resulting:
 
Resulting:
 
 
     ethernet eth1 {
 
     ethernet eth1 {
 
         address 192.168.0.1/24
 
         address 192.168.0.1/24
Line 559: Line 573:
 
VLAN interfaces are shown as <name>.<vlan-id>, e.g. eth1.100:
 
VLAN interfaces are shown as <name>.<vlan-id>, e.g. eth1.100:
  
  vyos@vyos:~$ '''show interfaces'''
+
  vyos@vyos:~$ show interfaces
 
  Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
 
  Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
 
  Interface        IP Address                        S/L  Description
 
  Interface        IP Address                        S/L  Description
 
  ---------        ----------                        ---  -----------
 
  ---------        ----------                        ---  -----------
  eth0            172.16.51.129/24                  u/u  OUTSIDE  
+
  eth0            172.16.51.129/24                  u/u  OUTSIDE
  eth1            192.168.0.1/24                    u/u  INSIDE  
+
  eth1            192.168.0.1/24                    u/u  INSIDE
  eth1.100        192.168.100.1/24                  u/u  VLAN 100  
+
  eth1.100        192.168.100.1/24                  u/u  VLAN 100
  lo              127.0.0.1/8                      u/u
+
  lo              127.0.0.1/8                      u/u
 
                   ::1/128
 
                   ::1/128
vyos@vyos:~$
 
 
 
=== Bridging ===
 
=== Bridging ===
  
Line 576: Line 588:
 
A bridge is created when a bridge interface is defined.  In the example below we will be creating a bridge for VLAN 100 and assigning a VIF to the bridge.
 
A bridge is created when a bridge interface is defined.  In the example below we will be creating a bridge for VLAN 100 and assigning a VIF to the bridge.
  
  '''set interfaces bridge 'br100''''
+
  set interfaces bridge 'br100'
  '''set interfaces ethernet eth1 vif 100 bridge-group bridge br100'''
+
  set interfaces ethernet eth1 vif 100 bridge-group bridge br100
  
 
Interfaces assigned to a bridge-group do not have address configuration.  An IP address can be assigned to the bridge interface itself, however, like any normal interface.
 
Interfaces assigned to a bridge-group do not have address configuration.  An IP address can be assigned to the bridge interface itself, however, like any normal interface.
  
  '''set interfaces bridge br100 address '192.168.100.1/24''''
+
  set interfaces bridge br100 address '192.168.100.1/24'
  
 
Example Result:
 
Example Result:
  
    bridge br100 {
+
bridge br100 {
        address 192.168.100.1/24
+
    address 192.168.100.1/24
    }
+
}
 
  [...]
 
  [...]
    ethernet eth1 {
+
ethernet eth1 {
 
  [...]
 
  [...]
        vif 100 {
+
    vif 100 {
            bridge-group {
+
        bridge-group {
                bridge br100
+
            bridge br100
            }
+
        }
        }
+
    }
    }
+
}
  
In addition to normal IP interface configuration, bridge interfaces support Spanning-Tree Protocol. STP is disabled by default.
+
In addition to normal IP interface configuration, bridge interfaces support Spanning-Tree Protocol. STP is disabled by default.
  
 
'''NOTE:''' Please use caution when introducing spanning-tree protocol on a network as it may result in topology changes.
 
'''NOTE:''' Please use caution when introducing spanning-tree protocol on a network as it may result in topology changes.
Line 604: Line 616:
 
To enable spanning-tree use the '''set interfaces bridge <name> stp true''' command:
 
To enable spanning-tree use the '''set interfaces bridge <name> stp true''' command:
  
  '''set interfaces bridge br100 stp true'''
+
  set interfaces bridge br100 stp true
  
 
STP '''priority''', '''forwarding-delay''', '''hello-time''', and '''max-age''' can be configured for the bridge-group.  The MAC aging time can also be configured using the '''aging''' directive.
 
STP '''priority''', '''forwarding-delay''', '''hello-time''', and '''max-age''' can be configured for the bridge-group.  The MAC aging time can also be configured using the '''aging''' directive.
Line 612: Line 624:
 
The '''show bridge''' operational command can be used to display configured bridges:
 
The '''show bridge''' operational command can be used to display configured bridges:
  
  vyos@vyos:~$ '''show bridge'''
+
  vyos@vyos:~$ show bridge
 
  bridge name    bridge id              STP enabled    interfaces
 
  bridge name    bridge id              STP enabled    interfaces
 
  br100          0000.000c29443b19      yes            eth1.100
 
  br100          0000.000c29443b19      yes            eth1.100
vyos@vyos:~$
 
  
 
If spanning-tree is enabled, the '''show bridge <name> spanning-tree''' command can be used to show STP configuration:
 
If spanning-tree is enabled, the '''show bridge <name> spanning-tree''' command can be used to show STP configuration:
+
 
  vyos@vyos:~$ '''show bridge br100 spanning-tree'''
+
  vyos@vyos:~$ show bridge br100 spanning-tree
 
  br100
 
  br100
 
   bridge id              0000.000c29443b19
 
   bridge id              0000.000c29443b19
Line 630: Line 641:
 
   hello timer              0.47                tcn timer                  0.00
 
   hello timer              0.47                tcn timer                  0.00
 
   topology change timer    0.00                gc timer                  64.63
 
   topology change timer    0.00                gc timer                  64.63
   flags                
+
   flags
+
 
 
  eth1.100 (1)
 
  eth1.100 (1)
 
   port id                8001                    state                forwarding
 
   port id                8001                    state                forwarding
Line 638: Line 649:
 
   designated port        8001                    forward delay timer        0.00
 
   designated port        8001                    forward delay timer        0.00
 
   designated cost          0                    hold timer                0.00
 
   designated cost          0                    hold timer                0.00
   flags                
+
   flags
 
vyos@vyos:~$
 
  
 
The MAC address-table for a bridge can be displayed using the '''show bridge <name> macs''' command:
 
The MAC address-table for a bridge can be displayed using the '''show bridge <name> macs''' command:
  
  vyos@vyos:~$ '''show bridge br100 macs'''         
+
  vyos@vyos:~$ show bridge br100 macs
 
  port no mac addr                is local?      ageing timer
 
  port no mac addr                is local?      ageing timer
 
   1    00:0c:29:44:3b:19      yes                0.00
 
   1    00:0c:29:44:3b:19      yes                0.00
vyos@vyos:~$
 
  
 
=== Bonding ===
 
=== Bonding ===
Line 654: Line 662:
  
 
Create interface bondX, where X is just a number:
 
Create interface bondX, where X is just a number:
  '''set interfaces bonding bond0 description 'my-sw1 int 23 and 24''''
+
  set interfaces bonding bond0 description 'my-sw1 int 23 and 24'
  
 
You are able to choose a hash policy:
 
You are able to choose a hash policy:
  vyos@vyos# '''set interfaces bonding bond0 hash-policy'''
+
  vyos@vyos# set interfaces bonding bond0 hash-policy
 
  Possible completions:
 
  Possible completions:
 
   layer2      use MAC addresses to generate the hash (802.3ad)
 
   layer2      use MAC addresses to generate the hash (802.3ad)
Line 664: Line 672:
  
 
For example:
 
For example:
  '''set interfaces bonding bond0 hash-policy 'layer2''''
+
  set interfaces bonding bond0 hash-policy 'layer2'
  
 
You may want to set IEEE 802.3ad Dynamic link aggregation (802.3ad) AKA LACP (don't forget to setup it on the other end of these links):
 
You may want to set IEEE 802.3ad Dynamic link aggregation (802.3ad) AKA LACP (don't forget to setup it on the other end of these links):
  '''set interfaces bonding bond0 mode '802.3ad''''
+
  set interfaces bonding bond0 mode '802.3ad'
 
or some other modes:
 
or some other modes:
  vyos@vyos# '''set interfaces bonding bond0 mode'''
+
  vyos@vyos# set interfaces bonding bond0 mode
 
  Possible completions:
 
  Possible completions:
 
   802.3ad      IEEE 802.3ad Dynamic link aggregation (Default)
 
   802.3ad      IEEE 802.3ad Dynamic link aggregation (Default)
Line 683: Line 691:
  
 
Now bond some physical interfaces into bond0:
 
Now bond some physical interfaces into bond0:
  '''set interfaces ethernet eth0 bond-group 'bond0''''
+
  set interfaces ethernet eth0 bond-group 'bond0'
  '''set interfaces ethernet eth0 description 'member of bond0''''
+
  set interfaces ethernet eth0 description 'member of bond0'
  '''set interfaces ethernet eth1 bond-group 'bond0''''
+
  set interfaces ethernet eth1 bond-group 'bond0'
  '''set interfaces ethernet eth1 description 'member of bond0''''
+
  set interfaces ethernet eth1 description 'member of bond0'
  
 
After a commit you may treat bond0 as almost a physical interface (you can't change its` duplex, for example) and assign IPs or VIFs on it.
 
After a commit you may treat bond0 as almost a physical interface (you can't change its` duplex, for example) and assign IPs or VIFs on it.
  
 
You may check the result:
 
You may check the result:
  vyos@vyos# '''run sh interfaces bonding'''
+
  vyos@vyos# run sh interfaces bonding
 
  Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
 
  Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
 
  Interface        IP Address                        S/L  Description
 
  Interface        IP Address                        S/L  Description
 
  ---------        ----------                        ---  -----------
 
  ---------        ----------                        ---  -----------
 
  bond0            -                                u/u  my-sw1 int 23 and 24
 
  bond0            -                                u/u  my-sw1 int 23 and 24
  bond0.10        192.168.0.1/24                    u/u  office-net  
+
  bond0.10        192.168.0.1/24                    u/u  office-net
 
  bond0.100        10.10.10.1/24                    u/u  management-net
 
  bond0.100        10.10.10.1/24                    u/u  management-net
  
Line 703: Line 711:
 
Set Virtual Tunnel interface
 
Set Virtual Tunnel interface
  
  '''set interfaces vti vti0 address 192.168.2.249/30'''
+
  set interfaces vti vti0 address 192.168.2.249/30
  
  vyos@vyos# '''show interfaces vti'''
+
  vyos@vyos# show interfaces vti
 
  vti vti0 {
 
  vti vti0 {
 
     address 192.168.2.249/30
 
     address 192.168.2.249/30
Line 712: Line 720:
  
 
== Routing ==
 
== Routing ==
VyOS is a "router first" network operating system. It supports static routing, policy routing, and dynamic routing using standard protocols (RIP, OSPF, and BGP).
+
 
 +
VyOS is a "router first" network operating system. It supports static routing, policy routing, and dynamic routing using standard protocols (RIP, OSPF, and BGP).
  
 
=== Static ===
 
=== Static ===
  
Static routes are manually configured network routes.
+
Static routes are manually configured network routes.
  
 
A typical use for a static route is a static default route for systems that do not make use of DHCP or dynamic routing protocols:
 
A typical use for a static route is a static default route for systems that do not make use of DHCP or dynamic routing protocols:
  
  '''set protocols static route 0.0.0.0/0 next-hop 203.0.113.1 distance '1''''
+
  set protocols static route 0.0.0.0/0 next-hop 203.0.113.1 distance '1'
  
 
Producing the following configuration:
 
Producing the following configuration:
Line 732: Line 741:
 
  }
 
  }
  
Another common use of static routes is to blackhole (drop) traffic.  In the example below, RFC 1918 private IP networks are set as blackhole routes.  This does not prevent networks within these segments from being used, since the most specific route is always used.  It does, however, prevent traffic to unknown private networks from leaving the router.  Commonly refereed to as leaking.
+
Another common use of static routes is to blackhole (drop) traffic.  In the example below, RFC 1918 private IP networks are set as blackhole routes.  This does not prevent networks within these segments from being used, since the most specific route is always used.  It does, however, prevent traffic to unknown private networks from leaving the router.  Commonly referred to as leaking.
  
  '''set protocols static route 10.0.0.0/8 blackhole distance '254''''
+
  set protocols static route 10.0.0.0/8 blackhole distance '254'
  '''set protocols static route 172.16.0.0/12 blackhole distance '254''''
+
  set protocols static route 172.16.0.0/12 blackhole distance '254'
  '''set protocols static route 192.168.0.0/16 blackhole distance '254''''
+
  set protocols static route 192.168.0.0/16 blackhole distance '254'
  
 
Resulting configuration:
 
Resulting configuration:
Line 763: Line 772:
 
Node 1:
 
Node 1:
  
  '''set interfaces loopback address 1.1.1.1/32 '''
+
  set interfaces loopback address 1.1.1.1/32
  '''set protocols rip network 192.168.0.0/24'''
+
  set protocols rip network 192.168.0.0/24
  '''set protocols rip redistribute connected'''
+
  set protocols rip redistribute connected
  
 
Node 2:
 
Node 2:
  '''set interfaces loopback address 2.2.2.2/32 '''
+
  set interfaces loopback address 2.2.2.2/32
  '''set protocols rip network 192.168.0.0/24'''
+
  set protocols rip network 192.168.0.0/24
  '''set protocols rip redistribute connected'''
+
  set protocols rip redistribute connected
  
  
 
Resulting configuration:
 
Resulting configuration:
  
Node 1:
+
'''Node 1:'''
  ''rip{ ''
+
  rip {
''    network 192.168.0.0/24 ''
+
    network 192.168.0.0/24
''    redistribute { ''
+
    redistribute {
''      connected { ''
+
        connected {
''        } ''
+
        }
''    } ''
+
    }
  ''} ''
+
  }
 
  
Node 2:
+
'''Node 2:'''
  ''rip{ ''
+
  rip {
''    network 192.168.0.0/24 ''
+
    network 192.168.0.0/24
''    redistribute { ''
+
    redistribute {
''      connected { ''
+
        connected {
''        } ''
+
        }
''    } ''
+
    }
  ''} ''
+
  }
  
 
=== OSPF ===
 
=== OSPF ===
 +
 
==== IPv4 ====
 
==== IPv4 ====
 +
 
A typical configuration using 2 nodes, redistribute loopback address and the node 1 sending the default route:
 
A typical configuration using 2 nodes, redistribute loopback address and the node 1 sending the default route:
  
Node 1:
+
'''Node 1:'''
 
+
set interfaces loopback lo address 1.1.1.1/32
'''set interfaces loopback lo address 1.1.1.1/32 '''
+
  set protocols ospf area 0 network 192.168.0.0/24'''
  '''set protocols ospf area 0 network 192.168.0.0/24'''
+
  set protocols ospf default-information originate always'''
  '''set protocols ospf default-information originate always'''
+
  set protocols ospf default-information originate metric 10'''
  '''set protocols ospf default-information originate metric 10'''
+
  set protocols ospf default-information originate metric-type 2'''
  '''set protocols ospf default-information originate metric-type 2'''
+
  set protocols ospf log-adjacency-changes'''
  '''set protocols ospf log-adjacency-changes'''
+
  set protocols ospf parameters router-id 1.1.1.1'''
  '''set protocols ospf parameters router-id 1.1.1.1'''
+
  set protocols ospf redistribute connected metric-type 2'''
  '''set protocols ospf redistribute connected metric-type 2'''
+
  set protocols ospf redistribute connected route-map CONNECT'''
  '''set protocols ospf redistribute connected route-map CONNECT'''
 
  
  '''set policy route-map CONNECT rule 10 action permit'''
+
  set policy route-map CONNECT rule 10 action permit'''
  '''set policy route-map CONNECT rule 10 match interface lo'''
+
  set policy route-map CONNECT rule 10 match interface lo'''
  
  
Node 2:
+
'''Node 2:'''
'''set interfaces loopback lo address 2.2.2.2/32 '''
+
set interfaces loopback lo address 2.2.2.2/32
  '''set protocols ospf area 0 network 192.168.0.0/24 '''
+
  set protocols ospf area 0 network 192.168.0.0/24
  '''set protocols ospf log-adjacency-changes '''
+
  set protocols ospf log-adjacency-changes
  '''set protocols ospf parameters router-id 2.2.2.2 '''
+
  set protocols ospf parameters router-id 2.2.2.2
  '''set protocols ospf redistribute connected metric-type 2 '''
+
  set protocols ospf redistribute connected metric-type 2
  '''set protocols ospf redistribute connected route-map CONNECT '''
+
  set protocols ospf redistribute connected route-map CONNECT
  
  '''set policy route-map CONNECT rule 10 action permit '''
+
  set policy route-map CONNECT rule 10 action permit
  '''set policy route-map CONNECT rule 10 match interface lo '''
+
  set policy route-map CONNECT rule 10 match interface lo
  
  
 
Resulting configuration:
 
Resulting configuration:
  
Node 1:
+
'''Node 1:'''
  ''ospf { ''
+
  ospf {
''    area 0 { ''
+
    area 0 {
''        network 192.168.0.0/24 ''
+
        network 192.168.0.0/24
''     } ''
+
     }
''     default-information { ''
+
     default-information {
''        originate { ''
+
        originate {
''            always ''
+
            always
''            metric 10 ''
+
            metric 10
''            metric-type 2 ''
+
            metric-type 2
''        } ''
+
        }
''     } ''
+
     }
''     log-adjacency-changes { ''
+
     log-adjacency-changes {
''     } ''
+
     }
''     parameters { ''
+
     parameters {
''         router-id 1.1.1.1 ''
+
         router-id 1.1.1.1
''     } ''
+
     }
''     redistribute { ''
+
     redistribute {
''         connected { ''
+
         connected {
''             metric-type 2 ''
+
             metric-type 2
''             route-map CONNECT ''
+
             route-map CONNECT
''         } ''
+
         }
''     } ''
+
     }
  '' } ''
+
  }
  
  ''route-map CONNECT {''
+
  route-map CONNECT {''
''    rule 10 {''
+
    rule 10 {''
''        action permit''
+
        action permit''
''        match {''
+
        match {''
''          interface lo''
+
            interface lo''
''      }''
+
        }''
''  }''
+
  }''
'' }''
+
  }''
  
  
Node 2:
+
'''Node 2:'''
  ''ospf { ''
+
  ospf {
''    area 0 { ''
+
    area 0 {
''        network 192.168.0.0/24 ''
+
        network 192.168.0.0/24
''     } ''
+
     }
''     log-adjacency-changes { ''
+
     log-adjacency-changes {
''     } ''
+
     }
''     parameters { ''
+
     parameters {
''         router-id 2.2.2.2 ''
+
         router-id 2.2.2.2
''     } ''
+
     }
''     redistribute { ''
+
     redistribute {
''         connected { ''
+
         connected {
''             metric-type 2 ''
+
             metric-type 2
''             route-map CONNECT ''
+
             route-map CONNECT
''         } ''
+
         }
''     } ''
+
     }
  '' } ''
+
  }
  
  ''route-map CONNECT {''
+
  route-map CONNECT {
''    rule 10 {''
+
    rule 10 {
''        action permit''
+
        action permit
''        match {''
+
        match {
''          interface lo''
+
          interface lo
''      }''
+
        }
''  }''
+
    }
  '' }''
+
  }
  
 
==== IPv6 ====
 
==== IPv6 ====
Line 897: Line 906:
 
Node 1:
 
Node 1:
  
  '''set protocols ospfv3 area 0.0.0.0 interface eth1 '''
+
  set protocols ospfv3 area 0.0.0.0 interface eth1
  '''set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64 '''
+
  set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64
  '''set protocols ospfv3 parameters router-id 192.168.1.1 '''
+
  set protocols ospfv3 parameters router-id 192.168.1.1
  '''set protocols ospfv3 redistribute connected '''
+
  set protocols ospfv3 redistribute connected
  
 
Node 2:
 
Node 2:
  
  '''set protocols ospfv3 area 0.0.0.0 interface eth1 '''
+
  set protocols ospfv3 area 0.0.0.0 interface eth1
  '''set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64 '''
+
  set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64
  '''set protocols ospfv3 parameters router-id 192.168.2.1 '''
+
  set protocols ospfv3 parameters router-id 192.168.2.1
  '''set protocols ospfv3 redistribute connected '''
+
  set protocols ospfv3 redistribute connected
  
 
Resulting configuration:
 
Resulting configuration:
  
Node 1:
+
'''Node 1:'''
 +
protocols {
 +
  ospfv3 {
 +
    area 0.0.0.0 {
 +
        interface eth1
 +
        range 2001:db8:1::/64 {
 +
        }
 +
    }
 +
    parameters {
 +
        router-id 192.168.1.1
 +
    }
 +
    redistribute {
 +
        connected {
 +
        }
 +
    }
 +
  }
 +
}
  
''protocols {
 
''ospfv3 {
 
''    area 0.0.0.0 {
 
''        interface eth1
 
''        range 2001:db8:1::/64 {
 
''        }
 
''    }
 
''    parameters {
 
''        router-id 192.168.1.1
 
''    }
 
''    redistribute {
 
''        connected {
 
''        }
 
''    }
 
''  }
 
''}
 
  
Node 2:
+
'''Node 2:'''
 +
protocols {
 +
  ospfv3 {
 +
    area 0.0.0.0 {
 +
        interface eth1
 +
        range 2001:db8:2::/64 {
 +
        }
 +
    }
 +
    parameters {
 +
        router-id 192.168.2.1
 +
    }
 +
    redistribute {
 +
        connected {
 +
        }
 +
    }
 +
  }
 +
}
 +
 
  
''protocols { ''
 
''ospfv3 { ''
 
''    area 0.0.0.0 { ''
 
''        interface eth1 ''
 
''        range 2001:db8:2::/64 { ''
 
''        } ''
 
''    } ''
 
''    parameters { ''
 
''        router-id 192.168.2.1 ''
 
''    } ''
 
''    redistribute { ''
 
''        connected { ''
 
''        } ''
 
''    } ''
 
''  } ''
 
''} ''
 
 
=== BGP ===
 
=== BGP ===
 +
 
==== IPv4 ====
 
==== IPv4 ====
 
A simple eBGP configuration:
 
A simple eBGP configuration:
  
Node 1:
+
'''Node 1:'''
 +
set protocols bgp 65536 neighbor 192.168.0.2 ebgp-multihop '2'
 +
set protocols bgp 65536 neighbor 192.168.0.2 remote-as '65537'
 +
set protocols bgp 65536 neighbor 192.168.0.2 update-source ‘192.168.0.1
 +
set protocols bgp 65536 network '1.0.0.0/16'
 +
set protocols bgp 65536 parameters router-id ‘192.168.0.1
  
'''set protocols bgp 65536 neighbor 192.168.0.2 ebgp-multihop '2' '''
+
'''Node 2:'''
  '''set protocols bgp 65536 neighbor 192.168.0.2 remote-as '65537' '''
+
set protocols bgp 65537 neighbor 192.168.0.1 ebgp-multihop '2'
  '''set protocols bgp 65536 neighbor 192.168.0.2 update-source ‘192.168.0.1 '''
+
  set protocols bgp 65537 neighbor 192.168.0.1 remote-as '65536’
  '''set protocols bgp 65536 network '1.0.0.0/16' '''
+
  set protocols bgp 65537 neighbor 192.168.0.1 update-source ‘192.168.0.2
  '''set protocols bgp 65536 parameters router-id ‘192.168.0.1 '''
+
  set protocols bgp 65537 network 2.0.0.0/16'
 +
  set protocols bgp 65537 parameters router-id ‘192.168.0.2
  
Node 2:
 
'''set protocols bgp 65537 neighbor 192.168.0.1 ebgp-multihop '2' '''
 
'''set protocols bgp 65537 neighbor 192.168.0.1 remote-as '65536’ '''
 
'''set protocols bgp 65537 neighbor 192.168.0.1 update-source ‘192.168.0.2 '''
 
'''set protocols bgp 65537 network 2.0.0.0/16' '''
 
'''set protocols bgp 65537 parameters router-id ‘192.168.0.2 '''
 
  
 
+
Don’t forget, the CIDR declared in the network statement MUST''' exist in your routing table (dynamic or static), the best way to make sure that is true is creating a static route:
Don’t forget, the CIDR declared in the network statement '''MUST''' exist in your routing table (dynamic or static), the best way to make sure that is true is creating a static route:
 
  
 
Node 1:
 
Node 1:
  '''set protocols static route 1.0.0.0/16 blackhole distance '254' '''
+
  set protocols static route 1.0.0.0/16 blackhole distance '254'
  
  
 
Node 2:
 
Node 2:
  '''set protocols static route 2.0.0.0/16 blackhole distance '254' '''
+
  set protocols static route 2.0.0.0/16 blackhole distance '254'
  
  
 
Resulting configuration:
 
Resulting configuration:
  
Node 1:
+
'''Node 1:'''
  ''bgp 65536 { ''
+
  bgp 65536 {
''    neighbor 192.168.0.2 { ''
+
    neighbor 192.168.0.2 {
''        ebgp-multihop 2 ''
+
        ebgp-multihop 2
''        remote-as 65537 ''
+
        remote-as 65537
''        update-source 192.168.0.1 ''
+
        update-source 192.168.0.1
''    } ''
+
    }
''    network 1.0.0.0/16 { ''
+
    network 1.0.0.0/16 {
''    } ''
+
    }
''    parameters { ''
+
    parameters {
''        router-id 192.168.0.1 ''
+
        router-id 192.168.0.1
''    } ''
+
    }
  '' } ''
+
  }
  
  ''static { ''
+
  static {
''    route 1.0.0.0/16 { ''
+
    route 1.0.0.0/16 {
''        blackhole { ''
+
        blackhole {
''          distance 254 ''
+
            distance 254
''        } ''
+
        }
  ''    } ''
+
    }
 +
  }
  
  
 +
'''Node 2:'''
 +
bgp 65537 {
 +
    neighbor 192.168.0.1 {
 +
        ebgp-multihop 2
 +
        remote-as 65536
 +
        update-source 192.168.0.2
 +
    }
 +
    network 2.0.0.0/16 {
 +
    }
 +
    parameters {
 +
        router-id 192.168.0.2
 +
    }
 +
}
  
Node 2:
+
  static {
''bgp 65537 { ''
+
    route 2.0.0.0/16 {
''    neighbor 192.168.0.1 { ''
+
        blackhole {
''        ebgp-multihop 2 ''
+
            distance 254
''        remote-as 65536 ''
+
        }
''        update-source 192.168.0.2 ''
+
    }
''    } ''
+
  }
''    network 2.0.0.0/16 { ''
 
''    } ''
 
  ''    parameters { ''
 
''        router-id 192.168.0.2 ''
 
''    } ''
 
'' } ''
 
 
 
 
 
''static { ''
 
''    route 2.0.0.0/16 { ''
 
''        blackhole { ''
 
''          distance 254 ''
 
''        } ''
 
  ''    } ''
 
  
 
==== IPv6 ====
 
==== IPv6 ====
A simple BGP configuration, but over IPv6.
 
  
Node 1:
+
A simple BGP configuration via IPv6.
  
'''set protocols bgp 65536 neighbor 2a00:100::2 ebgp-multihop '2' '''
+
'''Node 1:'''
  '''set protocols bgp 65536 neighbor 2a00:100::2 remote-as '65537' '''
+
set protocols bgp 65536 neighbor 2a00:100::2 ebgp-multihop '2'
  '''set protocols bgp 65536 neighbor 2a00:100::2 update-source '2a00:100::1' '''
+
  set protocols bgp 65536 neighbor 2a00:100::2 remote-as '65537'
  '''set protocols bgp 65536 neighbor 2a00:100::2 address-family ipv6-unicast
+
  set protocols bgp 65536 neighbor 2a00:100::2 update-source '2a00:100::1'
  '''set protocols bgp 65536 address-family ipv6-unicast network '2a00:100:1::/48' '''
+
  set protocols bgp 65536 neighbor 2a00:100::2 address-family ipv6-unicast
  '''set protocols bgp 65536 parameters router-id '1.1.1.1' '''
+
  set protocols bgp 65536 address-family ipv6-unicast network '2a00:100:1::/48'
 +
  set protocols bgp 65536 parameters router-id '1.1.1.1'
  
Node 2:
+
'''Node 2:'''
'''set protocols bgp 65537 neighbor 2a00:100::1 ebgp-multihop '2' '''
+
set protocols bgp 65537 neighbor 2a00:100::1 ebgp-multihop '2'
  '''set protocols bgp 65537 neighbor 2a00:100::1 remote-as '65536' '''
+
  set protocols bgp 65537 neighbor 2a00:100::1 remote-as '65536'
  '''set protocols bgp 65537 neighbor 2a00:100::1 update-source '2a00:100::2' '''
+
  set protocols bgp 65537 neighbor 2a00:100::1 update-source '2a00:100::2'
  '''set protocols bgp 65536 neighbor 2a00:100::1 address-family ipv6-unicast
+
  set protocols bgp 65536 neighbor 2a00:100::1 address-family ipv6-unicast
  '''set protocols bgp 65537 address-family ipv6-unicast network '2a00:100:2::/48' '''
+
  set protocols bgp 65537 address-family ipv6-unicast network '2a00:100:2::/48'
  '''set protocols bgp 65537 parameters router-id '1.1.1.2' '''
+
  set protocols bgp 65537 parameters router-id '1.1.1.2'
  
  
Don’t forget, the CIDR declared in the network statement '''MUST''' exist in your routing table (dynamic or static), the best way to make sure that is true is creating a static route:
+
Don’t forget, the CIDR declared in the network statement MUST exist in your routing table (dynamic or static), the best way to make sure that is true is creating a static route:
  
Node 1:
+
'''Node 1:'''
'''set protocols static route6 2a001:100:1::/48 blackhole distance '254' '''
+
  set protocols static route6 2a001:100:1::/48 blackhole distance '254'
 
 
 
 
Node 2:
 
  '''set protocols static route6 2a00:100:2::/48 blackhole distance '254' '''
 
  
 +
'''Node 2:'''
 +
set protocols static route6 2a00:100:2::/48 blackhole distance '254'
  
 
Resulting configuration:
 
Resulting configuration:
  
Node 1:
+
'''Node 1:'''
  ''bgp 65536 { ''
+
  bgp 65536 {
''    neighbor 2a00:100::2 { ''
+
      neighbor 2a00:100::2 {
''        address-family {
+
          address-family {
''            ipv6-unicast {
+
              ipv6-unicast {
''            }
+
              }
''        }
+
          }
''        ebgp-multihop 2 ''
+
          ebgp-multihop 2
''        remote-as 65537 ''
+
          remote-as 65537
''        update-source 2a00:100::1 ''
+
          update-source 2a00:100::1
''    } ''
+
      }
''    network 2a00:100:1::/48 { ''
+
      network 2a00:100:1::/48 {
''    } ''
+
      }
''    parameters { ''
+
      parameters {
''        router-id 1.1.1.1 ''
+
          router-id 1.1.1.1
''    } ''
+
      }
  '' } ''
+
  }
  
  ''static { ''
+
  static {
''    route6 2a00:100:1::/48 { ''
+
      route6 2a00:100:1::/48 {
''        blackhole { ''
+
        blackhole {
''          distance 254 ''
+
            distance 254
''        } ''
+
        }
  ''    } ''
+
      }
 +
  }
  
 +
'''Node 2:'''
 +
bgp 65537 {
 +
      neighbor 2a00:100::1 {
 +
          address-family {
 +
              ipv6-unicast {
 +
              }
 +
          }
 +
          ebgp-multihop 2
 +
          remote-as 65536
 +
          update-source 2a00:100::2
 +
      }
 +
      network 2a00:100:2::/48 {
 +
      }
 +
      parameters {
 +
          router-id 1.1.1.2
 +
      }
 +
}
  
 
+
  static {
Node 2:
+
      route6 2a00:100:2::/48 {
''bgp 65537 { ''
+
        blackhole {
''    neighbor 2a00:100::1 { ''
+
            distance 254
''        address-family {
+
        }
''            ipv6-unicast {
+
      }
''            }
+
  }
''        }
 
''        ebgp-multihop 2 ''
 
''        remote-as 65536 ''
 
''        update-source 2a00:100::2 ''
 
''    } ''
 
''    network 2a00:100:2::/48 { ''
 
''    } ''
 
''    parameters { ''
 
''        router-id 1.1.1.2 ''
 
''    } ''
 
'' } ''
 
 
 
 
 
  ''static { ''
 
''    route6 2a00:100:2::/48 { ''
 
''        blackhole { ''
 
''          distance 254 ''
 
''        } ''
 
  ''    } ''
 
  
 
==== Route Filtering ====
 
==== Route Filtering ====
 
Route filtering can be applied using a route-map:
 
Route filtering can be applied using a route-map:
  
Node1:
+
'''Node1:'''
'''set policy prefix-list AS65537-IN rule 10 action 'permit' '''
+
set policy prefix-list AS65537-IN rule 10 action 'permit'
  '''set policy prefix-list AS65537-IN rule 10 prefix '2.0.0.0/16' '''
+
  set policy prefix-list AS65537-IN rule 10 prefix '2.0.0.0/16'
  '''set policy prefix-list AS65537-OUT rule 10 action 'deny' '''
+
  set policy prefix-list AS65537-OUT rule 10 action 'deny'
  '''set policy prefix-list AS65537-OUT rule 10 prefix '2.0.0.0/16' '''
+
  set policy prefix-list AS65537-OUT rule 10 prefix '2.0.0.0/16'
  '''set policy prefix-list6 AS65537-IN rule 10 action 'permit' '''
+
  set policy prefix-list6 AS65537-IN rule 10 action 'permit'
  '''set policy prefix-list6 AS65537-IN rule 10 prefix '2a00:100:2::/48' '''
+
  set policy prefix-list6 AS65537-IN rule 10 prefix '2a00:100:2::/48'
  '''set policy prefix-list6 AS65537-OUT rule 10 action 'deny' '''
+
  set policy prefix-list6 AS65537-OUT rule 10 action 'deny'
  '''set policy prefix-list6 AS65537-OUT rule 10 prefix '2a00:100:2::/48' '''
+
  set policy prefix-list6 AS65537-OUT rule 10 prefix '2a00:100:2::/48'
  '''set policy route-map AS65537-IN rule 10 action 'permit' '''
+
  set policy route-map AS65537-IN rule 10 action 'permit'
  '''set policy route-map AS65537-IN rule 10 match ip address prefix-list 'AS65537-IN' '''
+
  set policy route-map AS65537-IN rule 10 match ip address prefix-list 'AS65537-IN'
  '''set policy route-map AS65537-IN rule 10 match ipv6 address prefix-list 'AS65537-IN' '''
+
  set policy route-map AS65537-IN rule 10 match ipv6 address prefix-list 'AS65537-IN'
  '''set policy route-map AS65537-IN rule 20 action 'deny' '''
+
  set policy route-map AS65537-IN rule 20 action 'deny'
  '''set policy route-map AS65537-OUT rule 10 action 'deny' '''
+
  set policy route-map AS65537-OUT rule 10 action 'deny'
  '''set policy route-map AS65537-OUT rule 10 match ip address prefix-list 'AS65537-OUT' '''
+
  set policy route-map AS65537-OUT rule 10 match ip address prefix-list 'AS65537-OUT'
  '''set policy route-map AS65537-OUT rule 10 match ipv6 address prefix-list 'AS65537-OUT' '''
+
  set policy route-map AS65537-OUT rule 10 match ipv6 address prefix-list 'AS65537-OUT'
  '''set policy route-map AS65537-OUT rule 20 action 'permit' '''
+
  set policy route-map AS65537-OUT rule 20 action 'permit'
  '''set protocols bgp 65536 neighbor 2a00:100::2 route-map export 'AS65537-OUT' '''
+
  set protocols bgp 65536 neighbor 2a00:100::2 route-map export 'AS65537-OUT'
  '''set protocols bgp 65536 neighbor 2a00:100::2 route-map import 'AS65537-IN' '''
+
  set protocols bgp 65536 neighbor 2a00:100::2 route-map import 'AS65537-IN'
  
Node2:
+
'''Node2:'''
'''set policy prefix-list AS65536-IN rule 10 action 'permit' '''
+
set policy prefix-list AS65536-IN rule 10 action 'permit'
  '''set policy prefix-list AS65536-IN rule 10 prefix '1.0.0.0/16' '''
+
  set policy prefix-list AS65536-IN rule 10 prefix '1.0.0.0/16'
  '''set policy prefix-list AS65536-OUT rule 10 action 'deny' '''
+
  set policy prefix-list AS65536-OUT rule 10 action 'deny'
  '''set policy prefix-list AS65536-OUT rule 10 prefix '1.0.0.0/16' '''
+
  set policy prefix-list AS65536-OUT rule 10 prefix '1.0.0.0/16'
  '''set policy prefix-list6 AS65536-IN rule 10 action 'permit' '''
+
  set policy prefix-list6 AS65536-IN rule 10 action 'permit'
  '''set policy prefix-list6 AS65536-IN rule 10 prefix '2a00:100:1::/48' '''
+
  set policy prefix-list6 AS65536-IN rule 10 prefix '2a00:100:1::/48'
  '''set policy prefix-list6 AS65536-OUT rule 10 action 'deny' '''
+
  set policy prefix-list6 AS65536-OUT rule 10 action 'deny'
  '''set policy prefix-list6 AS65536-OUT rule 10 prefix '2a00:100:1::/48' '''
+
  set policy prefix-list6 AS65536-OUT rule 10 prefix '2a00:100:1::/48'
  '''set policy route-map AS65536-IN rule 10 action 'permit' '''
+
  set policy route-map AS65536-IN rule 10 action 'permit'
  '''set policy route-map AS65536-IN rule 10 match ip address prefix-list 'AS65536-IN' '''
+
  set policy route-map AS65536-IN rule 10 match ip address prefix-list 'AS65536-IN'
  '''set policy route-map AS65536-IN rule 10 match ipv6 address prefix-list 'AS65536-IN' '''
+
  set policy route-map AS65536-IN rule 10 match ipv6 address prefix-list 'AS65536-IN'
  '''set policy route-map AS65536-IN rule 20 action 'deny' '''
+
  set policy route-map AS65536-IN rule 20 action 'deny'
  '''set policy route-map AS65536-OUT rule 10 action 'deny' '''
+
  set policy route-map AS65536-OUT rule 10 action 'deny'
  '''set policy route-map AS65536-OUT rule 10 match ip address prefix-list 'AS65536-OUT' '''
+
  set policy route-map AS65536-OUT rule 10 match ip address prefix-list 'AS65536-OUT'
  '''set policy route-map AS65536-OUT rule 10 match ipv6 address prefix-list 'AS65536-OUT' '''
+
  set policy route-map AS65536-OUT rule 10 match ipv6 address prefix-list 'AS65536-OUT'
  '''set policy route-map AS65536-OUT rule 20 action 'permit' '''
+
  set policy route-map AS65536-OUT rule 20 action 'permit'
  '''set protocols bgp 65537 neighbor 2a00:100::1 route-map export 'AS65536-OUT' '''
+
  set protocols bgp 65537 neighbor 2a00:100::1 route-map export 'AS65536-OUT'
  '''set protocols bgp 65537 neighbor 2a00:100::1 route-map import 'AS65536-IN' '''
+
  set protocols bgp 65537 neighbor 2a00:100::1 route-map import 'AS65536-IN'
  
 
We could expand on this and also deny link local and multicast in the rule 20 action deny.
 
We could expand on this and also deny link local and multicast in the rule 20 action deny.
Line 1,189: Line 1,196:
  
 
'''Important note on usage of terms:''' The firewall makes use of the terms <code>in</code>, <code>out</code>, and <code>local</code> for firewall policy. Users experienced with netfilter often confuse <code>in</code> to be a reference to the <code>INPUT</code> chain, and <code>out</code> the <code>OUTPUT</code> chain from netfilter.  This is not the case.  These instead indicate the use of the <code>FORWARD</code> chain and either the input or output interface.  The <code>INPUT</code> chain, which is used for local traffic to the OS, is a reference to as <code>local</code> with respect to its input interface.
 
'''Important note on usage of terms:''' The firewall makes use of the terms <code>in</code>, <code>out</code>, and <code>local</code> for firewall policy. Users experienced with netfilter often confuse <code>in</code> to be a reference to the <code>INPUT</code> chain, and <code>out</code> the <code>OUTPUT</code> chain from netfilter.  This is not the case.  These instead indicate the use of the <code>FORWARD</code> chain and either the input or output interface.  The <code>INPUT</code> chain, which is used for local traffic to the OS, is a reference to as <code>local</code> with respect to its input interface.
 
  
 
=== Zone-based Firewall Policy ===
 
=== Zone-based Firewall Policy ===
Line 1,196: Line 1,202:
  
 
An introduction can to zone-based firewalls can be found [[A primer to Zone Based Firewall|here]]. For an example see [[Zone-policy_example|Zone-policy example]].
 
An introduction can to zone-based firewalls can be found [[A primer to Zone Based Firewall|here]]. For an example see [[Zone-policy_example|Zone-policy example]].
 
  
 
=== Groups ===
 
=== Groups ===
Line 1,206: Line 1,211:
 
Here is an example of a network group for the IP networks that make up the internal network:
 
Here is an example of a network group for the IP networks that make up the internal network:
  
  '''set firewall group network-group NET-INSIDE network 192.168.0.0/24'''
+
  set firewall group network-group NET-INSIDE network 192.168.0.0/24
  '''set firewall group network-group NET-INSIDE network 192.168.1.0/24'''
+
  set firewall group network-group NET-INSIDE network 192.168.1.0/24
  
 
A port group represents only port numbers, not the protocol.  Port groups can be referenced for either TCP or UDP.  It is recommended that TCP and UDP groups are created separately to avoid accidentally filtering unnecessary ports.  Ranges of ports can be specified by using a <code>-</code>.
 
A port group represents only port numbers, not the protocol.  Port groups can be referenced for either TCP or UDP.  It is recommended that TCP and UDP groups are created separately to avoid accidentally filtering unnecessary ports.  Ranges of ports can be specified by using a <code>-</code>.
Line 1,213: Line 1,218:
 
Here is an example of a port group a server:
 
Here is an example of a port group a server:
  
  '''set firewall group port-group PORT-TCP-SERVER1 port 80'''
+
  set firewall group port-group PORT-TCP-SERVER1 port 80
  '''set firewall group port-group PORT-TCP-SERVER1 port 443'''
+
  set firewall group port-group PORT-TCP-SERVER1 port 443
  '''set firewall group port-group PORT-TCP-SERVER1 port 5000-5010'''
+
  set firewall group port-group PORT-TCP-SERVER1 port 5000-5010
 
 
  
 
=== Rule-Sets ===
 
=== Rule-Sets ===
Line 1,224: Line 1,228:
 
Example of a rule-set to filter traffic to the internal network:
 
Example of a rule-set to filter traffic to the internal network:
  
  '''set firewall name INSIDE-OUT default-action drop'''
+
  set firewall name INSIDE-OUT default-action drop
  '''set firewall name INSIDE-OUT rule 1010 action accept'''
+
  set firewall name INSIDE-OUT rule 1010 action accept
  '''set firewall name INSIDE-OUT rule 1010 state established enable'''
+
  set firewall name INSIDE-OUT rule 1010 state established enable
  '''set firewall name INSIDE-OUT rule 1010 state related enable'''
+
  set firewall name INSIDE-OUT rule 1010 state related enable
  '''set firewall name INSIDE-OUT rule 1020 action drop'''
+
  set firewall name INSIDE-OUT rule 1020 action drop
  '''set firewall name INSIDE-OUT rule 1020 state invalid enable'''
+
  set firewall name INSIDE-OUT rule 1020 state invalid enable
 
 
  
 
=== Applying a Rule-Set to an Interface ===
 
=== Applying a Rule-Set to an Interface ===
Line 1,236: Line 1,239:
 
Once a rule-set is created, it can be applied to an interface.  Note only one rule-set can be applied to each interface for <code>in</code>, <code>out</code>, or <code>local</code> traffic for each protocol (IPv4 and IPv6).
 
Once a rule-set is created, it can be applied to an interface.  Note only one rule-set can be applied to each interface for <code>in</code>, <code>out</code>, or <code>local</code> traffic for each protocol (IPv4 and IPv6).
  
  '''set interfaces ethernet eth1 firewall out name INSIDE-OUT'''
+
  set interfaces ethernet eth1 firewall out name INSIDE-OUT
 
 
  
 
=== Applying a Rule-Set to a Zone ===
 
=== Applying a Rule-Set to a Zone ===
Line 1,243: Line 1,245:
 
A named rule-set can also be applied to a zone relationship (note, zones must first be created):
 
A named rule-set can also be applied to a zone relationship (note, zones must first be created):
  
  '''set zone-policy zone INSIDE from OUTSIDE firewall name INSIDE-OUT'''
+
  set zone-policy zone INSIDE from OUTSIDE firewall name INSIDE-OUT
  
 +
=== Example Partial Config ===
  
=== Example Partial Config ===
+
firewall {
<pre>
 
firewall {
 
 
     all-ping enable
 
     all-ping enable
 
     broadcast-ping disable
 
     broadcast-ping disable
Line 1,300: Line 1,301:
 
         }
 
         }
 
     }
 
     }
}
+
}
interfaces {
+
interfaces {
 
     ethernet eth1 {
 
     ethernet eth1 {
 
         address dhcp
 
         address dhcp
Line 1,312: Line 1,313:
 
         }
 
         }
 
     }
 
     }
}
+
}
</pre>
 
  
 
[https://www.xfinity.com/support/internet/list-of-blocked-ports/ XFinity Blocked Port List]
 
[https://www.xfinity.com/support/internet/list-of-blocked-ports/ XFinity Blocked Port List]
Line 1,329: Line 1,329:
 
In the example used for the Quick Start configuration above, we demonstrate the following configuration:
 
In the example used for the Quick Start configuration above, we demonstrate the following configuration:
  
  '''set nat source rule 100 outbound-interface 'eth0''''
+
  set nat source rule 100 outbound-interface 'eth0'
  '''set nat source rule 100 source address '192.168.0.0/24''''
+
  set nat source rule 100 source address '192.168.0.0/24'
  '''set nat source rule 100 translation address 'masquerade''''
+
  set nat source rule 100 translation address 'masquerade'
  
 
Which generates the following configuration:
 
Which generates the following configuration:
Line 1,379: Line 1,379:
 
To setup a NAT reflection rule, we need to create a rule to NAT connections from the internal network to the same internal network to use the source address of the internal interface.
 
To setup a NAT reflection rule, we need to create a rule to NAT connections from the internal network to the same internal network to use the source address of the internal interface.
  
  '''set nat source rule 110 description 'NAT Reflection: INSIDE''''
+
  set nat source rule 110 description 'NAT Reflection: INSIDE'
  '''set nat source rule 110 destination address '192.168.0.0/24''''
+
  set nat source rule 110 destination address '192.168.0.0/24'
  '''set nat source rule 110 outbound-interface 'eth1''''
+
  set nat source rule 110 outbound-interface 'eth1'
  '''set nat source rule 110 source address '192.168.0.0/24''''
+
  set nat source rule 110 source address '192.168.0.0/24'
  '''set nat source rule 110 translation address 'masquerade''''
+
  set nat source rule 110 translation address 'masquerade'
  
 
Which results in a configuration of:
 
Which results in a configuration of:
Line 1,421: Line 1,421:
 
Our configuration commands would be:
 
Our configuration commands would be:
  
  '''set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100''''
+
  set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100'
  '''set nat destination rule 10 destination port '80''''
+
  set nat destination rule 10 destination port '80'
  '''set nat destination rule 10 inbound-interface 'eth0''''
+
  set nat destination rule 10 inbound-interface 'eth0'
  '''set nat destination rule 10 protocol 'tcp''''
+
  set nat destination rule 10 protocol 'tcp'
  '''set nat destination rule 10 translation address '192.168.0.100''''
+
  set nat destination rule 10 translation address '192.168.0.100'
  
 
Which would generate the following NAT destination configuration:
 
Which would generate the following NAT destination configuration:
Line 1,453: Line 1,453:
 
So in our firewall policy, we want to allow traffic coming in on the outside interface, destined for TCP port 80 and the IP address of 192.168.0.100.
 
So in our firewall policy, we want to allow traffic coming in on the outside interface, destined for TCP port 80 and the IP address of 192.168.0.100.
  
  '''set firewall name OUTSIDE-IN rule 20 action 'accept''''
+
  set firewall name OUTSIDE-IN rule 20 action 'accept'
  '''set firewall name OUTSIDE-IN rule 20 destination address '192.168.0.100''''
+
  set firewall name OUTSIDE-IN rule 20 destination address '192.168.0.100'
  '''set firewall name OUTSIDE-IN rule 20 destination port '80''''
+
  set firewall name OUTSIDE-IN rule 20 destination port '80'
  '''set firewall name OUTSIDE-IN rule 20 protocol 'tcp''''
+
  set firewall name OUTSIDE-IN rule 20 protocol 'tcp'
  '''set firewall name OUTSIDE-IN rule 20 state new 'enable''''
+
  set firewall name OUTSIDE-IN rule 20 state new 'enable'
  
 
This would generate the following configuration:
 
This would generate the following configuration:
Line 1,473: Line 1,473:
 
  }
 
  }
  
'''Note''':  If you have configured the INSIDE-OUT policy, you will need to add additional rules to permit inbound NAT traffic.  
+
'''Note''':  If you have configured the INSIDE-OUT policy, you will need to add additional rules to permit inbound NAT traffic.
 
 
  
 
=== 1-to-1 NAT ===
 
=== 1-to-1 NAT ===
Line 1,490: Line 1,489:
 
Here's an extract of a simple 1-to-1 NAT configuration with one internal and one external interface:
 
Here's an extract of a simple 1-to-1 NAT configuration with one internal and one external interface:
  
  '''set interfaces ethernet eth0 address '192.168.1.1/24''''
+
  set interfaces ethernet eth0 address '192.168.1.1/24'
  '''set interfaces ethernet eth0 description 'Inside interface''''
+
  set interfaces ethernet eth0 description 'Inside interface'
  '''set interfaces ethernet eth1 address '1.2.3.4/24''''
+
  set interfaces ethernet eth1 address '1.2.3.4/24'
  '''set interfaces ethernet eth1 description 'Outside interface''''
+
  set interfaces ethernet eth1 description 'Outside interface'
  '''set nat destination rule 2000 description '1-to-1 NAT example''''
+
  set nat destination rule 2000 description '1-to-1 NAT example'
  '''set nat destination rule 2000 destination address '1.2.3.4''''
+
  set nat destination rule 2000 destination address '1.2.3.4'
  '''set nat destination rule 2000 inbound-interface 'eth1''''
+
  set nat destination rule 2000 inbound-interface 'eth1'
  '''set nat destination rule 2000 translation address '192.168.1.10''''
+
  set nat destination rule 2000 translation address '192.168.1.10'
  '''set nat source rule 2000 description '1-to-1 NAT example''''
+
  set nat source rule 2000 description '1-to-1 NAT example'
  '''set nat source rule 2000 outbound-interface 'eth1''''
+
  set nat source rule 2000 outbound-interface 'eth1'
  '''set nat source rule 2000 source address '192.168.1.10''''
+
  set nat source rule 2000 source address '192.168.1.10'
  '''set nat source rule 2000 translation address '1.2.3.4''''
+
  set nat source rule 2000 translation address '1.2.3.4'
  
 
Firewall rules are written as normal, using the internal IP address as the source of outbound rules and the destination of inbound rules.
 
Firewall rules are written as normal, using the internal IP address as the source of outbound rules and the destination of inbound rules.
 
  
 
=== NPTv6 (RFC6296) ===
 
=== NPTv6 (RFC6296) ===
Line 1,511: Line 1,509:
 
== VPN ==
 
== VPN ==
 
=== OpenVPN ===
 
=== OpenVPN ===
 +
{{main|OpenVPN}}
  
 
Traditionally hardware routers implement IPsec exclusively due to relative ease of implementing it in hardware and insufficient CPU power for doing encryption in software. Since VyOS is a software router, this is less of a concern. OpenVPN has been widely used on UNIX platform for a long time and is a popular option for remote access VPN, though it's also capable of site-to-site connections.
 
Traditionally hardware routers implement IPsec exclusively due to relative ease of implementing it in hardware and insufficient CPU power for doing encryption in software. Since VyOS is a software router, this is less of a concern. OpenVPN has been widely used on UNIX platform for a long time and is a popular option for remote access VPN, though it's also capable of site-to-site connections.
Line 1,533: Line 1,532:
 
First, one one of the systems generate the key using the operational command <code>generate openvpn key <filename></code>.  This will generate a key with the name provided in the <code>/config/auth/</code> directory.  Once generated, you will need to copy this key to the remote router.
 
First, one one of the systems generate the key using the operational command <code>generate openvpn key <filename></code>.  This will generate a key with the name provided in the <code>/config/auth/</code> directory.  Once generated, you will need to copy this key to the remote router.
  
In our example, we used the filename <code>openvpn-1.key</code> which we will reference in our configuration.
+
In our example, we used the filename <code>openvpn-1.key</code> which we will reference in our configuration.
  
 
* The public IP address of the local side of the VPN will be 198.51.100.10
 
* The public IP address of the local side of the VPN will be 198.51.100.10
Line 1,590: Line 1,589:
 
   sha512      SHA-512 algorithm
 
   sha512      SHA-512 algorithm
  
If you change the default encryption and hashing algorithms, be sure that the local and remote ends have matching configurations, otherwise the tunnel will not come up.  
+
If you change the default encryption and hashing algorithms, be sure that the local and remote ends have matching configurations, otherwise the tunnel will not come up.
  
 
Static routes can be configured referencing the tunnel interface; for example, the local router will use a network of 10.0.0.0/16, while the remote has a  network of 10.1.0.0/16:
 
Static routes can be configured referencing the tunnel interface; for example, the local router will use a network of 10.0.0.0/16, while the remote has a  network of 10.1.0.0/16:
Line 1,659: Line 1,658:
 
Example for configuring a simple L2TP over IPsec VPN for remote access (works with native Windows and Mac VPN clients):
 
Example for configuring a simple L2TP over IPsec VPN for remote access (works with native Windows and Mac VPN clients):
  
  '''set vpn ipsec ipsec-interfaces interface eth0'''
+
  set vpn ipsec ipsec-interfaces interface eth0
  '''set vpn ipsec nat-traversal enable'''
+
  set vpn ipsec nat-traversal enable
  '''set vpn ipsec nat-networks allowed-network 0.0.0.0/0'''
+
  set vpn ipsec nat-networks allowed-network 0.0.0.0/0
+
 
  '''set vpn l2tp remote-access outside-address 203.0.113.2'''
+
  set vpn l2tp remote-access outside-address 203.0.113.2
  '''set vpn l2tp remote-access client-ip-pool start 192.168.255.1'''
+
  set vpn l2tp remote-access client-ip-pool start 192.168.255.1
  '''set vpn l2tp remote-access client-ip-pool stop 192.168.255.255'''
+
  set vpn l2tp remote-access client-ip-pool stop 192.168.255.254
  '''set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret'''
+
  set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret
  '''set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret <secret>'''
+
  set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret <secret>
  '''set vpn l2tp remote-access authentication mode local'''
+
  set vpn l2tp remote-access authentication mode local
  '''set vpn l2tp remote-access authentication local-users username <username> password <password>'''
+
  set vpn l2tp remote-access authentication local-users username <username> password <password>
  
 
In the example above an external IP of 203.0.113.2 is assumed.
 
In the example above an external IP of 203.0.113.2 is assumed.
Line 1,685: Line 1,684:
 
Example:
 
Example:
  
  '''set firewall name OUTSIDE-LOCAL rule 40 action 'accept''''
+
  set firewall name OUTSIDE-LOCAL rule 40 action 'accept'
  '''set firewall name OUTSIDE-LOCAL rule 40 destination port '50''''
+
  set firewall name OUTSIDE-LOCAL rule 40 destination port '50'
  '''set firewall name OUTSIDE-LOCAL rule 40 protocol 'esp''''
+
  set firewall name OUTSIDE-LOCAL rule 40 protocol 'esp'
  '''set firewall name OUTSIDE-LOCAL rule 41 action 'accept''''
+
  set firewall name OUTSIDE-LOCAL rule 41 action 'accept'
  '''set firewall name OUTSIDE-LOCAL rule 41 destination port '500''''
+
  set firewall name OUTSIDE-LOCAL rule 41 destination port '500'
  '''set firewall name OUTSIDE-LOCAL rule 41 protocol 'udp''''
+
  set firewall name OUTSIDE-LOCAL rule 41 protocol 'udp'
  '''set firewall name OUTSIDE-LOCAL rule 42 action 'accept''''
+
  set firewall name OUTSIDE-LOCAL rule 42 action 'accept'
  '''set firewall name OUTSIDE-LOCAL rule 42 destination port '4500''''
+
  set firewall name OUTSIDE-LOCAL rule 42 destination port '4500'
  '''set firewall name OUTSIDE-LOCAL rule 42 protocol 'udp''''
+
  set firewall name OUTSIDE-LOCAL rule 42 protocol 'udp'
  '''set firewall name OUTSIDE-LOCAL rule 43 action 'accept''''
+
  set firewall name OUTSIDE-LOCAL rule 43 action 'accept'
  '''set firewall name OUTSIDE-LOCAL rule 43 destination port '1701''''
+
  set firewall name OUTSIDE-LOCAL rule 43 destination port '1701'
  '''set firewall name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec''''
+
  set firewall name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec'
  '''set firewall name OUTSIDE-LOCAL rule 43 protocol 'udp''''
+
  set firewall name OUTSIDE-LOCAL rule 43 protocol 'udp'
  
 
Also note that if you wish to allow the VPN to be used for external access you will need to add the appropriate source NAT rules to your configuration.
 
Also note that if you wish to allow the VPN to be used for external access you will need to add the appropriate source NAT rules to your configuration.
  
  '''set nat source rule 110 outbound-interface 'eth0''''
+
  set nat source rule 110 outbound-interface 'eth0'
  '''set nat source rule 110 source address '192.168.255.0/24''''
+
  set nat source rule 110 source address '192.168.255.0/24'
  '''set nat source rule 110 translation address masquerade'''
+
  set nat source rule 110 translation address masquerade
  
 
To be able to resolve when connected to the VPN, the following DNS rules are needed as well.
 
To be able to resolve when connected to the VPN, the following DNS rules are needed as well.
  '''set vpn l2tp remote-access dns-servers server-1 '8.8.8.8''''
+
  set vpn l2tp remote-access dns-servers server-1 '8.8.8.8'
  '''set vpn l2tp remote-access dns-servers server-2 '8.8.4.4''''
+
  set vpn l2tp remote-access dns-servers server-2 '8.8.4.4'
  
  
 
Established sessions can be viewed using the '''show vpn remote-access''' operational command.
 
Established sessions can be viewed using the '''show vpn remote-access''' operational command.
  
  vyos@vyos:~$ '''show vpn remote-access'''
+
  vyos@vyos:~$ show vpn remote-access
 
  Active remote access VPN sessions:
 
  Active remote access VPN sessions:
  User            Proto Iface    Tunnel IP      TX byte RX byte  Time  
+
  User            Proto Iface    Tunnel IP      TX byte RX byte  Time
  ----            ----- -----    ---------      ------- -------  ----  
+
  ----            ----- -----    ---------      ------- -------  ----
 
  vyos            L2TP  l2tp0    192.168.255.1      3.2K    8.0K  00h06m13s
 
  vyos            L2TP  l2tp0    192.168.255.1      3.2K    8.0K  00h06m13s
  
 
=== Site-to-Site IPsec ===
 
=== Site-to-Site IPsec ===
  
Example:  
+
Example:
 
+
* eth1 is WAN interface
*eth1 is WAN interface
+
* left subnet: 192.168.0.0/24 #s ite1, server side (i.e. locality, actually there is no client or server roles)
*left subnet: 192.168.0.0/24 #site1, server side (i.e. locality, actually there is no client or server roles)
+
* left local_ip: 1.1.1.1 # server side WAN IP
*left local_ip: 1.1.1.1 #server side WAN IP
+
* right subnet: 10.0.0.0/24  # site2,remote office side
*right subnet: 10.0.0.0/24  #site2,remote office side
+
* right local_ip: 2.2.2.2 # remote office side WAN IP
*right local_ip: 2.2.2.2 #remote office side WAN IP
 
 
 
  
 
  # server side config
 
  # server side config
  '''set vpn ipsec esp-group office-srv-esp compression 'disable''''
+
  set vpn ipsec esp-group office-srv-esp compression 'disable'
  '''set vpn ipsec esp-group office-srv-esp lifetime '1800''''
+
  set vpn ipsec esp-group office-srv-esp lifetime '1800'
  '''set vpn ipsec esp-group office-srv-esp mode 'tunnel''''
+
  set vpn ipsec esp-group office-srv-esp mode 'tunnel'
  '''set vpn ipsec esp-group office-srv-esp pfs 'enable''''
+
  set vpn ipsec esp-group office-srv-esp pfs 'enable'
  '''set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256''''
+
  set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256'
  '''set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1''''
+
  set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1'
  '''set vpn ipsec ike-group office-srv-ike ikev2-reauth 'no''''
+
  set vpn ipsec ike-group office-srv-ike ikev2-reauth 'no'
  '''set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1''''
+
  set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1'
  '''set vpn ipsec ike-group office-srv-ike lifetime '3600''''
+
  set vpn ipsec ike-group office-srv-ike lifetime '3600'
  '''set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256''''
+
  set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256'
  '''set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1''''
+
  set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1'
  '''set vpn ipsec ipsec-interfaces interface 'eth1''''
+
  set vpn ipsec ipsec-interfaces interface 'eth1'
  '''set vpn ipsec site-to-site peer 2.2.2.2 authentication mode 'pre-shared-secret''''
+
  set vpn ipsec site-to-site peer 2.2.2.2 authentication mode 'pre-shared-secret'
  '''set vpn ipsec site-to-site peer 2.2.2.2 authentication pre-shared-secret 'SomePreSharedKey''''
+
  set vpn ipsec site-to-site peer 2.2.2.2 authentication pre-shared-secret 'SomePreSharedKey'
  '''set vpn ipsec site-to-site peer 2.2.2.2 ike-group 'office-srv-ike''''
+
  set vpn ipsec site-to-site peer 2.2.2.2 ike-group 'office-srv-ike'
  '''set vpn ipsec site-to-site peer 2.2.2.2 local-address '1.1.1.1''''
+
  set vpn ipsec site-to-site peer 2.2.2.2 local-address '1.1.1.1'
  '''set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 allow-nat-networks 'disable''''
+
  set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 allow-nat-networks 'disable'
  '''set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 allow-public-networks 'disable''''
+
  set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 allow-public-networks 'disable'
  '''set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 esp-group 'office-srv-esp''''
+
  set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 esp-group 'office-srv-esp'
  '''set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 local prefix '192.168.0.0/24''''
+
  set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 local prefix '192.168.0.0/24'
  '''set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 remote prefix '10.0.0.0/21''''
+
  set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 remote prefix '10.0.0.0/21'
 
 
  
 
  # remote office side config
 
  # remote office side config
  '''set vpn ipsec esp-group office-srv-esp compression 'disable''''
+
  set vpn ipsec esp-group office-srv-esp compression 'disable'
  '''set vpn ipsec esp-group office-srv-esp lifetime '1800''''
+
  set vpn ipsec esp-group office-srv-esp lifetime '1800'
  '''set vpn ipsec esp-group office-srv-esp mode 'tunnel''''
+
  set vpn ipsec esp-group office-srv-esp mode 'tunnel'
  '''set vpn ipsec esp-group office-srv-esp pfs 'enable''''
+
  set vpn ipsec esp-group office-srv-esp pfs 'enable'
  '''set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256''''
+
  set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256'
  '''set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1''''
+
  set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1'
  '''set vpn ipsec ike-group office-srv-ike ikev2-reauth 'no''''
+
  set vpn ipsec ike-group office-srv-ike ikev2-reauth 'no'
  '''set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1''''
+
  set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1'
  '''set vpn ipsec ike-group office-srv-ike lifetime '3600''''
+
  set vpn ipsec ike-group office-srv-ike lifetime '3600'
  '''set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256''''
+
  set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256'
  '''set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1''''
+
  set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1'
  '''set vpn ipsec ipsec-interfaces interface 'eth1''''
+
  set vpn ipsec ipsec-interfaces interface 'eth1'
  '''set vpn ipsec site-to-site peer 1.1.1.1 authentication mode 'pre-shared-secret''''
+
  set vpn ipsec site-to-site peer 1.1.1.1 authentication mode 'pre-shared-secret'
  '''set vpn ipsec site-to-site peer 1.1.1.1 authentication pre-shared-secret 'SomePreSharedKey''''
+
  set vpn ipsec site-to-site peer 1.1.1.1 authentication pre-shared-secret 'SomePreSharedKey'
  '''set vpn ipsec site-to-site peer 1.1.1.1 ike-group 'office-srv-ike''''
+
  set vpn ipsec site-to-site peer 1.1.1.1 ike-group 'office-srv-ike'
  '''set vpn ipsec site-to-site peer 1.1.1.1 local-address '2.2.2.2''''
+
  set vpn ipsec site-to-site peer 1.1.1.1 local-address '2.2.2.2'
  '''set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 allow-nat-networks 'disable''''
+
  set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 allow-nat-networks 'disable'
  '''set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 allow-public-networks 'disable''''
+
  set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 allow-public-networks 'disable'
  '''set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 esp-group 'office-srv-esp''''
+
  set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 esp-group 'office-srv-esp'
  '''set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 local prefix '10.0.0.0/21''''
+
  set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 local prefix '10.0.0.0/21'
  '''set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 remote prefix '192.168.0.0/24''''  
+
  set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 remote prefix '192.168.0.0/24'
  
  vyos@srv-gw0:~$ '''show vpn ike sa'''
+
  vyos@srv-gw0:~$ show vpn ike sa
  Peer ID / IP                            Local ID / IP              
+
  Peer ID / IP                            Local ID / IP
 
  ------------                            -------------
 
  ------------                            -------------
  2.2.2.2                                1.1.1.1                        
+
  2.2.2.2                                1.1.1.1
 
     State  Encrypt  Hash    D-H Grp  NAT-T  A-Time  L-Time
 
     State  Encrypt  Hash    D-H Grp  NAT-T  A-Time  L-Time
 
     -----  -------  ----    -------  -----  ------  ------
 
     -----  -------  ----    -------  -----  ------  ------
     up    aes256  sha1    5        no    734    3600  
+
     up    aes256  sha1    5        no    734    3600
 
  
  vyos@srv-gw0:~$ '''show vpn ipsec sa'''
+
 
  Peer ID / IP                            Local ID / IP              
+
  vyos@srv-gw0:~$ show vpn ipsec sa
 +
  Peer ID / IP                            Local ID / IP
 
  ------------                            -------------
 
  ------------                            -------------
 
  2.2.2.2                                1.1.1.1
 
  2.2.2.2                                1.1.1.1
Line 1,793: Line 1,789:
 
     0      up    7.5M/230.6K    aes256  sha1    no    567    1800    all
 
     0      up    7.5M/230.6K    aes256  sha1    no    567    1800    all
  
If there is SNAT rules on eth1, need to add exclude rule  
+
If there is SNAT rules on eth1, need to add exclude rule
 
#server side
 
'''set nat source rule 10 destination address '10.0.0.0/24'
 
'''set nat source rule 10 'exclude''''
 
'''set nat source rule 10 outbound-interface 'eth1''''
 
'''set nat source rule 10 source address '192.168.0.0/24''''
 
  
  #remote office side
+
  # server side
  '''set nat source rule 10 destination address '192.168.0.0/24'
+
  set nat source rule 10 destination address '10.0.0.0/24'
  '''set nat source rule 10 'exclude''''
+
set nat source rule 10 'exclude'
  '''set nat source rule 10 outbound-interface 'eth1''''
+
set nat source rule 10 outbound-interface 'eth1'
  '''set nat source rule 10 source address '10.0.0.0/24''''
+
set nat source rule 10 source address '192.168.0.0/24'
 +
 
 +
  # remote office side
 +
set nat source rule 10 destination address '192.168.0.0/24'
 +
set nat source rule 10 'exclude'
 +
  set nat source rule 10 outbound-interface 'eth1'
 +
  set nat source rule 10 source address '10.0.0.0/24'
  
 
To allow traffic to pass through to clients, you need to add the following rules. (if you used the default configuration at the top of this page)
 
To allow traffic to pass through to clients, you need to add the following rules. (if you used the default configuration at the top of this page)
  
  #server side
+
  # server side
  '''set firewall name OUTSIDE-LOCAL rule 32 action 'accept'
+
  set firewall name OUTSIDE-LOCAL rule 32 action 'accept'
  '''set firewall name OUTSIDE-LOCAL rule 32 source address '10.0.0.0/24''''
+
  set firewall name OUTSIDE-LOCAL rule 32 source address '10.0.0.0/24'
  
  #remote office side
+
  # remote office side
  '''set firewall name OUTSIDE-LOCAL rule 32 action 'accept'
+
  set firewall name OUTSIDE-LOCAL rule 32 action 'accept'
  '''set firewall name OUTSIDE-LOCAL rule 32 source address '192.168.0.0/24''''
+
  set firewall name OUTSIDE-LOCAL rule 32 source address '192.168.0.0/24'
 +
 
 +
=== DMVPN ===
 +
 
 +
Advanced DMVPN configuration examples are available on the [[DMVPN]] page.
  
 
== QoS and Traffic Policy ==
 
== QoS and Traffic Policy ==
Line 1,827: Line 1,827:
 
  set traffic-policy shaper WAN-OUT default ceiling '100%'
 
  set traffic-policy shaper WAN-OUT default ceiling '100%'
 
  set traffic-policy shaper WAN-OUT default queue-type 'fair-queue'
 
  set traffic-policy shaper WAN-OUT default queue-type 'fair-queue'
+
 
 
  set traffic-policy shaper LAN-OUT bandwidth '200Mbit'
 
  set traffic-policy shaper LAN-OUT bandwidth '200Mbit'
 
  set traffic-policy shaper LAN-OUT default bandwidth '50%'
 
  set traffic-policy shaper LAN-OUT default bandwidth '50%'
Line 1,885: Line 1,885:
 
Multiple ranges can be defined and can contain holes.
 
Multiple ranges can be defined and can contain holes.
 
  set service dhcp-server shared-network-name 'LAN' authoritative
 
  set service dhcp-server shared-network-name 'LAN' authoritative
  set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' range 0 start '192.168.0.128'  
+
  set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' range 0 start '192.168.0.128'
 
  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' range 0 stop '192.168.0.254'
 
  set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' default-router '192.168.0.1'
 
  set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' default-router '192.168.0.1'
Line 1,939: Line 1,939:
 
VyOS can act as a DHCP relay, sending DHCP requests from locally connected networks to a central DHCP server, or servers:
 
VyOS can act as a DHCP relay, sending DHCP requests from locally connected networks to a central DHCP server, or servers:
  
  set service dhcp‐relay interface eth0
+
  set service dhcp-relay interface eth0
 
  set service dhcp-relay interface eth1
 
  set service dhcp-relay interface eth1
  set service dhcp‐relay server 192.168.0.4
+
  set service dhcp-relay server 192.168.0.4
  set service dhcp‐relay server 192.168.0.5
+
  set service dhcp-relay server 192.168.0.5
  
 
An important note that dhcp-relay currently requires specifying the interface the DHCP server replies come from in addition to interfaces to listen on.  An upstream bug exists for this: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=648401
 
An important note that dhcp-relay currently requires specifying the interface the DHCP server replies come from in addition to interfaces to listen on.  An upstream bug exists for this: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=648401
  
By default the ISC dhcrelay process will relay relay packets; as this is not expected behavior, disabling this functionality is recommended using the following directive:
+
By default the ISC dhcp-relay process will relay relay packets; as this is not expected behavior, disabling this functionality is recommended using the following directive:
  
 
   set service dhcp-relay relay-options relay-agents-packets discard
 
   set service dhcp-relay relay-options relay-agents-packets discard
Line 1,952: Line 1,952:
 
Additional protections can be configured matching <code>hop-limit</code> and <code>max-size</code> for DHCP packets.
 
Additional protections can be configured matching <code>hop-limit</code> and <code>max-size</code> for DHCP packets.
  
   set service dhcp‐relay hop-count 10
+
   set service dhcp-relay hop-count 10
   set service dhcp‐relay max-size 576
+
   set service dhcp-relay max-size 576
  
 
== DNS Forwarder ==
 
== DNS Forwarder ==
Line 2,012: Line 2,012:
  
 
In addition you can disable the whole service without removing the configuration by <code>set service broadcast-relay disable</code>.
 
In addition you can disable the whole service without removing the configuration by <code>set service broadcast-relay disable</code>.
 +
  
 
== System Configuration ==
 
== System Configuration ==
 
 
  
 
=== System Users ===
 
=== System Users ===
  
VyOS supports two levels of users: admin and operator.
+
As of 1.1.8 release and 1.2.0 release candidates, VyOS support two user privilege levels: admin and operator.
 +
However, the operator level is a legacy feature and was proved insecure: any user can escape the restricted shell in multiple easy way. That feature will be removed in future releases, and we do not recommend using it.
  
The operator level restricts a user to operational commands and prevents changes to system configuration.  This is useful for gathering information about the state of the system (dhcp leases, vpn connections, routing tables, etc...) and for manipulating state of the system, such as resetting connections, clearing counters and bringing up and taking down connection oriented interfaces.
 
 
The admin level has all of the capabilities of the operator level, plus the ability to change system configuration.  The admin level also enables a user to use the sudo command, which essentially means the user has root access to the system.
 
  
 
==== Creating Login User Accounts ====
 
==== Creating Login User Accounts ====
Line 2,031: Line 2,028:
 
  set system login user jsmith full-name "Johan Smith"
 
  set system login user jsmith full-name "Johan Smith"
 
  set system login user jsmith authentication plaintext-password mypassword
 
  set system login user jsmith authentication plaintext-password mypassword
set system login user jsmith level admin
 
 
  commit
 
  commit
  
Line 2,038: Line 2,034:
 
  show system login
 
  show system login
  
will show the contents of the <code>ystem login</code> configuration node:  
+
will show the contents of the <code>system login</code> configuration node:
  
 
  user jsmith {
 
  user jsmith {
Line 2,109: Line 2,105:
 
A list of available images can be shown using the '''show system image''' command in operational mode.
 
A list of available images can be shown using the '''show system image''' command in operational mode.
  
  vyos@vyos:~$ '''show system image'''  
+
  vyos@vyos:~$ '''show system image'''
 
  The system currently has the following image(s) installed:
 
  The system currently has the following image(s) installed:
+
 
 
     1: 999.hydrogen.12130649 (default boot) (running image)
 
     1: 999.hydrogen.12130649 (default boot) (running image)
 
     2: 999.hydrogen.12100644
 
     2: 999.hydrogen.12100644
+
 
  vyos@vyos:~$  
+
  vyos@vyos:~$
  
 
Images no longer needed can be removed using the '''delete system image''' command.
 
Images no longer needed can be removed using the '''delete system image''' command.
  
Finally, new system images can be added using the '''add system image''' command.  The add image command will extract the image from the release ISO (either on the local filesystem or remotely if a URL is provided).  The image install process will prompt you to use the current system configuration and SSH security keys, allowing for the new image to boot using the current configuration.
+
Finally, new system images can be added using the '''add system image''' command.  The add image command will extract the image from the release ISO (either on the local filesystem or remotely if a URL is provided).  The image install process will prompt you to use the current system configuration and SSH security keys, allowing for the new image to boot using the current configuration.
  
 
Note that configuration is associated to each image, and each image has a unique copy of its configuration.  This is different than a traditional network router where the configuration is shared across all images.
 
Note that configuration is associated to each image, and each image has a unique copy of its configuration.  This is different than a traditional network router where the configuration is shared across all images.
Line 2,131: Line 2,127:
 
Verifying connectivity can be done with the familiar '''ping''' and '''traceroute''' commands. The options for each are shown (the options for each command were displayed using the built-in help as described in the [[#Using_the_Command-Line_Interface|Using the Command-Line Interface]] section and are omitted from the output here):
 
Verifying connectivity can be done with the familiar '''ping''' and '''traceroute''' commands. The options for each are shown (the options for each command were displayed using the built-in help as described in the [[#Using_the_Command-Line_Interface|Using the Command-Line Interface]] section and are omitted from the output here):
  
  vyos@vyos:~$ '''ping'''
+
  vyos@vyos:~$ ping
 
  Possible completions:
 
  Possible completions:
 
   <hostname>    Send Internet Control Message Protocol (ICMP) echo request
 
   <hostname>    Send Internet Control Message Protocol (ICMP) echo request
Line 2,140: Line 2,136:
 
Several options are available when more extensive troubleshooting is needed:
 
Several options are available when more extensive troubleshooting is needed:
  
  vyos@vyos:~$ '''ping 8.8.8.8'''
+
  vyos@vyos:~$ ping 8.8.8.8
 
  Possible completions:
 
  Possible completions:
 
   <Enter>      Execute the current command
 
   <Enter>      Execute the current command
Line 2,165: Line 2,161:
 
  vyos@vyos:~$
 
  vyos@vyos:~$
  
  vyos@vyos:~$ '''traceroute'''
+
  vyos@vyos:~$ traceroute
 
  Possible completions:
 
  Possible completions:
 
   <hostname>    Track network path to specified node
 
   <hostname>    Track network path to specified node
Line 2,176: Line 2,172:
 
However, another tool, '''mtr''', is available which combines ping and traceroute into a single tool. An example of its output is shown:
 
However, another tool, '''mtr''', is available which combines ping and traceroute into a single tool. An example of its output is shown:
  
  vyos@vyos:~$ '''mtr 10.62.212.12'''
+
  vyos@vyos:~$ mtr 10.62.212.12
  
 
The output of '''mtr''' consumes the screen and will replace your command prompt:
 
The output of '''mtr''' consumes the screen and will replace your command prompt:
Line 2,195: Line 2,191:
 
It's possible to monitor network traffic, either at the flow level or protocol level. This can be useful when troubleshooting a variety of protocols and configurations. The following interface types can be monitored:
 
It's possible to monitor network traffic, either at the flow level or protocol level. This can be useful when troubleshooting a variety of protocols and configurations. The following interface types can be monitored:
  
  vyos@vyos:~$ '''monitor interfaces'''
+
  vyos@vyos:~$ monitor interfaces
 
  Possible completions:
 
  Possible completions:
 
   <Enter>      Execute the current command
 
   <Enter>      Execute the current command
Line 2,215: Line 2,211:
  
 
                     12.5Kb              25.0Kb              37.5Kb              50.0Kb        62.5Kb
 
                     12.5Kb              25.0Kb              37.5Kb              50.0Kb        62.5Kb
  └───────────────────┴───────────────────┴───────────────────┴───────────────────┴───────────────────
+
  ????????????????????????????????????????????????????????????????????????????????????????????????????
 
  10.11.111.255                        => 10.11.110.37                            0b      0b      0b
 
  10.11.111.255                        => 10.11.110.37                            0b      0b      0b
 
                                     <=                                      624b    749b    749b
 
                                     <=                                      624b    749b    749b
Line 2,226: Line 2,222:
 
  10.11.111.255                        => 10.11.110.255                          0b      0b      0b
 
  10.11.111.255                        => 10.11.110.255                          0b      0b      0b
 
                                     <=                                      680b    136b    136b
 
                                     <=                                      680b    136b    136b
  ────────────────────────────────────────────────────────────────────────────────────────────────────
+
  ????????????????????????????????????????????????????????????????????????????????????????????????????
 
  TX:            cumm:  26.7KB  peak:  40.6Kb                      rates:  23.2Kb  21.4Kb  21.4Kb
 
  TX:            cumm:  26.7KB  peak:  40.6Kb                      rates:  23.2Kb  21.4Kb  21.4Kb
 
  RX:                    67.5KB          63.6Kb                              54.6Kb  54.0Kb  54.0Kb
 
  RX:                    67.5KB          63.6Kb                              54.6Kb  54.0Kb  54.0Kb
Line 2,235: Line 2,231:
 
To monitor interface traffic, issue the '''monitor interfaces <type> <name> traffic''' command, replacing '''<type>''' and '''<name>''' with your desired interface type and name, respectively. This command invokes the familiar '''tshark''' utility and the following options are available:
 
To monitor interface traffic, issue the '''monitor interfaces <type> <name> traffic''' command, replacing '''<type>''' and '''<name>''' with your desired interface type and name, respectively. This command invokes the familiar '''tshark''' utility and the following options are available:
  
  vyos@vyos:~$ '''monitor interfaces ethernet eth0 traffic'''
+
  vyos@vyos:~$ monitor interfaces ethernet eth0 traffic
 
  Possible completions:
 
  Possible completions:
 
   <Enter>      Execute the current command
 
   <Enter>      Execute the current command

Latest revision as of 22:16, 22 June 2019

Warning sign.png This page is migrated to Readthedocs .
Information found on this page is in progress of being migrated to readthedocs. https://vyos.readthedocs.io/en/latest/index.html


The VyOS User Guide is focused on providing a general overview of the installation, configuration, and operation of the VyOS network operating system.

(There is an alternative form of documentation on readthedocs.io which is generated from the sources at github/vyos/vyos-documentation)

Introduction

VyOS is a Linux-based network operating system that provides software-based network routing, firewall, and VPN functionality.

The VyOS project was started in late 2013 as a community fork of the GPL portions of Vyatta Core 6.6R1 with the goal of maintaining a free and open source network operating system in response to the decision to discontinue the community edition of Vyatta. Here everyone loves learning, older managers and new users.

VyOS is primarily based on Debian GNU/Linux and the Quagga routing engine. Its configuration syntax and command-line interface are loosely derived from Juniper JUNOS as modeled by the XORP project (which was the original routing engine Vyatta was based upon). Vyatta changed to the Quagga routing engine for release 4.0.

Installation

Main article: Installation

The latest ISO image for VyOS can be downloaded at www.vyos.net.

The recommended system requirements are 512MB RAM and 2GB storage.

The VyOS ISO is a Live CD and will boot to a functional VyOS image. To login to the system, use the default username:password of: vyos:vyos

Linux vyatta 3.3.8-1-amd64-vyatta #1 SMP Wed Oct 30 22:54:40 CET 2013 x86_64
Welcome to VyOS.
This system is open-source software. The exact distribution terms for
each module comprising the full system are described in the individual
files in /usr/share/doc/*/copyright.
Last login: Wed Dec 11 17:33:09 2013
vyos@vyos:~$

Unlike general purpose Linux distributions, VyOS uses "image installation" that mimics the user experience of traditional hardware routers and allows you to keep multiple VyOS versions on the same machine and switch to a previous version if something breaks after upgrade. Every version is contained in its own squashfs image that is mounted in a union filesystem together with a directory for mutable data (configs etc.).

Note: older versions used to support non-image installation ("install system" command). It's been deprecated since the time image installation was introduced (long before the fork), and does not provide any version management capabilities. You should not use it for new installations even if it's still available in new versions. You should not worry about older systems installed that way though, they can be upgraded with "add system image".

To install VyOS, run install image.

vyos@vyos:~$ install image
Welcome to the VyOS install program.  This script
will walk you through the process of installing the
VyOS image to a local hard drive.
Would you like to continue? (Yes/No) [Yes]: [return]
Probing drives: OK
Looking for pre-existing RAID groups...none found.
The VyOS image will require a minimum 1000MB root.
Would you like me to try to partition a drive automatically
or would you rather partition it manually with parted?  If
you have already setup your partitions, you may skip this step
Partition (Auto/Parted/Skip) [Auto]: [return]
I found the following drives on your system:
 sda  2147MB


Install the image on? [sda]: [return]
This will destroy all data on /dev/sda.
Continue? (Yes/No) [No]: Yes
How big of a root partition should I create? (1000MB - 2147MB) [2147]MB: [return]
Creating filesystem on /dev/sda1: OK
Done!
Mounting /dev/sda1...
What would you like to name this image? [VyOS_999.hydrogen.11291501]: [return]
OK.  This image will be named: VyOS_999.hydrogen.11291501
Copying squashfs image...
Copying kernel and initrd images...
Done!
I found the following configuration files:
    /config/config.boot
    /opt/vyatta/etc/config.boot.default
Which one should I copy to sda? [/config/config.boot]: [return]
Copying /config/config.boot to sda.
Enter password for administrator account
Enter password for user 'vyos': <removed>
Retype password for user 'vyos': <removed>
I need to install the GRUB boot loader.
I found the following drives on your system:
 sda  2147MB


Which drive should GRUB modify the boot partition on? [sda]: [return]
Setting up grub: OK
Done!
vyos@vyos:~$

After the installation is complete, remove the Live CD and reboot the system:

vyos@vyos:~$ reboot
Proceed with reboot? (Yes/No) [No] Yes
vyos@vyos:~$

Using the Command-Line Interface

Main article: Command line interface

The VyOS CLI comprises an operational mode and a configuration mode.

Operational mode allows for commands to perform operational system tasks and view system and service status, while configuration mode allows for the modification of system configuration. The command tree page lists available commands and their functions.

The CLI provides a built-in help system. In the CLI the [?] key may be used to display available commands. The [tab] key can be used to auto-complete commands and will present the help system upon a conflict or unknown value.

For example typing sh followed by the [tab] key will complete to show. Pressing [tab] a second time will display the possible sub-commands of the show command.

vyos@vyos:~$ s[tab]
set   show
vyos@vyos:~$

Example showing possible show commands:

vyos@vyos:~$ show [tab]
Possible completions:
  arp           Show Address Resolution Protocol (ARP) information
  bridge        Show bridging information
  cluster       Show clustering information
  configuration Show running configuration
  conntrack     Show conntrack entries in the conntrack table
  conntrack-sync
                Show connection syncing information
  date          Show system date and time
  dhcp          Show Dynamic Host Configuration Protocol (DHCP) information
  dhcpv6        Show status related to DHCPv6
  disk          Show status of disk device
  dns           Show Domain Name Server (DNS) information
  file          Show files for a particular image
  firewall      Show firewall information
  flow-accounting
                Show flow accounting statistics
  hardware      Show system hardware details
  history       show command history
  host          Show host information
  incoming      Show ethernet input-policy information
: q
vyos@vyos:~$

When the output of a command results in more lines than can be displayed on the terminal screen the output is paginated as indicated by a : prompt.

When viewing in page mode the following commands are available:

  • [q] key can be used to cancel output
  • [space] will scroll down one page
  • [b] will scroll back one page
  • [return] will scroll down one line
  • [up-arrow] and [down-arrow] will scroll up or down one line at a time respectively
  • [left-arrow] and [right-arrow] can be used to scroll left or right in the event that the output has lines which exceed the terminal size.

To enter configuration mode use the configure command:

vyos@vyos:~$ configure
[edit]
vyos@vyos:~#

Note that the prompt changes from $ to #. To exit configuration mode, type exit.

vyos@vyos:~# exit
exit
vyos@vyos:~$

See the configuration section of this document for more information on configuration mode.

Quick Start Guide

Below is a very basic configuration example that will provide a NAT gateway for a device with two interfaces.

Enter configuration mode:

vyos@vyos$ configure
vyos@vyos#

Configure network interfaces:

set interfaces ethernet eth0 address dhcp
set interfaces ethernet eth0 description 'OUTSIDE'
set interfaces ethernet eth1 address '192.168.0.1/24'
set interfaces ethernet eth1 description 'INSIDE'

Enable SSH for remote management:

set service ssh port '22'

Configure Source NAT for our "Inside" network.

set nat source rule 100 outbound-interface 'eth0'
set nat source rule 100 source address '192.168.0.0/24'
set nat source rule 100 translation address masquerade

Configure a DHCP Server:


set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 default-router '192.168.0.1'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 dns-server '192.168.0.1'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 domain-name 'internal-network'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 lease '86400'

>= 1.2.0

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'

<= 1.1.8

set service dhcp-server disabled 'false'
set service dhcp-server shared-network-name LAN subnet 192.168.0.0/24 start 192.168.0.9 stop '192.168.0.254'

And a DNS forwarder:

set service dns forwarding cache-size '0'
set service dns forwarding listen-on 'eth1'
set service dns forwarding name-server '8.8.8.8'
set service dns forwarding name-server '8.8.4.4'

Add a set of firewall policies for our "Outside" interface:

set firewall name OUTSIDE-IN default-action 'drop'
set firewall name OUTSIDE-IN rule 10 action 'accept'
set firewall name OUTSIDE-IN rule 10 state established 'enable'
set firewall name OUTSIDE-IN rule 10 state related 'enable'
set firewall name OUTSIDE-LOCAL default-action 'drop'
set firewall name OUTSIDE-LOCAL rule 10 action 'accept'
set firewall name OUTSIDE-LOCAL rule 10 state established 'enable'
set firewall name OUTSIDE-LOCAL rule 10 state related 'enable'
set firewall name OUTSIDE-LOCAL rule 20 action 'accept'
set firewall name OUTSIDE-LOCAL rule 20 icmp type-name 'echo-request'
set firewall name OUTSIDE-LOCAL rule 20 protocol 'icmp'
set firewall name OUTSIDE-LOCAL rule 20 state new 'enable'
set firewall name OUTSIDE-LOCAL rule 30 action 'drop'
set firewall name OUTSIDE-LOCAL rule 30 destination port '22'
set firewall name OUTSIDE-LOCAL rule 30 protocol 'tcp'
set firewall name OUTSIDE-LOCAL rule 30 recent count '4'
set firewall name OUTSIDE-LOCAL rule 30 recent time '60'
set firewall name OUTSIDE-LOCAL rule 30 state new 'enable'
set firewall name OUTSIDE-LOCAL rule 31 action 'accept'
set firewall name OUTSIDE-LOCAL rule 31 destination port '22'
set firewall name OUTSIDE-LOCAL rule 31 protocol 'tcp'
set firewall name OUTSIDE-LOCAL rule 31 state new 'enable'

Apply the firewall policies:

set interfaces ethernet eth0 firewall in name 'OUTSIDE-IN'
set interfaces ethernet eth0 firewall local name 'OUTSIDE-LOCAL'

Commit changes, save the configuration, and exit configuration mode:

vyos@vyos# commit
vyos@vyos# save
Saving configuration to '/config/config.boot'...
Done
vyos@vyos# exit
vyos@vyos$

Configuration Overview

VyOS makes use of a unified configuration file for all system configuration: config.boot. This allows for easy template creation, backup, and replication of system configuration.

The current configuration can be viewed using the show configuration command.

vyos@vyos:~$ show configuration
interfaces {
    ethernet eth0 {
        address dhcp
        hw-id 00:0c:29:44:3b:0f
    }
    loopback lo {
    }
}
service {
    ssh {
        port 22
    }
}
system {
    config-management {
        commit-revisions 20
    }
    console {
        device ttyS0 {
            speed 9600
        }
    }
    login {
        user vyos {
            authentication {
                encrypted-password ****************
            }
            level admin
        }
    }
    ntp {
        server 0.pool.ntp.org {
        }
        server 1.pool.ntp.org {
        }
        server 2.pool.ntp.org {
        }
    }
    syslog {
        global {
            facility all {
                level notice
            }
            facility protocols {
                level debug
            }
        }
    }
}
vyos@vyos:~$

Because configuration changes are made using set and delete commands, the commands to generate the active configuration can also be displayed using the show configuration commands command.

vyos@vyos:~$ show configuration commands
set interfaces ethernet eth0 address 'dhcp'
set interfaces ethernet eth0 hw-id '00:0c:29:44:3b:0f'
set interfaces loopback 'lo'
set service ssh port '22'
set system config-management commit-revisions '20'
set system console device ttyS0 speed '9600'
set system login user vyos authentication encrypted-password '<removed>'
set system login user vyos level 'admin'
set system ntp server '0.pool.ntp.org'
set system ntp server '1.pool.ntp.org'
set system ntp server '2.pool.ntp.org'
set system syslog global facility all level 'notice'
set system syslog global facility protocols level 'debug'
vyos@vyos:~$

Configuration changes made do not take effect until committed using the commit command in configuration mode.

vyos@vyos# commit
[edit]
vyos@vyos# exit
Warning: configuration changes have not been saved.
vyos@vyos:~$

In order to preserve configuration changes upon reboot, the configuration must also be saved once applied. This is done using the save command in configuration mode.

vyos@vyos# save
Saving configuration to '/config/config.boot'...
Done
[edit]
vyos@vyos#

The show command within configuration mode will show the current configuration indicating line changes with a + for additions and a - for deletions.

vyos@vyos:~$ configure
[edit]
vyos@vyos# show interfaces
  ethernet eth0 {
      address dhcp
      hw-id 00:0c:29:44:3b:0f
  }
  loopback lo {
  }
[edit]
vyos@vyos# set interfaces ethernet eth0 description 'OUTSIDE'
[edit]
vyos@vyos# show interfaces
 ethernet eth0 {
     address dhcp
+    description OUTSIDE
     hw-id 00:0c:29:44:3b:0f
 }
 loopback lo {
 }
[edit]
vyos@vyos#

Configuration mode can not be exited while uncommitted changes exist. To exit configuration mode without applying changes, the exit discard command can be used.

vyos@vyos# exit
Cannot exit: configuration modified.
Use 'exit discard' to discard the changes and exit.
[edit]
vyos@vyos# exit discard
exit
vyos@vyos:~$

VyOS also maintains backups of previous configurations. To compare configuration revisions in configuration mode, use the compare command:

vyos@vyos# compare [tab]
Possible completions:
  <Enter>	Compare working & active configurations
  saved		Compare working & saved configurations
  <N>		Compare working with revision N
  <N> <M>	Compare revision N with M
  Revisions:
    0	2013-12-17 20:01:37 root by boot-config-loader
    1	2013-12-13 15:59:31 root by boot-config-loader
    2	2013-12-12 21:56:22 vyos by cli
    3	2013-12-12 21:55:11 vyos by cli
    4	2013-12-12 21:27:54 vyos by cli
    5	2013-12-12 21:23:29 vyos by cli
    6	2013-12-12 21:13:59 root by boot-config-loader
    7	2013-12-12 16:25:19 vyos by cli
    8	2013-12-12 15:44:36 vyos by cli
    9	2013-12-12 15:42:07 root by boot-config-loader
    10	2013-12-12 15:42:06 root by init


[edit]
vyos@vyos#

You can rollback configuration using the rollback command, however this command will currently trigger a system reboot.

vyos@vyos# compare 1
[edit system]
>host-name vyos-1
[edit]
vyos@vyos# rollback 1
Proceed with reboot? [confirm][y]
Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013):
The system is going down for reboot NOW!
[edit]
vyos@vyos#


VyOS also supports saving and loading configuration remotely using SCP, FTP, or TFTP.

vyos@vyos# save [tab]
Possible completions:
  <Enter>       Save to system config file
  <file>        Save to file on local machine
  scp://<user>:<passwd>@<host>/<file> Save to file on remote machine
  ftp://<user>:<passwd>@<host>/<file> Save to file on remote machine
  tftp://<host>/<file>      Save to file on remote machine
vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot
Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'...
######################################################################## 100.0%
Done

Network Interfaces

Configured interfaces on a VyOS system can be displayed using the show interfaces command.

vyos@vyos:~$ show interfaces
Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
Interface        IP Address                        S/L  Description
---------        ----------                        ---  -----------
eth0             172.16.51.129/24                  u/u  OUTSIDE
eth1             192.168.0.1/24                    u/u  INSIDE
lo               127.0.0.1/8                       u/u
                 ::1/128
vyos@vyos:~$

A specific interface can be shown using the show interfaces <type> <name> command.

vyos@vyos:~$ show interfaces ethernet eth0
eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000
    link/ether 00:0c:29:44:3b:0f brd ff:ff:ff:ff:ff:ff
    inet 172.16.51.129/24 brd 172.16.51.255 scope global eth0
    inet6 fe80::20c:29ff:fe44:3b0f/64 scope link
       valid_lft forever preferred_lft forever
    Description: OUTSIDE
    RX:  bytes    packets     errors    dropped    overrun      mcast
        274397       3064          0          0          0          0
    TX:  bytes    packets     errors    dropped    carrier collisions
        257276       1890          0          0          0          0
vyos@vyos:~$

Each interface can be configured with a description and address.

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

Different network interfaces provide type-specific configuration. Ethernet interfaces, for example, allow the configuration of speed and duplex.

Many services, such as network routing, firewall, and traffic policy also maintain interface-specific configuration. These will be covered in their respective sections.

Ethernet Interfaces

Main article: Ethernet#Ethernet_Interfaces

Ethernet interfaces allow for the configuration of speed, duplex, and hw-id (MAC address). Below is an example configuration:

set interfaces ethernet eth1 address '192.168.0.1/24'
set interfaces ethernet eth1 description 'INSIDE'
set interfaces ethernet eth1 duplex 'auto'
set interfaces ethernet eth1 speed 'auto'

Resulting in:

   ethernet eth1 {
       address 192.168.0.1/24
       description INSIDE
       duplex auto
       hw-id 00:0c:29:44:3b:19
       smp_affinity auto
       speed auto
   }
set interfaces ethernet eth1 disable

Will disable an existing interface.


In addition, Ethernet interfaces provide the extended operational commands show interfaces ethernet <name> physical and show interfaces ethernet <name> statistics. Statistics available are driver dependent.

vyos@vyos:~$ show interfaces ethernet eth0 physical
Settings for eth0:
        Supported ports: [ TP ]
        Supported link modes:   10baseT/Half 10baseT/Full
                                100baseT/Half 100baseT/Full
                                1000baseT/Full
        Supports auto-negotiation: Yes
        Advertised link modes:  10baseT/Half 10baseT/Full
                                100baseT/Half 100baseT/Full
                                1000baseT/Full
        Advertised pause frame use: No
        Advertised auto-negotiation: Yes
        Speed: 1000Mb/s
        Duplex: Full
        Port: Twisted Pair
        PHYAD: 0
        Transceiver: internal
        Auto-negotiation: on
        MDI-X: Unknown
        Supports Wake-on: d
        Wake-on: d
        Current message level: 0x00000007 (7)
        Link detected: yes
driver: e1000
version: 7.3.21-k8-NAPI
firmware-version:
bus-info: 0000:02:01.0
vyos@vyos:~$ show interfaces ethernet eth0 statistics
NIC statistics:
     rx_packets: 3530
     tx_packets: 2179
[...]

VLAN Sub-Interfaces (802.1Q)

802.1Q VLAN interfaces are represented as virtual sub-interfaces in VyOS. The term used for this is vif. Configuration of a tagged sub-interface is accomplished using the configuration command set interfaces ethernet <name> vif <vlan-id>.

set interfaces ethernet eth1 vif 100 description 'VLAN 100'
set interfaces ethernet eth1 vif 100 address '192.168.100.1/24'

Resulting:

   ethernet eth1 {
       address 192.168.0.1/24
       description INSIDE
       duplex auto
       hw-id 00:0c:29:44:3b:19
       smp_affinity auto
       speed auto
       vif 100 {
           address 192.168.100.1/24
           description "VLAN 100"
       }
   }

VLAN interfaces are shown as <name>.<vlan-id>, e.g. eth1.100:

vyos@vyos:~$ show interfaces
Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
Interface        IP Address                        S/L  Description
---------        ----------                        ---  -----------
eth0             172.16.51.129/24                  u/u  OUTSIDE
eth1             192.168.0.1/24                    u/u  INSIDE
eth1.100         192.168.100.1/24                  u/u  VLAN 100
lo               127.0.0.1/8                       u/u
                 ::1/128

Bridging

Interfaces in VyOS can be bridged together to provide software switching of Layer-2 traffic.

A bridge is created when a bridge interface is defined. In the example below we will be creating a bridge for VLAN 100 and assigning a VIF to the bridge.

set interfaces bridge 'br100'
set interfaces ethernet eth1 vif 100 bridge-group bridge br100

Interfaces assigned to a bridge-group do not have address configuration. An IP address can be assigned to the bridge interface itself, however, like any normal interface.

set interfaces bridge br100 address '192.168.100.1/24'

Example Result:

bridge br100 {
    address 192.168.100.1/24
}
[...]
ethernet eth1 {
[...]
    vif 100 {
        bridge-group {
            bridge br100
        }
    }
}

In addition to normal IP interface configuration, bridge interfaces support Spanning-Tree Protocol. STP is disabled by default.

NOTE: Please use caution when introducing spanning-tree protocol on a network as it may result in topology changes.

To enable spanning-tree use the set interfaces bridge <name> stp true command:

set interfaces bridge br100 stp true

STP priority, forwarding-delay, hello-time, and max-age can be configured for the bridge-group. The MAC aging time can also be configured using the aging directive.

For member interfaces, the bridge-group priority and cost can be configured.

The show bridge operational command can be used to display configured bridges:

vyos@vyos:~$ show bridge
bridge name     bridge id               STP enabled     interfaces
br100           0000.000c29443b19       yes             eth1.100

If spanning-tree is enabled, the show bridge <name> spanning-tree command can be used to show STP configuration:

vyos@vyos:~$ show bridge br100 spanning-tree
br100
 bridge id              0000.000c29443b19
 designated root        0000.000c29443b19
 root port                 0                    path cost                  0
 max age                  20.00                 bridge max age            20.00
 hello time                2.00                 bridge hello time          2.00
 forward delay            15.00                 bridge forward delay      15.00
 ageing time             300.00
 hello timer               0.47                 tcn timer                  0.00
 topology change timer     0.00                 gc timer                  64.63
 flags
eth1.100 (1)
 port id                8001                    state                forwarding
 designated root        0000.000c29443b19       path cost                  4
 designated bridge      0000.000c29443b19       message age timer          0.00
 designated port        8001                    forward delay timer        0.00
 designated cost           0                    hold timer                 0.00
 flags

The MAC address-table for a bridge can be displayed using the show bridge <name> macs command:

vyos@vyos:~$ show bridge br100 macs
port no mac addr                is local?       ageing timer
  1     00:0c:29:44:3b:19       yes                0.00

Bonding

You can combine (aggregate) 2 or more physical interfaces into a single logical one. It's called bonding, or LAG, or etherchannel, or portchannel.

Create interface bondX, where X is just a number:

set interfaces bonding bond0 description 'my-sw1 int 23 and 24'

You are able to choose a hash policy:

vyos@vyos# set interfaces bonding bond0 hash-policy
Possible completions:
  layer2       use MAC addresses to generate the hash (802.3ad)
  layer2+3     combine MAC address and IP address to make hash
  layer3+4     combine IP address and port to make hash

For example:

set interfaces bonding bond0 hash-policy 'layer2'

You may want to set IEEE 802.3ad Dynamic link aggregation (802.3ad) AKA LACP (don't forget to setup it on the other end of these links):

set interfaces bonding bond0 mode '802.3ad'

or some other modes:

vyos@vyos# set interfaces bonding bond0 mode
Possible completions:
  802.3ad      IEEE 802.3ad Dynamic link aggregation (Default)
  active-backup
               Fault tolerant: only one slave in the bond is active
  broadcast    Fault tolerant: transmits everything on all slave interfaces
  round-robin  Load balance: transmit packets in sequential order
  transmit-load-balance
               Load balance: adapts based on transmit load and speed
  adaptive-load-balance
               Load balance: adapts based on transmit and receive plus ARP
  xor-hash     Load balance: distribute based on MAC address

Now bond some physical interfaces into bond0:

set interfaces ethernet eth0 bond-group 'bond0'
set interfaces ethernet eth0 description 'member of bond0'
set interfaces ethernet eth1 bond-group 'bond0'
set interfaces ethernet eth1 description 'member of bond0'

After a commit you may treat bond0 as almost a physical interface (you can't change its` duplex, for example) and assign IPs or VIFs on it.

You may check the result:

vyos@vyos# run sh interfaces bonding
Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
Interface        IP Address                        S/L  Description
---------        ----------                        ---  -----------
bond0            -                                 u/u  my-sw1 int 23 and 24
bond0.10         192.168.0.1/24                    u/u  office-net
bond0.100        10.10.10.1/24                     u/u  management-net

Tunnel Interfaces

Set Virtual Tunnel interface

set interfaces vti vti0 address 192.168.2.249/30
vyos@vyos# show interfaces vti
vti vti0 {
    address 192.168.2.249/30
    description "Description"
}

Routing

VyOS is a "router first" network operating system. It supports static routing, policy routing, and dynamic routing using standard protocols (RIP, OSPF, and BGP).

Static

Static routes are manually configured network routes.

A typical use for a static route is a static default route for systems that do not make use of DHCP or dynamic routing protocols:

set protocols static route 0.0.0.0/0 next-hop 203.0.113.1 distance '1'

Producing the following configuration:

static {
    route 0.0.0.0/0 {
        next-hop 203.0.113.1 {
            distance 1
        }
    }
}

Another common use of static routes is to blackhole (drop) traffic. In the example below, RFC 1918 private IP networks are set as blackhole routes. This does not prevent networks within these segments from being used, since the most specific route is always used. It does, however, prevent traffic to unknown private networks from leaving the router. Commonly referred to as leaking.

set protocols static route 10.0.0.0/8 blackhole distance '254'
set protocols static route 172.16.0.0/12 blackhole distance '254'
set protocols static route 192.168.0.0/16 blackhole distance '254'

Resulting configuration:

route 10.0.0.0/8 {
    blackhole {
        distance 254
    }
}
route 172.16.0.0/12 {
    blackhole {
        distance 254
    }
}
route 192.168.0.0/16 {
    blackhole {
        distance 254
    }
}

Note that routes with a distance of 255 are effectively disabled and not installed into the kernel.

RIP

Simple RIP configuration using 2 nodes and redistributing connected interfaces.

Node 1:

set interfaces loopback address 1.1.1.1/32
set protocols rip network 192.168.0.0/24
set protocols rip redistribute connected

Node 2:

set interfaces loopback address 2.2.2.2/32
set protocols rip network 192.168.0.0/24
set protocols rip redistribute connected


Resulting configuration:

Node 1:

rip {
    network 192.168.0.0/24
    redistribute {
       connected {
       }
    }
}

Node 2:

rip {
    network 192.168.0.0/24
    redistribute {
       connected {
       }
    }
}

OSPF

IPv4

A typical configuration using 2 nodes, redistribute loopback address and the node 1 sending the default route:

Node 1:

set interfaces loopback lo address 1.1.1.1/32
set protocols ospf area 0 network 192.168.0.0/24
set protocols ospf default-information originate always
set protocols ospf default-information originate metric 10
set protocols ospf default-information originate metric-type 2
set protocols ospf log-adjacency-changes
set protocols ospf parameters router-id 1.1.1.1
set protocols ospf redistribute connected metric-type 2
set protocols ospf redistribute connected route-map CONNECT
set policy route-map CONNECT rule 10 action permit
set policy route-map CONNECT rule 10 match interface lo


Node 2:

set interfaces loopback lo address 2.2.2.2/32
set protocols ospf area 0 network 192.168.0.0/24
set protocols ospf log-adjacency-changes
set protocols ospf parameters router-id 2.2.2.2
set protocols ospf redistribute connected metric-type 2
set protocols ospf redistribute connected route-map CONNECT
set policy route-map CONNECT rule 10 action permit
set policy route-map CONNECT rule 10 match interface lo


Resulting configuration:

Node 1:

ospf {
   area 0 {
        network 192.168.0.0/24
   }
   default-information {
        originate {
            always
            metric 10
            metric-type 2
        }
   }
   log-adjacency-changes {
   }
   parameters {
       router-id 1.1.1.1
   }
   redistribute {
       connected {
           metric-type 2
           route-map CONNECT
       }
   }
}
route-map CONNECT {
    rule 10 {
        action permit
        match {
           interface lo
       }
  }
 }


Node 2:

ospf {
   area 0 {
        network 192.168.0.0/24
   }
   log-adjacency-changes {
   }
   parameters {
       router-id 2.2.2.2
   }
   redistribute {
       connected {
           metric-type 2
           route-map CONNECT
       }
   }
}
route-map CONNECT {
    rule 10 {
       action permit
       match {
          interface lo
       }
    }
}

IPv6

A typical configuration using 2 nodes.

Node 1:

set protocols ospfv3 area 0.0.0.0 interface eth1
set protocols ospfv3 area 0.0.0.0 range 2001:db8:1::/64
set protocols ospfv3 parameters router-id 192.168.1.1
set protocols ospfv3 redistribute connected

Node 2:

set protocols ospfv3 area 0.0.0.0 interface eth1
set protocols ospfv3 area 0.0.0.0 range 2001:db8:2::/64
set protocols ospfv3 parameters router-id 192.168.2.1
set protocols ospfv3 redistribute connected

Resulting configuration:

Node 1:

protocols {
  ospfv3 {
    area 0.0.0.0 {
        interface eth1
        range 2001:db8:1::/64 {
        }
    }
    parameters {
        router-id 192.168.1.1
    }
    redistribute {
        connected {
        }
    }
  }
}


Node 2:

protocols {
  ospfv3 {
    area 0.0.0.0 {
        interface eth1
        range 2001:db8:2::/64 {
        }
    }
    parameters {
        router-id 192.168.2.1
    }
    redistribute {
        connected {
        }
    }
  }
}


BGP

IPv4

A simple eBGP configuration:

Node 1:

set protocols bgp 65536 neighbor 192.168.0.2 ebgp-multihop '2'
set protocols bgp 65536 neighbor 192.168.0.2 remote-as '65537'
set protocols bgp 65536 neighbor 192.168.0.2 update-source ‘192.168.0.1
set protocols bgp 65536 network '1.0.0.0/16'
set protocols bgp 65536 parameters router-id ‘192.168.0.1

Node 2:

set protocols bgp 65537 neighbor 192.168.0.1 ebgp-multihop '2'
set protocols bgp 65537 neighbor 192.168.0.1 remote-as '65536’
set protocols bgp 65537 neighbor 192.168.0.1 update-source ‘192.168.0.2
set protocols bgp 65537 network 2.0.0.0/16'
set protocols bgp 65537 parameters router-id ‘192.168.0.2


Don’t forget, the CIDR declared in the network statement MUST exist in your routing table (dynamic or static), the best way to make sure that is true is creating a static route:

Node 1:

set protocols static route 1.0.0.0/16 blackhole distance '254'


Node 2:

set protocols static route 2.0.0.0/16 blackhole distance '254'


Resulting configuration:

Node 1:

bgp 65536 {
    neighbor 192.168.0.2 {
        ebgp-multihop 2
        remote-as 65537
        update-source 192.168.0.1
    }
    network 1.0.0.0/16 {
    }
    parameters {
        router-id 192.168.0.1
    }
}
static {
    route 1.0.0.0/16 {
        blackhole {
            distance 254
        }
    }
}


Node 2:

bgp 65537 {
    neighbor 192.168.0.1 {
        ebgp-multihop 2
        remote-as 65536
        update-source 192.168.0.2
    }
    network 2.0.0.0/16 {
    }
    parameters {
        router-id 192.168.0.2
    }
}
static {
    route 2.0.0.0/16 {
        blackhole {
            distance 254
        }
    }
}

IPv6

A simple BGP configuration via IPv6.

Node 1:

set protocols bgp 65536 neighbor 2a00:100::2 ebgp-multihop '2'
set protocols bgp 65536 neighbor 2a00:100::2 remote-as '65537'
set protocols bgp 65536 neighbor 2a00:100::2 update-source '2a00:100::1'
set protocols bgp 65536 neighbor 2a00:100::2 address-family ipv6-unicast
set protocols bgp 65536 address-family ipv6-unicast network '2a00:100:1::/48'
set protocols bgp 65536 parameters router-id '1.1.1.1'

Node 2:

set protocols bgp 65537 neighbor 2a00:100::1 ebgp-multihop '2'
set protocols bgp 65537 neighbor 2a00:100::1 remote-as '65536'
set protocols bgp 65537 neighbor 2a00:100::1 update-source '2a00:100::2'
set protocols bgp 65536 neighbor 2a00:100::1 address-family ipv6-unicast
set protocols bgp 65537 address-family ipv6-unicast network '2a00:100:2::/48'
set protocols bgp 65537 parameters router-id '1.1.1.2'


Don’t forget, the CIDR declared in the network statement MUST exist in your routing table (dynamic or static), the best way to make sure that is true is creating a static route:

Node 1:

set protocols static route6 2a001:100:1::/48 blackhole distance '254'

Node 2:

set protocols static route6 2a00:100:2::/48 blackhole distance '254'

Resulting configuration:

Node 1:

bgp 65536 {
     neighbor 2a00:100::2 {
         address-family {
             ipv6-unicast {
             }
         }
         ebgp-multihop 2
         remote-as 65537
         update-source 2a00:100::1
     }
     network 2a00:100:1::/48 {
     }
     parameters {
         router-id 1.1.1.1
     }
}
static {
     route6 2a00:100:1::/48 {
        blackhole {
           distance 254
        }
     }
}

Node 2:

bgp 65537 {
     neighbor 2a00:100::1 {
         address-family {
             ipv6-unicast {
             }
         }
         ebgp-multihop 2
         remote-as 65536
         update-source 2a00:100::2
     }
     network 2a00:100:2::/48 {
     }
     parameters {
         router-id 1.1.1.2
     }
}
static {
     route6 2a00:100:2::/48 {
        blackhole {
           distance 254
        }
     }
}

Route Filtering

Route filtering can be applied using a route-map:

Node1:

set policy prefix-list AS65537-IN rule 10 action 'permit'
set policy prefix-list AS65537-IN rule 10 prefix '2.0.0.0/16'
set policy prefix-list AS65537-OUT rule 10 action 'deny'
set policy prefix-list AS65537-OUT rule 10 prefix '2.0.0.0/16'
set policy prefix-list6 AS65537-IN rule 10 action 'permit'
set policy prefix-list6 AS65537-IN rule 10 prefix '2a00:100:2::/48'
set policy prefix-list6 AS65537-OUT rule 10 action 'deny'
set policy prefix-list6 AS65537-OUT rule 10 prefix '2a00:100:2::/48'
set policy route-map AS65537-IN rule 10 action 'permit'
set policy route-map AS65537-IN rule 10 match ip address prefix-list 'AS65537-IN'
set policy route-map AS65537-IN rule 10 match ipv6 address prefix-list 'AS65537-IN'
set policy route-map AS65537-IN rule 20 action 'deny'
set policy route-map AS65537-OUT rule 10 action 'deny'
set policy route-map AS65537-OUT rule 10 match ip address prefix-list 'AS65537-OUT'
set policy route-map AS65537-OUT rule 10 match ipv6 address prefix-list 'AS65537-OUT'
set policy route-map AS65537-OUT rule 20 action 'permit'
set protocols bgp 65536 neighbor 2a00:100::2 route-map export 'AS65537-OUT'
set protocols bgp 65536 neighbor 2a00:100::2 route-map import 'AS65537-IN'

Node2:

set policy prefix-list AS65536-IN rule 10 action 'permit'
set policy prefix-list AS65536-IN rule 10 prefix '1.0.0.0/16'
set policy prefix-list AS65536-OUT rule 10 action 'deny'
set policy prefix-list AS65536-OUT rule 10 prefix '1.0.0.0/16'
set policy prefix-list6 AS65536-IN rule 10 action 'permit'
set policy prefix-list6 AS65536-IN rule 10 prefix '2a00:100:1::/48'
set policy prefix-list6 AS65536-OUT rule 10 action 'deny'
set policy prefix-list6 AS65536-OUT rule 10 prefix '2a00:100:1::/48'
set policy route-map AS65536-IN rule 10 action 'permit'
set policy route-map AS65536-IN rule 10 match ip address prefix-list 'AS65536-IN'
set policy route-map AS65536-IN rule 10 match ipv6 address prefix-list 'AS65536-IN'
set policy route-map AS65536-IN rule 20 action 'deny'
set policy route-map AS65536-OUT rule 10 action 'deny'
set policy route-map AS65536-OUT rule 10 match ip address prefix-list 'AS65536-OUT'
set policy route-map AS65536-OUT rule 10 match ipv6 address prefix-list 'AS65536-OUT'
set policy route-map AS65536-OUT rule 20 action 'permit'
set protocols bgp 65537 neighbor 2a00:100::1 route-map export 'AS65536-OUT'
set protocols bgp 65537 neighbor 2a00:100::1 route-map import 'AS65536-IN'

We could expand on this and also deny link local and multicast in the rule 20 action deny.

Policy Routing

VyOS supports Policy Routing, allowing traffic to be assigned to a different routing table. Traffic can be matched using standard 5-tuple matching (source address, destination address, protocol, source port, destination port).

The following example will show how VyOS can be used to redirect web traffic to an external transparent proxy:

 set policy route FILTER-WEB rule 1000 destination port 80
 set policy route FILTER-WEB rule 1000 protocol tcp
 set policy route FILTER-WEB rule 1000 set table 100

This creates a route policy called FILTER-WEB with one rule to set the routing table for matching traffic (TCP port 80) to table ID 100 instead of the default routing table.

To create routing table 100 and add a new default gateway to be used by traffic matching our route policy:

 set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2

This can be confirmed using the show ip route table 100 operational command.

Finally, to apply the policy route to ingress traffic on our LAN interface, we use:

 set interfaces ethernet eth1 policy route FILTER-WEB

The route policy functionality in VyOS can also be used to rewrite TCP MSS using the set policy route <name> rule <rule> set tcp-mss <value> directive, modify DSCP value using [...] set dscp <value>, or mark the traffic with an internal ID using [...] set mark <value> for further processing (e.g. QOS) on a per-rule basis for matching traffic.

In addition to 5-tuple matching, additional options such as time-based rules, are available. See the built-in help for a complete list of options.

Firewall

VyOS makes use of Linux netfilter for packet filtering.

The firewall supports the creation of groups for ports, addresses, and networks (implemented using netfilter ipset) and the option of interface or zone based firewall policy.

Important note on usage of terms: The firewall makes use of the terms in, out, and local for firewall policy. Users experienced with netfilter often confuse in to be a reference to the INPUT chain, and out the OUTPUT chain from netfilter. This is not the case. These instead indicate the use of the FORWARD chain and either the input or output interface. The INPUT chain, which is used for local traffic to the OS, is a reference to as local with respect to its input interface.

Zone-based Firewall Policy

As an alternative to applying policy to an interface directly, a zone-based firewall can be created to simplify configuration when multiple interfaces belong to the same security zone. Instead of applying to rulesets to interfaces they are applied to source zone-destination zone pairs.

An introduction can to zone-based firewalls can be found here. For an example see Zone-policy example.

Groups

Firewall groups represent collections of IP addresses, networks, or ports. Once created, a group can be referenced by firewall rules as either a source or destination. Members can be added or removed from a group without changes to or the need to reload individual firewall rules. Note that groups can also be referenced by NAT configuration.

While network groups accept IP networks in CIDR notation, specific IP addresses can be added as a 32-bit prefix. If you foresee the need to add a mix of addresses and networks, the network group is recommended.

Here is an example of a network group for the IP networks that make up the internal network:

set firewall group network-group NET-INSIDE network 192.168.0.0/24
set firewall group network-group NET-INSIDE network 192.168.1.0/24

A port group represents only port numbers, not the protocol. Port groups can be referenced for either TCP or UDP. It is recommended that TCP and UDP groups are created separately to avoid accidentally filtering unnecessary ports. Ranges of ports can be specified by using a -.

Here is an example of a port group a server:

set firewall group port-group PORT-TCP-SERVER1 port 80
set firewall group port-group PORT-TCP-SERVER1 port 443
set firewall group port-group PORT-TCP-SERVER1 port 5000-5010

Rule-Sets

A rule-set is a named collection of firewall rules that can be applied to an interface or zone. Each rule is numbered, has an action to apply if the rule is matched, and the ability to specify the criteria to match.

Example of a rule-set to filter traffic to the internal network:

set firewall name INSIDE-OUT default-action drop
set firewall name INSIDE-OUT rule 1010 action accept
set firewall name INSIDE-OUT rule 1010 state established enable
set firewall name INSIDE-OUT rule 1010 state related enable
set firewall name INSIDE-OUT rule 1020 action drop
set firewall name INSIDE-OUT rule 1020 state invalid enable

Applying a Rule-Set to an Interface

Once a rule-set is created, it can be applied to an interface. Note only one rule-set can be applied to each interface for in, out, or local traffic for each protocol (IPv4 and IPv6).

set interfaces ethernet eth1 firewall out name INSIDE-OUT

Applying a Rule-Set to a Zone

A named rule-set can also be applied to a zone relationship (note, zones must first be created):

set zone-policy zone INSIDE from OUTSIDE firewall name INSIDE-OUT

Example Partial Config

firewall {
   all-ping enable
   broadcast-ping disable
   config-trap disable
   group {
       network-group BAD-NETWORKS {
           network 1.2.3.0/24
           network 1.2.4.0/24
       }
       network-group GOOD-NETWORKS {
           network 4.5.6.0/24
           network 4.5.7.0/24
       }
       port-group BAD-PORTS {
           port 65535
       }
   }
   name FROM-INTERNET {
       default-action accept
       description "From the Internet"
       rule 10 {
           action accept
           description "Authorized Networks"
           protocol all
           source {
               group {
                   network-group GOOD-NETWORKS
               }
           }
       }
       rule 11 {
           action drop
           description "Bad Networks"
           protocol all
           source {
               group {
                   network-group BAD-NETWORKS
               }
           }
       }
       rule 30 {
           action drop
           description "BAD PORTS"
           destination {
               group {
                   port-group BAD-PORTS
               }
           }
           log enable
           protocol all
       }
   }
}
interfaces {
   ethernet eth1 {
       address dhcp
       description OUTSIDE
       duplex auto
       firewall {
           in {
               name FROM-INTERNET
           }
       }
   }
}

XFinity Blocked Port List

NAT

Source NAT

Source NAT is typically referred to simply as NAT. To be more correct, what most people refer to as NAT is actually the process of Port Address Translation (PAT), or NAT Overload: The process of having many internal host systems communicate to the Internet using a single or subset of IP addresses.

To setup SNAT, we need to know:

  • The internal IP addresses we want to translate
  • The outgoing interface to perform the translation on
  • The external IP address to translate to

In the example used for the Quick Start configuration above, we demonstrate the following configuration:

set nat source rule 100 outbound-interface 'eth0'
set nat source rule 100 source address '192.168.0.0/24'
set nat source rule 100 translation address 'masquerade'

Which generates the following configuration:

rule 100 {
    outbound-interface eth0
    source {
        address 192.168.0.0/24
    }
    translation {
        address masquerade
    }
}

In this example, we use masquerade as the translation address instead of an IP address. The masquerade target is effectively an alias to say "use whatever IP address is on the outgoing interface", rather than a statically configured IP address. This is useful if you use DHCP for your outgoing interface and do not know what the external address will be.

When using NAT for a large number of host systems it recommended that a minimum of 1 IP address is used to NAT every 256 host systems. This is due to the limit of 65,000 port numbers available for unique translations and a reserving an average of 200-300 sessions per host system.

Example: For an ~ 8,000 host network a source NAT pool of 32 IP addresses is recommended.

A pool of addresses can be defined by using a - in the set nat source rule [n] translation address statement.

set nat source rule 100 translation address '203.0.113.32-203.0.113.63'



Note: Avoiding "Leaky" NAT

Linux netfilter will not NAT traffic marked as INVALID. This often confuses people into thinking that Linux (or specifically VyOS) has a broken NAT implementation because non-NATed traffic is seen leaving an external interface. This is actually working as intended, and a packet capture of the "leaky" traffic should reveal that the traffic is either an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems after Linux netfilter considers the connection closed. The most common is the additional TCP RST some host implementations send after terminating a connection (which is implementation-specific).

In other words, connection tracking has already observed the connection be closed and has transition the flow to INVALID to prevent attacks from attempting to reuse the connection.

You can avoid the "leaky" behavior by using a firewall policy that drops "invalid" state packets.

Having control over the matching of INVALID state traffic, e.g. the ability to selectively log, is an important troubleshooting tool for observing broken protocol behavior. For this reason, VyOS does not globally drop invalid state traffic, instead allowing the operator to make the determination on how the traffic is handled.



Note: Avoiding NAT breakage in the absence of split-DNS

A typical problem with using NAT and hosting public servers is the ability for internal systems to reach an internal server using it's external IP address. The solution to this is usually the use of split-DNS to correctly point host systems to the internal address when requests are made internally. Because many smaller networks lack DNS infrastructure, a work-around is commonly deployed to facilitate the traffic by NATing the request from internal hosts to the source address of the internal interface on the firewall. This technique is commonly reffered to as NAT Reflection, or Hairpin NAT.

In this example, we will be using the example Quick Start configuration above as a starting point.

To setup a NAT reflection rule, we need to create a rule to NAT connections from the internal network to the same internal network to use the source address of the internal interface.

set nat source rule 110 description 'NAT Reflection: INSIDE'
set nat source rule 110 destination address '192.168.0.0/24'
set nat source rule 110 outbound-interface 'eth1'
set nat source rule 110 source address '192.168.0.0/24'
set nat source rule 110 translation address 'masquerade'

Which results in a configuration of:

rule 110 {
    description "NAT Reflection: INSIDE"
    destination {
        address 192.168.0.0/24
    }
    outbound-interface eth1
    source {
        address 192.168.0.0/24
    }
    translation {
        address masquerade
    }
}

Destination NAT

DNAT is typically referred to as a Port Forward. When using VyOS as a NAT router and firewall, a common configuration task is to redirect incoming traffic to a system behind the firewall.

In this example, we will be using the example Quick Start configuration above as a starting point.

To setup a destination NAT rule we need to gather:

  • The interface traffic will be coming in on
  • The protocol and port we wish to forward
  • The IP address of the internal system we wish to forward traffic to

In our example, we will be forwarding web server traffic to an internal web server on 192.168.0.100.

HTTP traffic makes use of the TCP protocol on port 80.

For other common port numbers, see: [1]

Our configuration commands would be:

set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100'
set nat destination rule 10 destination port '80'
set nat destination rule 10 inbound-interface 'eth0'
set nat destination rule 10 protocol 'tcp'
set nat destination rule 10 translation address '192.168.0.100'

Which would generate the following NAT destination configuration:

nat {
    destination {
        rule 10 {
            description "Port Forward: HTTP to 192.168.0.100"
            destination {
                port 80
            }
            inbound-interface eth0
            protocol tcp
            translation {
                address 192.168.0.100
            }
        }
    }
}

Note that if forwarding traffic to a different port than it is arriving on, you may also configure the translation port using set nat destination rule [n] translation port.

This establishes our Port Forward rule, but if we created a firewall policy it will likely block the traffic.

It is important to note that when creating firewall rules that the DNAT translation occurs before traffic traverses the firewall. In other words, the destination address has already been translated to 192.168.0.100.

So in our firewall policy, we want to allow traffic coming in on the outside interface, destined for TCP port 80 and the IP address of 192.168.0.100.

set firewall name OUTSIDE-IN rule 20 action 'accept'
set firewall name OUTSIDE-IN rule 20 destination address '192.168.0.100'
set firewall name OUTSIDE-IN rule 20 destination port '80'
set firewall name OUTSIDE-IN rule 20 protocol 'tcp'
set firewall name OUTSIDE-IN rule 20 state new 'enable'

This would generate the following configuration:

rule 20 {
    action accept
    destination {
        address 192.168.0.100
        port 80
    }
    protocol tcp
    state {
        new enable
    }
}

Note: If you have configured the INSIDE-OUT policy, you will need to add additional rules to permit inbound NAT traffic.

1-to-1 NAT

Another term often used for DNAT is 1-to-1 NAT.

For a 1-to-1 NAT configuration, both DNAT and SNAT are used to NAT all traffic from an external IP address to an internal IP address and vice-versa.

Typically, a 1-to-1 NAT rule omits the destination port (all ports) and replaces the protocol with either all or ip.

Then a corresponding SNAT rule is created to NAT outgoing traffic for the internal IP to a reserved external IP. This dedicates an external IP address to an internal IP address and is useful for protocols which don't have the notion of ports, such as GRE.

1-to-1 NAT example

Here's an extract of a simple 1-to-1 NAT configuration with one internal and one external interface:

set interfaces ethernet eth0 address '192.168.1.1/24'
set interfaces ethernet eth0 description 'Inside interface'
set interfaces ethernet eth1 address '1.2.3.4/24'
set interfaces ethernet eth1 description 'Outside interface'
set nat destination rule 2000 description '1-to-1 NAT example'
set nat destination rule 2000 destination address '1.2.3.4'
set nat destination rule 2000 inbound-interface 'eth1'
set nat destination rule 2000 translation address '192.168.1.10'
set nat source rule 2000 description '1-to-1 NAT example'
set nat source rule 2000 outbound-interface 'eth1'
set nat source rule 2000 source address '192.168.1.10'
set nat source rule 2000 translation address '1.2.3.4'

Firewall rules are written as normal, using the internal IP address as the source of outbound rules and the destination of inbound rules.

NPTv6 (RFC6296)

See here : How_to_do_NPTv6

VPN

OpenVPN

Main article: OpenVPN

Traditionally hardware routers implement IPsec exclusively due to relative ease of implementing it in hardware and insufficient CPU power for doing encryption in software. Since VyOS is a software router, this is less of a concern. OpenVPN has been widely used on UNIX platform for a long time and is a popular option for remote access VPN, though it's also capable of site-to-site connections.

The advantages of OpenVPN are:

  • It uses a single TCP or UDP connection and does not rely on packet source addresses, so it will work even through a double NAT: perfect for public hotspots and such
  • It's easy to setup and offers very flexible split tunneling
  • There's a variety of client GUI frontends for any platform

The disadvantages are:

  • It's slower than IPsec due to higher protocol overhead and the fact it runs in user mode while IPsec, on Linux, is in kernel mode
  • None of the operating systems have client software installed by default

In the VyOS CLI, a key point often overlooked is that rather than being configured using the set vpn stanza, OpenVPN is configured as a network interface using set interfaces openvpn.

OpenVPN Site-To-Site

While many are aware of OpenVPN as a Client VPN solution, it is often overlooked as a site-to-site VPN solution due to lack of support for this mode in many router platforms.

Site-to-site mode supports x.509 but doesn't require it and can also work with static keys, which is simpler in many cases. In this example, we'll configure a simple site-to-site OpenVPN tunnel using a 2048-bit pre-shared key.

First, one one of the systems generate the key using the operational command generate openvpn key <filename>. This will generate a key with the name provided in the /config/auth/ directory. Once generated, you will need to copy this key to the remote router.

In our example, we used the filename openvpn-1.key which we will reference in our configuration.

  • The public IP address of the local side of the VPN will be 198.51.100.10
  • The remote will be 203.0.113.11
  • The tunnel will use 10.255.1.1 for the local IP and 10.255.1.2 for the remote.
  • OpenVPN allows for either TCP or UDP. UDP will provide the lowest latency, while TCP will work better for lossy connections; generally UDP is preferred when possible.
  • The official port for OpenVPN is 1194, which we reserve for client VPN; we will use 1195 for site-to-site VPN.
  • The persistent-tunnel directive will allow us to configure tunnel-related attributes, such as firewall policy as we would on any normal network interface.
  • If known, the IP of the remote router can be configured using the remote-host directive; if unknown, it can be omitted. We will assume a dynamic IP for our remote router.

Local Configuration:

 set interfaces openvpn vtun1 mode site-to-site
 set interfaces openvpn vtun1 protocol udp
 set interfaces openvpn vtun1 persistent-tunnel
 set interfaces openvpn vtun1 local-host '198.51.100.10'
 set interfaces openvpn vtun1 local-port '1195'
 set interfaces openvpn vtun1 remote-port '1195'
 set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key'
 set interfaces openvpn vtun1 local-address '10.255.1.1'
 set interfaces openvpn vtun1 remote-address '10.255.1.2'

Remote Configuration:

 set interfaces openvpn vtun1 mode site-to-site
 set interfaces openvpn vtun1 protocol udp
 set interfaces openvpn vtun1 persistent-tunnel
 set interfaces openvpn vtun1 remote-host '198.51.100.10'
 set interfaces openvpn vtun1 local-port '1195'
 set interfaces openvpn vtun1 remote-port '1195'
 set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key'
 set interfaces openvpn vtun1 local-address '10.255.1.2'
 set interfaces openvpn vtun1 remote-address '10.255.1.1'

The configurations above will default to using 128-bit Blowfish in CBC mode for encryption and SHA-1 for HMAC authentication. These are both considered weak, but a number of other encryption and hashing algorithms are available:

For Encryption:

vyos@vyos# set interfaces openvpn vtun1 encryption
Possible completions:
  des          DES algorithm
  3des         DES algorithm with triple encryption
  bf128        Blowfish algorithm with 128-bit key
  bf256        Blowfish algorithm with 256-bit key
  aes128       AES algorithm with 128-bit key
  aes192       AES algorithm with 192-bit key
  aes256       AES algorithm with 256-bit key

For Hashing:

vyos@vyos# set interfaces openvpn vtun1 hash
Possible completions:
  md5          MD5 algorithm
  sha1         SHA-1 algorithm
  sha256       SHA-256 algorithm
  sha512       SHA-512 algorithm

If you change the default encryption and hashing algorithms, be sure that the local and remote ends have matching configurations, otherwise the tunnel will not come up.

Static routes can be configured referencing the tunnel interface; for example, the local router will use a network of 10.0.0.0/16, while the remote has a network of 10.1.0.0/16:

Local Configuration:

 set protocols static interface-route 10.1.0.0/16 next-hop-interface vtun1

Remote Configuration:

 set protocols static interface-route 10.0.0.0/16 next-hop-interface vtun1

Firewall policy can also be applied to the tunnel interface for local, in, and out directions and function identically to ethernet interfaces.

If making use of multiple tunnels, OpenVPN must have a way to distinguish between different tunnels aside from the pre-shared-key. This is either by referencing IP address or port number. One option is to dedicate a public IP to each tunnel. Another option is to dedicate a port number to each tunnel (e.g. 1195,1196,1197...)

OpenVPN status can be verified using the show openvpn operational commands. See the built-in help for a complete list of options.

OpenVPN Server

Multi-client server is the most popular OpenVPN mode on routers. It always x.509 authentication and therefore requires a PKI setup. This guide assumes you have already setup a PKI and have a CA certificate, a server certificate and key, a certificate revokation list, a Diffie-Hellman key exchange parameters file. You do not need client certificates and keys for the server setup.

In this example we will use the most complicated case: a setup where each client is a router that has its own subnet (think HQ and branch offices), since simpler setups are subsets of it.

Suppose you want to use 10.23.1.0/24 network for client tunnel endpoints and all client subnets belong to 10.23.0.0/20. All clients need access to the 192.168.0.0/16 network.

First we need to specify the basic settings. 1194/UDP is the default. The persistent-tunnel option is recommended, it prevents the TUN/TAP device from closing on connection resets or daemon reloads.

set interfaces openvpn vtun10 mode server
set interfaces openvpn vtun10 local-port 1194
set interfaces openvpn vtun10 persistent-tunnel
set interfaces openvpn vtun10 protocol udp

Then we need to specify the location of the cryptographic materials. Suppose you keep the files in /config/auth/openvpn

set interfaces openvpn vtun10 tls ca-cert-file /config/auth/openvpn/ca.crt
set interfaces openvpn vtun10 tls cert-file /config/auth/openvpn/server.crt
set interfaces openvpn vtun10 tls key-file /config/auth/openvpn/server.key
set interfaces openvpn vtun10 tls crl-file /config/auth/openvpn/crl.pem
set interfaces openvpn vtun10 tls dh-file /config/auth/openvpn/dh2048.pem

Now we need to specify the server network settings. In all cases we need to specify the subnet for client tunnel endpoints. Since we want clients to access a specific network behind out router, we will use a push-route option for installing that route on clients.

set interfaces openvpn vtun10 server push-route 192.168.0.0/16
set interfaces openvpn vtun10 server subnet 10.23.1.0/24

Since it's a HQ and branch offices setup, we will want all clients to have fixed addresses and we will route traffic to specific subnets through them. We need configuration for each client to achieve this. Note that clients are identified by the CN field of their x.509 certificates, in this example the CN is client0:

set interfaces openvpn vtun10 server client client0 ip 10.23.1.10
set interfaces openvpn vtun10 server client client0 subnet 10.23.2.0/25

OpenVPN will not automatically create routes in the kernel for client subnets when they connect and will only use client-subnet association internally, so we need to create a route to the 10.23.0.0/20 network ourselves:

set protocols static interface-route 10.23.0.0/20 next-hop-interface vtun10

L2TP over IPsec

Example for configuring a simple L2TP over IPsec VPN for remote access (works with native Windows and Mac VPN clients):

set vpn ipsec ipsec-interfaces interface eth0
set vpn ipsec nat-traversal enable
set vpn ipsec nat-networks allowed-network 0.0.0.0/0
set vpn l2tp remote-access outside-address 203.0.113.2
set vpn l2tp remote-access client-ip-pool start 192.168.255.1
set vpn l2tp remote-access client-ip-pool stop 192.168.255.254
set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret
set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret <secret>
set vpn l2tp remote-access authentication mode local
set vpn l2tp remote-access authentication local-users username <username> password <password>

In the example above an external IP of 203.0.113.2 is assumed.

If a local firewall policy is in place on your external interface you will need to open:

  • UDP port 500 (IKE)
  • IP protocol number 50 (ESP)
  • UDP port 1701 for IPsec

In addition when NAT is detected by the VPN client ESP is encapsulated in UDP for NAT-traversal:

  • UDP port 4500 (NAT-T)

Example:

set firewall name OUTSIDE-LOCAL rule 40 action 'accept'
set firewall name OUTSIDE-LOCAL rule 40 destination port '50'
set firewall name OUTSIDE-LOCAL rule 40 protocol 'esp'
set firewall name OUTSIDE-LOCAL rule 41 action 'accept'
set firewall name OUTSIDE-LOCAL rule 41 destination port '500'
set firewall name OUTSIDE-LOCAL rule 41 protocol 'udp'
set firewall name OUTSIDE-LOCAL rule 42 action 'accept'
set firewall name OUTSIDE-LOCAL rule 42 destination port '4500'
set firewall name OUTSIDE-LOCAL rule 42 protocol 'udp'
set firewall name OUTSIDE-LOCAL rule 43 action 'accept'
set firewall name OUTSIDE-LOCAL rule 43 destination port '1701'
set firewall name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec'
set firewall name OUTSIDE-LOCAL rule 43 protocol 'udp'

Also note that if you wish to allow the VPN to be used for external access you will need to add the appropriate source NAT rules to your configuration.

set nat source rule 110 outbound-interface 'eth0'
set nat source rule 110 source address '192.168.255.0/24'
set nat source rule 110 translation address masquerade

To be able to resolve when connected to the VPN, the following DNS rules are needed as well.

set vpn l2tp remote-access dns-servers server-1 '8.8.8.8'
set vpn l2tp remote-access dns-servers server-2 '8.8.4.4'


Established sessions can be viewed using the show vpn remote-access operational command.

vyos@vyos:~$ show vpn remote-access
Active remote access VPN sessions:
User            Proto Iface     Tunnel IP       TX byte RX byte  Time
----            ----- -----     ---------       ------- -------  ----
vyos            L2TP  l2tp0     192.168.255.1      3.2K    8.0K  00h06m13s

Site-to-Site IPsec

Example:

  • eth1 is WAN interface
  • left subnet: 192.168.0.0/24 #s ite1, server side (i.e. locality, actually there is no client or server roles)
  • left local_ip: 1.1.1.1 # server side WAN IP
  • right subnet: 10.0.0.0/24 # site2,remote office side
  • right local_ip: 2.2.2.2 # remote office side WAN IP
# server side config
set vpn ipsec esp-group office-srv-esp compression 'disable'
set vpn ipsec esp-group office-srv-esp lifetime '1800'
set vpn ipsec esp-group office-srv-esp mode 'tunnel'
set vpn ipsec esp-group office-srv-esp pfs 'enable'
set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256'
set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1'
set vpn ipsec ike-group office-srv-ike ikev2-reauth 'no'
set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1'
set vpn ipsec ike-group office-srv-ike lifetime '3600'
set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256'
set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1'
set vpn ipsec ipsec-interfaces interface 'eth1'
set vpn ipsec site-to-site peer 2.2.2.2 authentication mode 'pre-shared-secret'
set vpn ipsec site-to-site peer 2.2.2.2 authentication pre-shared-secret 'SomePreSharedKey'
set vpn ipsec site-to-site peer 2.2.2.2 ike-group 'office-srv-ike'
set vpn ipsec site-to-site peer 2.2.2.2 local-address '1.1.1.1'
set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 allow-nat-networks 'disable'
set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 allow-public-networks 'disable'
set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 esp-group 'office-srv-esp'
set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 local prefix '192.168.0.0/24'
set vpn ipsec site-to-site peer 2.2.2.2 tunnel 0 remote prefix '10.0.0.0/21'
# remote office side config
set vpn ipsec esp-group office-srv-esp compression 'disable'
set vpn ipsec esp-group office-srv-esp lifetime '1800'
set vpn ipsec esp-group office-srv-esp mode 'tunnel'
set vpn ipsec esp-group office-srv-esp pfs 'enable'
set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256'
set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1'
set vpn ipsec ike-group office-srv-ike ikev2-reauth 'no'
set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1'
set vpn ipsec ike-group office-srv-ike lifetime '3600'
set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256'
set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1'
set vpn ipsec ipsec-interfaces interface 'eth1'
set vpn ipsec site-to-site peer 1.1.1.1 authentication mode 'pre-shared-secret'
set vpn ipsec site-to-site peer 1.1.1.1 authentication pre-shared-secret 'SomePreSharedKey'
set vpn ipsec site-to-site peer 1.1.1.1 ike-group 'office-srv-ike'
set vpn ipsec site-to-site peer 1.1.1.1 local-address '2.2.2.2'
set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 allow-nat-networks 'disable'
set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 allow-public-networks 'disable'
set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 esp-group 'office-srv-esp'
set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 local prefix '10.0.0.0/21'
set vpn ipsec site-to-site peer 1.1.1.1 tunnel 0 remote prefix '192.168.0.0/24'
vyos@srv-gw0:~$ show vpn ike sa
Peer ID / IP                            Local ID / IP
------------                            -------------
2.2.2.2                                 1.1.1.1
   State  Encrypt  Hash    D-H Grp  NAT-T  A-Time  L-Time
   -----  -------  ----    -------  -----  ------  ------
   up     aes256   sha1    5        no     734     3600


vyos@srv-gw0:~$ show vpn ipsec sa
Peer ID / IP                            Local ID / IP
------------                            -------------
2.2.2.2                                 1.1.1.1
   Tunnel  State  Bytes Out/In   Encrypt  Hash    NAT-T  A-Time  L-Time  Proto
   ------  -----  -------------  -------  ----    -----  ------  ------  -----
   0       up     7.5M/230.6K    aes256   sha1    no     567     1800    all

If there is SNAT rules on eth1, need to add exclude rule

# server side
set nat source rule 10 destination address '10.0.0.0/24'
set nat source rule 10 'exclude'
set nat source rule 10 outbound-interface 'eth1'
set nat source rule 10 source address '192.168.0.0/24'
# remote office side
set nat source rule 10 destination address '192.168.0.0/24'
set nat source rule 10 'exclude'
set nat source rule 10 outbound-interface 'eth1'
set nat source rule 10 source address '10.0.0.0/24'

To allow traffic to pass through to clients, you need to add the following rules. (if you used the default configuration at the top of this page)

# server side
set firewall name OUTSIDE-LOCAL rule 32 action 'accept'
set firewall name OUTSIDE-LOCAL rule 32 source address '10.0.0.0/24'
# remote office side
set firewall name OUTSIDE-LOCAL rule 32 action 'accept'
set firewall name OUTSIDE-LOCAL rule 32 source address '192.168.0.0/24'

DMVPN

Advanced DMVPN configuration examples are available on the DMVPN page.

QoS and Traffic Policy

The traffic policy subsystem provides an interface to Linux traffic control.

One common use of traffic policy is to limit bandwidth for an interface. In the example below we limit bandwidth for our LAN connection to 200M download and out WAN connection to 50M upload:

set traffic-policy shaper WAN-OUT bandwidth '50Mbit'
set traffic-policy shaper WAN-OUT default bandwidth '50%'
set traffic-policy shaper WAN-OUT default ceiling '100%'
set traffic-policy shaper WAN-OUT default queue-type 'fair-queue'
set traffic-policy shaper LAN-OUT bandwidth '200Mbit'
set traffic-policy shaper LAN-OUT default bandwidth '50%'
set traffic-policy shaper LAN-OUT default ceiling '100%'
set traffic-policy shaper LAN-OUT default queue-type 'fair-queue'

Resulting in the following configuration:

traffic-policy {
    shaper WAN-OUT {
        bandwidth 50Mbit
        default {
            bandwidth 50%
            ceiling 100%
            queue-type fair-queue
        }
    }
    shaper LAN-OUT {
        bandwidth 200Mbit
        default {
            bandwidth 50%
            ceiling 100%
            queue-type fair-queue
        }
    }
}

Once defined, a traffic policy can be applied to each interface using the interface-level traffic-policy directive:

set interfaces ethernet eth0 traffic-policy out 'WAN-OUT'
set interfaces ethernet eth1 traffic-policy out 'LAN-OUT'

Note that a traffic policy can also be defined to match specific traffic flows using class statements.

VyOS also supports HFSC (included in Lithium).

set traffic-policy shaper-hfsc

See further information on the QoS page.

DHCP Server

For more information, refer to the DHCP server page.

VyOS provides a DHCP server. The following example provides open pool addressing for a LAN network:

VyOS < 1.2.0

set service dhcp-server shared-network-name 'LAN' authoritative enable
set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' start '192.168.0.128' stop '192.168.0.254'
set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' default-router '192.168.0.1'
set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' dns-server '192.168.0.1'
set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' domain-name 'internal-net'
set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' lease 86400

VyOS >= 1.2.0

Multiple ranges can be defined and can contain holes.

set service dhcp-server shared-network-name 'LAN' authoritative
set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' range 0 start '192.168.0.128'
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' default-router '192.168.0.1'
set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' dns-server '192.168.0.1'
set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' domain-name 'internal-net'
set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' lease 86400

This will provide dynamic addressing using a 24-hour lease and the range of 128-254 for host addressing, reserving the first half of the network for static assignment. Note that the DHCP service will NOT be authoritative for the subnet unless explicitly configured.

Static mappings can also be configured for hosts which need a fixed address via DHCP:

set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' static-mapping 'SERVER' ip-address '192.168.0.10'
set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' static-mapping 'SERVER' mac-address '00:53:00:00:00:01'

Failover

VyOS provides support for DHCP failover:

set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover local-address '192.168.0.1'
set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover name 'foo'
set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover peer-address '192.168.0.2'

NOTE: name must be identical on both sides!

The primary and secondary statements determines whether the server is primary or secondary

set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'primary'

or

set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'secondary'

DHCPv6 server

DHCPv6 server shares most of the configuration options with IPv4 DHCP, with one major exception: in IPv6, DHCP is never used for default gateway configuration. If default gateway is configured automatically, it is always done via router advertisment (RA).

Since router advertisment cannot be deactivated even if DHCPv6 is in use, first you need to set the "managed flag" in RA, which instructs clients to request an IPv6 address via DHCPv6 instead of using SLAAC or EUI-64.

set interfaces ethernet eth1 address '2001:db8:ff::1/64'
set interfaces ethernet eth1 ipv6 router-advert managed-flag 'true'

Then you can setup DHCPv6 server:

set service dhcpv6-server shared-network-name LAN subnet 2001:db8:ff::/64 address-range prefix '2001:db8:ff::/64'
set service dhcpv6-server shared-network-name LAN subnet 2001:db8:ff::/64 address-range start 2001:db8::1000 stop '2001:db8::ffff'
set service dhcpv6-server shared-network-name LAN subnet 2001:db8:ff::/64 name-server '2001:db8:aa::bb'

DHCP-Relay

VyOS can act as a DHCP relay, sending DHCP requests from locally connected networks to a central DHCP server, or servers:

set service dhcp-relay interface eth0
set service dhcp-relay interface eth1
set service dhcp-relay server 192.168.0.4
set service dhcp-relay server 192.168.0.5

An important note that dhcp-relay currently requires specifying the interface the DHCP server replies come from in addition to interfaces to listen on. An upstream bug exists for this: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=648401

By default the ISC dhcp-relay process will relay relay packets; as this is not expected behavior, disabling this functionality is recommended using the following directive:

 set service dhcp-relay relay-options relay-agents-packets discard

Additional protections can be configured matching hop-limit and max-size for DHCP packets.

 set service dhcp-relay hop-count 10
 set service dhcp-relay max-size 576

DNS Forwarder

VyOS provides a DNS forwarder. This example shows the forwarder being used to listen for DNS request on interface eth1 and use Google Public DNS for name servers with caching disabled:

 set service dns forwarding name-server 8.8.8.8
 set service dns forwarding name-server 8.8.4.4
 set service dns forwarding cache-size 0
 set service dns forwarding listen-on eth1

Alternatively, DNS servers can be specified to be the system DNS servers using the set service dns forwarding system directive, or to those obtained via DHCP using the [...] dhcp <interface> directive.

By default, the forwarder will also make use of the local hosts on the system; this can be disable using the ignore-host-file directive.

To add entries to the local hosts file for the system, the set system static-host-mapping directive can be used:

 set system static-host-mapping host-name example.com inet 127.0.0.1

Dynamic DNS

VyOS provides a dynamic DNS update agent which can be used to update DNS providers when dynamic addressing is used.

set service dns dynamic interface eth0

More information here : Dynamic_DNS

mDNS Repeater

VyOS (1.2.x) provides a Multicast DNS repeater functionality.

Multicast DNS uses the 224.0.0.51 address, which is "administratively scoped" and does not leave the subnet. It re-broadcast mDNS packets from one interface to other interfaces. This enables support for e.g. Airplay devices across multiple VLANs.

set service mdns repeater interface eth0
set service mdns repeater interface eth1

Will re-broadcast all mDNS packets from eth0 to eth1 and vice versa.

mDNS repeater can be disabled using set service mdns repeater disable

UDP broadcast relay

Certain vendors use broadcasts to identify their equipemnt within one ethernet segment. Unfortunately if you split your network with multiple VLANs you loose the ability of identifying your equiment. This is where "UDP broadcast relay" comes into work. It will forward received broadcasts to other configured networks.

Every UDP port which will be forward requires one unique ID. Currently we support 99 IDs!

Forward broadcasts on port 1900 for eth3, eth4 and eth5

set service broadcast-relay id 1 description 'SONOS'
set service broadcast-relay id 1 interface 'eth3'
set service broadcast-relay id 1 interface 'eth4'
set service broadcast-relay id 1 interface 'eth5'
set service broadcast-relay id 1 port '1900'

Forward broadcasts on port 6969 for eth3, eth4

set service broadcast-relay id 2 description 'SONOS MGMT'
set service broadcast-relay id 2 interface 'eth3'
set service broadcast-relay id 2 interface 'eth4'
set service broadcast-relay id 2 port '6969'

Each broadcast relay instance can be disabled using set service broadcast-relay id <n> disable.

In addition you can disable the whole service without removing the configuration by set service broadcast-relay disable.


System Configuration

System Users

As of 1.1.8 release and 1.2.0 release candidates, VyOS support two user privilege levels: admin and operator. However, the operator level is a legacy feature and was proved insecure: any user can escape the restricted shell in multiple easy way. That feature will be removed in future releases, and we do not recommend using it.


Creating Login User Accounts

Create user account jsmith, with admin level access and the password "mypassword"

set system login user jsmith full-name "Johan Smith"
set system login user jsmith authentication plaintext-password mypassword
commit

The command:

show system login

will show the contents of the system login configuration node:

user jsmith {
    authentication {
        encrypted-password $6$0OQHjuQ8M$AYXVn7jufdfqPrSk4/XXsDBw99JBtNsETkQKDgVLptXogHA2bU9BWlvViOFPBoFxIi.iqjqrvsQdQ./cfiiPT.
        plaintext-password ""
    }
    full-name "Johan Smith"
    level admin
}

Configuring for SSH Access using Shared Public Keys

The following command will load the public key dev.pub for user jsmith

loadkey jsmith dev.pub

Note: this requires uploading the dev.pub public key to the vyos firewall first. As an alternative you can also load the ssh public key directly from a remote system:

loadkey jsmith scp://devuser@dev001.vyos.net/home/devuser/.ssh/dev.pub

IPv6

Advanced IPv6 configuration examples are available on the IPv6 page.

Clustering

VyOS supports multicast and unicast clustering. Multicast is default and to use the unicast method you can add the peer directive to the interface with the ip of the other cluster member.

In the example below SSH is clustered between two nodes with the unicast method.

cluster {
  dead-interval 20000
  group cluster {
    auto-failback false
    primary vyos
    secondary vyos2
    service ssh
    service 192.168.0.123/24/eth0
  }
  interface eth0 {
    peer 192.168.0.121
  }
  keepalive-interval 5000
  monitor-dead-interval 20000
  pre-shared-secret S3cr#t
}

System Image Management

The VyOS image-based installation is implemented by creating a directory for each image on the storage device selected during the install process.

The directory structure of the boot device:

 /
 /boot
 /boot/grub
 /boot/VyOS_999.hydrogen.11291501

The image directory contains the system kernel, a compressed image of the root filesystem for the OS, and a directory for persistent storage, such as configuration.

On boot, the system will extract the OS image into memory and mount the appropriate live-rw sub-directories to provide persistent storage system configuration.

This process allows for a system to always boot to a known working state, as the OS image is fixed and non-persistent. It also allows for multiple releases of VyOS to be installed on the same storage device.

The image can be selected manually at boot if needed, but the system will otherwise boot the image configured to be the default.

The default boot image can be set using the set system image default-boot command in operational mode.

A list of available images can be shown using the show system image command in operational mode.

vyos@vyos:~$ show system image
The system currently has the following image(s) installed:
   1: 999.hydrogen.12130649 (default boot) (running image)
   2: 999.hydrogen.12100644
vyos@vyos:~$

Images no longer needed can be removed using the delete system image command.

Finally, new system images can be added using the add system image command. The add image command will extract the image from the release ISO (either on the local filesystem or remotely if a URL is provided). The image install process will prompt you to use the current system configuration and SSH security keys, allowing for the new image to boot using the current configuration.

Note that configuration is associated to each image, and each image has a unique copy of its configuration. This is different than a traditional network router where the configuration is shared across all images.

If you need some files from a previous images - take a look inside a /live directory.

Troubleshooting

Sometimes things break or don't work as expected. This section describes several troubleshooting tools provided by VyOS that can help when something goes wrong.

Basic Connectivity Verification

Verifying connectivity can be done with the familiar ping and traceroute commands. The options for each are shown (the options for each command were displayed using the built-in help as described in the Using the Command-Line Interface section and are omitted from the output here):

vyos@vyos:~$ ping
Possible completions:
 <hostname>    Send Internet Control Message Protocol (ICMP) echo request
 <x.x.x.x>
 <h:h:h:h:h:h:h:h>
vyos@vyos:~$

Several options are available when more extensive troubleshooting is needed:

vyos@vyos:~$ ping 8.8.8.8
Possible completions:
 <Enter>       Execute the current command
 adaptive      Ping options
 allow-broadcast
 audible
 bypass-route
 count
 deadline
 flood
 interface
 interval
 mark
 no-loopback
 numeric
 pattern
 quiet
 record-route
 size
 timestamp
 tos
 ttl
 verbose
vyos@vyos:~$
vyos@vyos:~$ traceroute
Possible completions:
 <hostname>    Track network path to specified node
 <x.x.x.x>
 <h:h:h:h:h:h:h:h>
 ipv4          Track network path to <hostname|IPv4 address>
 ipv6          Track network path to <hostname|IPv6 address>
vyos@vyos:~$

However, another tool, mtr, is available which combines ping and traceroute into a single tool. An example of its output is shown:

vyos@vyos:~$ mtr 10.62.212.12

The output of mtr consumes the screen and will replace your command prompt:

                                       My traceroute  [v0.75]
vyos (0.0.0.0)                                                                         Fri Feb 24 14:28:08 2017
Keys:  Help   Display mode   Restart statistics   Order of fields   quit
                                                                             Packets               Pings
Host                                                                 Loss%   Snt   Last   Avg  Best  Wrst StDev
1. 10.11.110.4                                                       0.0%    34    0.5   0.5   0.4   0.8   0.1
2. 10.62.255.184                                                     0.0%    34    1.1   1.0   0.9   1.4   0.1
3. 10.62.255.71                                                      0.0%    34    1.4   1.4   1.3   2.0   0.1
4. 10.62.212.12                                                      0.0%    34    1.6   1.6   1.6   1.7   0.0

Several options are available for changing the display output. Press h to invoke the built in help system. To quit, just press q and you'll be returned to the VyOS command prompt.

Monitoring Network Interfaces

It's possible to monitor network traffic, either at the flow level or protocol level. This can be useful when troubleshooting a variety of protocols and configurations. The following interface types can be monitored:

vyos@vyos:~$ monitor interfaces
Possible completions:
 <Enter>       Execute the current command
 bonding       Monitor a bonding interface
 bridge        Monitor a bridge interface
 ethernet      Monitor a ethernet interface
 loopback      Monitor a loopback interface
 openvpn       Monitor an openvpn interface
 pppoe         Monitor pppoe interface
 pseudo-ethernet
               Monitor a pseudo-ethernet interface
 tunnel        Monitor a tunnel interface
 vrrp          Monitor a vrrp interface
 vti           Monitor a vti interface
 wireless      Monitor wireless interface
vyos@vyos:~$

To monitor traffic flows, issue the monitor interfaces <type> <name> flow command, replacing <type> and <name> with your desired interface type and name, respectively. Output looks like the following:

                   12.5Kb              25.0Kb              37.5Kb              50.0Kb        62.5Kb
????????????????????????????????????????????????????????????????????????????????????????????????????
10.11.111.255                        => 10.11.110.37                            0b      0b      0b
                                    <=                                       624b    749b    749b
10.11.110.29                         => 10.62.200.11                            0b    198b    198b
                                    <=                                         0b    356b    356b
255.255.255.255                      => 10.11.110.47                            0b      0b      0b
                                    <=                                       724b    145b    145b
10.11.111.255                        => 10.11.110.47                            0b      0b      0b
                                    <=                                       724b    145b    145b
10.11.111.255                        => 10.11.110.255                           0b      0b      0b
                                    <=                                       680b    136b    136b
????????????????????????????????????????????????????????????????????????????????????????????????????
TX:             cumm:  26.7KB   peak:   40.6Kb                      rates:   23.2Kb  21.4Kb  21.4Kb
RX:                    67.5KB           63.6Kb                               54.6Kb  54.0Kb  54.0Kb
TOTAL:                 94.2KB            104Kb                               77.8Kb  75.4Kb  75.4Kb

Several options are available for changing the display output. Press h to invoke the built in help system. To quit, just press q and you'll be returned to the VyOS command prompt.

To monitor interface traffic, issue the monitor interfaces <type> <name> traffic command, replacing <type> and <name> with your desired interface type and name, respectively. This command invokes the familiar tshark utility and the following options are available:

vyos@vyos:~$ monitor interfaces ethernet eth0 traffic
Possible completions:
 <Enter>       Execute the current command
 detail        Monitor detailed traffic for the specified ethernet interface
 filter        Monitor filtered traffic for the specified ethernet interface
 save          Save monitored traffic to a file
 unlimited     Monitor traffic for the specified ethernet interface
vyos@vyos:~$

To quit monitoring, press Ctrl-c and you'll be returned to the VyOS command prompt. The detail keyword provides verbose output of the traffic seen on the monitored interface. The filter keyword accepts valid PCAP filter expressions, enclosed in single or double quotes (e.g. 'port 25' or "port 161 and udp"). The save keyword allows you to save the traffic dump to a file. The unlimited keyword is used to specify that an unlimited number of packets can be captured (by default, 1,000 packets are captured and you're returned to the VyOS command prompt).