From e175b066d4701be34352db2a17cd31e4195d4af9 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 7 Oct 2018 14:39:58 +0200 Subject: Reformat TOC and overall document style --- docs/_static/css/custom.css | 56 ++ docs/_templates/layout.html | 4 + docs/apxA-troubleshooting.rst | 164 ----- docs/apxB-examples.rst | 105 --- docs/ch01-install.rst | 99 --- docs/ch02-cli.rst | 84 --- docs/ch03-quick-start.rst | 164 ----- docs/ch04-configuration-overview.rst | 209 ------ docs/ch05-network-interfaces.rst | 573 -------------- docs/ch06-routing.rst | 306 -------- docs/ch07-firewall.rst | 176 ----- docs/ch08-nat.rst | 322 -------- docs/ch09-vpn.rst | 867 ---------------------- docs/ch10-qos.rst | 1351 --------------------------------- docs/ch11-services.rst | 874 ---------------------- docs/ch12-system.rst | 355 --------- docs/ch13-clustering.rst | 28 - docs/ch14-image-mgmt.rst | 104 --- docs/cli.rst | 86 +++ docs/clustering.rst | 30 + docs/conf.py | 9 +- docs/configuration-overview.rst | 211 ++++++ docs/examples.rst | 107 +++ docs/firewall.rst | 178 +++++ docs/image-mgmt.rst | 106 +++ docs/index.rst | 68 +- docs/install.rst | 101 +++ docs/nat.rst | 324 ++++++++ docs/network-interfaces.rst | 575 +++++++++++++++ docs/qos.rst | 1353 ++++++++++++++++++++++++++++++++++ docs/quick-start.rst | 166 +++++ docs/routing.rst | 308 ++++++++ docs/services.rst | 876 ++++++++++++++++++++++ docs/system.rst | 357 +++++++++ docs/troubleshooting.rst | 166 +++++ docs/vpn.rst | 869 ++++++++++++++++++++++ 36 files changed, 5900 insertions(+), 5831 deletions(-) create mode 100644 docs/_static/css/custom.css create mode 100644 docs/_templates/layout.html delete mode 100644 docs/apxA-troubleshooting.rst delete mode 100644 docs/apxB-examples.rst delete mode 100644 docs/ch01-install.rst delete mode 100644 docs/ch02-cli.rst delete mode 100644 docs/ch03-quick-start.rst delete mode 100644 docs/ch04-configuration-overview.rst delete mode 100644 docs/ch05-network-interfaces.rst delete mode 100644 docs/ch06-routing.rst delete mode 100644 docs/ch07-firewall.rst delete mode 100644 docs/ch08-nat.rst delete mode 100644 docs/ch09-vpn.rst delete mode 100644 docs/ch10-qos.rst delete mode 100644 docs/ch11-services.rst delete mode 100644 docs/ch12-system.rst delete mode 100644 docs/ch13-clustering.rst delete mode 100644 docs/ch14-image-mgmt.rst create mode 100644 docs/cli.rst create mode 100644 docs/clustering.rst create mode 100644 docs/configuration-overview.rst create mode 100644 docs/examples.rst create mode 100644 docs/firewall.rst create mode 100644 docs/image-mgmt.rst create mode 100644 docs/install.rst create mode 100644 docs/nat.rst create mode 100644 docs/network-interfaces.rst create mode 100644 docs/qos.rst create mode 100644 docs/quick-start.rst create mode 100644 docs/routing.rst create mode 100644 docs/services.rst create mode 100644 docs/system.rst create mode 100644 docs/troubleshooting.rst create mode 100644 docs/vpn.rst (limited to 'docs') diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 00000000..a8b94c6e --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,56 @@ +.wy-nav-content { + max-width : none; +} + +.wy-tray-container li.wy-tray-item-info { + background : #409ad5; +} + +.wy-table-responsive { + overflow : visible !important; +} + +.wy-table-responsive table td { + white-space : normal !important; +} + +.wy-menu-vertical header, +.wy-menu-vertical p.caption { + color : #ffcc00 !important; +} + +.wy-menu-vertical li.current a { + color : #040077 !important; +} + +.wy-menu-vertical li ul li a { + color : #ffffff !important; +} + +.wy-menu-vertical a { + color : #ffffff !important; +} + +.wy-menu-vertical a:active { + background-color : #409ad5 !important; +} + +.wy-side-nav-search { + background-color : #FF0000 !important; +} + +.wy-side-nav-search img { + background-color : #FF0000 !important; +} + +.wy-side-nav-search > div.version { + color : rgba(255, 255, 255, 0.7) !important; +} + +.wy-nav-top { + background-color : #FF0000 !important; +} + +.wy-nav-top img { + background-color : #FF0000 !important; +} diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 00000000..387301ea --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,4 @@ +{% extends "!layout.html" %} +{% block extrahead %} + +{% endblock %} \ No newline at end of file diff --git a/docs/apxA-troubleshooting.rst b/docs/apxA-troubleshooting.rst deleted file mode 100644 index 917dc1b7..00000000 --- a/docs/apxA-troubleshooting.rst +++ /dev/null @@ -1,164 +0,0 @@ -Appendix A - 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 `Command-Line Interface`_ -section and are omitted from the output here): - -.. code-block:: sh - - vyos@vyos:~$ ping - Possible completions: - Send Internet Control Message Protocol (ICMP) echo request - - - -Several options are available when more extensive troubleshooting is needed: - -.. code-block:: sh - - vyos@vyos:~$ ping 8.8.8.8 - Possible completions: - 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 - -.. code-block:: sh - - vyos@vyos:~$ traceroute - Possible completions: - Track network path to specified node - - - ipv4 Track network path to - ipv6 Track network path to - -However, another tool, mtr_, is available which combines ping and traceroute -into a single tool. An example of its output is shown: - -.. code-block:: sh - - vyos@vyos:~$ mtr 10.62.212.12 - - My traceroute [v0.85] - vyos (0.0.0.0) - 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 - -.. note:: The output of ``mtr`` consumes the screen and will replace your - command prompt. - -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: - -.. code-block:: sh - - vyos@vyos:~$ monitor interfaces - Possible completions: - 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 - -To monitor traffic flows, issue the :code:`monitor interfaces flow` -command, replacing `` and `` with your desired interface type and -name, respectively. Output looks like the following: - -.. code-block:: sh - - 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 :code:`monitor interfaces -traffic` command, replacing `` and `` with your desired interface -type and name, respectively. This command invokes the familiar tshark_ utility -and the following options are available: - -.. code-block:: sh - - vyos@vyos:~$ monitor interfaces ethernet eth0 traffic - Possible completions: - 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 - -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). - -.. _mtr: http://www.bitwizard.nl/mtr/ -.. _tshark: https://www.wireshark.org/docs/man-pages/tshark.html -.. _`PCAP filter expressions`: http://www.tcpdump.org/manpages/pcap-filter.7.html diff --git a/docs/apxB-examples.rst b/docs/apxB-examples.rst deleted file mode 100644 index 8497316c..00000000 --- a/docs/apxB-examples.rst +++ /dev/null @@ -1,105 +0,0 @@ -Appendix B - Configuration Examples -=================================== - -VyOS DMVPN Hub --------------- - -General infomration can be found in the DMVPN_ chapter. - -Configuration -^^^^^^^^^^^^^ - -.. code-block:: sh - - set interfaces tunnel tun100 address '172.16.253.134/29' - set interfaces tunnel tun100 encapsulation 'gre' - set interfaces tunnel tun100 local-ip '11.22.33.44' - set interfaces tunnel tun100 multicast 'enable' - set interfaces tunnel tun100 parameters ip key '1' - - set protocols nhrp tunnel tun100 cisco-authentication '' - set protocols nhrp tunnel tun100 holding-time '300' - set protocols nhrp tunnel tun100 multicast 'dynamic' - set protocols nhrp tunnel tun100 redirect - set protocols nhrp tunnel tun100 shortcut - - set vpn ipsec esp-group ESP-HUB compression 'disable' - set vpn ipsec esp-group ESP-HUB lifetime '1800' - set vpn ipsec esp-group ESP-HUB mode 'tunnel' - set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' - set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' - set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' - set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' - set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' - set vpn ipsec ike-group IKE-HUB ikev2-reauth 'no' - set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' - set vpn ipsec ike-group IKE-HUB lifetime '3600' - set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' - set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' - set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' - set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' - set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' - set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' - set vpn ipsec ipsec-interfaces interface 'eth0' - - set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' - set vpn ipsec profile NHRPVPN authentication pre-shared-secret '' - set vpn ipsec profile NHRPVPN bind tunnel 'tun100' - set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' - set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' - -Cisco IOS Spoke -^^^^^^^^^^^^^^^ - -This example is verified with a Cisco 2811 platform running IOS 15.1(4)M9 and -VyOS 1.1.7 (helium) up to VyOS 1.2 (Crux). - -.. code-block:: sh - - Cisco IOS Software, 2800 Software (C2800NM-ADVENTERPRISEK9-M), Version 15.1(4)M9, RELEASE SOFTWARE (fc3) - Technical Support: http://www.cisco.com/techsupport - Copyright (c) 1986-2014 by Cisco Systems, Inc. - Compiled Fri 12-Sep-14 10:45 by prod_rel_team - - ROM: System Bootstrap, Version 12.3(8r)T7, RELEASE SOFTWARE (fc1) - -Use this configuration on your Cisco device: - -.. code-block:: sh - - crypto pki token default removal timeout 0 - crypto keyring DMVPN - pre-shared-key address 1.2.3.4 key - ! - crypto isakmp policy 10 - encr aes 256 - authentication pre-share - group 2 - ! - crypto isakmp invalid-spi-recovery - crypto isakmp keepalive 30 30 periodic - crypto isakmp profile DMVPN - keyring DMVPN - match identity address 11.22.33.44 255.255.255.255 - ! - crypto ipsec transform-set DMVPN-AES256 esp-aes 256 esp-sha-hmac - mode transport - ! - crypto ipsec profile DMVPN - set security-association idle-time 720 - set transform-set DMVPN-AES256 - ! - interface Tunnel10 - description Tunnel to DMVPN HUB - ip address 172.16.253.129 255.255.255.248 - no ip redirects - ip nhrp authentication - ip nhrp map multicast 11.22.33.44 - ip nhrp map 172.16.253.134 11.22.33.44 - ip nhrp network-id 1 - ip nhrp holdtime 600 - ip nhrp nhs 172.16.253.134 - ip nhrp registration timeout 75 - tunnel source Dialer1 - tunnel mode gre multipoint - tunnel key 1 diff --git a/docs/ch01-install.rst b/docs/ch01-install.rst deleted file mode 100644 index b1896ef6..00000000 --- a/docs/ch01-install.rst +++ /dev/null @@ -1,99 +0,0 @@ -Installation -============ - -The latest ISO image for VyOS can be downloaded at https://www.vyos.net. - -The recommended system requirements are 512 MiB RAM and 2 GiB 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 ``vyos`` with password ``vyos``. - -.. code-block:: sh - - The programs included with the Debian GNU/Linux system are free software; - the exact distribution terms for each program are described in the - individual files in /usr/share/doc/*/copyright. - - Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent - permitted by applicable law. - vyos@vyos:~$ - - vyos@vyos:~$ uname -a - Linux vyos 4.18.11-amd64-vyos #23 SMP Mon Oct 1 17:29:22 CEST 2018 x86_64 GNU/Linux - -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``. In addition the ``install system`` command has been - removed in VyOS 1.2 (Crux). - -To install VyOS, run ``install image``. - -.. code-block:: sh - - 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]: Yes - Probing drives: OK - Looking for pre-existing RAID groups...none found. - The VyOS image will require a minimum 2000MB 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]: - - I found the following drives on your system: - sda 4294MB - - Install the image on? [sda]: - - This will destroy all data on /dev/sda. - Continue? (Yes/No) [No]: Yes - - How big of a root partition should I create? (2000MB - 4294MB) [4294]MB: - - Creating filesystem on /dev/sda1: OK - Done! - Mounting /dev/sda1... - What would you like to name this image? [1.2.0-rolling+201809210337]: - OK. This image will be named: 1.2.0-rolling+201809210337 - Copying squashfs image... - Copying kernel and initrd images... - Done! - I found the following configuration files: - /opt/vyatta/etc/config.boot.default - Which one should I copy to sda? [/opt/vyatta/etc/config.boot.default]: - - Copying /opt/vyatta/etc/config.boot.default to sda. - Enter password for administrator account - Enter password for user 'vyos': - Retype password for user 'vyos': - I need to install the GRUB boot loader. - I found the following drives on your system: - sda 4294MB - - Which drive should GRUB modify the boot partition on? [sda]: - - Setting up grub: OK - Done! - vyos@vyos:~$ - -After the installation is complete, remove the Live CD and reboot the system: - -.. code-block:: sh - - vyos@vyos:~$ reboot - Proceed with reboot? (Yes/No) [No] Yes diff --git a/docs/ch02-cli.rst b/docs/ch02-cli.rst deleted file mode 100644 index da93dcd8..00000000 --- a/docs/ch02-cli.rst +++ /dev/null @@ -1,84 +0,0 @@ -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. - -.. code-block:: sh - - vyos@vyos:~$ s[tab] - set show - vyos@vyos:~$ - -Example showing possible show commands: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - vyos@vyos:~$ configure - [edit] - vyos@vyos:~# - -.. note:: Prompt changes from `$` to `#`. To exit configuration mode, type `exit`. - -.. code-block:: sh - - vyos@vyos:~# exit - exit - vyos@vyos:~$ - -See the configuration section of this document for more information on -configuration mode. diff --git a/docs/ch03-quick-start.rst b/docs/ch03-quick-start.rst deleted file mode 100644 index 3a4773b6..00000000 --- a/docs/ch03-quick-start.rst +++ /dev/null @@ -1,164 +0,0 @@ -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: - -.. code-block:: sh - - vyos@vyos$ configure - vyos@vyos# - -Configure network interfaces: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - set service ssh port '22' - -Configure Source NAT for our "Inside" network. - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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: - -Please note that the `listen-on` statement is deprecated. Please use -`listen-address` instead! - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - vyos@vyos# commit - vyos@vyos# save - Saving configuration to '/config/config.boot'... - Done - vyos@vyos# exit - vyos@vyos$ - -Basic QoS ---------- - -The traffic policy subsystem provides an interface to Linux traffic control -(tc_). - -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 200 Mbit download -and out WAN connection to 50 Mbit upload: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - set interfaces ethernet eth0 traffic-policy out 'WAN-OUT' - set interfaces ethernet eth1 traffic-policy out 'LAN-OUT' - -.. note:: A traffic policy can also be defined to match specific traffic - flows using class statements. - -VyOS 1.2 (Crux) also supports HFSC (:code:`set traffic-policy shaper-hfsc`) - -See further information in the `QoS and Traffic Policy`_ chapter. - -.. _tc: http://en.wikipedia.org/wiki/Tc_(Linux) diff --git a/docs/ch04-configuration-overview.rst b/docs/ch04-configuration-overview.rst deleted file mode 100644 index 54951364..00000000 --- a/docs/ch04-configuration-overview.rst +++ /dev/null @@ -1,209 +0,0 @@ -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. - -.. code-block:: sh - - 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. - -.. code-block:: sh - - 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 '' - 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. - -.. code-block:: sh - - 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. - -.. code-block:: sh - - 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. - -.. code-block:: sh - - 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. - -.. code-block:: sh - - 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: - -.. code-block:: sh - - vyos@vyos# compare [tab] - Possible completions: - Compare working & active configurations - saved Compare working & saved configurations - Compare working with revision N - 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. - -.. code-block:: sh - - 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. - -.. code-block:: sh - - vyos@vyos# save [tab] - Possible completions: - Save to system config file - Save to file on local machine - scp://:@/ Save to file on remote machine - ftp://:@/ Save to file on remote machine - tftp:/// 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 diff --git a/docs/ch05-network-interfaces.rst b/docs/ch05-network-interfaces.rst deleted file mode 100644 index 2e2a9ee5..00000000 --- a/docs/ch05-network-interfaces.rst +++ /dev/null @@ -1,573 +0,0 @@ -Network Interfaces -================== - -Configured interfaces on a VyOS system can be displayed using the `show -interfaces` command. - -.. code-block:: sh - - 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 ` -command. - -.. code-block:: sh - - vyos@vyos:~$ show interfaces ethernet eth0 - eth0: 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:~$ - -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. - -Interface Addresses -------------------- - -Each interface can be configured with a description and address. Interface -addresses might be: - -* Static IPv4 `address 172.16.51.129/24` -* Static IPv6 `address 2001:db8:1::ffff/64` -* DHCP IPv4 `address dhcp` -* DHCP IPv6 `address dhcpv6` - -An interface description is assigned using the following command: - -.. code-block:: sh - - set interfaces ethernet eth0 description 'OUTSIDE' - -IPv4 -^^^^ - -Static Address -************** - -This method is supported on all interfaces, apart from OpenVPN that uses -different syntax and wireless modems that are always autoconfigured through -PPP. - -The command is `set interfaces $type $name address $address`. Examples: - -.. code-block:: sh - - set interfaces ethernet eth0 address 192.0.2.1/24 - set interfaces tunnel tun0 address 10.0.0.1/30 - set interfaces bridge br0 address 203.0.113.45/26 - set interfaces ethernet eth0 vif 30 address 192.0.30.254/24 - -DHCP -**** - -This method is supported on all physical interfaces, and those that are -directly connected to a physical interface (ethernet, VLAN, bridge, bond, -pseudo-ethernet, wireless). - -The command is `set interfaces $type $name address dhcp`. Examples: - -.. code-block:: sh - - set interfaces ethernet eth0 vif 90 address dhcp - set interfaces bridge br0 address dhcp - -IPv6 -^^^^ - -Static Address -************** - -This method is supported on all interfaces, apart from OpenVPN that uses -different syntax and wireless modems that are always autoconfigured through -PPP. Static IPv6 addresses are supported on all interfaces except VTI. - -The command is `set interfaces $type $name address $address`. Examples: - -.. code-block:: sh - - set interfaces ethernet eth0 address 2001:db8:100::ffff/64 - set interfaces tunnel tun0 address 2001:db8::1/64 - set interfaces bridge br0 address 2001:db8:200::1/64 - set interfaces ethernet eth0 vif 30 address 2001:db8:3::ffff/64 - -DHCP -**** - -This method is supported on all physical interfaces, and those that are -directly connected to a physical interface (ethernet, VLAN, bridge, bond, -pseudo-ethernet, wireless). - -The command is `set interfaces $type $name address dhcpv6`. Examples: - -.. code-block:: sh - - set interfaces bonding bond1 address dhcpv6 - set interfaces bridge br0 vif 56 address dhcpv6 - -Autoconfiguration (SLAAC) -************************* - -SLAAC is specified in RFC4862_. This method is supported on all physical -interfaces, and those that are directly connected to a physical interface -(ethernet, VLAN, bridge, bond, pseudo-ethernet, wireless). - -The command is `set interfaces $type $name ipv6 address autoconf`. Examples: - -.. code-block:: sh - - set interfaces ethernet eth0 vif 90 ipv6 address autoconf - set interfaces bridge br0 ipv6 address autoconf - -.. note:: This method automatically disables IPv6 traffic forwarding on the - interface in question. - -EUI-64 -****** - -EUI-64 (64-Bit Extended Unique Identifier) as specified in RFC4291_. IPv6 -addresses in /64 networks can be automatically generated from the prefix and -MAC address, if you specify the prefix. - -The command is `set interfaces $type $name ipv6 address eui64 $prefix`. Examples: - -.. code-block:: sh - - set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64 - set interfaces pseudo-ethernet peth0 ipv6 address eui64 2001:db8:aa::/64 - -Ethernet Interfaces -------------------- - -Ethernet interfaces allow for the configuration of speed, duplex, and hw-id -(MAC address). Below is an example configuration: - -.. code-block:: sh - - set interfaces ethernet eth1 address '192.168.0.1/24' - set interfaces ethernet eth1 address '2001:db8:1::ffff/64' - set interfaces ethernet eth1 description 'INSIDE' - set interfaces ethernet eth1 duplex 'auto' - set interfaces ethernet eth1 speed 'auto' - -Resulting in: - -.. code-block:: sh - - ethernet eth1 { - address 192.168.0.1/24 - address 2001:db8:1::ffff/64 - 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 physical` and `show interfaces ethernet -statistics`. Statistics available are driver dependent. - -.. code-block:: sh - - 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 -vif `. - -.. code-block:: sh - - 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 '2001:db8:100::1/64' - -Resulting in: - -.. code-block:: sh - - ethernet eth1 { - address 192.168.100.1/24 - address 2001:db8:100::1/64 - 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 `.`, e.g. `eth1.100`: - -.. code-block:: sh - - 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. - -.. code-block:: sh - - 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. - -.. code-block:: sh - - set interfaces bridge br100 address '192.168.100.1/24' - set interfaces bridge br100 address '2001:db8:100::1/64' - -Example Result: - -.. code-block:: sh - - bridge br100 { - address 192.168.100.1/24 - address 2001:db8:100::1/64 - } - [...] - 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 stp true` command: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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 spanning-tree` command -can be used to show STP configuration: - -.. code-block:: sh - - 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 - macs` command: - -.. code-block:: sh - - 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 ether-channel, or port-channel. - -Create interface bondX, where X is just a number: - -.. code-block:: sh - - set interfaces bonding bond0 description 'my-sw1 int 23 and 24' - -You are able to choose a hash policy: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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): - -.. code-block:: sh - - set interfaces bonding bond0 mode '802.3ad' - -or some other modes: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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 - -.. code-block:: sh - - set interfaces vti vti0 address 192.168.2.249/30 - set interfaces vti vti0 address 2001:db8:2::249/64 - -Results in: - -.. code-block:: sh - - vyos@vyos# show interfaces vti - vti vti0 { - address 192.168.2.249/30 - address 2001:db8:2::249/64 - description "Description" - } - -WireGuard VPN Interface ------------------------ - -WireGuard_ is an extremely simple yet fast and modern VPN that utilizes -state-of-the-art cryptography. See https://www.wireguard.com for more -information. - -Configuration -^^^^^^^^^^^^^ - -Generate the keypair, which creates a public and private part and stores it -within VyOS. - -.. code-block:: sh - - wg01:~$ configure - wg01# run generate wireguard keypair - -The public key is being shared with your peer(s), your peer will encrypt all -traffic to your system using this public key. - -.. code-block:: sh - - wg01# run show wireguard pubkey - u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk= - -The next step is to configure your local side as well as the policy based -trusted destination addresses. If you only initiate a connection, the listen -port and endpoint is optional, if you however act as a server and endpoints -initiate the connections to your system, you need to define a port your clients -can connect to, otherwise it's randomly chosen and may make it difficult with -firewall rules, since the port may be a different one when you reboot your -system. - -You will also need the public key of your peer as well as the network(s) you -want to tunnel (allowed-ips) to configure a wireguard tunnel. The public key -below is always the public key from your peer, not your local one. - -**local side** - -.. code-block:: sh - - set interfaces wireguard wg01 address '10.1.0.1/24' - set interfaces wireguard wg01 description 'VPN-to-wg02' - set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.2.0.0/24' - set interfaces wireguard wg01 peer to-wg02 endpoint '192.168.0.142:12345' - set interfaces wireguard wg01 peer to-wg02 pubkey 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' - set interfaces wireguard wg01 port '12345' - set protocols static interface-route 10.2.0.0/24 next-hop-interface wg01 - -The last step is to define an interface route for 10.2.0.0/24 to get through -the wireguard interface `wg01`. Multiple IPs or networks can be defined and -routed, the last check is allowed-ips which either prevents or allows the -traffic. - -**remote side** - -.. code-block:: sh - - set interfaces wireguard wg01 address '10.2.0.1/24' - set interfaces wireguard wg01 description 'VPN-to-wg01' - set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.1.0.0/24' - set interfaces wireguard wg01 peer to-wg02 endpoint '192.168.0.124:12345' - set interfaces wireguard wg01 peer to-wg02 pubkey 'u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk=' - set interfaces wireguard wg01 port '12345' - set protocols static interface-route 10.1.0.0/24 next-hop-interface wg01 - -Assure that your firewall rules allow the traffic, in which case you have a -working VPN using wireguard. - -.. code-block:: sh - - wg01# ping 10.2.0.1 - PING 10.2.0.1 (10.2.0.1) 56(84) bytes of data. - 64 bytes from 10.2.0.1: icmp_seq=1 ttl=64 time=1.16 ms - 64 bytes from 10.2.0.1: icmp_seq=2 ttl=64 time=1.77 ms - - wg02# ping 10.1.0.1 - PING 10.1.0.1 (10.1.0.1) 56(84) bytes of data. - 64 bytes from 10.1.0.1: icmp_seq=1 ttl=64 time=4.40 ms - 64 bytes from 10.1.0.1: icmp_seq=2 ttl=64 time=1.02 ms - -An additional layer of symmetric-key crypto can be used on top of the -asymmetric crypto, which is optional. - -.. code-block:: sh - - wg01# run generate wireguard preshared-key - rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= - -Copy the key, it is not stored on the local file system. Make sure you -distribute that key in a safe manner, it's a symmatric key, so only you and -your peer should have knowledge if its content. - -.. code-block:: sh - - wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' - wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' - -.. _RFC4862: https://tools.ietf.org/html/rfc4862 -.. _RFC4291: http://tools.ietf.org/html/rfc4291#section-2.5.1 -.. _WireGuard: https://www.wireguard.com diff --git a/docs/ch06-routing.rst b/docs/ch06-routing.rst deleted file mode 100644 index 5efe6442..00000000 --- a/docs/ch06-routing.rst +++ /dev/null @@ -1,306 +0,0 @@ -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: - -.. code-block:: sh - - set protocols static route 0.0.0.0/0 next-hop 10.1.1.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. - -.. code-block:: sh - - 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' - -.. note:: 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:** - -.. code-block:: sh - - set interfaces loopback address 10.1.1.1/32 - set protocols rip network 192.168.0.0/24 - set protocols rip redistribute connected - -**Node 2:** - -.. code-block:: sh - - set interfaces loopback address 10.2.2.2/32 - set protocols rip network 192.168.0.0/24 - set protocols rip redistribute connected - -OSPF ----- - -IPv4 -^^^^ - -A typical configuration using 2 nodes, redistribute loopback address and the -node 1 sending the default route: - -**Node 1:** - -.. code-block:: sh - - set interfaces loopback lo address 10.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 10.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:** - -.. code-block:: sh - - set interfaces loopback lo address 10.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 10.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 - -IPv6 -^^^^ - -A typical configuration using 2 nodes. - -**Node 1:** - -.. code-block:: sh - - 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:** - -.. code-block:: sh - - 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 - -BGP ---- - -IPv4 -^^^^ - -A simple eBGP configuration: - -**Node 1:** - -.. code-block:: sh - - set protocols bgp 65534 neighbor 192.168.0.2 ebgp-multihop '2' - set protocols bgp 65534 neighbor 192.168.0.2 remote-as '65535' - set protocols bgp 65534 neighbor 192.168.0.2 update-source '192.168.0.1' - set protocols bgp 65534 network '172.16.0.0/16' - set protocols bgp 65534 parameters router-id '192.168.0.1' - -**Node 2:** - -.. code-block:: sh - - set protocols bgp 65535 neighbor 192.168.0.1 ebgp-multihop '2' - set protocols bgp 65535 neighbor 192.168.0.1 remote-as '65534' - set protocols bgp 65535 neighbor 192.168.0.1 update-source '192.168.0.2' - set protocols bgp 65535 network '172.17.0.0/16' - set protocols bgp 65535 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:** - -.. code-block:: sh - - set protocols static route 1.0.0.0/16 blackhole distance '254' - -**Node 2:** - -.. code-block:: sh - - set protocols static route 2.0.0.0/16 blackhole distance '254' - - -IPv6 -^^^^ - -A simple BGP configuration via IPv6. - -**Node 1:** - -.. code-block:: sh - - set protocols bgp 65534 neighbor 2001:db8::2 ebgp-multihop '2' - set protocols bgp 65534 neighbor 2001:db8::2 remote-as '65535' - set protocols bgp 65534 neighbor 2001:db8::2 update-source '2001:db8::1' - set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast - set protocols bgp 65534 address-family ipv6-unicast network '2001:db8:1::/48' - set protocols bgp 65534 parameters router-id '10.1.1.1' - -**Node 2:** - -.. code-block:: sh - - set protocols bgp 65535 neighbor 2001:db8::1 ebgp-multihop '2' - set protocols bgp 65535 neighbor 2001:db8::1 remote-as '65534' - set protocols bgp 65535 neighbor 2001:db8::1 update-source '2001:db8::2' - set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast - set protocols bgp 65535 address-family ipv6-unicast network '2001:db8:2::/48' - set protocols bgp 65535 parameters router-id '10.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:** - -.. code-block:: sh - - set protocols static route6 2a001:100:1::/48 blackhole distance '254' - -**Node 2:** - -.. code-block:: sh - - set protocols static route6 2001:db8:2::/48 blackhole distance '254' - -Route Filter -^^^^^^^^^^^^ - -Route filter can be applied using a route-map: - -**Node1:** - -.. code-block:: sh - - set policy prefix-list AS65535-IN rule 10 action 'permit' - set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16' - set policy prefix-list AS65535-OUT rule 10 action 'deny' - set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16' - set policy prefix-list6 AS65535-IN rule 10 action 'permit' - set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48' - set policy prefix-list6 AS65535-OUT rule 10 action 'deny' - set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48' - set policy route-map AS65535-IN rule 10 action 'permit' - set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN' - set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN' - set policy route-map AS65535-IN rule 20 action 'deny' - set policy route-map AS65535-OUT rule 10 action 'deny' - set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT' - set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT' - set policy route-map AS65535-OUT rule 20 action 'permit' - set protocols bgp 65534 neighbor 2001:db8::2 route-map export 'AS65535-OUT' - set protocols bgp 65534 neighbor 2001:db8::2 route-map import 'AS65535-IN' - -**Node2:** - -.. code-block:: sh - - set policy prefix-list AS65534-IN rule 10 action 'permit' - set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16' - set policy prefix-list AS65534-OUT rule 10 action 'deny' - set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16' - set policy prefix-list6 AS65534-IN rule 10 action 'permit' - set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48' - set policy prefix-list6 AS65534-OUT rule 10 action 'deny' - set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48' - set policy route-map AS65534-IN rule 10 action 'permit' - set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN' - set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN' - set policy route-map AS65534-IN rule 20 action 'deny' - set policy route-map AS65534-OUT rule 10 action 'deny' - set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT' - set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT' - set policy route-map AS65534-OUT rule 20 action 'permit' - set protocols bgp 65535 neighbor 2001:db8::1 route-map export 'AS65534-OUT' - set protocols bgp 65535 neighbor 2001:db8::1 route-map import 'AS65534-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: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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 rule `set tcp-mss ` directive, -modify DSCP value using `set dscp `, or mark the traffic with an -internal ID using `set mark ` 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. diff --git a/docs/ch07-firewall.rst b/docs/ch07-firewall.rst deleted file mode 100644 index 397c31ac..00000000 --- a/docs/ch07-firewall.rst +++ /dev/null @@ -1,176 +0,0 @@ -Firewall -======== - -VyOS makes use of Linux [http://netfilter.org/ 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 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 ------- - -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:: 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: - -.. code-block:: sh - - 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 `-`. - -Here is an example of a port group a server: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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). - -.. code-block:: sh - - 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): - -.. code-block:: sh - - set zone-policy zone INSIDE from OUTSIDE firewall name INSIDE-OUT - -Example Partial Config ----------------------- - -.. code-block:: sh - - 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 - } - } - } - } - -[https://www.xfinity.com/support/internet/list-of-blocked-ports/ XFinity Blocked Port List] - diff --git a/docs/ch08-nat.rst b/docs/ch08-nat.rst deleted file mode 100644 index d87f33de..00000000 --- a/docs/ch08-nat.rst +++ /dev/null @@ -1,322 +0,0 @@ -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: - -.. code-block:: sh - - 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. - -.. code-block:: sh - - 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. - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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: http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers - -Our configuration commands would be: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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:: 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. - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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) ---------------- - -NPTv6 stands for Network Prefix Translation. It's a form of NAT for IPv6. It's -described in RFC6296_. NPTv6 is supported in linux kernel since version 3.13. - -Usage ------ - -NPTv6 is very useful for IPv6 multihoming. Let's assume the following network -configuration: - -* eth0 : LAN -* eth1 : WAN1, with 2001:db8:e1::/48 routed towards it -* eth2 : WAN2, with 2001:db8:e2::/48 routed towards it - -Regarding LAN hosts addressing, why would you choose 2001:db8:e1::/48 over -2001:db8:e2::/48? What happens when you get a new provider with a different -routed IPv6 subnet? - -The solution here is to assign to your hosts ULAs_ and to prefix-translate -their address to the right subnet when going through your router. - -* LAN Subnet : fc00:dead:beef::/48 -* WAN 1 Subnet : 2001:db8:e1::/48 -* WAN 2 Subnet : 2001:db8:e2::/48 - -* eth0 addr : fc00:dead:beef::1/48 -* eth1 addr : 2001:db8:e1::1/48 -* eth2 addr : 2001:db8:e2::1/48 - -VyOS Support ------------- - -NPTv6 support has been added in VyOS 1.2 (Crux) and is available through -`nat nptv6` configuration nodes. - -.. code-block:: sh - - set rule 10 inside-prefix 'fc00:dead:beef::/48' - set rule 10 outside-interface 'eth1' - set rule 10 outside-prefix '2001:db8:e1::/48' - set rule 20 inside-prefix 'fc00:dead:beef::/48' - set rule 20 outside-interface 'eth2' - set rule 20 outside-prefix '2001:db8:e2::/48' - -Resulting in the following ip6tables rules: - -.. code-block:: sh - - Chain VYOS_DNPT_HOOK (1 references) - pkts bytes target prot opt in out source destination - 0 0 DNPT all eth1 any anywhere 2001:db8:e1::/48 src-pfx 2001:db8:e1::/48 dst-pfx fc00:dead:beef::/48 - 0 0 DNPT all eth2 any anywhere 2001:db8:e2::/48 src-pfx 2001:db8:e2::/48 dst-pfx fc00:dead:beef::/48 - 0 0 RETURN all any any anywhere anywhere - Chain VYOS_SNPT_HOOK (1 references) - pkts bytes target prot opt in out source destination - 0 0 SNPT all any eth1 fc00:dead:beef::/48 anywhere src-pfx fc00:dead:beef::/48 dst-pfx 2001:db8:e1::/48 - 0 0 SNPT all any eth2 fc00:dead:beef::/48 anywhere src-pfx fc00:dead:beef::/48 dst-pfx 2001:db8:e2::/48 - 0 0 RETURN all any any anywhere anywhere - -.. _RFC6296: https://tools.ietf.org/html/rfc6296 -.. _ULAs: http://en.wikipedia.org/wiki/Unique_local_address diff --git a/docs/ch09-vpn.rst b/docs/ch09-vpn.rst deleted file mode 100644 index 142bdc8b..00000000 --- a/docs/ch09-vpn.rst +++ /dev/null @@ -1,867 +0,0 @@ -VPN -=== - -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 `. 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: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - set protocols static interface-route 10.1.0.0/16 next-hop-interface vtun1 - -Remote Configuration: - -.. code-block:: sh - - 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 uses -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. - -.. code-block:: sh - - 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` - -.. code-block:: sh - - 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. - -.. code-block:: sh - - 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:: Clients are identified by the CN field of their x.509 certificates, - in this example the CN is ``client0``: - -.. code-block:: sh - - 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: - -.. code-block:: sh - - 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): - -.. code-block:: sh - - 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 - set vpn l2tp remote-access authentication mode local - set vpn l2tp remote-access authentication local-users username 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: - -.. code-block:: sh - - 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. - -.. code-block:: sh - - 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. - -.. code-block:: sh - - 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' - -.. note:: Those are the `Google public DNS`_ servers. You can also use the - public available servers from Quad9_ (9.9.9.9) or Cloudflare_ (1.1.1.1). - -Established sessions can be viewed using the **show vpn remote-access** -operational command. - -.. code-block:: sh - - 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 - -RADIUS authentication -^^^^^^^^^^^^^^^^^^^^^ - -The above configuration made use of local accounts on the VyOS router for -authenticating L2TP/IPSec clients. In bigger environments usually something -like RADIUS_ (FreeRADIUS_ or Microsoft `Network Policy Server`_, NPS) is used. - -VyOS supports either `local` or `radius` user authentication: - -.. code-block:: sh - - set vpn l2tp remote-access authentication mode - -In addition one or more RADIUS_ servers can be configured to server for user -authentication. This is done using the `radius-server` and `key` nodes: - -.. code-block:: sh - - set vpn l2tp remote-access authentication radius-server 1.1.1.1 key 'foo' - set vpn l2tp remote-access authentication radius-server 2.2.2.2 key 'foo' - -.. note:: Some RADIUS_ severs make use of an access control list who is allowed - to query the server. Please configure your VyOS router in the allowed client - list. - -RADIUS source address -********************* - -Yet there is no way to configure the used RADIUS_ client source IP address on -the VyOS router, this is work in progres, see https://phabricator.vyos.net/T828. - -The IP address nearest to the radius server is currently used. If in doubt, -configure all IP addresses from the VyOS router in question. - -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 - -.. code-block:: sh - - # server 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 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' - -Show status of new setup: - -.. code-block:: sh - - 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 - -.. code-block:: sh - - # 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) - -.. code-block:: sh - - # 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 ------ - -**D** ynamic **M** ultipoint **V** irtual **P** rivate **N** etworking - -DMVPN is a dynamic VPN technology originally developed by Cisco. While their -implementation was somewhat proprietary, the underlying technologies are -actually standards based. The three technologies are: - -* **NHRP** - NBMA Next Hop Resolution Protocol RFC2332_ -* **mGRE** - Multipoint Generic Routing Encapsulation / mGRE RFC1702_ -* **IPSec** - IP Security (too many RFCs to list, but start with RFC4301_) - -NHRP provides the dynamic tunnel endpoint discovery mechanism (endpoint -registration, and endpoint discovery/lookup), mGRE provides the tunnel -encapsulation itself, and the IPSec protocols handle the key exchange, and -crypto mechanism. - -In short, DMVPN provides the capability for creating a dynamic-mesh VPN -network without having to pre-configure (static) all possible tunnel end-point -peers. - -.. note:: DMVPN only automates the tunnel endpoint discovery and setup. A - complete solution also incorporates the use of a routing protocol. BGP is - particularly well suited for use with DMVPN. - -Baseline Configuration: - -**STEPS:** - -#. Create tunnel config (`interfaces tunnel`) -#. Create nhrp (`protocols nhrp`) -#. Create ipsec vpn (optional, but recommended for security) (`vpn ipsec`) - -The tunnel will be set to mGRE if for encapsulation `gre` is set, and no -`remote-ip` is set. If the public ip is provided by DHCP the tunnel `local-ip` -can be set to "0.0.0.0" - -.. figure:: _static/images/vpn_dmvpn_topology01.png - :scale: 40 % - :alt: Baseline DMVPN topology - - Baseline DMVPN topology - -HUB Configuration -^^^^^^^^^^^^^^^^^ - -.. code-block:: sh - - interfaces - tunnel { - address - encapsulation gre - local-ip - multicast enable - description - parameters { - ip { - - } - } - } - } - protocols { - nhrp { - tunnel { - cisco-authentication - holding-time - multicast dynamic - redirect - } - } - } - vpn { - ipsec { - esp-group { - lifetime <30-86400> - mode tunnel - pfs enable - proposal <1-65535> { - encryption aes256 - hash sha1 - } - proposal <1-65535> { - encryption 3des - hash md5 - } - } - ike-group { - key-exchange ikev1 - lifetime <30-86400> - proposal <1-65535> { - encryption aes256 - hash sha1 - } - proposal <1-65535> { - encryption aes128 - hash sha1 - } - } - ipsec-interfaces { - interface - } - profile { - authentication { - mode pre-shared-secret - pre-shared-secret - } - bind { - tunnel - } - esp-group - ike-group - } - } - } - -HUB Example Configuration: - -.. code-block:: sh - - set interfaces ethernet eth0 address '1.1.1.1/30' - set interfaces ethernet eth1 address '192.168.1.1/24' - set system host-name 'HUB' - - set interfaces tunnel tun0 address 10.0.0.1/24 - set interfaces tunnel tun0 encapsulation gre - set interfaces tunnel tun0 local-ip 1.1.1.1 - set interfaces tunnel tun0 multicast enable - set interfaces tunnel tun0 parameters ip key 1 - - set protocols nhrp tunnel tun0 cisco-authentication SECRET - set protocols nhrp tunnel tun0 holding-time 300 - set protocols nhrp tunnel tun0 multicast dynamic - set protocols nhrp tunnel tun0 redirect - - set vpn ipsec ipsec-interfaces interface eth0 - set vpn ipsec ike-group IKE-HUB proposal 1 - set vpn ipsec ike-group IKE-HUB proposal 1 encryption aes256 - set vpn ipsec ike-group IKE-HUB proposal 1 hash sha1 - set vpn ipsec ike-group IKE-HUB proposal 2 encryption aes128 - set vpn ipsec ike-group IKE-HUB proposal 2 hash sha1 - set vpn ipsec ike-group IKE-HUB lifetime 3600 - set vpn ipsec esp-group ESP-HUB proposal 1 encryption aes256 - set vpn ipsec esp-group ESP-HUB proposal 1 hash sha1 - set vpn ipsec esp-group ESP-HUB proposal 2 encryption 3des - set vpn ipsec esp-group ESP-HUB proposal 2 hash md5 - set vpn ipsec esp-group ESP-HUB lifetime 1800 - set vpn ipsec esp-group ESP-HUB pfs dh-group2 - - set vpn ipsec profile NHRPVPN - set vpn ipsec profile NHRPVPN authentication mode pre-shared-secret - set vpn ipsec profile NHRPVPN authentication pre-shared-secret SECRET - set vpn ipsec profile NHRPVPN bind tunnel tun0 - set vpn ipsec profile NHRPVPN esp-group ESP-HUB - set vpn ipsec profile NHRPVPN ike-group IKE-HUB - - set protocols static route 0.0.0.0/0 next-hop 1.1.1.2 - set protocols static route 192.168.2.0/24 next-hop 10.0.0.2 - set protocols static route 192.168.3.0/24 next-hop 10.0.0.3 - -SPOKE Configuration -^^^^^^^^^^^^^^^^^^^ - -SPOKE1 Configuration: - -.. code-block:: sh - - interfaces - tunnel { - address - encapsulation gre - local-ip - multicast enable - description - parameters { - ip { - - } - } - } - } - protocols { - nhrp { - tunnel { - cisco-authentication - map { - nbma-address - register - } - holding-time - multicast nhs - redirect - shortcut - } - } - } - vpn { - ipsec { - esp-group { - lifetime <30-86400> - mode tunnel - pfs enable - proposal <1-65535> { - encryption aes256 - hash sha1 - } - proposal <1-65535> { - encryption 3des - hash md5 - } - } - ike-group { - key-exchange ikev1 - lifetime <30-86400> - proposal <1-65535> { - encryption aes256 - hash sha1 - } - proposal <1-65535> { - encryption aes128 - hash sha1 - } - } - ipsec-interfaces { - interface - } - profile { - authentication { - mode pre-shared-secret - pre-shared-secret - } - bind { - tunnel - } - esp-group - ike-group - } - } - } - -SPOKE1 Example Configuration - -.. code-block:: sh - - set interfaces ethernet eth0 address 'dhcp' - set interfaces ethernet eth1 address '192.168.2.1/24' - set system host-name 'SPOKE1' - - set interfaces tunnel tun0 address 10.0.0.2/24 - set interfaces tunnel tun0 encapsulation gre - set interfaces tunnel tun0 local-ip 0.0.0.0 - set interfaces tunnel tun0 multicast enable - set interfaces tunnel tun0 parameters ip key 1 - - set protocols nhrp tunnel tun0 cisco-authentication 'SECRET' - set protocols nhrp tunnel tun0 map 10.0.0.1/24 nbma-address 1.1.1.1 - set protocols nhrp tunnel tun0 map 10.0.0.1/24 'register' - set protocols nhrp tunnel tun0 multicast 'nhs' - set protocols nhrp tunnel tun0 'redirect' - set protocols nhrp tunnel tun0 'shortcut' - - set vpn ipsec ipsec-interfaces interface eth0 - set vpn ipsec ike-group IKE-SPOKE proposal 1 - set vpn ipsec ike-group IKE-SPOKE proposal 1 encryption aes256 - set vpn ipsec ike-group IKE-SPOKE proposal 1 hash sha1 - set vpn ipsec ike-group IKE-SPOKE proposal 2 encryption aes128 - set vpn ipsec ike-group IKE-SPOKE proposal 2 hash sha1 - set vpn ipsec ike-group IKE-SPOKE lifetime 3600 - set vpn ipsec esp-group ESP-SPOKE proposal 1 encryption aes256 - set vpn ipsec esp-group ESP-SPOKE proposal 1 hash sha1 - set vpn ipsec esp-group ESP-SPOKE proposal 2 encryption 3des - set vpn ipsec esp-group ESP-SPOKE proposal 2 hash md5 - set vpn ipsec esp-group ESP-SPOKE lifetime 1800 - set vpn ipsec esp-group ESP-SPOKE pfs dh-group2 - - set vpn ipsec profile NHRPVPN - set vpn ipsec profile NHRPVPN authentication mode pre-shared-secret - set vpn ipsec profile NHRPVPN authentication pre-shared-secret SECRET - set vpn ipsec profile NHRPVPN bind tunnel tun0 - set vpn ipsec profile NHRPVPN esp-group ESP-SPOKE - set vpn ipsec profile NHRPVPN ike-group IKE-SPOKE - - set protocols static route 192.168.1.0/24 next-hop 10.0.0.1 - set protocols static route 192.168.3.0/24 next-hop 10.0.0.3 - - -SPOKE2 Configuration - -.. code-block:: sh - - interfaces - tunnel { - address - encapsulation gre - local-ip - multicast enable - description - parameters { - ip { - - } - } - } - } - protocols { - nhrp { - tunnel { - cisco-authentication - map { - nbma-address - register - } - holding-time - multicast nhs - redirect - shortcut - } - } - } - vpn { - ipsec { - esp-group { - lifetime <30-86400> - mode tunnel - pfs enable - proposal <1-65535> { - encryption aes256 - hash sha1 - } - proposal <1-65535> { - encryption 3des - hash md5 - } - } - ike-group { - key-exchange ikev1 - lifetime <30-86400> - proposal <1-65535> { - encryption aes256 - hash sha1 - } - proposal <1-65535> { - encryption aes128 - hash sha1 - } - } - ipsec-interfaces { - interface - } - profile { - authentication { - mode pre-shared-secret - pre-shared-secret - } - bind { - tunnel - } - esp-group - ike-group - } - } - } - -SPOKE2 Example Configuration - -.. code-block:: sh - - set interfaces ethernet eth0 address 'dhcp' - set interfaces ethernet eth1 address '192.168.3.1/24' - set system host-name 'SPOKE2' - - set interfaces tunnel tun0 address 10.0.0.3/24 - set interfaces tunnel tun0 encapsulation gre - set interfaces tunnel tun0 local-ip 0.0.0.0 - set interfaces tunnel tun0 multicast enable - set interfaces tunnel tun0 parameters ip key 1 - - set protocols nhrp tunnel tun0 cisco-authentication SECRET - set protocols nhrp tunnel tun0 map 10.0.0.1/24 nbma-address 1.1.1.1 - set protocols nhrp tunnel tun0 map 10.0.0.1/24 register - set protocols nhrp tunnel tun0 multicast nhs - set protocols nhrp tunnel tun0 redirect - set protocols nhrp tunnel tun0 shortcut - - set vpn ipsec ipsec-interfaces interface eth0 - set vpn ipsec ike-group IKE-SPOKE proposal 1 - set vpn ipsec ike-group IKE-SPOKE proposal 1 encryption aes256 - set vpn ipsec ike-group IKE-SPOKE proposal 1 hash sha1 - set vpn ipsec ike-group IKE-SPOKE proposal 2 encryption aes128 - set vpn ipsec ike-group IKE-SPOKE proposal 2 hash sha1 - set vpn ipsec ike-group IKE-SPOKE lifetime 3600 - set vpn ipsec esp-group ESP-SPOKE proposal 1 encryption aes256 - set vpn ipsec esp-group ESP-SPOKE proposal 1 hash sha1 - set vpn ipsec esp-group ESP-SPOKE proposal 2 encryption 3des - set vpn ipsec esp-group ESP-SPOKE proposal 2 hash md5 - set vpn ipsec esp-group ESP-SPOKE lifetime 1800 - set vpn ipsec esp-group ESP-SPOKE pfs dh-group2 - - set vpn ipsec profile NHRPVPN - set vpn ipsec profile NHRPVPN authentication mode pre-shared-secret - set vpn ipsec profile NHRPVPN authentication pre-shared-secret SECRET - set vpn ipsec profile NHRPVPN bind tunnel tun0 - set vpn ipsec profile NHRPVPN esp-group ESP-SPOKE - set vpn ipsec profile NHRPVPN ike-group IKE-SPOKE - - set protocols static route 192.168.1.0/24 next-hop 10.0.0.1 - set protocols static route 192.168.2.0/24 next-hop 10.0.0.2 - -.. _`Google Public DNS`: https://developers.google.com/speed/public-dns -.. _Quad9: https://quad9.net -.. _CloudFlare: https://blog.cloudflare.com/announcing-1111 -.. _RADIUS: https://en.wikipedia.org/wiki/RADIUS -.. _FreeRADIUS: https://freeradius.org -.. _`Network Policy Server`: https://en.wikipedia.org/wiki/Network_Policy_Server -.. _RFC2332: https://tools.ietf.org/html/rfc2332 -.. _RFC1702: https://tools.ietf.org/html/rfc1702 -.. _RFC4301: https://tools.ietf.org/html/rfc4301 diff --git a/docs/ch10-qos.rst b/docs/ch10-qos.rst deleted file mode 100644 index 4be68662..00000000 --- a/docs/ch10-qos.rst +++ /dev/null @@ -1,1351 +0,0 @@ -QoS and Traffic Policy -====================== - -VyOS uses tc_ as backend for QoS. VyOS provides its users with configuration -nodes for the following shaping/queueing/policing disciplines: - -* HTB -* HFSC -* SFQ -* pfifo -* network-emulator -* PRIO -* GRED -* TBF -* DRR - -Configuration nodes -------------------- - -VyOS QoS configuration is done in two steps. The first one consists in setting -up your classes/queues and traffic filters to distribute traffic amongst them. -The second step is to apply such traffic policy to an interface ingress or -egress. - -Creating a traffic policy -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Such configuration takes place under the `traffic-policy` tree. - -Available subtrees : - -.. code-block:: sh - - set traffic-policy drop-tail NAME - set traffic-policy fair-queue NAME - set traffic-policy limiter NAME - set traffic-policy network-emulator NAME - set traffic-policy priority-queue NAME - set traffic-policy random-detect NAME - set traffic-policy rate-control NAME - set traffic-policy round-robin NAME - set traffic-policy shaper NAME - set traffic-policy shaper-hfsc NAME - -Apply traffic policy to an interface -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Once a traffic-policy is created, you can apply it to an interface : - -.. code-block:: sh - - set interfaces ethernet eth0 traffic-policy in WAN-IN - set interfaces etherhet eth0 traffic-policy out WAN-OUT - -Traffic policies in VyOS ------------------------- -An overview of QoS traffic policies supported by VyOS. - -Drop-tail (FIFO) -^^^^^^^^^^^^^^^^ - -A packet queuing mechanism on a FIFO (First In, First Out) basis; packets are -sent out in the same order as they arrive. The queue has a defined length, -packets arriving after the queue is filled up will be dropped (hence the name -`drop tail`, the "tail" of the queue will be dropped). With this policy in -place, all traffic is treated equally and put into a single queue. Applicable -to outbound traffic only. - -Available commands: - -* Define a drop-tail policy (unique name, exclusive to this policy): - - :code:`set traffic-policy drop-tail ` - -* Add a description: - - :code:`set traffic-policy drop-tail description ` - -* Set the queue length limit (max. number of packets in queue), range - 0...4294967295 packets: - - :code:`set traffic-policy drop-tail queue-limit ` - -Fair queue (SFQ) -^^^^^^^^^^^^^^^^ - -Fair queue is a packet queuing mechanism that separates traffic flows based on -their source/destination IP addresses and/or source port and places them into -buckets. Bandwidth is allocated fairly between buckets based on the Stochastic -airness Queuing algorithm. Applicable to outbound traffic only. - -Available commands: - -* Define a fair queue policy: - - :code:`set traffic-policy fair-queue ` - -* Add a description: - - :code:`set traffic-policy fair-queue description ` - -* Set hash update interval; the algorithm used is stochastic and thus not - 'truly' fair, hash collisions can occur, in which case traffic flows may be - put into the same bucket. To mitigate this, the hashes can be updated at a - set interval, Range 0...4294967295 seconds: - - :code:`set traffic-policy fair-queue hash-interval ` - -* Set the queue-limit (max. number of packets in queue), range 0...4294967295 - packets, default 127: - - :code:`set traffic-policy fair-queue queue-limit ` - -Limiter -^^^^^^^ - -The limiter performs ingress policing of traffic flows. Multiple classes of -traffic can be defined and traffic limits can be applied to each class. Traffic -exceeding the defined bandwidth limits is dropped. Applicable to inbound -traffic only. - -Available commands: - -* Define a traffic limiter policy: - :code:`set traffic-policy limiter ` -* Add a description: - :code:`set traffic-policy limiter description ` - -Traffic classes -*************** - -* Define a traffic class for a limiter policy, range for class ID is 1...4095: - - :code:`set traffic-policy limiter class ` - -* Add a class description: - - :code:`set traffic-policy limiter class description - ` - -* Specify a bandwidth limit for a class, in kbit/s: - - :code:`set traffic-policy limiter class bandwidth - `. - - Available suffixes: - - * kbit (kilobits per second, default) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) - -* Set a burst size for a class, the maximum amount of traffic that can be sent, - in bytes: - - :code:`set traffic-policy limiter class - burst `. - - Available suffixes: - - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) - -Default class -############# - -* Define a default class for a limiter policy that applies to traffic not - matching any other classes for this policy: - - :code:`set traffic-policy limiter default` - -* Specify a bandwidth limit for the default class, in kbit/s: - - :code:`set traffic-policy limiter default bandwidth `. - - Available suffixes: - - * kbit (kilobits per second, default) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) - -* Set a burst size for the default class, the maximum amount of traffic that - can be sent, in bytes: - - :code:`set traffic-policy limiter default burst `. - - Available suffixes: - - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) - -* Specify the priority of the default class to set the order in which the rules - are evaluated, the higher the number the lower the priority, range 0...20 - (default 20): - - :code:`set traffic-policy limiter default priority ` - -Matching rules -************** - -* Define a traffic class matching rule: - - :code:`set traffic-policy limiter class match - ` - -* Add a description: - - :code:`set traffic-policy limiter class match - description ` - -* Specify the priority of a matching rule to set the order in which the rules - are evaluated, the higher the number the lower the priority, range 0...20 - (default 20): - - :code:`set traffic-policy limiter class - priority ` - -* Specify a match criterion based on a **destination MAC address** - (format: xx:xx:xx:xx:xx:xx): - - :code:`set traffic-policy limiter class match - ether destination ` - -* Specify a match criterion based on a **source MAC address** (format: - xx:xx:xx:xx:xx:xx): - - :code:`set traffic-policy limiter class match - ether source ` - -* Specify a match criterion based on **packet type/protocol**, range 0...65535: - - :code:`set traffic-policy limiter class match - ether protocol ` - -* Specify a match criterion based on the **fwmark field**, range 0....4294967295: - - :code:`set traffic-policy limiter class match - mark ` - -* Specify a match criterion based on **VLAN ID**, range 1...4096: - - :code:`set traffic-policy limiter class match - vif ` - -**IPv4** - -* Specify a match criterion based on **destination IPv4 address** and/or port, - port may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy limiter class - match ip destination ` - -* Specify a match criterion based on **source IPv4 address** and/or port, port - may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy limiter class - match ip source ` - -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: - - :code:`set traffic-policy limiter class match - ip dscp ` - -* Specify a match criterion based on **IPv4 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: - - :code:`set traffic-policy limiter class match - ip protocol ` - -**IPv6** - -* Specify a match criterion based on **destination IPv6 address and/or port**, - port may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy limiter class match - ipv6 destination ` - -* Specify a match criterion based on **source IPv6 address and/or port**, port - may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy limiter class match - ipv6 source ` - -* Specify a match criterion based on **DSCP (Differentiated Services Code - Point) value**, DSCP value may be specified as decimal or hexadecimal number: - - :code:`set traffic-policy limiter class match - ipv6 dscp ` - -* Specify a match criterion based on **IPv6 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: - - :code:`set traffic-policy limiter class match - ipv6 protocol ` - -Network emulator -^^^^^^^^^^^^^^^^ - -The network emulator policy emulates WAN traffic, which is useful for testing -purposes. Applicable to outbound traffic only. - -Available commands: - -* Define a network emulator policy: - - :code:`set traffic-policy network-emulator ` - -* Add a description: - - :code:`set traffic-policy network-emulator description ` - -* Specify a bandwidth limit in kbit/s: - - :code:`set traffic-policy network-emulator bandwidth ` - - Available suffixes: - - * kbit (kilobits per second, default) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) - -* Set a burst size, the maximum amount of traffic that can be sent, in bytes: - - :code:`set traffic-policy network-emulator burst ` - - Available suffixes: - - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) - -* Define a delay between packets: - - :code:`set traffic-policy network-emulator network-delay ` - - Available suffixes: - - * secs (seconds) - * ms (milliseconds, default) - * us (microseconds) - -* Set a percentage of corrupted of packets (one bit flip, unchanged checksum): - - :code:`set traffic-policy network-emulator packet-corruption - ` - -* Set a percentage of random packet loss: - - :code:`set traffic-policy network-emulator packet-loss ` - -* Set a percentage of packets for random reordering: - - :code:`set traffic-policy network-emulator packet-reordering - ` - -* Set a queue length limit in packets, range 0...4294967295, default 127: - - :code:`set traffic-policy network-emulator queue-limit ` - -Priority queue -^^^^^^^^^^^^^^ - -Up to seven queues with differing priorities can be defined, packets are placed -into queues based on associated match criteria. Packets are transmitted from -the queues in priority order. If queues with a higher order are being filled -with packets continuously, packets from lower priority queues will only be -transmitted after traffic volume from higher priority queues decreases. - -Available commands: - -* Define a priority queue: - - :code:`set traffic-policy priority-queue ` - -* Add a description: - - :code:`set traffic-policy priority-queue description ` - -Traffic classes -*************** - -* Define a traffic class, each class is a separate queue, range for class ID - is 1...7, while 1 being the lowest priority: - - :code:`set traffic-policy priority-queue class ` - -* Add a class description: - - :code:`set traffic-policy priority-queue class - description ` - -* Set a queue length limit in packets, default 1000: - - :code:`set traffic-policy priority-queue class - queue-limit ` - -* Specify a queue type for a traffic class, available queue types: - - * drop-tail - * fair-queue - * random-detect - - :code:`set traffic-policy priority-queue class - queue-type ` - -Default class -############# - -* Define a default priority queue: - - :code:`set traffic-policy priority-queue default` - -* Define a maximum queue length for the default traffic class in packets: - - :code:`set traffic-policy priority-queue default queue-limit - ` - -* Specify the queuing type for the default traffic class, available queue types: - - * drop-tail - * fair-queue - * random-detect - - :code:`set traffic-policy priority-queue default queue-type ` - -Matching rules -************** - -* Define a class matching rule: - - :code:`set traffic-policy priority-queue class match - ` - -* Add a match rule description: - - :code:`set traffic-policy priority-queue class match - description ` - -* Specify a match criterion based on a **destination MAC address** - (format: xx:xx:xx:xx:xx:xx): - - :code:`set traffic-policy priority-queue class match - ether destination ` - -* Specify a match criterion based on a **source MAC address** - (format: xx:xx:xx:xx:xx:xx): - - :code:`set traffic-policy priority-queue class match - ether source ` - -* Specify a match criterion based on **packet type/protocol**, range 0...65535: - - :code:`set traffic-policy priority-queue class match - ether protocol ` - -* Specify a match criterion based on **ingress interface**: - - :code:`set traffic-policy priority-queue class match - interface ` - -* Specify a match criterion based on the **fwmark field**, range 0....4294967295: - - :code:`set traffic-policy priority-queue class match - mark ` - -* Specify a match criterion based on **VLAN ID**, range 1...4096: - - :code:`set traffic-policy priority-queue class match - vif ` - -**IPv4** - -* Specify a match criterion based on **destination IPv4 address and/or port**, - port may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy priority-queue class match - ip destination ` - -* Specify a match criterion based on **source IPv4 address and/or port**, port - may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy priority-queue class match - ip source ` - -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: - - :code:`set traffic-policy priority-queue class match - ip dscp ` - -* Specify a match criterion based on **IPv4 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: - - :code:`set traffic-policy priority-queue class match - ip protocol ` - -**IPv6** - -* Specify a match criterion based on **destination IPv6 address and/or port**, - port may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy priority-queue class match - ipv6 destination ` - -* Specify a match criterion based on **source IPv6 address and/or port**, port - may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy priority-queue class match - ipv6 source ` - -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: - - :code:`set traffic-policy priority-queue class match - ipv6 dscp ` - -* Specify a match criterion based on **IPv6 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: - - :code:`set traffic-policy priority-queue class match - ipv6 protocol ` - -Random Early Detection (RED/WRED) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -RED -*** - -A Random Early Detection (RED) policy starts randomly dropping packets from a -queue before it reaches its queue limit thus avoiding congestion. It is also -beneficial for TCP connections as the gradual dropping of packets acts as a -signal for the sender to decrease its transmission rate, avoiding global TCP -synchronisation. Applicable to outbound traffic only. - -Available commands: - -* Define a RED policy: - - :code:`set traffic-policy random-detect ` - -* Add a description: - - :code:`set traffic-policy random-detect description ` - -* Set a bandwidth limit, default auto: - - :code:`set traffic-policy random-detect bandwidth ` - - Available suffixes: - - * auto (bandwidth limit based on interface speed, default) - * kbit (kilobits per second) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) - -WRED -**** - -In contrast to RED, Weighted Random Early Detection (WRED) differentiates -between classes of traffic in a single queue and assigns different precedence -to traffic flows accordingly; low priority packets are dropped from a queue -earlier than high priority packets. This is achieved by using the first three -bits of the ToS (Type of Service) field to categorise data streams and in -accordance with the defined precedence parameters a decision is made. A WRED -policy is defined with the following parameters: - -* precedence -* min-threshold -* max-threshold -* average-packet -* mark-probability -* queue-limit - -If the average queue size is lower than the :code:`min-threshold`, an arriving -packet is placed in the queue. If the average queue size is between -:code:`min-threshold` and :code:`max-threshold` an arriving packet is either -dropped or placed in the queue depending on the defined :code:`mark-probability`. -In case the average queue size is larger than :code:`max-threshold`, packets -are dropped. If the current queue size is larger than :code:`queue-limit`, -packets are dropped. The average queue size depends on its former average size -and its current size. If :code:`max-threshold` is set but :code:`min-threshold` -is not, then :code:`min-threshold` is scaled to 50% of :code:`max-threshold`. -In principle, values must be :code:`min-threshold` < :code:`max-threshold` < -:code:`queue-limit`. Applicable to outbound traffic only. - -Possible values for WRED parameters: - -* precedence - IP precedence, first three bits of the ToS field as defined in - RFC791_. - - +------------+----------------------+ - | Precedence | Priority | - +============+======================+ - | 7 | Network Control | - +------------+----------------------+ - | 6 | Internetwork Control | - +------------+----------------------+ - | 5 | CRITIC/ECP | - +------------+----------------------+ - | 4 | Flash Override | - +------------+----------------------+ - | 3 | Flash | - +------------+----------------------+ - | 2 | Immediate | - +------------+----------------------+ - | 1 | Priority | - +------------+----------------------+ - | 0 | Routine | - +------------+----------------------+ - -* min-threshold - Min value for the average queue length, packets are dropped - if the average queue length reaches this threshold. Range 0...4096, default - is dependent on precedence: - - +------------+-----------------------+ - | Precedence | default min-threshold | - +============+=======================+ - | 7 | 16 | - +------------+-----------------------+ - | 6 | 15 | - +------------+-----------------------+ - | 5 | 14 | - +------------+-----------------------+ - | 4 | 13 | - +------------+-----------------------+ - | 3 | 12 | - +------------+-----------------------+ - | 2 | 11 | - +------------+-----------------------+ - | 1 | 10 | - +------------+-----------------------+ - | 0 | 9 | - +------------+-----------------------+ - -* max-threshold - Max value for the average queue length, packets are dropped - if this value is exceeded. Range 0...4096 packets, default 18. - -* average-packet - Average packet size in bytes, default 1024. - -* mark-probability - The fraction of packets (n/probability) dropped from the - queue when the average queue length reaches max-threshold, - default 10. - -* queue-limit - Packets are dropped when the current queue length reaches this - value, default 4*max-threshold. - -Usage: - -:code:`set traffic-policy random-detect precedence - [average-packet | mark-probability | -max-threshold | min-threshold | queue-limit ]` - -Rate control (TBF) -^^^^^^^^^^^^^^^^^^ - -The rate control policy uses the Token Bucket Filter (TBF_) algorithm to limit -the packet flow to a set rate. Short bursts can be allowed to exceed the limit. -Applicable to outbound traffic only. - -Available commands: - -* Define a rate control policy: - - :code:`set traffic-policy rate-control ` - -* Add a description: - - :code:`set traffic-policy rate-control description ` - -* Specify a bandwidth limit in kbits/s: - - :code:`set traffic-policy rate-control bandwidth ` - - Available suffixes: - - * kbit (kilobits per second, default) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) - -* Specify a burst size in bytes, default 15 kilobytes: - - :code:`set traffic-policy rate-control burst ` - - Available suffixes: - - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) - -* Specify a latency in milliseconds; the maximum amount of time packets are - allowed to wait in the queue, default 50 milliseconds: - - :code:`set traffic-policy rate-control latency` - - Available suffixes: - - * secs (seconds) - * ms (milliseconds, default) - * us (microseconds) - -Round robin (DRR) -^^^^^^^^^^^^^^^^^ - -The round robin policy divides available bandwidth between all defined traffic -classes. - -Available commands: - -* Define a round robin policy: - - :code:`set traffic-policy round-robin ` - -* Add a description: - - :code:`set traffic-policy round-robin description ` - -* Define a traffic class ID, range 2...4095: - - :code:`set traffic-policy round-robin class ` - -**Default policy:** - -* Define a default priority queue: - - :code:`set traffic-policy round-robin default` - -* Set the number of packets that can be sent per scheduling quantum: - - :code:`set traffic-policy round-robin default quantum ` - -* Define a maximum queue lenght for the default policy in packets: - - :code:`set traffic-policy round-robin default queue-limit ` - -* Specify the queuing type for the default policy, available queue types: - - * drop-tail - * fair-queue - * priority (based on the DSCP values in the ToS byte) - - :code:`set traffic-policy round-robin default queue-type ` - -Matching rules -************** - -* Define a class matching rule: - - :code:`set traffic-policy round-robin class match - ` - -* Add a match rule description: - - :code:`set traffic-policy round-robin class match - description ` - -* Specify a match criterion based on a **destination MAC address** (format: - xx:xx:xx:xx:xx:xx): - - :code:`set traffic-policy round-robin class match - ether destination ` - -* Specify a match criterion based on a **source MAC address** (format: - xx:xx:xx:xx:xx:xx): - - :code:`set traffic-policy round-robin class match - ether source ` - -* Specify a match criterion based on **packet type/protocol**, range 0...65535: - - :code:`set traffic-policy round-robin class match - ether protocol ` - -* Specify a match criterion based on **ingress interface**: - - :code:`set traffic-policy round-robin class match - interface ` - -* Specify a match criterion based on the **fwmark field**, range 0....4294967295: - - :code:`set traffic-policy round-robin class match - mark ` - -* Specify a match criterion based on **VLAN ID**, range 1...4096: - - :code:`set traffic-policy round-robin class match - vif *` - -**IPv4** - -* Specify a match criterion based on **destination IPv4 address and/or port**, - port may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy round-robin class match - ip destination ` - -* Specify a match criterion based on **source IPv4 address and/or port**, port - may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy round-robin class match - ip source ` - -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: - - :code:`set traffic-policy round-robin class match - ip dscp ` - -* Specify a match criterion based on **IPv4 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: - - :code:`set traffic-policy round-robin class match - ip protocol ` - -**IPv6** - -* Specify a match criterion based on **destination IPv6 address and/or port**, - port may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy round-robin class match - ipv6 destination ` - -* Specify a match criterion based on **source IPv6 address and/or port**, port - may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy round-robin class match - ipv6 source ` - -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: - - :code:`set traffic-policy round-robin class match - ipv6 dscp ` - -* Specify a match criterion based on **IPv6 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: - - :code:`set traffic-policy round-robin class match - ipv6 protocol ` - -Traffic shaper -^^^^^^^^^^^^^^ - -The shaper policy uses the Hierarchical Token Bucket algorithm to allocate -different amounts of bandwidth to different traffic classes. In contrast to -round robin, shaper limits bandwidth allocation by traffic class whereas round -robin divides the total available bandwidth between classes. - -Avialable commands: - -* Define a shaper policy: - - :code:`set traffic-policy shaper ` - -* Add a description: - - :code:`set traffic-policy shaper description ` - -* Set the available bandwidth for all combined traffic of this policy in kbit/s, - default 100%: - - :code:`set traffic-policy shaper bandwidth ` - - Available suffixes: - - * % (percentage of total bandwidth) - * kbit (kilobits per second) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) - -Traffic classes -*************** - -* Define a traffic class for a shaper policy, range for class ID is 2...4095: - - :code:`set traffic-policy shaper class ` - -* Add a class description: - - :code:`set traffic-policy shaper class description - ` - -* Specify a bandwidth limit for a class, in kbit/s: - - :code:`set traffic-policy shaper class bandwidth ` - - Available suffixes: - - * kbit (kilobits per second, default) - * mbit (megabits per second) - * gbit (gigabits per second) - * kbps (kilobytes per second) - * mbps (megabytes per second) - * gbps (gigabytes per second) - -* Set a burst size for a class, the maximum amount of traffic that can be sent, - in bytes: - - :code:`set traffic-policy shaper class - burst ` - - Available suffixes: - - * kb (kilobytes) - * mb (megabytes) - * gb (gigabytes) - -* Set a bandwidth ceiling for a class in kbit/s: - - :code:`set traffic-policy shaper class ceiling ` - - Available suffixes: - - * % (percentage of total bandwidth) - * kbit (kilobits per second) - * mbit (megabits per second) - * gbit (gigabits per second) - -* Set the priority of a class for allocation of additional bandwidth, if unused - bandwidth is available. Range 0...7, lowest number has lowest priority, - default 0: - - :code:`set traffic-policy shaper class - priority ` - -* Set a queue length limit in packets: - - :code:`set traffic-policy shaper class queue-limit - ` - -* Specify a queue type for a traffic class, default fair-queue. Available - queue types: - - * drop-tail - * fair-queue - * random-detect - * priority - - :code:`set traffic-policy shaper class queue-type ` - -* Modify DSCP field; the DSCP field value of packets in a class can be - rewritten to change the forwarding behaviour and allow for traffic - conditioning: - - :code:`set traffic-policy shaper class set-dscp ` - - DSCP values as per RFC2474_ and RFC4595_: - - +---------+------------+--------+------------------------------+ - | Binary | Configured | Drop | Description | - | value | value | rate | | - +=========+============+========+==============================+ - | 101110 | 46 | - | Expedited forwarding (EF) | - +---------+------------+--------+------------------------------+ - | 000000 | 0 | - | Best effort traffic, default | - +---------+------------+--------+------------------------------+ - | 001010 | 10 | Low | Assured Forwarding(AF) 11 | - +---------+------------+--------+------------------------------+ - | 001100 | 12 | Medium | Assured Forwarding(AF) 12 | - +---------+------------+--------+------------------------------+ - | 001110 | 14 | High | Assured Forwarding(AF) 13 | - +---------+------------+--------+------------------------------+ - | 010010 | 18 | Low | Assured Forwarding(AF) 21 | - +---------+------------+--------+------------------------------+ - | 010100 | 20 | Medium | Assured Forwarding(AF) 22 | - +---------+------------+--------+------------------------------+ - | 010110 | 22 | High | Assured Forwarding(AF) 23 | - +---------+------------+--------+------------------------------+ - | 011010 | 26 | Low | Assured Forwarding(AF) 31 | - +---------+------------+--------+------------------------------+ - | 011100 | 28 | Medium | Assured Forwarding(AF) 32 | - +---------+------------+--------+------------------------------+ - | 011110 | 30 | High | Assured Forwarding(AF) 33 | - +---------+------------+--------+------------------------------+ - | 100010 | 34 | Low | Assured Forwarding(AF) 41 | - +---------+------------+--------+------------------------------+ - | 100100 | 36 | Medium | Assured Forwarding(AF) 42 | - +---------+------------+--------+------------------------------+ - | 100110 | 38 | High | Assured Forwarding(AF) 43 | - +---------+------------+--------+------------------------------+ - -Matching rules -************** - -* Define a class matching rule: - - :code:`set traffic-policy shaper class match - ` - -* Add a match rule description: - - :code:`set traffic-policy shaper class match - description ` - -* Specify a match criterion based on a **destination MAC address** - (format: xx:xx:xx:xx:xx:xx): - - :code:`set traffic-policy shaper class match - ether destination ` - -* Specify a match criterion based on a **source MAC address** - (format: xx:xx:xx:xx:xx:xx): - - :code:`set traffic-policy shaper class match - ether source ` - -* Specify a match criterion based on **packet type/protocol**, range 0...65535: - - :code:`set traffic-policy shaper class match - ether protocol ` - -* Specify a match criterion based on **ingress interface**: - - :code:`set traffic-policy shaper class match - interface ` - -* Specify a match criterion based on the **fwmark field**, range 0....4294967295: - - :code:`set traffic-policy shaper class match - mark ` - -* Specify a match criterion based on **VLAN ID**, range 1...4096: - - :code:`set traffic-policy round-robin class match - vif ` - -**IPv4** - -* Specify a match criterion based on **destination IPv4 address and/or port**, - port may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy shaper class match - ip destination ` - -* Specify a match criterion based on **source IPv4 address and/or port**, port - may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy shaper class match - ip source ` - -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: - - :code:`set traffic-policy shaper class match - ip dscp ` - -* Specify a match criterion based on **IPv4 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: - - :code:`set traffic-policy shaper class match - ip protocol ` - -**IPv6** - -* Specify a match criterion based on **destination IPv6 address and/or port**, - port may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy shaper class match - ipv6 destination ` - -* Specify a match criterion based on **source IPv6 address and/or port**, - port may be specified as number or service name (i.e. ssh): - - :code:`set traffic-policy shaper class match - ipv6 source ` - -* Specify a match criterion based on **DSCP (Differentiated Services Code Point) - value**, DSCP value may be specified as decimal or hexadecimal number: - - :code:`set traffic-policy shaper class match - ipv6 dscp ` - -* Specify a match criterion based on **IPv6 protocol**, protocol may be - specified by name (i.e. icmp) or IANA-assigned number: - - :code:`set traffic-policy shaper class match - ipv6 protocol ` - -shaper-hfsc (HFSC_ + sfq) -^^^^^^^^^^^^^^^^^^^^^^^^^ - -TBD - -Ingress shaping ---------------- - -The case of ingress shaping. Only a **limiter** policy can be applied directly -for ingress traffic on an interface. It is possible though to use what is -called an Intermediate Functional Block (IFB_) to allow the usage of any policy -on the ingress traffic. - -Let's assume eth0 is your WAN link. You created two traffic-policies: `WAN-IN` -and `WAN-OUT`. - -Steps to do: - -* First, create the IFB: - - :code:`set interfaces input ifb0 description "WAN Input"` - -* Apply the `WAN-OUT` traffic-policy to ifb0 input. - - :code:`set interfaces input ifb0 traffic-policy in WAN-IN` - -* Redirect traffic from eth0 to ifb0 - - :code:`set interfaces ethernet eth0 redirect ifb0` - -Classful policies and traffic matching --------------------------------------- - -`limiter`, `round-robin`, `priority-queue`, `shaper` and `shaper-hfsc` -distribute traffic into different classes with different options. In VyOS, -classes are numbered and work like firewall rules. e.g: - -:code:`set traffic-policy shaper SHAPER class 30` - -Matching traffic -^^^^^^^^^^^^^^^^ - -A class can have multiple match filters: - -.. code-block:: sh - - set traffic-policy class N match MATCH-FILTER-NAME - -Example: - -.. code-block:: sh - - set traffic-policy shaper SHAPER class 30 match HTTP - set traffic-policy shaper SHAPER class 30 match HTTPs - -A match filter contains multiple criteria and will match traffic if all those criteria are true. - -For example: - -.. code-block:: sh - - set traffic-policy shaper SHAPER class 30 match HTTP ip protocol tcp - set traffic-policy shaper SHAPER class 30 match HTTP ip source port 80 - -This will match tcp traffic with source port 80. - -description -*********** - -.. code-block:: sh - - set traffic-policy shaper SHAPER class 30 match MATCH description "match filter description" - -ether -***** - -.. code-block:: sh - - edit traffic-policy shaper SHAPER class 30 match MATCH ether - -destination -########### - -protocol -######## - -source -###### - -interface -********* - -.. code-block:: sh - - edit traffic-policy shaper SHAPER class 30 match MATCH interface - -ip -** -.. code-block:: sh - - edit traffic-policy shaper SHAPER class 30 match MATCH ip - -destination -########### - -.. code-block:: sh - - set destination address IPv4-SUBNET - set destination port U32-PORT - -dscp -#### - -.. code-block:: sh - - set dscp DSCPVALUE - -max-length -########## - -.. code-block:: sh - - set max-length U32-MAXLEN - -Will match ipv4 packets with a total length lesser than set value. - -protocol -######## - -.. code-block:: sh - - set protocol - -source -###### - -.. code-block:: sh - - set source address IPv4-SUBNET - set source port U32-PORT - -tcp -### - -.. note:: You must set ip protocol to TCP to use the TCP filters. - -.. note:: This filter will only match packets with an IPv4 header length of - 20 bytes (which is the majority of IPv4 packets anyway). - -.. code-block:: sh - - set tcp ack - -Will match tcp packets with ACK flag set. - -.. code-block:: sh - - set tcp syn - -Will match tcp packets with SYN flag set. - -ipv6 -**** - -.. code-block:: sh - - edit traffic-policy shaper SHAPER class 30 match MATCH ipv6 - -destination -########### - - .. code-block:: sh - - set destination address IPv6-SUBNET - set destination port U32-PORT - -dscp -#### - -.. code-block:: sh - - set dscp DSCPVALUE - -max-length -########## - -.. code-block:: sh - - set max-length U32-MAXLEN - -Will match ipv6 packets with a payload length lesser than set value. - -protocol -######## - -.. code-block:: sh - - set protocol IPPROTOCOL - -source -###### - -.. code-block:: sh - - set source address IPv6-SUBNET - set source port U32-PORT - -tcp -### - -.. note:: You must set ipv6 protocol to TCP to use the TCP filters. - -.. note:: This filter will only match IPv6 packets with no header extension, see - http://en.wikipedia.org/wiki/IPv6_packet#Extension_headers for no header - extension. - -.. code-block:: sh - - set tcp ack - -Will match tcp packets with ACK flag set. - -.. code-block:: sh - - set tcp syn - -Will match tcp packets with SYN flag set. - -mark -**** - -.. code-block:: sh - - set traffic-policy shaper SHAPER class 30 match MATCH mark **firewall-mark** - -vif -*** - -.. code-block:: sh - - set traffic-policy shaper SHAPER class 30 match MATCH vif **vlan-tag** - -.. code-block:: sh - - set interfaces ethernet eth0 traffic-policy out 'WAN-OUT' - set interfaces ethernet eth1 traffic-policy out 'LAN-OUT' - -.. _tc: http://en.wikipedia.org/wiki/Tc_(Linux) -.. _RFC791: https://tools.ietf.org/html/rfc791 -.. _TBF: https://en.wikipedia.org/wiki/Token_bucket -.. _RFC2474: https://tools.ietf.org/html/rfc2474#page-7 -.. _RFC4595: https://tools.ietf.org/html/rfc4594#page-19 -.. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve -.. _IFB: http://www.linuxfoundation.org/collaborate/workgroups/networking/ifb diff --git a/docs/ch11-services.rst b/docs/ch11-services.rst deleted file mode 100644 index dce41acb..00000000 --- a/docs/ch11-services.rst +++ /dev/null @@ -1,874 +0,0 @@ -Services -======== - -DHCP ----- - -Multiple DHCP Servers can be run from a single machine. Each DHCP service is -identified by a `shared-network-name`. - -DHCP Server Example -^^^^^^^^^^^^^^^^^^^ - -In this example, we are offering address space in the 172.16.17.0/24 network, -which is on eth1, and pppoe0 is our connection to the internet. We are using -the network name `dhcpexample`. - -Prerequisites -^^^^^^^^^^^^^ - -Configuring the PPPoE interface is assumed to be done already, and appears -on `pppoe0` - -Interface Configuration -^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: sh - - set interface eth1 address 172.16.17.1/24 - -Multiple ranges can be defined and can contain holes. - -.. code-block:: sh - - set service dhcp-server shared-network-name dhcpexample authoritative - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 default-router 172.16.17.1 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 dns-server 172.16.17.1 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 lease 86400 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 start 172.16.17.100 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 stop 172.16.17.199 - -Failover -^^^^^^^^ - -VyOS provides support for DHCP failover: - -.. code-block:: sh - - 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 - -.. code-block:: sh - - set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'primary' - -or - -.. code-block:: sh - - set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'secondary' - -.. note:: In order for the primary and the secondary DHCP server to keep - their lease tables in sync, they must be able to reach each other on TCP - port 647. If you have firewall rules in effect, adjust them accordingly. - -Static mappings MAC/IP -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: sh - - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 static-mapping static-mapping-01 ip-address 172.16.17.10 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 static-mapping static-mapping-01 mac-address ff:ff:ff:ff:ff:ff - -Explanation -^^^^^^^^^^^ - -:code:`set service dhcp-server shared-network-name dhcpexample authoritative` -This says that this device is the only DHCP server for this network. If other -devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to -any device trying to request an IP address that is not valid for this network. - -:code:`set service dhcp-server shared-network-name dhcpexample subnet -172.16.17.0/24 default-router 172.16.17.1` This is a configuration parameter -for the subnet, saying that as part of the response, tell the client that I am -the default router for this network - -:code:`set service dhcp-server shared-network-name dhcpexample subnet -172.16.17.0/24 dns-server 172.16.17.1` This is a configuration parameter for -the subnet, saying that as part of the response, tell the client that I am the -DNS server for this network. If you do not want to run a DNS server, you could -also provide one of the public DNS servers, such as google's. You can add -multiple entries by repeating the line. - -:code:`set service dhcp-server shared-network-name dhcpexample subnet -172.16.17.0/24 lease 86400` Assign the IP address to this machine for 24 -hours. It is unlikely you'd need to shorten this period, unless you are running -a network with lots of devices appearing and disappearing. - -:code:`set service dhcp-server shared-network-name dhcpexample subnet -172.16.17.0/24 start 172.16.17.100 stop 172.16.17.199` Make the IP Addresses -between .100 and .199 available for clients. - -DHCPv6 server -------------- - -VyOS provides DHCPv6 server functionality which is described in this section. -In order to use the DHCPv6 server it has to be enabled first: - -.. code-block:: sh - - set service dhcpv6-server - -To restart the DHCPv6 server (operational mode): - -.. code-block:: sh - - restart dhcpv6 server - -To show the current status of the DHCPv6 server use: - -.. code-block:: sh - - show dhcpv6 server status - -Show statuses of all assigned leases: - -.. code-block:: sh - - show dhcpv6 server leases - -DHCPv6 server options -^^^^^^^^^^^^^^^^^^^^^ - -DHCPv6 server preference value -****************************** - -Clients receiving advertise messages from multiple servers choose the server -with the highest preference value. The range for this value is `0...255`. Set -a preference value for the DHCPv6 server: - -.. code-block:: sh - - set service dhcpv6-server preference - -Delete a preference: - -.. code-block:: sh - - set service dhcpv6-server preference - -Show current preference: - -.. code-block:: sh - - show service dhcpv6-server preference - -Specify address lease time -************************** - -The default lease time for DHCPv6 leases is 24 hours. This can be changed by -supplying a `default-time`, `maximum-time` and `minimum-time` (all values in -seconds): - -.. code-block:: sh - - set service dhcpv6-server shared-network-name subnet lease-time {default | maximum | minimum } - -Reset the custom lease times: - -.. code-block:: sh - - delete service dhcpv6-server shared-network-name subnet lease-time {default | maximum | minimum} - -Show the current configuration: - -.. code-block:: sh - - show service dhcpv6-server shared-network-name subnet lease-time {default | maximum | minimum} - -Specify NIS domain -****************** - -A Network Information (NIS) domain can be set to be used for DHCPv6 clients: - -.. code-block:: sh - - set service dhcpv6-server shared-network-name subnet nis-domain - -To Delete the NIS domain: - -.. code-block:: sh - - delete service dhcpv6-server shared-network-name subnet nis-domain - -Show a configured NIS domain: - -.. code-block:: sh - - show service dhcpv6-server shared-network-name subnet nis-domain - -Specify NIS+ domain -******************* - -The procedure to specify a Network Information Service Plus (NIS+) domain is -similar to the NIS domain one: - -.. code-block:: sh - - set service dhcpv6-server shared-network-name subnet nisplus-domain - -To Delete the NIS+ domain: - -.. code-block:: sh - - delete service dhcpv6-server shared-network-name subnet nisplus-domain - -Show a configured NIS domain: - - # show service dhcpv6-server shared-network-name subnet nisplus-domain - -Specify NIS server address -************************** - -To specify a NIS server address for DHCPv6 clients: - -.. code-block:: sh - - set service dhcpv6-server shared-network-name subnet nis-server - -Delete a specified NIS server address: - -.. code-block:: sh - - delete service dhcpv6-server shared-network-name subnet nis-server - -Show specified NIS server addresses: - -.. code-block:: sh - - show service dhcpv6-server shared-network-name subnet nis-server - -Specify NIS+ server address -*************************** - -To specify a NIS+ server address for DHCPv6 clients: - -.. code-block:: sh - - set service dhcpv6-server shared-network-name subnet nisplus-server - -Delete a specified NIS+ server address: - -.. code-block:: sh - - delete service dhcpv6-server shared-network-name subnet nisplus-server - -Show specified NIS+ server addresses: - -.. code-block:: sh - - show service dhcpv6-server shared-network-name subnet nisplus-server - -Specify a SIP server address for DHCPv6 clients -*********************************************** - -By IPv6 address -############### - - -A Session Initiation Protocol (SIP) server address can be specified for DHCPv6 clients: - -.. code-block:: sh - - set service dhcpv6-server shared-network-name subnet sip-server-address - -Delete a specified SIP server address: - -.. code-block:: sh - - delete service dhcpv6-server shared-network-name subnet sip-server-address - -Show specified SIP server addresses: - -.. code-block:: sh - - show service dhcpv6-server shared-network-name subnet sip-server-address - -By FQDN -####### - -A name for SIP server can be specified: - -.. code-block:: sh - - set service dhcpv6-server shared-network-name subnet sip-server-name - -Delete a specified SIP server name: - -.. code-block:: sh - - delete service dhcpv6-server shared-network-name subnet sip-server-name - -Show specified SIP server names: - -.. code-block:: sh - - show service dhcpv6-server shared-network-name subnet sip-server-name - -Simple Network Time Protocol (SNTP) server address for DHCPv6 clients -********************************************************************* - -A SNTP server address can be specified for DHCPv6 clients: - -.. code-block:: sh - - set service dhcpv6-server shared-network-name subnet sntp-server-address - -Delete a specified SNTP server address: - -.. code-block:: sh - - delete service dhcpv6-server shared-network-name subnet sntp-server-address - -Show specified SNTP server addresses: - -.. code-block:: sh - - show service dhcpv6-server shared-network-name subnet sntp-server-address - -DHCPv6 address pools -^^^^^^^^^^^^^^^^^^^^ - -DHCPv6 address pools must be configured for the system to act as a DHCPv6 -server. The following example describes a common scenario. - -Example 1: DHCPv6 address pool -****************************** - -A shared network named `NET1` serves subnet `2001:db8:100::/64` which is -connected to `eth1`, a DNS server at `2001:db8:111::111` is used for name -services. The range of the address pool shall be `::100` through `::199`. The -lease time will be left at the default value which is 24 hours. - -.. code-block:: sh - - set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 address-range start 2001:db8:100::100 stop 2001:db8:100::199 - set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 name-server 2001:db8:111::111 - -Commit the changes and show the configuration: - -.. code-block:: sh - - commit - show service dhcpv6-server - shared-network-name NET1 { - subnet 2001:db8:100::/64 { - address-range { - start 2001:db8:100::100 { - stop 2001:db8:100::199 - } - } - name-server 2001:db8:111::111 - } - } - -Static mappings -^^^^^^^^^^^^^^^ - -In order to map specific IPv6 addresses to specific hosts static mappings can -be created. The following example explains the process. - -Example 1: Static IPv6 MAC-based mapping -**************************************** - -IPv6 address `2001:db8:100::101` shall be statically mapped to a device with -MAC address `00:15:c5:b7:5e:23`, this host-specific mapping shall be named -`client1`. - -.. note:: The MAC address identifier is defined by the last 4 byte of the - MAC address. - -.. code-block:: sh - - set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 static-mapping client1 ipv6-address 2001:db8:100::101 - set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 static-mapping client1 identifier c5b75e23 - -Commit the changes and show the configuration: - -.. code-block:: sh - - show service dhcp-server shared-network-name NET1 - shared-network-name NET1 { - subnet 2001:db8:100::/64 { - name-server 2001:db8:111::111 - address-range { - start 2001:db8:100::100 { - stop 2001:db8:100::199 { - } - } - static-mapping client1 { - ipv6-address 2001:db8:100::101 - identifier c5b75e23 - } - } - } - - -DHCP Relay ----------- - -If you want your router to forward DHCP requests to an external DHCP server -you can configure the system to act as a DHCP relay agent. The DHCP relay -agent works with IPv4 and IPv6 addresses. - -All interfaces used for the DHCP relay must be configured. See -https://wiki.vyos.net/wiki/Network_address_setup. - -DHCP relay example -^^^^^^^^^^^^^^^^^^ - -.. figure:: _static/images/service_dhcp-relay01.png - :scale: 80 % - :alt: DHCP relay example - - DHCP relay example - -In this example the interfaces used for the DHCP relay are eth1 and eth2. The -router receives DHCP client requests on eth1 and relays them through eth2 to -the DHCP server at 10.0.1.4. - -Configuration -^^^^^^^^^^^^^ - -Enable DHCP relay for eth1 and eth2: - -.. code-block:: sh - - set service dhcp-relay interface eth1 - set service dhcp-relay interface eth2 - -Set the IP address of the DHCP server: - -.. code-block:: sh - - set service dhcp-relay server 10.0.1.4 - -The router should discard DHCP packages already containing relay agent -information to ensure that only requests from DHCP clients are forwarded: - -.. code-block:: sh - - set service dhcp-relay relay-options relay-agents-packets discard - -Commit the changes and show the results: - -.. code-block:: sh - - commit - show service dhcp-relay - interface eth1 - interface eth2 - server 10.0.1.4 - relay-options { - relay-agents-packets discard - } - -The DHCP relay agent can be restarted with: - -.. code-block:: sh - - restart dhcp relay-agent - -DHCPv6 relay example -^^^^^^^^^^^^^^^^^^^^ - -.. figure:: _static/images/service_dhcpv6-relay01.png - :scale: 80 % - :alt: DHCPv6 relay example - - DHCPv6 relay example - -In this example DHCPv6 requests are received by the router on eth1 (`listening -interface`) and forwarded through eth2 (`upstream interface`) to the external -DHCPv6 server at 2001:db8:100::4. - -Configuration -************* - -Set eth1 to be the listening interface for the DHCPv6 relay: - -.. code-block:: sh - - set service dhcpv6-relay listen-interface eth1 - -Set eth2 to be the upstream interface and specify the IPv6 address of the DHCPv6 server: - -.. code-block:: sh - - set service dhcpv6-relay upstream-interface eth2 address 2001:db8:100::4 - -Commit the changes and show results: - -.. code-block:: sh - - commit - show service dhcpv6-relay - listen-interface eth1 { - } - upstream-interface eth2 { - address 2001:db8:100::4 - } - -Show the current status of the DHCPv6 relay agent: - -.. code-block:: sh - - show dhcpv6 relay-agent status - -The DHCPv6 relay agent can be restarted with: - -.. code-block:: sh - - restart dhcpv6 relay-agent - -Additional parameters -^^^^^^^^^^^^^^^^^^^^^ - -DHCP relay agent options -************************ - -Set the maximum hop count before packets are discarded. Range 0...255, -default 10. - -* :code:`set service dhcp-relay relay-options hop-count 'count'` - -Set maximum size of DHCP packets including relay agent information. If a -DHCP packet size surpasses this value it will be forwarded without appending -relay agent information. Range 64...1400, default 576. - -* :code:`set service dhcp-relay relay-options max-size 'size'` - -Set the port used to relay DHCP client messages. Range 1...65535, default 67. -After setting a different port, requests are still accepted on port 67 but -replies are forwarded to 255.255.255.255 port 0 instead of 68. - -* :code:`set service dhcp-relay relay-options port 'port'` - -Four policies for reforwarding DHCP packets exist: - -* **append:** The relay agent is allowed to append its own relay information - to a received DHCP packet, disregarding relay information already present in - the packet. - -* **discard:** Received packets which already contain relay information will - be discarded. - -* **forward:** All packets are forwarded, relay information already present - will be ignored. - -* **replace:** Relay information already present in a packet is stripped and - replaced with the router's own relay information set. - -* :code:`set service dhcp-relay relay-options relay-agents-packet 'policy'` - -DHCPv6 relay agent options -************************** - -Set listening port for DHCPv6 requests. Default: 547. - -* :code:`set service dhcpv6-relay listen-port 'port'` - -Set maximum hop count before packets are discarded. Default: 10. - -* :code:`set service dhcpv6-relay max-hop-count 'count'` - -If this is set the relay agent will insert the interface ID. This option is -set automatically if more than one listening interfaces are in use. - -* :code:`set service dhcpv6-relay use-interface-id-option` - -DNS Forwarding --------------- - -Use DNS forwarding if you want your router to function as a DNS server for the -local network. There are several options, the easiest being 'forward all -traffic to the system DNS server(s)' (defined with set system name-server): - -.. code-block:: sh - - set service dns forwarding system - -Manually setting DNS servers for forwarding: - -.. code-block:: sh - - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 - -Manually setting DNS servers with IPv6 connectivity: - -.. code-block:: sh - - set service dns forwarding name-server 2001:4860:4860::8888 - set service dns forwarding name-server 2001:4860:4860::8844 - -Setting a forwarding DNS server for a specific domain: - -.. code-block:: sh - - set service dns forwarding domain example.com server 192.0.2.1 - -Example 1 -^^^^^^^^^ - -Router with two interfaces eth0 (WAN link) and eth1 (LAN). A DNS server for the -local domain (example.com) is at 192.0.2.1, other DNS requests are forwarded -to Google's DNS servers. - -.. code-block:: sh - - set service dns forwarding domain example.com server 192.0.2.1 - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 - set service dns forwarding listen-on 'eth1' - -Example 2 -^^^^^^^^^ - -Same as example 1 but with additional IPv6 addresses for Google's public DNS -servers: - -.. code-block:: sh - - set service dns forwarding domain example.com server 192.0.2.1 - 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 2001:4860:4860::8888 - set service dns forwarding name-server 2001:4860:4860::8844 - set service dns forwarding listen-on 'eth1' - -Dynamic DNS ------------ - -VyOS is able to update a remote DNS record when an interface gets a new IP -address. In order to do so, VyOS includes ddclient_, a perl script written for -this exact purpose. - -ddclient_ uses two methods to update a DNS record. The first one will send -updates directly to the DNS daemon, in compliance with RFC2136_. The second -one involves a third party service, like DynDNS.com or any other similar -website. This method uses HTTP requests to transmit the new IP address. You -can configure both in VyOS. - -VyOS CLI and RFC2136 -^^^^^^^^^^^^^^^^^^^^ - -First, create an RFC2136_ config node : - -.. code-block:: sh - - edit service dns dynamic interface eth0 rfc2136 - -Present your RNDC key to ddclient : - -.. code-block:: sh - - set key /config/dyndns/mydnsserver.rndc.key - -Set the DNS server IP/FQDN : - -.. code-block:: sh - - set server dns.mydomain.com - -Set the NS zone to be updated : - -.. code-block:: sh - - set zone mydomain.com - -Set the records to be updated : - -.. code-block:: sh - - set record dyn - set record dyn2 - -You can optionally set a TTL (note : default value is 600 seconds) : - -.. code-block:: sh - - set ttl 600 - -This will generate the following ddclient config blocks: - -.. code-block:: sh - - server=dns.mydomain.com - protocol=nsupdate - password=/config/dyndns/mydnsserver.rndc.key - ttl=600 - zone=mydomain.com - dyn - server=dns.mydomain.com - protocol=nsupdate - password=/config/dyndns/mydnsserver.rndc.key - ttl=600 - zone=mydomain.com - dyn2 - -You can also keep a different dns zone updated. Just create a new config node: - -.. code-block:: sh - - edit service dns dynamic interface eth0 rfc2136 - -VyOS CLI and HTTP dynamic DNS services -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -VyOS is also able to use any service relying on protocols supported by ddclient. - -To use such a service, you must define a login, a password, one or multiple -hostnames, a protocol and a server. - -.. code-block:: sh - - edit service dns dynamic interface eth0 service HeNet - set login my-login # set password my-password - set host-name my-tunnel-id - set protocol dyndns2 - set server ipv4.tunnelbroker.net - -VyOS is also shipped with a list of known services. You don't need to set the -protocol and server value as VyOS has defaults provided for those. These are -the services VyOS knows about: - -* afraid -* changeip -* dnspark -* dslreports -* dyndns -* easydns -* namecheap -* noip -* zoneedit - -To use DynDNS for example: - -.. code-block:: sh - - edit service dns dynamic interface eth0 service dyndns - set login my-login - set password my-password - set host-name my-dyndns-hostname - -It's possible to use multiple services : - -.. code-block:: sh - - edit service dns dynamic interface eth0 service dyndns - set login my-login - set password my-password - set host-name my-dyndns-hostname - edit service dns dynamic interface eth0 service HeNet - set login my-login - set password my-password - set host-name my-tunnel-id - set protocol dyndns2 - set server ipv4.tunnelbroker.net - -ddclient behind NAT -^^^^^^^^^^^^^^^^^^^ - -By default, ddclient will update a dynamic dns record using the IP address -directly attached to the interface. If your VyOS instance is behind NAT, your -record will be updated to point to your internal IP. - -ddclient_ has another way to determine the WAN IP address. This is controlled -by these two options: - -.. code-block:: sh - - set service dns dynamic interface eth0 use-web url - set service dns dynamic interface eth0 use-web skip - -ddclient_ will load the webpage at `[url]` and will try to extract an IP -address for the response. ddclient_ will skip any address located before the -string set in `[skip]`. - -mDNS Repeater -------------- - -Starting with VyOS 1.2 a `Multicast DNS`_ (mDNS) repeater functionality is -provided. - -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. Apple Airplay devices across -multiple VLANs. - -To enable mDNS repeater you need to configure at least two interfaces. To re- -broadcast all mDNS packets from `eth0` to `eth1` and vice versa run: - -.. code-block:: sh - - set service mdns repeater interface eth0 - set service mdns repeater interface eth1 - -mDNS repeater can be temporarily disabled without deleting the service using - -.. code-block:: sh - - set service mdns repeater disable - -.. note:: You can not run this in a VRRP setup, if multiple mDNS repeaters - are launched in a subnet you will experience the mDNS packet storm death! - -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 play! 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! - -To Forward broadcasts on port 1900 for eth3, eth4 and eth5 configure the service -as follows: - -.. code-block:: sh - - 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 - -.. code-block:: sh - - 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 individually disabled without deleting the -configured node by: - -.. code-block:: sh - - set service broadcast-relay id disable - -In addition you can also disable the whole service without removing the -configuration by: - -.. code-block:: sh - - set service broadcast-relay disable - -.. note:: You can run the UDP broadcast relay service on multiple routers - connected to a subnet. There is **NO** UDP broadcast relay packet storm! - -.. _ddclient: http://sourceforge.net/p/ddclient/wiki/Home/ -.. _RFC2136: https://www.ietf.org/rfc/rfc2136.txt -.. _`Multicast DNS`: https://en.wikipedia.org/wiki/Multicast_DNS diff --git a/docs/ch12-system.rst b/docs/ch12-system.rst deleted file mode 100644 index e613bfac..00000000 --- a/docs/ch12-system.rst +++ /dev/null @@ -1,355 +0,0 @@ -System -====== - -After a basic system setup by setting up `Interface Addresses`_, VyOS should -be ready for further configuration which is described in this chapter. - -Host Information ----------------- - -This section describes the system's host information and how to configure them, -it covers the following topics: - -* Host name -* Domain -* IP address -* Default gateway -* Aliases - -Host Name -^^^^^^^^^ - -A hostname is the label (name) assigned to a network device (a host) on a -network and is used to distinguish one device from another on specific networks -or over the internet. - -Set a system host name: - -.. code-block:: sh - - set system host-name - -.. note:: Only letters, numbers and hyphens are allowed. - -Show host name: - -.. code-block:: sh - - show system host-name - -Delete host name: - -.. code-block:: sh - - delete system host-name - -Example: Set system hostname to 'RT01': - -.. code-block:: sh - - set system host-name RT01 - commit - show system host-name - host-name RT01 - -Domain Name -^^^^^^^^^^^ - -A domainname is the label (name) assigned to a computer network and is thus -unique! - -Set the system's domain: - -.. code-block:: sh - - set system domain-name - -.. note:: Only letters, numbers, hyphens and periods are allowed. - -Show domain: - -.. code-block:: sh - - show system domain-name - -Remove domain name: - -.. code-block:: sh - - set system delete domain-name - -Example: Set system domain to example.com: - -.. code-block:: sh - - set system domain-name example.com - commit - show system domain-name - domain-name example.com - -Static host mappings -^^^^^^^^^^^^^^^^^^^^ - -How to assign IPs to interfaces is described in chapter `Interface Addresses`_. -This section shows how to statically map a system IP to its host name for -local (meaning on this VyOS instance) DNS resolution: - -.. code-block:: sh - - set system static-host-mapping host-name inet - -Show static mapping: - -.. code-block:: sh - - show system static-host-mapping - -Example: Create a static mapping between the system's hostname `RT01` and -IP address `10.20.30.41`: - -.. code-block:: sh - - set system static-host-mapping host-name RT01 inet 10.20.30.41 - commit - show system static-host-mapping - host-name RT01 { - inet 10.20.30.41 - } - -Aliases -******* - -One or more system aliases (static mappings) can be defined: - -.. code-block:: sh - - set system static-host-mapping host-name alias - -Show aliases: - -.. code-block:: sh - - show system static-mapping - -Delete alias: - -.. code-block:: sh - - delete system static-host-mapping host-name alias - -Example: Set alias `router1` for system with hostname `RT01`: - -.. code-block:: sh - - set system static-host-mapping host-name RT01 alias router1 - commit - show system static-host-mapping - host-name RT01 { - alias router1 - inet 10.20.30.41 - } - -Default Gateway/Route -^^^^^^^^^^^^^^^^^^^^^ - -In the past (VyOS 1.1.8) used a gateway-address configured in the system tree -(`set system gateway-address `) this is no longer supported and -existing configurations are migrated to the new CLI commands. - -It is replaced by inserting a static route into the routing table using: - -.. code-block:: sh - - set protocols static route 0.0.0.0/0 next-hop - -Delete default route fomr the system - -.. code-block:: sh - - delete protocols static route 0.0.0.0/0 - -Show default route: - -.. code-block:: sh - - vyos@vyos$ show ip route 0.0.0.0 - Routing entry for 0.0.0.0/0 - Known via "static", distance 1, metric 0, best - Last update 3d00h23m ago - * 172.16.34.6, via eth1 - -System Users ------------- - -VyOS supports two levels of users: admin and operator. - -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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Create user account `jsmith`, with `admin` level access and the password -`mypassword` - -.. code-block:: sh - - set system login user jsmith full-name "Johan Smith" - set system login user jsmith authentication plaintext-password mypassword - set system login user jsmith level admin - -The command: - -.. code-block:: sh - - show system login - -will show the contents of :code:`system login` configuration node: - -.. code-block:: sh - - user jsmith { - authentication { - encrypted-password $6$0OQHjuQ8M$AYXVn7jufdfqPrSk4/XXsDBw99JBtNsETkQKDgVLptXogHA2bU9BWlvViOFPBoFxIi.iqjqrvsQdQ./cfiiPT. - plaintext-password "" - } - full-name "Johan Smith" - level admin - } - -SSH Access using Shared Public Keys -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following command will load the public key `dev.pub` for user `jsmith` - -.. code-block:: sh - - loadkey jsmith dev.pub - -.. note:: This requires uploading the `dev.pub` public key to the VyOS router - first. As an alternative you can also load the SSH public key directly - from a remote system: - -.. code-block:: sh - - loadkey jsmith scp://devuser@dev001.vyos.net/home/devuser/.ssh/dev.pub - -Syslog ------- - -Per default VyOSs has minimal syslog logging enabled which is stored and -rotated locally. Errors will be always logged to a local file, which includes -`local7` error messages, emergency messages will be sent to the console, too. - -To configure syslog, you need to switch into configuration mode. - -Logging to serial console -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The below would log all messages to :code:`/dev/console`. - -.. code-block:: sh - - set system syslog console facility all level all - -Use the **[tab]** function to display all facilities and levels which can -be configured. - -.. code-block:: sh - - vyos@vyos# set system syslog console facility - Possible completions: - > all All facilities excluding "mark" - > auth Authentication and authorization - > authpriv Non-system authorization - > cron Cron daemon - > daemon System daemons - > kern Kernel - > lpr Line printer spooler - > mail Mail subsystem - > mark Timestamp - > news USENET subsystem - > protocols depricated will be set to local7 - > security depricated will be set to auth - > syslog Authentication and authorization - > user Application processes - > uucp UUCP subsystem - > local0 Local facility 0 - > local1 Local facility 1 - > local2 Local facility 2 - > local3 Local facility 3 - > local4 Local facility 4 - > local5 Local facility 5 - > local6 Local facility 6 - > local7 Local facility 7 - - vyos@vyos# set system syslog console facility all level - Possible completions: - emerg Emergency messages - alert Urgent messages - crit Critical messages - err Error messages - warning Warning messages - notice Messages for further investigation - info Informational messages - debug Debug messages - all Log everything - - -Logging to a custom file -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Logging to a custom file, rotation size and the number of rotate files left -on the system can be configured. - -.. code-block:: sh - - set system syslog file facility level - set system syslog file archive file - set system syslog file FILENAME archive size - -The very same setting can be applied to the global configuration, to modify -the defaults for the global logging. - -Logging to a remote host -^^^^^^^^^^^^^^^^^^^^^^^^ - -Logging to a remote host leaves the local logging configuration intact, it -can be configured in parallel. You can log ro multiple hosts at the same time, -using either TCP or UDP. The default is sending the messages via UDP. - -**UDP** - -.. code-block:: sh - - set system syslog host 10.1.1.1 facility all level all - - set system syslog host 10.1.1.1 facility all protocol udp - - -**TCP** - -.. code-block:: sh - - set system syslog host 10.1.1.2 facility all level all - set system syslog host 10.1.1.2 facility all protocol tcp - -Logging to a local user account -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If logging to a local useraccount is configured, all defined log messages are -display on the console if the local user is logged in, if the user is not -logged in, no messages are being displayed. - -.. code-block:: sh - - set system syslog user facility level diff --git a/docs/ch13-clustering.rst b/docs/ch13-clustering.rst deleted file mode 100644 index 9f14c6ae..00000000 --- a/docs/ch13-clustering.rst +++ /dev/null @@ -1,28 +0,0 @@ -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. - -.. code-block:: sh - - 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 - } diff --git a/docs/ch14-image-mgmt.rst b/docs/ch14-image-mgmt.rst deleted file mode 100644 index a36ad112..00000000 --- a/docs/ch14-image-mgmt.rst +++ /dev/null @@ -1,104 +0,0 @@ -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: - -.. code-block:: sh - - / - /boot - /boot/grub - /boot/1.2.0-rolling+201810021347 - -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 :code:`set system image -default-boot` command in operational mode. - -A list of available images can be shown using the :code:`show system image` -command in operational mode. - -.. code-block:: sh - - vyos@vyos:~$ show system image - The system currently has the following image(s) installed: - - 1: 1.2.0-rolling+201810021347 (default boot) - 2: 1.2.0-rolling+201810021217 - 3: 1.2.0-rolling+201809280337 - 4: 1.2.0-rolling+201809252218 - 5: 1.2.0-rolling+201809192034 - 6: 1.2.0-rolling+201809191744 - 7: 1.2.0-rolling+201809150337 - 8: 1.2.0-rolling+201809141130 - 9: 1.2.0-rolling+201809140949 - 10: 1.2.0-rolling+201809131722 - - vyos@vyos:~$ - -Images no longer needed can be removed using the :code:`delete system image` -command. - - -Update VyOS Installation ------------------------- - -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. - -.. code-block:: sh - - vyos@vyos:~$ add system image https://downloads.vyos.io/rolling/current/amd64/vyos-1.2.0-rolling%2B201810030440-amd64.iso - Trying to fetch ISO file from https://downloads.vyos.io/rolling/current/amd64/vyos-1.2.0-rolling%2B201810030440-amd64.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k - ISO download succeeded. - Checking for digital signature file... - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 - curl: (22) The requested URL returned error: 404 Not Found - - Unable to fetch digital signature file. - Do you want to continue without signature check? (yes/no) [yes] - Checking MD5 checksums of files on the ISO image...OK. - Done! - - What would you like to name this image? [1.2.0-rolling+201810030440]: - - OK. This image will be named: 1.2.0-rolling+201810030440 - We do not have enough disk space to install this image! - We need 344880 KB, but we only have 17480 KB. - Exiting... - -.. note:: Rolling releases are not GPG signed, only the real release build - will have a proper GPG signature. - -.. note:: VyOS 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 -:code:`/live` directory. - diff --git a/docs/cli.rst b/docs/cli.rst new file mode 100644 index 00000000..66144fce --- /dev/null +++ b/docs/cli.rst @@ -0,0 +1,86 @@ +.. _cli: + +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. + +.. code-block:: sh + + vyos@vyos:~$ s[tab] + set show + vyos@vyos:~$ + +Example showing possible show commands: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + vyos@vyos:~$ configure + [edit] + vyos@vyos:~# + +.. note:: Prompt changes from `$` to `#`. To exit configuration mode, type `exit`. + +.. code-block:: sh + + vyos@vyos:~# exit + exit + vyos@vyos:~$ + +See the configuration section of this document for more information on +configuration mode. diff --git a/docs/clustering.rst b/docs/clustering.rst new file mode 100644 index 00000000..9eee31ea --- /dev/null +++ b/docs/clustering.rst @@ -0,0 +1,30 @@ +.. _clustering: + +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. + +.. code-block:: sh + + 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 + } diff --git a/docs/conf.py b/docs/conf.py index 05a92cff..e9960a8e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -39,8 +39,9 @@ release = u'1.2.0-beta' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = [ -] +extensions = ['sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.ifconfig'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -69,13 +70,15 @@ exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'default' +html_theme = "sphinx_rtd_theme" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst new file mode 100644 index 00000000..3024c277 --- /dev/null +++ b/docs/configuration-overview.rst @@ -0,0 +1,211 @@ +.. _configuration-overview: + +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. + +.. code-block:: sh + + 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. + +.. code-block:: sh + + 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 '' + 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. + +.. code-block:: sh + + 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. + +.. code-block:: sh + + 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. + +.. code-block:: sh + + 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. + +.. code-block:: sh + + 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: + +.. code-block:: sh + + vyos@vyos# compare [tab] + Possible completions: + Compare working & active configurations + saved Compare working & saved configurations + Compare working with revision N + 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. + +.. code-block:: sh + + 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. + +.. code-block:: sh + + vyos@vyos# save [tab] + Possible completions: + Save to system config file + Save to file on local machine + scp://:@/ Save to file on remote machine + ftp://:@/ Save to file on remote machine + tftp:/// 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 diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 00000000..7194188a --- /dev/null +++ b/docs/examples.rst @@ -0,0 +1,107 @@ +.. _examples: + +Appendix B - Configuration Examples +=================================== + +VyOS DMVPN Hub +-------------- + +General infomration can be found in the DMVPN_ chapter. + +Configuration +^^^^^^^^^^^^^ + +.. code-block:: sh + + set interfaces tunnel tun100 address '172.16.253.134/29' + set interfaces tunnel tun100 encapsulation 'gre' + set interfaces tunnel tun100 local-ip '11.22.33.44' + set interfaces tunnel tun100 multicast 'enable' + set interfaces tunnel tun100 parameters ip key '1' + + set protocols nhrp tunnel tun100 cisco-authentication '' + set protocols nhrp tunnel tun100 holding-time '300' + set protocols nhrp tunnel tun100 multicast 'dynamic' + set protocols nhrp tunnel tun100 redirect + set protocols nhrp tunnel tun100 shortcut + + set vpn ipsec esp-group ESP-HUB compression 'disable' + set vpn ipsec esp-group ESP-HUB lifetime '1800' + set vpn ipsec esp-group ESP-HUB mode 'tunnel' + set vpn ipsec esp-group ESP-HUB pfs 'dh-group2' + set vpn ipsec esp-group ESP-HUB proposal 1 encryption 'aes256' + set vpn ipsec esp-group ESP-HUB proposal 1 hash 'sha1' + set vpn ipsec esp-group ESP-HUB proposal 2 encryption '3des' + set vpn ipsec esp-group ESP-HUB proposal 2 hash 'md5' + set vpn ipsec ike-group IKE-HUB ikev2-reauth 'no' + set vpn ipsec ike-group IKE-HUB key-exchange 'ikev1' + set vpn ipsec ike-group IKE-HUB lifetime '3600' + set vpn ipsec ike-group IKE-HUB proposal 1 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 1 encryption 'aes256' + set vpn ipsec ike-group IKE-HUB proposal 1 hash 'sha1' + set vpn ipsec ike-group IKE-HUB proposal 2 dh-group '2' + set vpn ipsec ike-group IKE-HUB proposal 2 encryption 'aes128' + set vpn ipsec ike-group IKE-HUB proposal 2 hash 'sha1' + set vpn ipsec ipsec-interfaces interface 'eth0' + + set vpn ipsec profile NHRPVPN authentication mode 'pre-shared-secret' + set vpn ipsec profile NHRPVPN authentication pre-shared-secret '' + set vpn ipsec profile NHRPVPN bind tunnel 'tun100' + set vpn ipsec profile NHRPVPN esp-group 'ESP-HUB' + set vpn ipsec profile NHRPVPN ike-group 'IKE-HUB' + +Cisco IOS Spoke +^^^^^^^^^^^^^^^ + +This example is verified with a Cisco 2811 platform running IOS 15.1(4)M9 and +VyOS 1.1.7 (helium) up to VyOS 1.2 (Crux). + +.. code-block:: sh + + Cisco IOS Software, 2800 Software (C2800NM-ADVENTERPRISEK9-M), Version 15.1(4)M9, RELEASE SOFTWARE (fc3) + Technical Support: http://www.cisco.com/techsupport + Copyright (c) 1986-2014 by Cisco Systems, Inc. + Compiled Fri 12-Sep-14 10:45 by prod_rel_team + + ROM: System Bootstrap, Version 12.3(8r)T7, RELEASE SOFTWARE (fc1) + +Use this configuration on your Cisco device: + +.. code-block:: sh + + crypto pki token default removal timeout 0 + crypto keyring DMVPN + pre-shared-key address 1.2.3.4 key + ! + crypto isakmp policy 10 + encr aes 256 + authentication pre-share + group 2 + ! + crypto isakmp invalid-spi-recovery + crypto isakmp keepalive 30 30 periodic + crypto isakmp profile DMVPN + keyring DMVPN + match identity address 11.22.33.44 255.255.255.255 + ! + crypto ipsec transform-set DMVPN-AES256 esp-aes 256 esp-sha-hmac + mode transport + ! + crypto ipsec profile DMVPN + set security-association idle-time 720 + set transform-set DMVPN-AES256 + ! + interface Tunnel10 + description Tunnel to DMVPN HUB + ip address 172.16.253.129 255.255.255.248 + no ip redirects + ip nhrp authentication + ip nhrp map multicast 11.22.33.44 + ip nhrp map 172.16.253.134 11.22.33.44 + ip nhrp network-id 1 + ip nhrp holdtime 600 + ip nhrp nhs 172.16.253.134 + ip nhrp registration timeout 75 + tunnel source Dialer1 + tunnel mode gre multipoint + tunnel key 1 diff --git a/docs/firewall.rst b/docs/firewall.rst new file mode 100644 index 00000000..8ab4dacf --- /dev/null +++ b/docs/firewall.rst @@ -0,0 +1,178 @@ +.. _firewall: + +Firewall +======== + +VyOS makes use of Linux [http://netfilter.org/ 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 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 +------ + +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:: 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: + +.. code-block:: sh + + 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 `-`. + +Here is an example of a port group a server: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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). + +.. code-block:: sh + + 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): + +.. code-block:: sh + + set zone-policy zone INSIDE from OUTSIDE firewall name INSIDE-OUT + +Example Partial Config +---------------------- + +.. code-block:: sh + + 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 + } + } + } + } + +[https://www.xfinity.com/support/internet/list-of-blocked-ports/ XFinity Blocked Port List] + diff --git a/docs/image-mgmt.rst b/docs/image-mgmt.rst new file mode 100644 index 00000000..ebb1de23 --- /dev/null +++ b/docs/image-mgmt.rst @@ -0,0 +1,106 @@ +.. _image-mgmt: + +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: + +.. code-block:: sh + + / + /boot + /boot/grub + /boot/1.2.0-rolling+201810021347 + +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 :code:`set system image +default-boot` command in operational mode. + +A list of available images can be shown using the :code:`show system image` +command in operational mode. + +.. code-block:: sh + + vyos@vyos:~$ show system image + The system currently has the following image(s) installed: + + 1: 1.2.0-rolling+201810021347 (default boot) + 2: 1.2.0-rolling+201810021217 + 3: 1.2.0-rolling+201809280337 + 4: 1.2.0-rolling+201809252218 + 5: 1.2.0-rolling+201809192034 + 6: 1.2.0-rolling+201809191744 + 7: 1.2.0-rolling+201809150337 + 8: 1.2.0-rolling+201809141130 + 9: 1.2.0-rolling+201809140949 + 10: 1.2.0-rolling+201809131722 + + vyos@vyos:~$ + +Images no longer needed can be removed using the :code:`delete system image` +command. + + +Update VyOS Installation +------------------------ + +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. + +.. code-block:: sh + + vyos@vyos:~$ add system image https://downloads.vyos.io/rolling/current/amd64/vyos-1.2.0-rolling%2B201810030440-amd64.iso + Trying to fetch ISO file from https://downloads.vyos.io/rolling/current/amd64/vyos-1.2.0-rolling%2B201810030440-amd64.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k + ISO download succeeded. + Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 + curl: (22) The requested URL returned error: 404 Not Found + + Unable to fetch digital signature file. + Do you want to continue without signature check? (yes/no) [yes] + Checking MD5 checksums of files on the ISO image...OK. + Done! + + What would you like to name this image? [1.2.0-rolling+201810030440]: + + OK. This image will be named: 1.2.0-rolling+201810030440 + We do not have enough disk space to install this image! + We need 344880 KB, but we only have 17480 KB. + Exiting... + +.. note:: Rolling releases are not GPG signed, only the real release build + will have a proper GPG signature. + +.. note:: VyOS 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 +:code:`/live` directory. + diff --git a/docs/index.rst b/docs/index.rst index 4b3c4a13..39c9985f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,17 +1,8 @@ -.. VyOS documentation master file, created by - sphinx-quickstart on Sun Jul 1 14:35:07 2018. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. _index: Welcome to VyOS's documentation! ================================ -.. toctree:: - :maxdepth: 2 - :caption: Contents: - -Introduction -============ VyOS is an open source network operating system based on Debian GNU/Linux. VyOS provides a free routing platform that competes directly with other @@ -19,41 +10,24 @@ commercially available solutions from well known network providers. Because VyOS is run on standard amd64, i586 and ARM systems, it is able to be used as a router and firewall platform for cloud deployments. -.. include:: ch01-install.rst - -.. include:: ch02-cli.rst - -.. include:: ch03-quick-start.rst - -.. include:: ch04-configuration-overview.rst - -.. include:: ch05-network-interfaces.rst - -.. include:: ch06-routing.rst - -.. include:: ch07-firewall.rst - -.. include:: ch08-nat.rst - -.. include:: ch09-vpn.rst - -.. include:: ch10-qos.rst - -.. include:: ch11-services.rst - -.. include:: ch12-system.rst - -.. include:: ch13-clustering.rst - -.. include:: ch14-image-mgmt.rst - -.. include:: apxA-troubleshooting.rst - -.. include:: apxB-examples.rst - -Indices and tables -================== +.. toctree:: + :maxdepth: 3 + :caption: Contents: + + install.rst + cli.rst + quick-start.rst + configuration-overview.rst + network-interfaces.rst + routing.rst + firewall.rst + nat.rst + vpn.rst + qos.rst + services + system.rst + clustering.rst + image-mgmt.rst + troubleshooting.rst + examples.rst -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 00000000..4714e87c --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,101 @@ +.. _installation: + +Installation +============ + +The latest ISO image for VyOS can be downloaded at https://www.vyos.net. + +The recommended system requirements are 512 MiB RAM and 2 GiB 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 ``vyos`` with password ``vyos``. + +.. code-block:: sh + + The programs included with the Debian GNU/Linux system are free software; + the exact distribution terms for each program are described in the + individual files in /usr/share/doc/*/copyright. + + Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent + permitted by applicable law. + vyos@vyos:~$ + + vyos@vyos:~$ uname -a + Linux vyos 4.18.11-amd64-vyos #23 SMP Mon Oct 1 17:29:22 CEST 2018 x86_64 GNU/Linux + +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``. In addition the ``install system`` command has been + removed in VyOS 1.2 (Crux). + +To install VyOS, run ``install image``. + +.. code-block:: sh + + 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]: Yes + Probing drives: OK + Looking for pre-existing RAID groups...none found. + The VyOS image will require a minimum 2000MB 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]: + + I found the following drives on your system: + sda 4294MB + + Install the image on? [sda]: + + This will destroy all data on /dev/sda. + Continue? (Yes/No) [No]: Yes + + How big of a root partition should I create? (2000MB - 4294MB) [4294]MB: + + Creating filesystem on /dev/sda1: OK + Done! + Mounting /dev/sda1... + What would you like to name this image? [1.2.0-rolling+201809210337]: + OK. This image will be named: 1.2.0-rolling+201809210337 + Copying squashfs image... + Copying kernel and initrd images... + Done! + I found the following configuration files: + /opt/vyatta/etc/config.boot.default + Which one should I copy to sda? [/opt/vyatta/etc/config.boot.default]: + + Copying /opt/vyatta/etc/config.boot.default to sda. + Enter password for administrator account + Enter password for user 'vyos': + Retype password for user 'vyos': + I need to install the GRUB boot loader. + I found the following drives on your system: + sda 4294MB + + Which drive should GRUB modify the boot partition on? [sda]: + + Setting up grub: OK + Done! + vyos@vyos:~$ + +After the installation is complete, remove the Live CD and reboot the system: + +.. code-block:: sh + + vyos@vyos:~$ reboot + Proceed with reboot? (Yes/No) [No] Yes diff --git a/docs/nat.rst b/docs/nat.rst new file mode 100644 index 00000000..a69cffbe --- /dev/null +++ b/docs/nat.rst @@ -0,0 +1,324 @@ +.. _nat: + +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: + +.. code-block:: sh + + 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. + +.. code-block:: sh + + 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. + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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: http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers + +Our configuration commands would be: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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:: 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. + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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) +--------------- + +NPTv6 stands for Network Prefix Translation. It's a form of NAT for IPv6. It's +described in RFC6296_. NPTv6 is supported in linux kernel since version 3.13. + +Usage +----- + +NPTv6 is very useful for IPv6 multihoming. Let's assume the following network +configuration: + +* eth0 : LAN +* eth1 : WAN1, with 2001:db8:e1::/48 routed towards it +* eth2 : WAN2, with 2001:db8:e2::/48 routed towards it + +Regarding LAN hosts addressing, why would you choose 2001:db8:e1::/48 over +2001:db8:e2::/48? What happens when you get a new provider with a different +routed IPv6 subnet? + +The solution here is to assign to your hosts ULAs_ and to prefix-translate +their address to the right subnet when going through your router. + +* LAN Subnet : fc00:dead:beef::/48 +* WAN 1 Subnet : 2001:db8:e1::/48 +* WAN 2 Subnet : 2001:db8:e2::/48 + +* eth0 addr : fc00:dead:beef::1/48 +* eth1 addr : 2001:db8:e1::1/48 +* eth2 addr : 2001:db8:e2::1/48 + +VyOS Support +------------ + +NPTv6 support has been added in VyOS 1.2 (Crux) and is available through +`nat nptv6` configuration nodes. + +.. code-block:: sh + + set rule 10 inside-prefix 'fc00:dead:beef::/48' + set rule 10 outside-interface 'eth1' + set rule 10 outside-prefix '2001:db8:e1::/48' + set rule 20 inside-prefix 'fc00:dead:beef::/48' + set rule 20 outside-interface 'eth2' + set rule 20 outside-prefix '2001:db8:e2::/48' + +Resulting in the following ip6tables rules: + +.. code-block:: sh + + Chain VYOS_DNPT_HOOK (1 references) + pkts bytes target prot opt in out source destination + 0 0 DNPT all eth1 any anywhere 2001:db8:e1::/48 src-pfx 2001:db8:e1::/48 dst-pfx fc00:dead:beef::/48 + 0 0 DNPT all eth2 any anywhere 2001:db8:e2::/48 src-pfx 2001:db8:e2::/48 dst-pfx fc00:dead:beef::/48 + 0 0 RETURN all any any anywhere anywhere + Chain VYOS_SNPT_HOOK (1 references) + pkts bytes target prot opt in out source destination + 0 0 SNPT all any eth1 fc00:dead:beef::/48 anywhere src-pfx fc00:dead:beef::/48 dst-pfx 2001:db8:e1::/48 + 0 0 SNPT all any eth2 fc00:dead:beef::/48 anywhere src-pfx fc00:dead:beef::/48 dst-pfx 2001:db8:e2::/48 + 0 0 RETURN all any any anywhere anywhere + +.. _RFC6296: https://tools.ietf.org/html/rfc6296 +.. _ULAs: http://en.wikipedia.org/wiki/Unique_local_address diff --git a/docs/network-interfaces.rst b/docs/network-interfaces.rst new file mode 100644 index 00000000..e17d9dde --- /dev/null +++ b/docs/network-interfaces.rst @@ -0,0 +1,575 @@ +.. _network-interfaces: + +Network Interfaces +================== + +Configured interfaces on a VyOS system can be displayed using the `show +interfaces` command. + +.. code-block:: sh + + 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 ` +command. + +.. code-block:: sh + + vyos@vyos:~$ show interfaces ethernet eth0 + eth0: 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:~$ + +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. + +Interface Addresses +------------------- + +Each interface can be configured with a description and address. Interface +addresses might be: + +* Static IPv4 `address 172.16.51.129/24` +* Static IPv6 `address 2001:db8:1::ffff/64` +* DHCP IPv4 `address dhcp` +* DHCP IPv6 `address dhcpv6` + +An interface description is assigned using the following command: + +.. code-block:: sh + + set interfaces ethernet eth0 description 'OUTSIDE' + +IPv4 +^^^^ + +Static Address +************** + +This method is supported on all interfaces, apart from OpenVPN that uses +different syntax and wireless modems that are always autoconfigured through +PPP. + +The command is `set interfaces $type $name address $address`. Examples: + +.. code-block:: sh + + set interfaces ethernet eth0 address 192.0.2.1/24 + set interfaces tunnel tun0 address 10.0.0.1/30 + set interfaces bridge br0 address 203.0.113.45/26 + set interfaces ethernet eth0 vif 30 address 192.0.30.254/24 + +DHCP +**** + +This method is supported on all physical interfaces, and those that are +directly connected to a physical interface (ethernet, VLAN, bridge, bond, +pseudo-ethernet, wireless). + +The command is `set interfaces $type $name address dhcp`. Examples: + +.. code-block:: sh + + set interfaces ethernet eth0 vif 90 address dhcp + set interfaces bridge br0 address dhcp + +IPv6 +^^^^ + +Static Address +************** + +This method is supported on all interfaces, apart from OpenVPN that uses +different syntax and wireless modems that are always autoconfigured through +PPP. Static IPv6 addresses are supported on all interfaces except VTI. + +The command is `set interfaces $type $name address $address`. Examples: + +.. code-block:: sh + + set interfaces ethernet eth0 address 2001:db8:100::ffff/64 + set interfaces tunnel tun0 address 2001:db8::1/64 + set interfaces bridge br0 address 2001:db8:200::1/64 + set interfaces ethernet eth0 vif 30 address 2001:db8:3::ffff/64 + +DHCP +**** + +This method is supported on all physical interfaces, and those that are +directly connected to a physical interface (ethernet, VLAN, bridge, bond, +pseudo-ethernet, wireless). + +The command is `set interfaces $type $name address dhcpv6`. Examples: + +.. code-block:: sh + + set interfaces bonding bond1 address dhcpv6 + set interfaces bridge br0 vif 56 address dhcpv6 + +Autoconfiguration (SLAAC) +************************* + +SLAAC is specified in RFC4862_. This method is supported on all physical +interfaces, and those that are directly connected to a physical interface +(ethernet, VLAN, bridge, bond, pseudo-ethernet, wireless). + +The command is `set interfaces $type $name ipv6 address autoconf`. Examples: + +.. code-block:: sh + + set interfaces ethernet eth0 vif 90 ipv6 address autoconf + set interfaces bridge br0 ipv6 address autoconf + +.. note:: This method automatically disables IPv6 traffic forwarding on the + interface in question. + +EUI-64 +****** + +EUI-64 (64-Bit Extended Unique Identifier) as specified in RFC4291_. IPv6 +addresses in /64 networks can be automatically generated from the prefix and +MAC address, if you specify the prefix. + +The command is `set interfaces $type $name ipv6 address eui64 $prefix`. Examples: + +.. code-block:: sh + + set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64 + set interfaces pseudo-ethernet peth0 ipv6 address eui64 2001:db8:aa::/64 + +Ethernet Interfaces +------------------- + +Ethernet interfaces allow for the configuration of speed, duplex, and hw-id +(MAC address). Below is an example configuration: + +.. code-block:: sh + + set interfaces ethernet eth1 address '192.168.0.1/24' + set interfaces ethernet eth1 address '2001:db8:1::ffff/64' + set interfaces ethernet eth1 description 'INSIDE' + set interfaces ethernet eth1 duplex 'auto' + set interfaces ethernet eth1 speed 'auto' + +Resulting in: + +.. code-block:: sh + + ethernet eth1 { + address 192.168.0.1/24 + address 2001:db8:1::ffff/64 + 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 physical` and `show interfaces ethernet +statistics`. Statistics available are driver dependent. + +.. code-block:: sh + + 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 +vif `. + +.. code-block:: sh + + 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 '2001:db8:100::1/64' + +Resulting in: + +.. code-block:: sh + + ethernet eth1 { + address 192.168.100.1/24 + address 2001:db8:100::1/64 + 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 `.`, e.g. `eth1.100`: + +.. code-block:: sh + + 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. + +.. code-block:: sh + + 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. + +.. code-block:: sh + + set interfaces bridge br100 address '192.168.100.1/24' + set interfaces bridge br100 address '2001:db8:100::1/64' + +Example Result: + +.. code-block:: sh + + bridge br100 { + address 192.168.100.1/24 + address 2001:db8:100::1/64 + } + [...] + 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 stp true` command: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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 spanning-tree` command +can be used to show STP configuration: + +.. code-block:: sh + + 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 + macs` command: + +.. code-block:: sh + + 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 ether-channel, or port-channel. + +Create interface bondX, where X is just a number: + +.. code-block:: sh + + set interfaces bonding bond0 description 'my-sw1 int 23 and 24' + +You are able to choose a hash policy: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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): + +.. code-block:: sh + + set interfaces bonding bond0 mode '802.3ad' + +or some other modes: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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 + +.. code-block:: sh + + set interfaces vti vti0 address 192.168.2.249/30 + set interfaces vti vti0 address 2001:db8:2::249/64 + +Results in: + +.. code-block:: sh + + vyos@vyos# show interfaces vti + vti vti0 { + address 192.168.2.249/30 + address 2001:db8:2::249/64 + description "Description" + } + +WireGuard VPN Interface +----------------------- + +WireGuard_ is an extremely simple yet fast and modern VPN that utilizes +state-of-the-art cryptography. See https://www.wireguard.com for more +information. + +Configuration +^^^^^^^^^^^^^ + +Generate the keypair, which creates a public and private part and stores it +within VyOS. + +.. code-block:: sh + + wg01:~$ configure + wg01# run generate wireguard keypair + +The public key is being shared with your peer(s), your peer will encrypt all +traffic to your system using this public key. + +.. code-block:: sh + + wg01# run show wireguard pubkey + u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk= + +The next step is to configure your local side as well as the policy based +trusted destination addresses. If you only initiate a connection, the listen +port and endpoint is optional, if you however act as a server and endpoints +initiate the connections to your system, you need to define a port your clients +can connect to, otherwise it's randomly chosen and may make it difficult with +firewall rules, since the port may be a different one when you reboot your +system. + +You will also need the public key of your peer as well as the network(s) you +want to tunnel (allowed-ips) to configure a wireguard tunnel. The public key +below is always the public key from your peer, not your local one. + +**local side** + +.. code-block:: sh + + set interfaces wireguard wg01 address '10.1.0.1/24' + set interfaces wireguard wg01 description 'VPN-to-wg02' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.2.0.0/24' + set interfaces wireguard wg01 peer to-wg02 endpoint '192.168.0.142:12345' + set interfaces wireguard wg01 peer to-wg02 pubkey 'XMrlPykaxhdAAiSjhtPlvi30NVkvLQliQuKP7AI7CyI=' + set interfaces wireguard wg01 port '12345' + set protocols static interface-route 10.2.0.0/24 next-hop-interface wg01 + +The last step is to define an interface route for 10.2.0.0/24 to get through +the wireguard interface `wg01`. Multiple IPs or networks can be defined and +routed, the last check is allowed-ips which either prevents or allows the +traffic. + +**remote side** + +.. code-block:: sh + + set interfaces wireguard wg01 address '10.2.0.1/24' + set interfaces wireguard wg01 description 'VPN-to-wg01' + set interfaces wireguard wg01 peer to-wg02 allowed-ips '10.1.0.0/24' + set interfaces wireguard wg01 peer to-wg02 endpoint '192.168.0.124:12345' + set interfaces wireguard wg01 peer to-wg02 pubkey 'u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk=' + set interfaces wireguard wg01 port '12345' + set protocols static interface-route 10.1.0.0/24 next-hop-interface wg01 + +Assure that your firewall rules allow the traffic, in which case you have a +working VPN using wireguard. + +.. code-block:: sh + + wg01# ping 10.2.0.1 + PING 10.2.0.1 (10.2.0.1) 56(84) bytes of data. + 64 bytes from 10.2.0.1: icmp_seq=1 ttl=64 time=1.16 ms + 64 bytes from 10.2.0.1: icmp_seq=2 ttl=64 time=1.77 ms + + wg02# ping 10.1.0.1 + PING 10.1.0.1 (10.1.0.1) 56(84) bytes of data. + 64 bytes from 10.1.0.1: icmp_seq=1 ttl=64 time=4.40 ms + 64 bytes from 10.1.0.1: icmp_seq=2 ttl=64 time=1.02 ms + +An additional layer of symmetric-key crypto can be used on top of the +asymmetric crypto, which is optional. + +.. code-block:: sh + + wg01# run generate wireguard preshared-key + rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= + +Copy the key, it is not stored on the local file system. Make sure you +distribute that key in a safe manner, it's a symmatric key, so only you and +your peer should have knowledge if its content. + +.. code-block:: sh + + wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' + wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' + +.. _RFC4862: https://tools.ietf.org/html/rfc4862 +.. _RFC4291: http://tools.ietf.org/html/rfc4291#section-2.5.1 +.. _WireGuard: https://www.wireguard.com diff --git a/docs/qos.rst b/docs/qos.rst new file mode 100644 index 00000000..d3ec2271 --- /dev/null +++ b/docs/qos.rst @@ -0,0 +1,1353 @@ +.. _qos: + +QoS and Traffic Policy +====================== + +VyOS uses tc_ as backend for QoS. VyOS provides its users with configuration +nodes for the following shaping/queueing/policing disciplines: + +* HTB +* HFSC +* SFQ +* pfifo +* network-emulator +* PRIO +* GRED +* TBF +* DRR + +Configuration nodes +------------------- + +VyOS QoS configuration is done in two steps. The first one consists in setting +up your classes/queues and traffic filters to distribute traffic amongst them. +The second step is to apply such traffic policy to an interface ingress or +egress. + +Creating a traffic policy +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Such configuration takes place under the `traffic-policy` tree. + +Available subtrees : + +.. code-block:: sh + + set traffic-policy drop-tail NAME + set traffic-policy fair-queue NAME + set traffic-policy limiter NAME + set traffic-policy network-emulator NAME + set traffic-policy priority-queue NAME + set traffic-policy random-detect NAME + set traffic-policy rate-control NAME + set traffic-policy round-robin NAME + set traffic-policy shaper NAME + set traffic-policy shaper-hfsc NAME + +Apply traffic policy to an interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once a traffic-policy is created, you can apply it to an interface : + +.. code-block:: sh + + set interfaces ethernet eth0 traffic-policy in WAN-IN + set interfaces etherhet eth0 traffic-policy out WAN-OUT + +Traffic policies in VyOS +------------------------ +An overview of QoS traffic policies supported by VyOS. + +Drop-tail (FIFO) +^^^^^^^^^^^^^^^^ + +A packet queuing mechanism on a FIFO (First In, First Out) basis; packets are +sent out in the same order as they arrive. The queue has a defined length, +packets arriving after the queue is filled up will be dropped (hence the name +`drop tail`, the "tail" of the queue will be dropped). With this policy in +place, all traffic is treated equally and put into a single queue. Applicable +to outbound traffic only. + +Available commands: + +* Define a drop-tail policy (unique name, exclusive to this policy): + + :code:`set traffic-policy drop-tail ` + +* Add a description: + + :code:`set traffic-policy drop-tail description ` + +* Set the queue length limit (max. number of packets in queue), range + 0...4294967295 packets: + + :code:`set traffic-policy drop-tail queue-limit ` + +Fair queue (SFQ) +^^^^^^^^^^^^^^^^ + +Fair queue is a packet queuing mechanism that separates traffic flows based on +their source/destination IP addresses and/or source port and places them into +buckets. Bandwidth is allocated fairly between buckets based on the Stochastic +airness Queuing algorithm. Applicable to outbound traffic only. + +Available commands: + +* Define a fair queue policy: + + :code:`set traffic-policy fair-queue ` + +* Add a description: + + :code:`set traffic-policy fair-queue description ` + +* Set hash update interval; the algorithm used is stochastic and thus not + 'truly' fair, hash collisions can occur, in which case traffic flows may be + put into the same bucket. To mitigate this, the hashes can be updated at a + set interval, Range 0...4294967295 seconds: + + :code:`set traffic-policy fair-queue hash-interval ` + +* Set the queue-limit (max. number of packets in queue), range 0...4294967295 + packets, default 127: + + :code:`set traffic-policy fair-queue queue-limit ` + +Limiter +^^^^^^^ + +The limiter performs ingress policing of traffic flows. Multiple classes of +traffic can be defined and traffic limits can be applied to each class. Traffic +exceeding the defined bandwidth limits is dropped. Applicable to inbound +traffic only. + +Available commands: + +* Define a traffic limiter policy: + :code:`set traffic-policy limiter ` +* Add a description: + :code:`set traffic-policy limiter description ` + +Traffic classes +*************** + +* Define a traffic class for a limiter policy, range for class ID is 1...4095: + + :code:`set traffic-policy limiter class ` + +* Add a class description: + + :code:`set traffic-policy limiter class description + ` + +* Specify a bandwidth limit for a class, in kbit/s: + + :code:`set traffic-policy limiter class bandwidth + `. + + Available suffixes: + + * kbit (kilobits per second, default) + * mbit (megabits per second) + * gbit (gigabits per second) + * kbps (kilobytes per second) + * mbps (megabytes per second) + * gbps (gigabytes per second) + +* Set a burst size for a class, the maximum amount of traffic that can be sent, + in bytes: + + :code:`set traffic-policy limiter class + burst `. + + Available suffixes: + + * kb (kilobytes) + * mb (megabytes) + * gb (gigabytes) + +Default class +############# + +* Define a default class for a limiter policy that applies to traffic not + matching any other classes for this policy: + + :code:`set traffic-policy limiter default` + +* Specify a bandwidth limit for the default class, in kbit/s: + + :code:`set traffic-policy limiter default bandwidth `. + + Available suffixes: + + * kbit (kilobits per second, default) + * mbit (megabits per second) + * gbit (gigabits per second) + * kbps (kilobytes per second) + * mbps (megabytes per second) + * gbps (gigabytes per second) + +* Set a burst size for the default class, the maximum amount of traffic that + can be sent, in bytes: + + :code:`set traffic-policy limiter default burst `. + + Available suffixes: + + * kb (kilobytes) + * mb (megabytes) + * gb (gigabytes) + +* Specify the priority of the default class to set the order in which the rules + are evaluated, the higher the number the lower the priority, range 0...20 + (default 20): + + :code:`set traffic-policy limiter default priority ` + +Matching rules +************** + +* Define a traffic class matching rule: + + :code:`set traffic-policy limiter class match + ` + +* Add a description: + + :code:`set traffic-policy limiter class match + description ` + +* Specify the priority of a matching rule to set the order in which the rules + are evaluated, the higher the number the lower the priority, range 0...20 + (default 20): + + :code:`set traffic-policy limiter class + priority ` + +* Specify a match criterion based on a **destination MAC address** + (format: xx:xx:xx:xx:xx:xx): + + :code:`set traffic-policy limiter class match + ether destination ` + +* Specify a match criterion based on a **source MAC address** (format: + xx:xx:xx:xx:xx:xx): + + :code:`set traffic-policy limiter class match + ether source ` + +* Specify a match criterion based on **packet type/protocol**, range 0...65535: + + :code:`set traffic-policy limiter class match + ether protocol ` + +* Specify a match criterion based on the **fwmark field**, range 0....4294967295: + + :code:`set traffic-policy limiter class match + mark ` + +* Specify a match criterion based on **VLAN ID**, range 1...4096: + + :code:`set traffic-policy limiter class match + vif ` + +**IPv4** + +* Specify a match criterion based on **destination IPv4 address** and/or port, + port may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy limiter class + match ip destination ` + +* Specify a match criterion based on **source IPv4 address** and/or port, port + may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy limiter class + match ip source ` + +* Specify a match criterion based on **DSCP (Differentiated Services Code Point) + value**, DSCP value may be specified as decimal or hexadecimal number: + + :code:`set traffic-policy limiter class match + ip dscp ` + +* Specify a match criterion based on **IPv4 protocol**, protocol may be + specified by name (i.e. icmp) or IANA-assigned number: + + :code:`set traffic-policy limiter class match + ip protocol ` + +**IPv6** + +* Specify a match criterion based on **destination IPv6 address and/or port**, + port may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy limiter class match + ipv6 destination ` + +* Specify a match criterion based on **source IPv6 address and/or port**, port + may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy limiter class match + ipv6 source ` + +* Specify a match criterion based on **DSCP (Differentiated Services Code + Point) value**, DSCP value may be specified as decimal or hexadecimal number: + + :code:`set traffic-policy limiter class match + ipv6 dscp ` + +* Specify a match criterion based on **IPv6 protocol**, protocol may be + specified by name (i.e. icmp) or IANA-assigned number: + + :code:`set traffic-policy limiter class match + ipv6 protocol ` + +Network emulator +^^^^^^^^^^^^^^^^ + +The network emulator policy emulates WAN traffic, which is useful for testing +purposes. Applicable to outbound traffic only. + +Available commands: + +* Define a network emulator policy: + + :code:`set traffic-policy network-emulator ` + +* Add a description: + + :code:`set traffic-policy network-emulator description ` + +* Specify a bandwidth limit in kbit/s: + + :code:`set traffic-policy network-emulator bandwidth ` + + Available suffixes: + + * kbit (kilobits per second, default) + * mbit (megabits per second) + * gbit (gigabits per second) + * kbps (kilobytes per second) + * mbps (megabytes per second) + * gbps (gigabytes per second) + +* Set a burst size, the maximum amount of traffic that can be sent, in bytes: + + :code:`set traffic-policy network-emulator burst ` + + Available suffixes: + + * kb (kilobytes) + * mb (megabytes) + * gb (gigabytes) + +* Define a delay between packets: + + :code:`set traffic-policy network-emulator network-delay ` + + Available suffixes: + + * secs (seconds) + * ms (milliseconds, default) + * us (microseconds) + +* Set a percentage of corrupted of packets (one bit flip, unchanged checksum): + + :code:`set traffic-policy network-emulator packet-corruption + ` + +* Set a percentage of random packet loss: + + :code:`set traffic-policy network-emulator packet-loss ` + +* Set a percentage of packets for random reordering: + + :code:`set traffic-policy network-emulator packet-reordering + ` + +* Set a queue length limit in packets, range 0...4294967295, default 127: + + :code:`set traffic-policy network-emulator queue-limit ` + +Priority queue +^^^^^^^^^^^^^^ + +Up to seven queues with differing priorities can be defined, packets are placed +into queues based on associated match criteria. Packets are transmitted from +the queues in priority order. If queues with a higher order are being filled +with packets continuously, packets from lower priority queues will only be +transmitted after traffic volume from higher priority queues decreases. + +Available commands: + +* Define a priority queue: + + :code:`set traffic-policy priority-queue ` + +* Add a description: + + :code:`set traffic-policy priority-queue description ` + +Traffic classes +*************** + +* Define a traffic class, each class is a separate queue, range for class ID + is 1...7, while 1 being the lowest priority: + + :code:`set traffic-policy priority-queue class ` + +* Add a class description: + + :code:`set traffic-policy priority-queue class + description ` + +* Set a queue length limit in packets, default 1000: + + :code:`set traffic-policy priority-queue class + queue-limit ` + +* Specify a queue type for a traffic class, available queue types: + + * drop-tail + * fair-queue + * random-detect + + :code:`set traffic-policy priority-queue class + queue-type ` + +Default class +############# + +* Define a default priority queue: + + :code:`set traffic-policy priority-queue default` + +* Define a maximum queue length for the default traffic class in packets: + + :code:`set traffic-policy priority-queue default queue-limit + ` + +* Specify the queuing type for the default traffic class, available queue types: + + * drop-tail + * fair-queue + * random-detect + + :code:`set traffic-policy priority-queue default queue-type ` + +Matching rules +************** + +* Define a class matching rule: + + :code:`set traffic-policy priority-queue class match + ` + +* Add a match rule description: + + :code:`set traffic-policy priority-queue class match + description ` + +* Specify a match criterion based on a **destination MAC address** + (format: xx:xx:xx:xx:xx:xx): + + :code:`set traffic-policy priority-queue class match + ether destination ` + +* Specify a match criterion based on a **source MAC address** + (format: xx:xx:xx:xx:xx:xx): + + :code:`set traffic-policy priority-queue class match + ether source ` + +* Specify a match criterion based on **packet type/protocol**, range 0...65535: + + :code:`set traffic-policy priority-queue class match + ether protocol ` + +* Specify a match criterion based on **ingress interface**: + + :code:`set traffic-policy priority-queue class match + interface ` + +* Specify a match criterion based on the **fwmark field**, range 0....4294967295: + + :code:`set traffic-policy priority-queue class match + mark ` + +* Specify a match criterion based on **VLAN ID**, range 1...4096: + + :code:`set traffic-policy priority-queue class match + vif ` + +**IPv4** + +* Specify a match criterion based on **destination IPv4 address and/or port**, + port may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy priority-queue class match + ip destination ` + +* Specify a match criterion based on **source IPv4 address and/or port**, port + may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy priority-queue class match + ip source ` + +* Specify a match criterion based on **DSCP (Differentiated Services Code Point) + value**, DSCP value may be specified as decimal or hexadecimal number: + + :code:`set traffic-policy priority-queue class match + ip dscp ` + +* Specify a match criterion based on **IPv4 protocol**, protocol may be + specified by name (i.e. icmp) or IANA-assigned number: + + :code:`set traffic-policy priority-queue class match + ip protocol ` + +**IPv6** + +* Specify a match criterion based on **destination IPv6 address and/or port**, + port may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy priority-queue class match + ipv6 destination ` + +* Specify a match criterion based on **source IPv6 address and/or port**, port + may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy priority-queue class match + ipv6 source ` + +* Specify a match criterion based on **DSCP (Differentiated Services Code Point) + value**, DSCP value may be specified as decimal or hexadecimal number: + + :code:`set traffic-policy priority-queue class match + ipv6 dscp ` + +* Specify a match criterion based on **IPv6 protocol**, protocol may be + specified by name (i.e. icmp) or IANA-assigned number: + + :code:`set traffic-policy priority-queue class match + ipv6 protocol ` + +Random Early Detection (RED/WRED) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +RED +*** + +A Random Early Detection (RED) policy starts randomly dropping packets from a +queue before it reaches its queue limit thus avoiding congestion. It is also +beneficial for TCP connections as the gradual dropping of packets acts as a +signal for the sender to decrease its transmission rate, avoiding global TCP +synchronisation. Applicable to outbound traffic only. + +Available commands: + +* Define a RED policy: + + :code:`set traffic-policy random-detect ` + +* Add a description: + + :code:`set traffic-policy random-detect description ` + +* Set a bandwidth limit, default auto: + + :code:`set traffic-policy random-detect bandwidth ` + + Available suffixes: + + * auto (bandwidth limit based on interface speed, default) + * kbit (kilobits per second) + * mbit (megabits per second) + * gbit (gigabits per second) + * kbps (kilobytes per second) + * mbps (megabytes per second) + * gbps (gigabytes per second) + +WRED +**** + +In contrast to RED, Weighted Random Early Detection (WRED) differentiates +between classes of traffic in a single queue and assigns different precedence +to traffic flows accordingly; low priority packets are dropped from a queue +earlier than high priority packets. This is achieved by using the first three +bits of the ToS (Type of Service) field to categorise data streams and in +accordance with the defined precedence parameters a decision is made. A WRED +policy is defined with the following parameters: + +* precedence +* min-threshold +* max-threshold +* average-packet +* mark-probability +* queue-limit + +If the average queue size is lower than the :code:`min-threshold`, an arriving +packet is placed in the queue. If the average queue size is between +:code:`min-threshold` and :code:`max-threshold` an arriving packet is either +dropped or placed in the queue depending on the defined :code:`mark-probability`. +In case the average queue size is larger than :code:`max-threshold`, packets +are dropped. If the current queue size is larger than :code:`queue-limit`, +packets are dropped. The average queue size depends on its former average size +and its current size. If :code:`max-threshold` is set but :code:`min-threshold` +is not, then :code:`min-threshold` is scaled to 50% of :code:`max-threshold`. +In principle, values must be :code:`min-threshold` < :code:`max-threshold` < +:code:`queue-limit`. Applicable to outbound traffic only. + +Possible values for WRED parameters: + +* precedence - IP precedence, first three bits of the ToS field as defined in + RFC791_. + + +------------+----------------------+ + | Precedence | Priority | + +============+======================+ + | 7 | Network Control | + +------------+----------------------+ + | 6 | Internetwork Control | + +------------+----------------------+ + | 5 | CRITIC/ECP | + +------------+----------------------+ + | 4 | Flash Override | + +------------+----------------------+ + | 3 | Flash | + +------------+----------------------+ + | 2 | Immediate | + +------------+----------------------+ + | 1 | Priority | + +------------+----------------------+ + | 0 | Routine | + +------------+----------------------+ + +* min-threshold - Min value for the average queue length, packets are dropped + if the average queue length reaches this threshold. Range 0...4096, default + is dependent on precedence: + + +------------+-----------------------+ + | Precedence | default min-threshold | + +============+=======================+ + | 7 | 16 | + +------------+-----------------------+ + | 6 | 15 | + +------------+-----------------------+ + | 5 | 14 | + +------------+-----------------------+ + | 4 | 13 | + +------------+-----------------------+ + | 3 | 12 | + +------------+-----------------------+ + | 2 | 11 | + +------------+-----------------------+ + | 1 | 10 | + +------------+-----------------------+ + | 0 | 9 | + +------------+-----------------------+ + +* max-threshold - Max value for the average queue length, packets are dropped + if this value is exceeded. Range 0...4096 packets, default 18. + +* average-packet - Average packet size in bytes, default 1024. + +* mark-probability - The fraction of packets (n/probability) dropped from the + queue when the average queue length reaches max-threshold, + default 10. + +* queue-limit - Packets are dropped when the current queue length reaches this + value, default 4*max-threshold. + +Usage: + +:code:`set traffic-policy random-detect precedence + [average-packet | mark-probability | +max-threshold | min-threshold | queue-limit ]` + +Rate control (TBF) +^^^^^^^^^^^^^^^^^^ + +The rate control policy uses the Token Bucket Filter (TBF_) algorithm to limit +the packet flow to a set rate. Short bursts can be allowed to exceed the limit. +Applicable to outbound traffic only. + +Available commands: + +* Define a rate control policy: + + :code:`set traffic-policy rate-control ` + +* Add a description: + + :code:`set traffic-policy rate-control description ` + +* Specify a bandwidth limit in kbits/s: + + :code:`set traffic-policy rate-control bandwidth ` + + Available suffixes: + + * kbit (kilobits per second, default) + * mbit (megabits per second) + * gbit (gigabits per second) + * kbps (kilobytes per second) + * mbps (megabytes per second) + * gbps (gigabytes per second) + +* Specify a burst size in bytes, default 15 kilobytes: + + :code:`set traffic-policy rate-control burst ` + + Available suffixes: + + * kb (kilobytes) + * mb (megabytes) + * gb (gigabytes) + +* Specify a latency in milliseconds; the maximum amount of time packets are + allowed to wait in the queue, default 50 milliseconds: + + :code:`set traffic-policy rate-control latency` + + Available suffixes: + + * secs (seconds) + * ms (milliseconds, default) + * us (microseconds) + +Round robin (DRR) +^^^^^^^^^^^^^^^^^ + +The round robin policy divides available bandwidth between all defined traffic +classes. + +Available commands: + +* Define a round robin policy: + + :code:`set traffic-policy round-robin ` + +* Add a description: + + :code:`set traffic-policy round-robin description ` + +* Define a traffic class ID, range 2...4095: + + :code:`set traffic-policy round-robin class ` + +**Default policy:** + +* Define a default priority queue: + + :code:`set traffic-policy round-robin default` + +* Set the number of packets that can be sent per scheduling quantum: + + :code:`set traffic-policy round-robin default quantum ` + +* Define a maximum queue lenght for the default policy in packets: + + :code:`set traffic-policy round-robin default queue-limit ` + +* Specify the queuing type for the default policy, available queue types: + + * drop-tail + * fair-queue + * priority (based on the DSCP values in the ToS byte) + + :code:`set traffic-policy round-robin default queue-type ` + +Matching rules +************** + +* Define a class matching rule: + + :code:`set traffic-policy round-robin class match + ` + +* Add a match rule description: + + :code:`set traffic-policy round-robin class match + description ` + +* Specify a match criterion based on a **destination MAC address** (format: + xx:xx:xx:xx:xx:xx): + + :code:`set traffic-policy round-robin class match + ether destination ` + +* Specify a match criterion based on a **source MAC address** (format: + xx:xx:xx:xx:xx:xx): + + :code:`set traffic-policy round-robin class match + ether source ` + +* Specify a match criterion based on **packet type/protocol**, range 0...65535: + + :code:`set traffic-policy round-robin class match + ether protocol ` + +* Specify a match criterion based on **ingress interface**: + + :code:`set traffic-policy round-robin class match + interface ` + +* Specify a match criterion based on the **fwmark field**, range 0....4294967295: + + :code:`set traffic-policy round-robin class match + mark ` + +* Specify a match criterion based on **VLAN ID**, range 1...4096: + + :code:`set traffic-policy round-robin class match + vif *` + +**IPv4** + +* Specify a match criterion based on **destination IPv4 address and/or port**, + port may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy round-robin class match + ip destination ` + +* Specify a match criterion based on **source IPv4 address and/or port**, port + may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy round-robin class match + ip source ` + +* Specify a match criterion based on **DSCP (Differentiated Services Code Point) + value**, DSCP value may be specified as decimal or hexadecimal number: + + :code:`set traffic-policy round-robin class match + ip dscp ` + +* Specify a match criterion based on **IPv4 protocol**, protocol may be + specified by name (i.e. icmp) or IANA-assigned number: + + :code:`set traffic-policy round-robin class match + ip protocol ` + +**IPv6** + +* Specify a match criterion based on **destination IPv6 address and/or port**, + port may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy round-robin class match + ipv6 destination ` + +* Specify a match criterion based on **source IPv6 address and/or port**, port + may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy round-robin class match + ipv6 source ` + +* Specify a match criterion based on **DSCP (Differentiated Services Code Point) + value**, DSCP value may be specified as decimal or hexadecimal number: + + :code:`set traffic-policy round-robin class match + ipv6 dscp ` + +* Specify a match criterion based on **IPv6 protocol**, protocol may be + specified by name (i.e. icmp) or IANA-assigned number: + + :code:`set traffic-policy round-robin class match + ipv6 protocol ` + +Traffic shaper +^^^^^^^^^^^^^^ + +The shaper policy uses the Hierarchical Token Bucket algorithm to allocate +different amounts of bandwidth to different traffic classes. In contrast to +round robin, shaper limits bandwidth allocation by traffic class whereas round +robin divides the total available bandwidth between classes. + +Avialable commands: + +* Define a shaper policy: + + :code:`set traffic-policy shaper ` + +* Add a description: + + :code:`set traffic-policy shaper description ` + +* Set the available bandwidth for all combined traffic of this policy in kbit/s, + default 100%: + + :code:`set traffic-policy shaper bandwidth ` + + Available suffixes: + + * % (percentage of total bandwidth) + * kbit (kilobits per second) + * mbit (megabits per second) + * gbit (gigabits per second) + * kbps (kilobytes per second) + * mbps (megabytes per second) + * gbps (gigabytes per second) + +Traffic classes +*************** + +* Define a traffic class for a shaper policy, range for class ID is 2...4095: + + :code:`set traffic-policy shaper class ` + +* Add a class description: + + :code:`set traffic-policy shaper class description + ` + +* Specify a bandwidth limit for a class, in kbit/s: + + :code:`set traffic-policy shaper class bandwidth ` + + Available suffixes: + + * kbit (kilobits per second, default) + * mbit (megabits per second) + * gbit (gigabits per second) + * kbps (kilobytes per second) + * mbps (megabytes per second) + * gbps (gigabytes per second) + +* Set a burst size for a class, the maximum amount of traffic that can be sent, + in bytes: + + :code:`set traffic-policy shaper class + burst ` + + Available suffixes: + + * kb (kilobytes) + * mb (megabytes) + * gb (gigabytes) + +* Set a bandwidth ceiling for a class in kbit/s: + + :code:`set traffic-policy shaper class ceiling ` + + Available suffixes: + + * % (percentage of total bandwidth) + * kbit (kilobits per second) + * mbit (megabits per second) + * gbit (gigabits per second) + +* Set the priority of a class for allocation of additional bandwidth, if unused + bandwidth is available. Range 0...7, lowest number has lowest priority, + default 0: + + :code:`set traffic-policy shaper class + priority ` + +* Set a queue length limit in packets: + + :code:`set traffic-policy shaper class queue-limit + ` + +* Specify a queue type for a traffic class, default fair-queue. Available + queue types: + + * drop-tail + * fair-queue + * random-detect + * priority + + :code:`set traffic-policy shaper class queue-type ` + +* Modify DSCP field; the DSCP field value of packets in a class can be + rewritten to change the forwarding behaviour and allow for traffic + conditioning: + + :code:`set traffic-policy shaper class set-dscp ` + + DSCP values as per RFC2474_ and RFC4595_: + + +---------+------------+--------+------------------------------+ + | Binary | Configured | Drop | Description | + | value | value | rate | | + +=========+============+========+==============================+ + | 101110 | 46 | - | Expedited forwarding (EF) | + +---------+------------+--------+------------------------------+ + | 000000 | 0 | - | Best effort traffic, default | + +---------+------------+--------+------------------------------+ + | 001010 | 10 | Low | Assured Forwarding(AF) 11 | + +---------+------------+--------+------------------------------+ + | 001100 | 12 | Medium | Assured Forwarding(AF) 12 | + +---------+------------+--------+------------------------------+ + | 001110 | 14 | High | Assured Forwarding(AF) 13 | + +---------+------------+--------+------------------------------+ + | 010010 | 18 | Low | Assured Forwarding(AF) 21 | + +---------+------------+--------+------------------------------+ + | 010100 | 20 | Medium | Assured Forwarding(AF) 22 | + +---------+------------+--------+------------------------------+ + | 010110 | 22 | High | Assured Forwarding(AF) 23 | + +---------+------------+--------+------------------------------+ + | 011010 | 26 | Low | Assured Forwarding(AF) 31 | + +---------+------------+--------+------------------------------+ + | 011100 | 28 | Medium | Assured Forwarding(AF) 32 | + +---------+------------+--------+------------------------------+ + | 011110 | 30 | High | Assured Forwarding(AF) 33 | + +---------+------------+--------+------------------------------+ + | 100010 | 34 | Low | Assured Forwarding(AF) 41 | + +---------+------------+--------+------------------------------+ + | 100100 | 36 | Medium | Assured Forwarding(AF) 42 | + +---------+------------+--------+------------------------------+ + | 100110 | 38 | High | Assured Forwarding(AF) 43 | + +---------+------------+--------+------------------------------+ + +Matching rules +************** + +* Define a class matching rule: + + :code:`set traffic-policy shaper class match + ` + +* Add a match rule description: + + :code:`set traffic-policy shaper class match + description ` + +* Specify a match criterion based on a **destination MAC address** + (format: xx:xx:xx:xx:xx:xx): + + :code:`set traffic-policy shaper class match + ether destination ` + +* Specify a match criterion based on a **source MAC address** + (format: xx:xx:xx:xx:xx:xx): + + :code:`set traffic-policy shaper class match + ether source ` + +* Specify a match criterion based on **packet type/protocol**, range 0...65535: + + :code:`set traffic-policy shaper class match + ether protocol ` + +* Specify a match criterion based on **ingress interface**: + + :code:`set traffic-policy shaper class match + interface ` + +* Specify a match criterion based on the **fwmark field**, range 0....4294967295: + + :code:`set traffic-policy shaper class match + mark ` + +* Specify a match criterion based on **VLAN ID**, range 1...4096: + + :code:`set traffic-policy round-robin class match + vif ` + +**IPv4** + +* Specify a match criterion based on **destination IPv4 address and/or port**, + port may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy shaper class match + ip destination ` + +* Specify a match criterion based on **source IPv4 address and/or port**, port + may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy shaper class match + ip source ` + +* Specify a match criterion based on **DSCP (Differentiated Services Code Point) + value**, DSCP value may be specified as decimal or hexadecimal number: + + :code:`set traffic-policy shaper class match + ip dscp ` + +* Specify a match criterion based on **IPv4 protocol**, protocol may be + specified by name (i.e. icmp) or IANA-assigned number: + + :code:`set traffic-policy shaper class match + ip protocol ` + +**IPv6** + +* Specify a match criterion based on **destination IPv6 address and/or port**, + port may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy shaper class match + ipv6 destination ` + +* Specify a match criterion based on **source IPv6 address and/or port**, + port may be specified as number or service name (i.e. ssh): + + :code:`set traffic-policy shaper class match + ipv6 source ` + +* Specify a match criterion based on **DSCP (Differentiated Services Code Point) + value**, DSCP value may be specified as decimal or hexadecimal number: + + :code:`set traffic-policy shaper class match + ipv6 dscp ` + +* Specify a match criterion based on **IPv6 protocol**, protocol may be + specified by name (i.e. icmp) or IANA-assigned number: + + :code:`set traffic-policy shaper class match + ipv6 protocol ` + +shaper-hfsc (HFSC_ + sfq) +^^^^^^^^^^^^^^^^^^^^^^^^^ + +TBD + +Ingress shaping +--------------- + +The case of ingress shaping. Only a **limiter** policy can be applied directly +for ingress traffic on an interface. It is possible though to use what is +called an Intermediate Functional Block (IFB_) to allow the usage of any policy +on the ingress traffic. + +Let's assume eth0 is your WAN link. You created two traffic-policies: `WAN-IN` +and `WAN-OUT`. + +Steps to do: + +* First, create the IFB: + + :code:`set interfaces input ifb0 description "WAN Input"` + +* Apply the `WAN-OUT` traffic-policy to ifb0 input. + + :code:`set interfaces input ifb0 traffic-policy in WAN-IN` + +* Redirect traffic from eth0 to ifb0 + + :code:`set interfaces ethernet eth0 redirect ifb0` + +Classful policies and traffic matching +-------------------------------------- + +`limiter`, `round-robin`, `priority-queue`, `shaper` and `shaper-hfsc` +distribute traffic into different classes with different options. In VyOS, +classes are numbered and work like firewall rules. e.g: + +:code:`set traffic-policy shaper SHAPER class 30` + +Matching traffic +^^^^^^^^^^^^^^^^ + +A class can have multiple match filters: + +.. code-block:: sh + + set traffic-policy class N match MATCH-FILTER-NAME + +Example: + +.. code-block:: sh + + set traffic-policy shaper SHAPER class 30 match HTTP + set traffic-policy shaper SHAPER class 30 match HTTPs + +A match filter contains multiple criteria and will match traffic if all those criteria are true. + +For example: + +.. code-block:: sh + + set traffic-policy shaper SHAPER class 30 match HTTP ip protocol tcp + set traffic-policy shaper SHAPER class 30 match HTTP ip source port 80 + +This will match tcp traffic with source port 80. + +description +*********** + +.. code-block:: sh + + set traffic-policy shaper SHAPER class 30 match MATCH description "match filter description" + +ether +***** + +.. code-block:: sh + + edit traffic-policy shaper SHAPER class 30 match MATCH ether + +destination +########### + +protocol +######## + +source +###### + +interface +********* + +.. code-block:: sh + + edit traffic-policy shaper SHAPER class 30 match MATCH interface + +ip +** +.. code-block:: sh + + edit traffic-policy shaper SHAPER class 30 match MATCH ip + +destination +########### + +.. code-block:: sh + + set destination address IPv4-SUBNET + set destination port U32-PORT + +dscp +#### + +.. code-block:: sh + + set dscp DSCPVALUE + +max-length +########## + +.. code-block:: sh + + set max-length U32-MAXLEN + +Will match ipv4 packets with a total length lesser than set value. + +protocol +######## + +.. code-block:: sh + + set protocol + +source +###### + +.. code-block:: sh + + set source address IPv4-SUBNET + set source port U32-PORT + +tcp +### + +.. note:: You must set ip protocol to TCP to use the TCP filters. + +.. note:: This filter will only match packets with an IPv4 header length of + 20 bytes (which is the majority of IPv4 packets anyway). + +.. code-block:: sh + + set tcp ack + +Will match tcp packets with ACK flag set. + +.. code-block:: sh + + set tcp syn + +Will match tcp packets with SYN flag set. + +ipv6 +**** + +.. code-block:: sh + + edit traffic-policy shaper SHAPER class 30 match MATCH ipv6 + +destination +########### + + .. code-block:: sh + + set destination address IPv6-SUBNET + set destination port U32-PORT + +dscp +#### + +.. code-block:: sh + + set dscp DSCPVALUE + +max-length +########## + +.. code-block:: sh + + set max-length U32-MAXLEN + +Will match ipv6 packets with a payload length lesser than set value. + +protocol +######## + +.. code-block:: sh + + set protocol IPPROTOCOL + +source +###### + +.. code-block:: sh + + set source address IPv6-SUBNET + set source port U32-PORT + +tcp +### + +.. note:: You must set ipv6 protocol to TCP to use the TCP filters. + +.. note:: This filter will only match IPv6 packets with no header extension, see + http://en.wikipedia.org/wiki/IPv6_packet#Extension_headers for no header + extension. + +.. code-block:: sh + + set tcp ack + +Will match tcp packets with ACK flag set. + +.. code-block:: sh + + set tcp syn + +Will match tcp packets with SYN flag set. + +mark +**** + +.. code-block:: sh + + set traffic-policy shaper SHAPER class 30 match MATCH mark **firewall-mark** + +vif +*** + +.. code-block:: sh + + set traffic-policy shaper SHAPER class 30 match MATCH vif **vlan-tag** + +.. code-block:: sh + + set interfaces ethernet eth0 traffic-policy out 'WAN-OUT' + set interfaces ethernet eth1 traffic-policy out 'LAN-OUT' + +.. _tc: http://en.wikipedia.org/wiki/Tc_(Linux) +.. _RFC791: https://tools.ietf.org/html/rfc791 +.. _TBF: https://en.wikipedia.org/wiki/Token_bucket +.. _RFC2474: https://tools.ietf.org/html/rfc2474#page-7 +.. _RFC4595: https://tools.ietf.org/html/rfc4594#page-19 +.. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve +.. _IFB: http://www.linuxfoundation.org/collaborate/workgroups/networking/ifb diff --git a/docs/quick-start.rst b/docs/quick-start.rst new file mode 100644 index 00000000..b4905f2a --- /dev/null +++ b/docs/quick-start.rst @@ -0,0 +1,166 @@ +.. _quick-start: + +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: + +.. code-block:: sh + + vyos@vyos$ configure + vyos@vyos# + +Configure network interfaces: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + set service ssh port '22' + +Configure Source NAT for our "Inside" network. + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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: + +Please note that the `listen-on` statement is deprecated. Please use +`listen-address` instead! + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + vyos@vyos# commit + vyos@vyos# save + Saving configuration to '/config/config.boot'... + Done + vyos@vyos# exit + vyos@vyos$ + +Basic QoS +--------- + +The traffic policy subsystem provides an interface to Linux traffic control +(tc_). + +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 200 Mbit download +and out WAN connection to 50 Mbit upload: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + set interfaces ethernet eth0 traffic-policy out 'WAN-OUT' + set interfaces ethernet eth1 traffic-policy out 'LAN-OUT' + +.. note:: A traffic policy can also be defined to match specific traffic + flows using class statements. + +VyOS 1.2 (Crux) also supports HFSC (:code:`set traffic-policy shaper-hfsc`) + +See further information in the `QoS and Traffic Policy`_ chapter. + +.. _tc: http://en.wikipedia.org/wiki/Tc_(Linux) diff --git a/docs/routing.rst b/docs/routing.rst new file mode 100644 index 00000000..e570671d --- /dev/null +++ b/docs/routing.rst @@ -0,0 +1,308 @@ +.. _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). + +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: + +.. code-block:: sh + + set protocols static route 0.0.0.0/0 next-hop 10.1.1.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. + +.. code-block:: sh + + 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' + +.. note:: 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:** + +.. code-block:: sh + + set interfaces loopback address 10.1.1.1/32 + set protocols rip network 192.168.0.0/24 + set protocols rip redistribute connected + +**Node 2:** + +.. code-block:: sh + + set interfaces loopback address 10.2.2.2/32 + set protocols rip network 192.168.0.0/24 + set protocols rip redistribute connected + +OSPF +---- + +IPv4 +^^^^ + +A typical configuration using 2 nodes, redistribute loopback address and the +node 1 sending the default route: + +**Node 1:** + +.. code-block:: sh + + set interfaces loopback lo address 10.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 10.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:** + +.. code-block:: sh + + set interfaces loopback lo address 10.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 10.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 + +IPv6 +^^^^ + +A typical configuration using 2 nodes. + +**Node 1:** + +.. code-block:: sh + + 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:** + +.. code-block:: sh + + 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 + +BGP +--- + +IPv4 +^^^^ + +A simple eBGP configuration: + +**Node 1:** + +.. code-block:: sh + + set protocols bgp 65534 neighbor 192.168.0.2 ebgp-multihop '2' + set protocols bgp 65534 neighbor 192.168.0.2 remote-as '65535' + set protocols bgp 65534 neighbor 192.168.0.2 update-source '192.168.0.1' + set protocols bgp 65534 network '172.16.0.0/16' + set protocols bgp 65534 parameters router-id '192.168.0.1' + +**Node 2:** + +.. code-block:: sh + + set protocols bgp 65535 neighbor 192.168.0.1 ebgp-multihop '2' + set protocols bgp 65535 neighbor 192.168.0.1 remote-as '65534' + set protocols bgp 65535 neighbor 192.168.0.1 update-source '192.168.0.2' + set protocols bgp 65535 network '172.17.0.0/16' + set protocols bgp 65535 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:** + +.. code-block:: sh + + set protocols static route 1.0.0.0/16 blackhole distance '254' + +**Node 2:** + +.. code-block:: sh + + set protocols static route 2.0.0.0/16 blackhole distance '254' + + +IPv6 +^^^^ + +A simple BGP configuration via IPv6. + +**Node 1:** + +.. code-block:: sh + + set protocols bgp 65534 neighbor 2001:db8::2 ebgp-multihop '2' + set protocols bgp 65534 neighbor 2001:db8::2 remote-as '65535' + set protocols bgp 65534 neighbor 2001:db8::2 update-source '2001:db8::1' + set protocols bgp 65534 neighbor 2001:db8::2 address-family ipv6-unicast + set protocols bgp 65534 address-family ipv6-unicast network '2001:db8:1::/48' + set protocols bgp 65534 parameters router-id '10.1.1.1' + +**Node 2:** + +.. code-block:: sh + + set protocols bgp 65535 neighbor 2001:db8::1 ebgp-multihop '2' + set protocols bgp 65535 neighbor 2001:db8::1 remote-as '65534' + set protocols bgp 65535 neighbor 2001:db8::1 update-source '2001:db8::2' + set protocols bgp 65535 neighbor 2001:db8::1 address-family ipv6-unicast + set protocols bgp 65535 address-family ipv6-unicast network '2001:db8:2::/48' + set protocols bgp 65535 parameters router-id '10.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:** + +.. code-block:: sh + + set protocols static route6 2a001:100:1::/48 blackhole distance '254' + +**Node 2:** + +.. code-block:: sh + + set protocols static route6 2001:db8:2::/48 blackhole distance '254' + +Route Filter +^^^^^^^^^^^^ + +Route filter can be applied using a route-map: + +**Node1:** + +.. code-block:: sh + + set policy prefix-list AS65535-IN rule 10 action 'permit' + set policy prefix-list AS65535-IN rule 10 prefix '172.16.0.0/16' + set policy prefix-list AS65535-OUT rule 10 action 'deny' + set policy prefix-list AS65535-OUT rule 10 prefix '172.16.0.0/16' + set policy prefix-list6 AS65535-IN rule 10 action 'permit' + set policy prefix-list6 AS65535-IN rule 10 prefix '2001:db8:2::/48' + set policy prefix-list6 AS65535-OUT rule 10 action 'deny' + set policy prefix-list6 AS65535-OUT rule 10 prefix '2001:db8:2::/48' + set policy route-map AS65535-IN rule 10 action 'permit' + set policy route-map AS65535-IN rule 10 match ip address prefix-list 'AS65535-IN' + set policy route-map AS65535-IN rule 10 match ipv6 address prefix-list 'AS65535-IN' + set policy route-map AS65535-IN rule 20 action 'deny' + set policy route-map AS65535-OUT rule 10 action 'deny' + set policy route-map AS65535-OUT rule 10 match ip address prefix-list 'AS65535-OUT' + set policy route-map AS65535-OUT rule 10 match ipv6 address prefix-list 'AS65535-OUT' + set policy route-map AS65535-OUT rule 20 action 'permit' + set protocols bgp 65534 neighbor 2001:db8::2 route-map export 'AS65535-OUT' + set protocols bgp 65534 neighbor 2001:db8::2 route-map import 'AS65535-IN' + +**Node2:** + +.. code-block:: sh + + set policy prefix-list AS65534-IN rule 10 action 'permit' + set policy prefix-list AS65534-IN rule 10 prefix '172.17.0.0/16' + set policy prefix-list AS65534-OUT rule 10 action 'deny' + set policy prefix-list AS65534-OUT rule 10 prefix '172.17.0.0/16' + set policy prefix-list6 AS65534-IN rule 10 action 'permit' + set policy prefix-list6 AS65534-IN rule 10 prefix '2001:db8:1::/48' + set policy prefix-list6 AS65534-OUT rule 10 action 'deny' + set policy prefix-list6 AS65534-OUT rule 10 prefix '2001:db8:1::/48' + set policy route-map AS65534-IN rule 10 action 'permit' + set policy route-map AS65534-IN rule 10 match ip address prefix-list 'AS65534-IN' + set policy route-map AS65534-IN rule 10 match ipv6 address prefix-list 'AS65534-IN' + set policy route-map AS65534-IN rule 20 action 'deny' + set policy route-map AS65534-OUT rule 10 action 'deny' + set policy route-map AS65534-OUT rule 10 match ip address prefix-list 'AS65534-OUT' + set policy route-map AS65534-OUT rule 10 match ipv6 address prefix-list 'AS65534-OUT' + set policy route-map AS65534-OUT rule 20 action 'permit' + set protocols bgp 65535 neighbor 2001:db8::1 route-map export 'AS65534-OUT' + set protocols bgp 65535 neighbor 2001:db8::1 route-map import 'AS65534-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: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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 rule `set tcp-mss ` directive, +modify DSCP value using `set dscp `, or mark the traffic with an +internal ID using `set mark ` 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. diff --git a/docs/services.rst b/docs/services.rst new file mode 100644 index 00000000..f66cc343 --- /dev/null +++ b/docs/services.rst @@ -0,0 +1,876 @@ +.. _services: + +Services +======== + +DHCP +---- + +Multiple DHCP Servers can be run from a single machine. Each DHCP service is +identified by a `shared-network-name`. + +DHCP Server Example +^^^^^^^^^^^^^^^^^^^ + +In this example, we are offering address space in the 172.16.17.0/24 network, +which is on eth1, and pppoe0 is our connection to the internet. We are using +the network name `dhcpexample`. + +Prerequisites +^^^^^^^^^^^^^ + +Configuring the PPPoE interface is assumed to be done already, and appears +on `pppoe0` + +Interface Configuration +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: sh + + set interface eth1 address 172.16.17.1/24 + +Multiple ranges can be defined and can contain holes. + +.. code-block:: sh + + set service dhcp-server shared-network-name dhcpexample authoritative + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 default-router 172.16.17.1 + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 dns-server 172.16.17.1 + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 lease 86400 + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 start 172.16.17.100 + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 stop 172.16.17.199 + +Failover +^^^^^^^^ + +VyOS provides support for DHCP failover: + +.. code-block:: sh + + 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 + +.. code-block:: sh + + set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'primary' + +or + +.. code-block:: sh + + set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'secondary' + +.. note:: In order for the primary and the secondary DHCP server to keep + their lease tables in sync, they must be able to reach each other on TCP + port 647. If you have firewall rules in effect, adjust them accordingly. + +Static mappings MAC/IP +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: sh + + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 static-mapping static-mapping-01 ip-address 172.16.17.10 + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 static-mapping static-mapping-01 mac-address ff:ff:ff:ff:ff:ff + +Explanation +^^^^^^^^^^^ + +:code:`set service dhcp-server shared-network-name dhcpexample authoritative` +This says that this device is the only DHCP server for this network. If other +devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to +any device trying to request an IP address that is not valid for this network. + +:code:`set service dhcp-server shared-network-name dhcpexample subnet +172.16.17.0/24 default-router 172.16.17.1` This is a configuration parameter +for the subnet, saying that as part of the response, tell the client that I am +the default router for this network + +:code:`set service dhcp-server shared-network-name dhcpexample subnet +172.16.17.0/24 dns-server 172.16.17.1` This is a configuration parameter for +the subnet, saying that as part of the response, tell the client that I am the +DNS server for this network. If you do not want to run a DNS server, you could +also provide one of the public DNS servers, such as google's. You can add +multiple entries by repeating the line. + +:code:`set service dhcp-server shared-network-name dhcpexample subnet +172.16.17.0/24 lease 86400` Assign the IP address to this machine for 24 +hours. It is unlikely you'd need to shorten this period, unless you are running +a network with lots of devices appearing and disappearing. + +:code:`set service dhcp-server shared-network-name dhcpexample subnet +172.16.17.0/24 start 172.16.17.100 stop 172.16.17.199` Make the IP Addresses +between .100 and .199 available for clients. + +DHCPv6 server +------------- + +VyOS provides DHCPv6 server functionality which is described in this section. +In order to use the DHCPv6 server it has to be enabled first: + +.. code-block:: sh + + set service dhcpv6-server + +To restart the DHCPv6 server (operational mode): + +.. code-block:: sh + + restart dhcpv6 server + +To show the current status of the DHCPv6 server use: + +.. code-block:: sh + + show dhcpv6 server status + +Show statuses of all assigned leases: + +.. code-block:: sh + + show dhcpv6 server leases + +DHCPv6 server options +^^^^^^^^^^^^^^^^^^^^^ + +DHCPv6 server preference value +****************************** + +Clients receiving advertise messages from multiple servers choose the server +with the highest preference value. The range for this value is `0...255`. Set +a preference value for the DHCPv6 server: + +.. code-block:: sh + + set service dhcpv6-server preference + +Delete a preference: + +.. code-block:: sh + + set service dhcpv6-server preference + +Show current preference: + +.. code-block:: sh + + show service dhcpv6-server preference + +Specify address lease time +************************** + +The default lease time for DHCPv6 leases is 24 hours. This can be changed by +supplying a `default-time`, `maximum-time` and `minimum-time` (all values in +seconds): + +.. code-block:: sh + + set service dhcpv6-server shared-network-name subnet lease-time {default | maximum | minimum } + +Reset the custom lease times: + +.. code-block:: sh + + delete service dhcpv6-server shared-network-name subnet lease-time {default | maximum | minimum} + +Show the current configuration: + +.. code-block:: sh + + show service dhcpv6-server shared-network-name subnet lease-time {default | maximum | minimum} + +Specify NIS domain +****************** + +A Network Information (NIS) domain can be set to be used for DHCPv6 clients: + +.. code-block:: sh + + set service dhcpv6-server shared-network-name subnet nis-domain + +To Delete the NIS domain: + +.. code-block:: sh + + delete service dhcpv6-server shared-network-name subnet nis-domain + +Show a configured NIS domain: + +.. code-block:: sh + + show service dhcpv6-server shared-network-name subnet nis-domain + +Specify NIS+ domain +******************* + +The procedure to specify a Network Information Service Plus (NIS+) domain is +similar to the NIS domain one: + +.. code-block:: sh + + set service dhcpv6-server shared-network-name subnet nisplus-domain + +To Delete the NIS+ domain: + +.. code-block:: sh + + delete service dhcpv6-server shared-network-name subnet nisplus-domain + +Show a configured NIS domain: + + # show service dhcpv6-server shared-network-name subnet nisplus-domain + +Specify NIS server address +************************** + +To specify a NIS server address for DHCPv6 clients: + +.. code-block:: sh + + set service dhcpv6-server shared-network-name subnet nis-server + +Delete a specified NIS server address: + +.. code-block:: sh + + delete service dhcpv6-server shared-network-name subnet nis-server + +Show specified NIS server addresses: + +.. code-block:: sh + + show service dhcpv6-server shared-network-name subnet nis-server + +Specify NIS+ server address +*************************** + +To specify a NIS+ server address for DHCPv6 clients: + +.. code-block:: sh + + set service dhcpv6-server shared-network-name subnet nisplus-server + +Delete a specified NIS+ server address: + +.. code-block:: sh + + delete service dhcpv6-server shared-network-name subnet nisplus-server + +Show specified NIS+ server addresses: + +.. code-block:: sh + + show service dhcpv6-server shared-network-name subnet nisplus-server + +Specify a SIP server address for DHCPv6 clients +*********************************************** + +By IPv6 address +############### + + +A Session Initiation Protocol (SIP) server address can be specified for DHCPv6 clients: + +.. code-block:: sh + + set service dhcpv6-server shared-network-name subnet sip-server-address + +Delete a specified SIP server address: + +.. code-block:: sh + + delete service dhcpv6-server shared-network-name subnet sip-server-address + +Show specified SIP server addresses: + +.. code-block:: sh + + show service dhcpv6-server shared-network-name subnet sip-server-address + +By FQDN +####### + +A name for SIP server can be specified: + +.. code-block:: sh + + set service dhcpv6-server shared-network-name subnet sip-server-name + +Delete a specified SIP server name: + +.. code-block:: sh + + delete service dhcpv6-server shared-network-name subnet sip-server-name + +Show specified SIP server names: + +.. code-block:: sh + + show service dhcpv6-server shared-network-name subnet sip-server-name + +Simple Network Time Protocol (SNTP) server address for DHCPv6 clients +********************************************************************* + +A SNTP server address can be specified for DHCPv6 clients: + +.. code-block:: sh + + set service dhcpv6-server shared-network-name subnet sntp-server-address + +Delete a specified SNTP server address: + +.. code-block:: sh + + delete service dhcpv6-server shared-network-name subnet sntp-server-address + +Show specified SNTP server addresses: + +.. code-block:: sh + + show service dhcpv6-server shared-network-name subnet sntp-server-address + +DHCPv6 address pools +^^^^^^^^^^^^^^^^^^^^ + +DHCPv6 address pools must be configured for the system to act as a DHCPv6 +server. The following example describes a common scenario. + +Example 1: DHCPv6 address pool +****************************** + +A shared network named `NET1` serves subnet `2001:db8:100::/64` which is +connected to `eth1`, a DNS server at `2001:db8:111::111` is used for name +services. The range of the address pool shall be `::100` through `::199`. The +lease time will be left at the default value which is 24 hours. + +.. code-block:: sh + + set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 address-range start 2001:db8:100::100 stop 2001:db8:100::199 + set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 name-server 2001:db8:111::111 + +Commit the changes and show the configuration: + +.. code-block:: sh + + commit + show service dhcpv6-server + shared-network-name NET1 { + subnet 2001:db8:100::/64 { + address-range { + start 2001:db8:100::100 { + stop 2001:db8:100::199 + } + } + name-server 2001:db8:111::111 + } + } + +Static mappings +^^^^^^^^^^^^^^^ + +In order to map specific IPv6 addresses to specific hosts static mappings can +be created. The following example explains the process. + +Example 1: Static IPv6 MAC-based mapping +**************************************** + +IPv6 address `2001:db8:100::101` shall be statically mapped to a device with +MAC address `00:15:c5:b7:5e:23`, this host-specific mapping shall be named +`client1`. + +.. note:: The MAC address identifier is defined by the last 4 byte of the + MAC address. + +.. code-block:: sh + + set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 static-mapping client1 ipv6-address 2001:db8:100::101 + set service dhcpv6-server shared-network-name NET1 subnet 2001:db8:100::/64 static-mapping client1 identifier c5b75e23 + +Commit the changes and show the configuration: + +.. code-block:: sh + + show service dhcp-server shared-network-name NET1 + shared-network-name NET1 { + subnet 2001:db8:100::/64 { + name-server 2001:db8:111::111 + address-range { + start 2001:db8:100::100 { + stop 2001:db8:100::199 { + } + } + static-mapping client1 { + ipv6-address 2001:db8:100::101 + identifier c5b75e23 + } + } + } + + +DHCP Relay +---------- + +If you want your router to forward DHCP requests to an external DHCP server +you can configure the system to act as a DHCP relay agent. The DHCP relay +agent works with IPv4 and IPv6 addresses. + +All interfaces used for the DHCP relay must be configured. See +https://wiki.vyos.net/wiki/Network_address_setup. + +DHCP relay example +^^^^^^^^^^^^^^^^^^ + +.. figure:: _static/images/service_dhcp-relay01.png + :scale: 80 % + :alt: DHCP relay example + + DHCP relay example + +In this example the interfaces used for the DHCP relay are eth1 and eth2. The +router receives DHCP client requests on eth1 and relays them through eth2 to +the DHCP server at 10.0.1.4. + +Configuration +^^^^^^^^^^^^^ + +Enable DHCP relay for eth1 and eth2: + +.. code-block:: sh + + set service dhcp-relay interface eth1 + set service dhcp-relay interface eth2 + +Set the IP address of the DHCP server: + +.. code-block:: sh + + set service dhcp-relay server 10.0.1.4 + +The router should discard DHCP packages already containing relay agent +information to ensure that only requests from DHCP clients are forwarded: + +.. code-block:: sh + + set service dhcp-relay relay-options relay-agents-packets discard + +Commit the changes and show the results: + +.. code-block:: sh + + commit + show service dhcp-relay + interface eth1 + interface eth2 + server 10.0.1.4 + relay-options { + relay-agents-packets discard + } + +The DHCP relay agent can be restarted with: + +.. code-block:: sh + + restart dhcp relay-agent + +DHCPv6 relay example +^^^^^^^^^^^^^^^^^^^^ + +.. figure:: _static/images/service_dhcpv6-relay01.png + :scale: 80 % + :alt: DHCPv6 relay example + + DHCPv6 relay example + +In this example DHCPv6 requests are received by the router on eth1 (`listening +interface`) and forwarded through eth2 (`upstream interface`) to the external +DHCPv6 server at 2001:db8:100::4. + +Configuration +************* + +Set eth1 to be the listening interface for the DHCPv6 relay: + +.. code-block:: sh + + set service dhcpv6-relay listen-interface eth1 + +Set eth2 to be the upstream interface and specify the IPv6 address of the DHCPv6 server: + +.. code-block:: sh + + set service dhcpv6-relay upstream-interface eth2 address 2001:db8:100::4 + +Commit the changes and show results: + +.. code-block:: sh + + commit + show service dhcpv6-relay + listen-interface eth1 { + } + upstream-interface eth2 { + address 2001:db8:100::4 + } + +Show the current status of the DHCPv6 relay agent: + +.. code-block:: sh + + show dhcpv6 relay-agent status + +The DHCPv6 relay agent can be restarted with: + +.. code-block:: sh + + restart dhcpv6 relay-agent + +Additional parameters +^^^^^^^^^^^^^^^^^^^^^ + +DHCP relay agent options +************************ + +Set the maximum hop count before packets are discarded. Range 0...255, +default 10. + +* :code:`set service dhcp-relay relay-options hop-count 'count'` + +Set maximum size of DHCP packets including relay agent information. If a +DHCP packet size surpasses this value it will be forwarded without appending +relay agent information. Range 64...1400, default 576. + +* :code:`set service dhcp-relay relay-options max-size 'size'` + +Set the port used to relay DHCP client messages. Range 1...65535, default 67. +After setting a different port, requests are still accepted on port 67 but +replies are forwarded to 255.255.255.255 port 0 instead of 68. + +* :code:`set service dhcp-relay relay-options port 'port'` + +Four policies for reforwarding DHCP packets exist: + +* **append:** The relay agent is allowed to append its own relay information + to a received DHCP packet, disregarding relay information already present in + the packet. + +* **discard:** Received packets which already contain relay information will + be discarded. + +* **forward:** All packets are forwarded, relay information already present + will be ignored. + +* **replace:** Relay information already present in a packet is stripped and + replaced with the router's own relay information set. + +* :code:`set service dhcp-relay relay-options relay-agents-packet 'policy'` + +DHCPv6 relay agent options +************************** + +Set listening port for DHCPv6 requests. Default: 547. + +* :code:`set service dhcpv6-relay listen-port 'port'` + +Set maximum hop count before packets are discarded. Default: 10. + +* :code:`set service dhcpv6-relay max-hop-count 'count'` + +If this is set the relay agent will insert the interface ID. This option is +set automatically if more than one listening interfaces are in use. + +* :code:`set service dhcpv6-relay use-interface-id-option` + +DNS Forwarding +-------------- + +Use DNS forwarding if you want your router to function as a DNS server for the +local network. There are several options, the easiest being 'forward all +traffic to the system DNS server(s)' (defined with set system name-server): + +.. code-block:: sh + + set service dns forwarding system + +Manually setting DNS servers for forwarding: + +.. code-block:: sh + + set service dns forwarding name-server 8.8.8.8 + set service dns forwarding name-server 8.8.4.4 + +Manually setting DNS servers with IPv6 connectivity: + +.. code-block:: sh + + set service dns forwarding name-server 2001:4860:4860::8888 + set service dns forwarding name-server 2001:4860:4860::8844 + +Setting a forwarding DNS server for a specific domain: + +.. code-block:: sh + + set service dns forwarding domain example.com server 192.0.2.1 + +Example 1 +^^^^^^^^^ + +Router with two interfaces eth0 (WAN link) and eth1 (LAN). A DNS server for the +local domain (example.com) is at 192.0.2.1, other DNS requests are forwarded +to Google's DNS servers. + +.. code-block:: sh + + set service dns forwarding domain example.com server 192.0.2.1 + set service dns forwarding name-server 8.8.8.8 + set service dns forwarding name-server 8.8.4.4 + set service dns forwarding listen-on 'eth1' + +Example 2 +^^^^^^^^^ + +Same as example 1 but with additional IPv6 addresses for Google's public DNS +servers: + +.. code-block:: sh + + set service dns forwarding domain example.com server 192.0.2.1 + 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 2001:4860:4860::8888 + set service dns forwarding name-server 2001:4860:4860::8844 + set service dns forwarding listen-on 'eth1' + +Dynamic DNS +----------- + +VyOS is able to update a remote DNS record when an interface gets a new IP +address. In order to do so, VyOS includes ddclient_, a perl script written for +this exact purpose. + +ddclient_ uses two methods to update a DNS record. The first one will send +updates directly to the DNS daemon, in compliance with RFC2136_. The second +one involves a third party service, like DynDNS.com or any other similar +website. This method uses HTTP requests to transmit the new IP address. You +can configure both in VyOS. + +VyOS CLI and RFC2136 +^^^^^^^^^^^^^^^^^^^^ + +First, create an RFC2136_ config node : + +.. code-block:: sh + + edit service dns dynamic interface eth0 rfc2136 + +Present your RNDC key to ddclient : + +.. code-block:: sh + + set key /config/dyndns/mydnsserver.rndc.key + +Set the DNS server IP/FQDN : + +.. code-block:: sh + + set server dns.mydomain.com + +Set the NS zone to be updated : + +.. code-block:: sh + + set zone mydomain.com + +Set the records to be updated : + +.. code-block:: sh + + set record dyn + set record dyn2 + +You can optionally set a TTL (note : default value is 600 seconds) : + +.. code-block:: sh + + set ttl 600 + +This will generate the following ddclient config blocks: + +.. code-block:: sh + + server=dns.mydomain.com + protocol=nsupdate + password=/config/dyndns/mydnsserver.rndc.key + ttl=600 + zone=mydomain.com + dyn + server=dns.mydomain.com + protocol=nsupdate + password=/config/dyndns/mydnsserver.rndc.key + ttl=600 + zone=mydomain.com + dyn2 + +You can also keep a different dns zone updated. Just create a new config node: + +.. code-block:: sh + + edit service dns dynamic interface eth0 rfc2136 + +VyOS CLI and HTTP dynamic DNS services +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +VyOS is also able to use any service relying on protocols supported by ddclient. + +To use such a service, you must define a login, a password, one or multiple +hostnames, a protocol and a server. + +.. code-block:: sh + + edit service dns dynamic interface eth0 service HeNet + set login my-login # set password my-password + set host-name my-tunnel-id + set protocol dyndns2 + set server ipv4.tunnelbroker.net + +VyOS is also shipped with a list of known services. You don't need to set the +protocol and server value as VyOS has defaults provided for those. These are +the services VyOS knows about: + +* afraid +* changeip +* dnspark +* dslreports +* dyndns +* easydns +* namecheap +* noip +* zoneedit + +To use DynDNS for example: + +.. code-block:: sh + + edit service dns dynamic interface eth0 service dyndns + set login my-login + set password my-password + set host-name my-dyndns-hostname + +It's possible to use multiple services : + +.. code-block:: sh + + edit service dns dynamic interface eth0 service dyndns + set login my-login + set password my-password + set host-name my-dyndns-hostname + edit service dns dynamic interface eth0 service HeNet + set login my-login + set password my-password + set host-name my-tunnel-id + set protocol dyndns2 + set server ipv4.tunnelbroker.net + +ddclient behind NAT +^^^^^^^^^^^^^^^^^^^ + +By default, ddclient will update a dynamic dns record using the IP address +directly attached to the interface. If your VyOS instance is behind NAT, your +record will be updated to point to your internal IP. + +ddclient_ has another way to determine the WAN IP address. This is controlled +by these two options: + +.. code-block:: sh + + set service dns dynamic interface eth0 use-web url + set service dns dynamic interface eth0 use-web skip + +ddclient_ will load the webpage at `[url]` and will try to extract an IP +address for the response. ddclient_ will skip any address located before the +string set in `[skip]`. + +mDNS Repeater +------------- + +Starting with VyOS 1.2 a `Multicast DNS`_ (mDNS) repeater functionality is +provided. + +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. Apple Airplay devices across +multiple VLANs. + +To enable mDNS repeater you need to configure at least two interfaces. To re- +broadcast all mDNS packets from `eth0` to `eth1` and vice versa run: + +.. code-block:: sh + + set service mdns repeater interface eth0 + set service mdns repeater interface eth1 + +mDNS repeater can be temporarily disabled without deleting the service using + +.. code-block:: sh + + set service mdns repeater disable + +.. note:: You can not run this in a VRRP setup, if multiple mDNS repeaters + are launched in a subnet you will experience the mDNS packet storm death! + +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 play! 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! + +To Forward broadcasts on port 1900 for eth3, eth4 and eth5 configure the service +as follows: + +.. code-block:: sh + + 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 + +.. code-block:: sh + + 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 individually disabled without deleting the +configured node by: + +.. code-block:: sh + + set service broadcast-relay id disable + +In addition you can also disable the whole service without removing the +configuration by: + +.. code-block:: sh + + set service broadcast-relay disable + +.. note:: You can run the UDP broadcast relay service on multiple routers + connected to a subnet. There is **NO** UDP broadcast relay packet storm! + +.. _ddclient: http://sourceforge.net/p/ddclient/wiki/Home/ +.. _RFC2136: https://www.ietf.org/rfc/rfc2136.txt +.. _`Multicast DNS`: https://en.wikipedia.org/wiki/Multicast_DNS diff --git a/docs/system.rst b/docs/system.rst new file mode 100644 index 00000000..445d9248 --- /dev/null +++ b/docs/system.rst @@ -0,0 +1,357 @@ +.. _system: + +System +====== + +After a basic system setup by setting up `Interface Addresses`_, VyOS should +be ready for further configuration which is described in this chapter. + +Host Information +---------------- + +This section describes the system's host information and how to configure them, +it covers the following topics: + +* Host name +* Domain +* IP address +* Default gateway +* Aliases + +Host Name +^^^^^^^^^ + +A hostname is the label (name) assigned to a network device (a host) on a +network and is used to distinguish one device from another on specific networks +or over the internet. + +Set a system host name: + +.. code-block:: sh + + set system host-name + +.. note:: Only letters, numbers and hyphens are allowed. + +Show host name: + +.. code-block:: sh + + show system host-name + +Delete host name: + +.. code-block:: sh + + delete system host-name + +Example: Set system hostname to 'RT01': + +.. code-block:: sh + + set system host-name RT01 + commit + show system host-name + host-name RT01 + +Domain Name +^^^^^^^^^^^ + +A domainname is the label (name) assigned to a computer network and is thus +unique! + +Set the system's domain: + +.. code-block:: sh + + set system domain-name + +.. note:: Only letters, numbers, hyphens and periods are allowed. + +Show domain: + +.. code-block:: sh + + show system domain-name + +Remove domain name: + +.. code-block:: sh + + set system delete domain-name + +Example: Set system domain to example.com: + +.. code-block:: sh + + set system domain-name example.com + commit + show system domain-name + domain-name example.com + +Static host mappings +^^^^^^^^^^^^^^^^^^^^ + +How to assign IPs to interfaces is described in chapter `Interface Addresses`_. +This section shows how to statically map a system IP to its host name for +local (meaning on this VyOS instance) DNS resolution: + +.. code-block:: sh + + set system static-host-mapping host-name inet + +Show static mapping: + +.. code-block:: sh + + show system static-host-mapping + +Example: Create a static mapping between the system's hostname `RT01` and +IP address `10.20.30.41`: + +.. code-block:: sh + + set system static-host-mapping host-name RT01 inet 10.20.30.41 + commit + show system static-host-mapping + host-name RT01 { + inet 10.20.30.41 + } + +Aliases +******* + +One or more system aliases (static mappings) can be defined: + +.. code-block:: sh + + set system static-host-mapping host-name alias + +Show aliases: + +.. code-block:: sh + + show system static-mapping + +Delete alias: + +.. code-block:: sh + + delete system static-host-mapping host-name alias + +Example: Set alias `router1` for system with hostname `RT01`: + +.. code-block:: sh + + set system static-host-mapping host-name RT01 alias router1 + commit + show system static-host-mapping + host-name RT01 { + alias router1 + inet 10.20.30.41 + } + +Default Gateway/Route +^^^^^^^^^^^^^^^^^^^^^ + +In the past (VyOS 1.1.8) used a gateway-address configured in the system tree +(`set system gateway-address `) this is no longer supported and +existing configurations are migrated to the new CLI commands. + +It is replaced by inserting a static route into the routing table using: + +.. code-block:: sh + + set protocols static route 0.0.0.0/0 next-hop + +Delete default route fomr the system + +.. code-block:: sh + + delete protocols static route 0.0.0.0/0 + +Show default route: + +.. code-block:: sh + + vyos@vyos$ show ip route 0.0.0.0 + Routing entry for 0.0.0.0/0 + Known via "static", distance 1, metric 0, best + Last update 3d00h23m ago + * 172.16.34.6, via eth1 + +System Users +------------ + +VyOS supports two levels of users: admin and operator. + +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 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Create user account `jsmith`, with `admin` level access and the password +`mypassword` + +.. code-block:: sh + + set system login user jsmith full-name "Johan Smith" + set system login user jsmith authentication plaintext-password mypassword + set system login user jsmith level admin + +The command: + +.. code-block:: sh + + show system login + +will show the contents of :code:`system login` configuration node: + +.. code-block:: sh + + user jsmith { + authentication { + encrypted-password $6$0OQHjuQ8M$AYXVn7jufdfqPrSk4/XXsDBw99JBtNsETkQKDgVLptXogHA2bU9BWlvViOFPBoFxIi.iqjqrvsQdQ./cfiiPT. + plaintext-password "" + } + full-name "Johan Smith" + level admin + } + +SSH Access using Shared Public Keys +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following command will load the public key `dev.pub` for user `jsmith` + +.. code-block:: sh + + loadkey jsmith dev.pub + +.. note:: This requires uploading the `dev.pub` public key to the VyOS router + first. As an alternative you can also load the SSH public key directly + from a remote system: + +.. code-block:: sh + + loadkey jsmith scp://devuser@dev001.vyos.net/home/devuser/.ssh/dev.pub + +Syslog +------ + +Per default VyOSs has minimal syslog logging enabled which is stored and +rotated locally. Errors will be always logged to a local file, which includes +`local7` error messages, emergency messages will be sent to the console, too. + +To configure syslog, you need to switch into configuration mode. + +Logging to serial console +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The below would log all messages to :code:`/dev/console`. + +.. code-block:: sh + + set system syslog console facility all level all + +Use the **[tab]** function to display all facilities and levels which can +be configured. + +.. code-block:: sh + + vyos@vyos# set system syslog console facility + Possible completions: + > all All facilities excluding "mark" + > auth Authentication and authorization + > authpriv Non-system authorization + > cron Cron daemon + > daemon System daemons + > kern Kernel + > lpr Line printer spooler + > mail Mail subsystem + > mark Timestamp + > news USENET subsystem + > protocols depricated will be set to local7 + > security depricated will be set to auth + > syslog Authentication and authorization + > user Application processes + > uucp UUCP subsystem + > local0 Local facility 0 + > local1 Local facility 1 + > local2 Local facility 2 + > local3 Local facility 3 + > local4 Local facility 4 + > local5 Local facility 5 + > local6 Local facility 6 + > local7 Local facility 7 + + vyos@vyos# set system syslog console facility all level + Possible completions: + emerg Emergency messages + alert Urgent messages + crit Critical messages + err Error messages + warning Warning messages + notice Messages for further investigation + info Informational messages + debug Debug messages + all Log everything + + +Logging to a custom file +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Logging to a custom file, rotation size and the number of rotate files left +on the system can be configured. + +.. code-block:: sh + + set system syslog file facility level + set system syslog file archive file + set system syslog file FILENAME archive size + +The very same setting can be applied to the global configuration, to modify +the defaults for the global logging. + +Logging to a remote host +^^^^^^^^^^^^^^^^^^^^^^^^ + +Logging to a remote host leaves the local logging configuration intact, it +can be configured in parallel. You can log ro multiple hosts at the same time, +using either TCP or UDP. The default is sending the messages via UDP. + +**UDP** + +.. code-block:: sh + + set system syslog host 10.1.1.1 facility all level all + + set system syslog host 10.1.1.1 facility all protocol udp + + +**TCP** + +.. code-block:: sh + + set system syslog host 10.1.1.2 facility all level all + set system syslog host 10.1.1.2 facility all protocol tcp + +Logging to a local user account +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If logging to a local useraccount is configured, all defined log messages are +display on the console if the local user is logged in, if the user is not +logged in, no messages are being displayed. + +.. code-block:: sh + + set system syslog user facility level diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst new file mode 100644 index 00000000..09877df3 --- /dev/null +++ b/docs/troubleshooting.rst @@ -0,0 +1,166 @@ +.. _troubleshooting: + +Appendix A - 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 `Command-Line Interface`_ +section and are omitted from the output here): + +.. code-block:: sh + + vyos@vyos:~$ ping + Possible completions: + Send Internet Control Message Protocol (ICMP) echo request + + + +Several options are available when more extensive troubleshooting is needed: + +.. code-block:: sh + + vyos@vyos:~$ ping 8.8.8.8 + Possible completions: + 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 + +.. code-block:: sh + + vyos@vyos:~$ traceroute + Possible completions: + Track network path to specified node + + + ipv4 Track network path to + ipv6 Track network path to + +However, another tool, mtr_, is available which combines ping and traceroute +into a single tool. An example of its output is shown: + +.. code-block:: sh + + vyos@vyos:~$ mtr 10.62.212.12 + + My traceroute [v0.85] + vyos (0.0.0.0) + 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 + +.. note:: The output of ``mtr`` consumes the screen and will replace your + command prompt. + +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: + +.. code-block:: sh + + vyos@vyos:~$ monitor interfaces + Possible completions: + 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 + +To monitor traffic flows, issue the :code:`monitor interfaces flow` +command, replacing `` and `` with your desired interface type and +name, respectively. Output looks like the following: + +.. code-block:: sh + + 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 :code:`monitor interfaces +traffic` command, replacing `` and `` with your desired interface +type and name, respectively. This command invokes the familiar tshark_ utility +and the following options are available: + +.. code-block:: sh + + vyos@vyos:~$ monitor interfaces ethernet eth0 traffic + Possible completions: + 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 + +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). + +.. _mtr: http://www.bitwizard.nl/mtr/ +.. _tshark: https://www.wireshark.org/docs/man-pages/tshark.html +.. _`PCAP filter expressions`: http://www.tcpdump.org/manpages/pcap-filter.7.html diff --git a/docs/vpn.rst b/docs/vpn.rst new file mode 100644 index 00000000..28cacc69 --- /dev/null +++ b/docs/vpn.rst @@ -0,0 +1,869 @@ +.. _vpn: + +VPN +=== + +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 `. 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: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + set protocols static interface-route 10.1.0.0/16 next-hop-interface vtun1 + +Remote Configuration: + +.. code-block:: sh + + 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 uses +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. + +.. code-block:: sh + + 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` + +.. code-block:: sh + + 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. + +.. code-block:: sh + + 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:: Clients are identified by the CN field of their x.509 certificates, + in this example the CN is ``client0``: + +.. code-block:: sh + + 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: + +.. code-block:: sh + + 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): + +.. code-block:: sh + + 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 + set vpn l2tp remote-access authentication mode local + set vpn l2tp remote-access authentication local-users username 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: + +.. code-block:: sh + + 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. + +.. code-block:: sh + + 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. + +.. code-block:: sh + + 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' + +.. note:: Those are the `Google public DNS`_ servers. You can also use the + public available servers from Quad9_ (9.9.9.9) or Cloudflare_ (1.1.1.1). + +Established sessions can be viewed using the **show vpn remote-access** +operational command. + +.. code-block:: sh + + 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 + +RADIUS authentication +^^^^^^^^^^^^^^^^^^^^^ + +The above configuration made use of local accounts on the VyOS router for +authenticating L2TP/IPSec clients. In bigger environments usually something +like RADIUS_ (FreeRADIUS_ or Microsoft `Network Policy Server`_, NPS) is used. + +VyOS supports either `local` or `radius` user authentication: + +.. code-block:: sh + + set vpn l2tp remote-access authentication mode + +In addition one or more RADIUS_ servers can be configured to server for user +authentication. This is done using the `radius-server` and `key` nodes: + +.. code-block:: sh + + set vpn l2tp remote-access authentication radius-server 1.1.1.1 key 'foo' + set vpn l2tp remote-access authentication radius-server 2.2.2.2 key 'foo' + +.. note:: Some RADIUS_ severs make use of an access control list who is allowed + to query the server. Please configure your VyOS router in the allowed client + list. + +RADIUS source address +********************* + +Yet there is no way to configure the used RADIUS_ client source IP address on +the VyOS router, this is work in progres, see https://phabricator.vyos.net/T828. + +The IP address nearest to the radius server is currently used. If in doubt, +configure all IP addresses from the VyOS router in question. + +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 + +.. code-block:: sh + + # server 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 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' + +Show status of new setup: + +.. code-block:: sh + + 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 + +.. code-block:: sh + + # 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) + +.. code-block:: sh + + # 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 +----- + +**D** ynamic **M** ultipoint **V** irtual **P** rivate **N** etworking + +DMVPN is a dynamic VPN technology originally developed by Cisco. While their +implementation was somewhat proprietary, the underlying technologies are +actually standards based. The three technologies are: + +* **NHRP** - NBMA Next Hop Resolution Protocol RFC2332_ +* **mGRE** - Multipoint Generic Routing Encapsulation / mGRE RFC1702_ +* **IPSec** - IP Security (too many RFCs to list, but start with RFC4301_) + +NHRP provides the dynamic tunnel endpoint discovery mechanism (endpoint +registration, and endpoint discovery/lookup), mGRE provides the tunnel +encapsulation itself, and the IPSec protocols handle the key exchange, and +crypto mechanism. + +In short, DMVPN provides the capability for creating a dynamic-mesh VPN +network without having to pre-configure (static) all possible tunnel end-point +peers. + +.. note:: DMVPN only automates the tunnel endpoint discovery and setup. A + complete solution also incorporates the use of a routing protocol. BGP is + particularly well suited for use with DMVPN. + +Baseline Configuration: + +**STEPS:** + +#. Create tunnel config (`interfaces tunnel`) +#. Create nhrp (`protocols nhrp`) +#. Create ipsec vpn (optional, but recommended for security) (`vpn ipsec`) + +The tunnel will be set to mGRE if for encapsulation `gre` is set, and no +`remote-ip` is set. If the public ip is provided by DHCP the tunnel `local-ip` +can be set to "0.0.0.0" + +.. figure:: _static/images/vpn_dmvpn_topology01.png + :scale: 40 % + :alt: Baseline DMVPN topology + + Baseline DMVPN topology + +HUB Configuration +^^^^^^^^^^^^^^^^^ + +.. code-block:: sh + + interfaces + tunnel { + address + encapsulation gre + local-ip + multicast enable + description + parameters { + ip { + + } + } + } + } + protocols { + nhrp { + tunnel { + cisco-authentication + holding-time + multicast dynamic + redirect + } + } + } + vpn { + ipsec { + esp-group { + lifetime <30-86400> + mode tunnel + pfs enable + proposal <1-65535> { + encryption aes256 + hash sha1 + } + proposal <1-65535> { + encryption 3des + hash md5 + } + } + ike-group { + key-exchange ikev1 + lifetime <30-86400> + proposal <1-65535> { + encryption aes256 + hash sha1 + } + proposal <1-65535> { + encryption aes128 + hash sha1 + } + } + ipsec-interfaces { + interface + } + profile { + authentication { + mode pre-shared-secret + pre-shared-secret + } + bind { + tunnel + } + esp-group + ike-group + } + } + } + +HUB Example Configuration: + +.. code-block:: sh + + set interfaces ethernet eth0 address '1.1.1.1/30' + set interfaces ethernet eth1 address '192.168.1.1/24' + set system host-name 'HUB' + + set interfaces tunnel tun0 address 10.0.0.1/24 + set interfaces tunnel tun0 encapsulation gre + set interfaces tunnel tun0 local-ip 1.1.1.1 + set interfaces tunnel tun0 multicast enable + set interfaces tunnel tun0 parameters ip key 1 + + set protocols nhrp tunnel tun0 cisco-authentication SECRET + set protocols nhrp tunnel tun0 holding-time 300 + set protocols nhrp tunnel tun0 multicast dynamic + set protocols nhrp tunnel tun0 redirect + + set vpn ipsec ipsec-interfaces interface eth0 + set vpn ipsec ike-group IKE-HUB proposal 1 + set vpn ipsec ike-group IKE-HUB proposal 1 encryption aes256 + set vpn ipsec ike-group IKE-HUB proposal 1 hash sha1 + set vpn ipsec ike-group IKE-HUB proposal 2 encryption aes128 + set vpn ipsec ike-group IKE-HUB proposal 2 hash sha1 + set vpn ipsec ike-group IKE-HUB lifetime 3600 + set vpn ipsec esp-group ESP-HUB proposal 1 encryption aes256 + set vpn ipsec esp-group ESP-HUB proposal 1 hash sha1 + set vpn ipsec esp-group ESP-HUB proposal 2 encryption 3des + set vpn ipsec esp-group ESP-HUB proposal 2 hash md5 + set vpn ipsec esp-group ESP-HUB lifetime 1800 + set vpn ipsec esp-group ESP-HUB pfs dh-group2 + + set vpn ipsec profile NHRPVPN + set vpn ipsec profile NHRPVPN authentication mode pre-shared-secret + set vpn ipsec profile NHRPVPN authentication pre-shared-secret SECRET + set vpn ipsec profile NHRPVPN bind tunnel tun0 + set vpn ipsec profile NHRPVPN esp-group ESP-HUB + set vpn ipsec profile NHRPVPN ike-group IKE-HUB + + set protocols static route 0.0.0.0/0 next-hop 1.1.1.2 + set protocols static route 192.168.2.0/24 next-hop 10.0.0.2 + set protocols static route 192.168.3.0/24 next-hop 10.0.0.3 + +SPOKE Configuration +^^^^^^^^^^^^^^^^^^^ + +SPOKE1 Configuration: + +.. code-block:: sh + + interfaces + tunnel { + address + encapsulation gre + local-ip + multicast enable + description + parameters { + ip { + + } + } + } + } + protocols { + nhrp { + tunnel { + cisco-authentication + map { + nbma-address + register + } + holding-time + multicast nhs + redirect + shortcut + } + } + } + vpn { + ipsec { + esp-group { + lifetime <30-86400> + mode tunnel + pfs enable + proposal <1-65535> { + encryption aes256 + hash sha1 + } + proposal <1-65535> { + encryption 3des + hash md5 + } + } + ike-group { + key-exchange ikev1 + lifetime <30-86400> + proposal <1-65535> { + encryption aes256 + hash sha1 + } + proposal <1-65535> { + encryption aes128 + hash sha1 + } + } + ipsec-interfaces { + interface + } + profile { + authentication { + mode pre-shared-secret + pre-shared-secret + } + bind { + tunnel + } + esp-group + ike-group + } + } + } + +SPOKE1 Example Configuration + +.. code-block:: sh + + set interfaces ethernet eth0 address 'dhcp' + set interfaces ethernet eth1 address '192.168.2.1/24' + set system host-name 'SPOKE1' + + set interfaces tunnel tun0 address 10.0.0.2/24 + set interfaces tunnel tun0 encapsulation gre + set interfaces tunnel tun0 local-ip 0.0.0.0 + set interfaces tunnel tun0 multicast enable + set interfaces tunnel tun0 parameters ip key 1 + + set protocols nhrp tunnel tun0 cisco-authentication 'SECRET' + set protocols nhrp tunnel tun0 map 10.0.0.1/24 nbma-address 1.1.1.1 + set protocols nhrp tunnel tun0 map 10.0.0.1/24 'register' + set protocols nhrp tunnel tun0 multicast 'nhs' + set protocols nhrp tunnel tun0 'redirect' + set protocols nhrp tunnel tun0 'shortcut' + + set vpn ipsec ipsec-interfaces interface eth0 + set vpn ipsec ike-group IKE-SPOKE proposal 1 + set vpn ipsec ike-group IKE-SPOKE proposal 1 encryption aes256 + set vpn ipsec ike-group IKE-SPOKE proposal 1 hash sha1 + set vpn ipsec ike-group IKE-SPOKE proposal 2 encryption aes128 + set vpn ipsec ike-group IKE-SPOKE proposal 2 hash sha1 + set vpn ipsec ike-group IKE-SPOKE lifetime 3600 + set vpn ipsec esp-group ESP-SPOKE proposal 1 encryption aes256 + set vpn ipsec esp-group ESP-SPOKE proposal 1 hash sha1 + set vpn ipsec esp-group ESP-SPOKE proposal 2 encryption 3des + set vpn ipsec esp-group ESP-SPOKE proposal 2 hash md5 + set vpn ipsec esp-group ESP-SPOKE lifetime 1800 + set vpn ipsec esp-group ESP-SPOKE pfs dh-group2 + + set vpn ipsec profile NHRPVPN + set vpn ipsec profile NHRPVPN authentication mode pre-shared-secret + set vpn ipsec profile NHRPVPN authentication pre-shared-secret SECRET + set vpn ipsec profile NHRPVPN bind tunnel tun0 + set vpn ipsec profile NHRPVPN esp-group ESP-SPOKE + set vpn ipsec profile NHRPVPN ike-group IKE-SPOKE + + set protocols static route 192.168.1.0/24 next-hop 10.0.0.1 + set protocols static route 192.168.3.0/24 next-hop 10.0.0.3 + + +SPOKE2 Configuration + +.. code-block:: sh + + interfaces + tunnel { + address + encapsulation gre + local-ip + multicast enable + description + parameters { + ip { + + } + } + } + } + protocols { + nhrp { + tunnel { + cisco-authentication + map { + nbma-address + register + } + holding-time + multicast nhs + redirect + shortcut + } + } + } + vpn { + ipsec { + esp-group { + lifetime <30-86400> + mode tunnel + pfs enable + proposal <1-65535> { + encryption aes256 + hash sha1 + } + proposal <1-65535> { + encryption 3des + hash md5 + } + } + ike-group { + key-exchange ikev1 + lifetime <30-86400> + proposal <1-65535> { + encryption aes256 + hash sha1 + } + proposal <1-65535> { + encryption aes128 + hash sha1 + } + } + ipsec-interfaces { + interface + } + profile { + authentication { + mode pre-shared-secret + pre-shared-secret + } + bind { + tunnel + } + esp-group + ike-group + } + } + } + +SPOKE2 Example Configuration + +.. code-block:: sh + + set interfaces ethernet eth0 address 'dhcp' + set interfaces ethernet eth1 address '192.168.3.1/24' + set system host-name 'SPOKE2' + + set interfaces tunnel tun0 address 10.0.0.3/24 + set interfaces tunnel tun0 encapsulation gre + set interfaces tunnel tun0 local-ip 0.0.0.0 + set interfaces tunnel tun0 multicast enable + set interfaces tunnel tun0 parameters ip key 1 + + set protocols nhrp tunnel tun0 cisco-authentication SECRET + set protocols nhrp tunnel tun0 map 10.0.0.1/24 nbma-address 1.1.1.1 + set protocols nhrp tunnel tun0 map 10.0.0.1/24 register + set protocols nhrp tunnel tun0 multicast nhs + set protocols nhrp tunnel tun0 redirect + set protocols nhrp tunnel tun0 shortcut + + set vpn ipsec ipsec-interfaces interface eth0 + set vpn ipsec ike-group IKE-SPOKE proposal 1 + set vpn ipsec ike-group IKE-SPOKE proposal 1 encryption aes256 + set vpn ipsec ike-group IKE-SPOKE proposal 1 hash sha1 + set vpn ipsec ike-group IKE-SPOKE proposal 2 encryption aes128 + set vpn ipsec ike-group IKE-SPOKE proposal 2 hash sha1 + set vpn ipsec ike-group IKE-SPOKE lifetime 3600 + set vpn ipsec esp-group ESP-SPOKE proposal 1 encryption aes256 + set vpn ipsec esp-group ESP-SPOKE proposal 1 hash sha1 + set vpn ipsec esp-group ESP-SPOKE proposal 2 encryption 3des + set vpn ipsec esp-group ESP-SPOKE proposal 2 hash md5 + set vpn ipsec esp-group ESP-SPOKE lifetime 1800 + set vpn ipsec esp-group ESP-SPOKE pfs dh-group2 + + set vpn ipsec profile NHRPVPN + set vpn ipsec profile NHRPVPN authentication mode pre-shared-secret + set vpn ipsec profile NHRPVPN authentication pre-shared-secret SECRET + set vpn ipsec profile NHRPVPN bind tunnel tun0 + set vpn ipsec profile NHRPVPN esp-group ESP-SPOKE + set vpn ipsec profile NHRPVPN ike-group IKE-SPOKE + + set protocols static route 192.168.1.0/24 next-hop 10.0.0.1 + set protocols static route 192.168.2.0/24 next-hop 10.0.0.2 + +.. _`Google Public DNS`: https://developers.google.com/speed/public-dns +.. _Quad9: https://quad9.net +.. _CloudFlare: https://blog.cloudflare.com/announcing-1111 +.. _RADIUS: https://en.wikipedia.org/wiki/RADIUS +.. _FreeRADIUS: https://freeradius.org +.. _`Network Policy Server`: https://en.wikipedia.org/wiki/Network_Policy_Server +.. _RFC2332: https://tools.ietf.org/html/rfc2332 +.. _RFC1702: https://tools.ietf.org/html/rfc1702 +.. _RFC4301: https://tools.ietf.org/html/rfc4301 -- cgit v1.2.3