1. 程式人生 > >vyos User Guide

vyos User Guide

vyos User Guide

來源 https://wiki.vyos.net/wiki/User_Guide

 

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

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

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
[email protected]:~$

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.

[email protected]:~$ 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]:
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!
[email protected]:~$

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

[email protected]:~$ reboot
Proceed with reboot? (Yes/No) [No] Yes
[email protected]:~$

Using the 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.

[email protected]:~$ s[tab]
set   show
[email protected]:~$

Example showing possible show commands:

[email protected]:~$ 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
[email protected]:~$

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:

[email protected]:~$ configure
[edit]
[email protected]:~#

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

[email protected]:~# exit
exit
[email protected]:~$

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:

[email protected]$ configure
[email protected]#

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 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 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'
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:

[email protected]# commit
[email protected]# save
Saving configuration to '/config/config.boot'...
Done
[email protected]# exit
[email protected]$

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.

[email protected]:~$ 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
            }
        }
    }
}
[email protected]:~$

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.

[email protected]:~$ 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'
[email protected]:~$

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

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

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.

[email protected]# save
Saving configuration to '/config/config.boot'...
Done
[edit]
[email protected]#

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

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

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

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

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

[email protected]# 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]
[email protected]#

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

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


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

[email protected]# 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
[email protected]# 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.

[email protected]:~$ 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
[email protected]:~$

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

[email protected]:~$ 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
[email protected]:~$

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

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
   }

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.

[email protected]:~$ 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
[email protected]:~$ 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:

[email protected]:~$ 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 priorityforwarding-delayhello-time, and max-age can be configured for the bridge-group. The MAC aging time can also be configured using the agingdirective.

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

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

[email protected]:~$ 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:

[email protected]:~$ 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:

[email protected]:~$ 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:

[email protected]# 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:

[email protected]# 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:

[email protected]# 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
[email protected]# 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 refereed 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 inout, 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 inout, 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 {