diff options
Diffstat (limited to 'docs/configuration')
59 files changed, 9453 insertions, 0 deletions
diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst new file mode 100644 index 00000000..ed255916 --- /dev/null +++ b/docs/configuration/firewall/index.rst @@ -0,0 +1,258 @@ +.. _firewall: + +Firewall +======== + +VyOS makes use of Linux `netfilter <http://netfilter.org/>`_ 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. + +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:: none + + 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 + +Groups need to have unique names. Even though some contain IPv4 addresses and others contain IPv6 addresses, they still need to have unique names, so you may want to append "-v4" or "-v6" to your group names. + +.. code-block:: none + + set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24 + set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64 + + +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:: none + + 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:: none + + 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:: none + + set interfaces ethernet eth1 firewall out name INSIDE-OUT + +.. _routing-mss-clamp: + +TCP-MSS Clamping +---------------- + +As Internet wide PMTU discovery rarely works, we sometimes need to clamp +our TCP MSS value to a specific value. This is a field in the TCP +Options part of a SYN packet. By setting the MSS value, you are telling +the remote side unequivocally 'do not try to send me packets bigger than +this value'. + +Starting with VyOS 1.2 there is a firewall option to clamp your TCP MSS +value for IPv4 and IPv6. + + +.. note:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting + in 1452 bytes on a 1492 byte MTU. + + +IPv4 +^^^^ + +.. cfgcmd:: set firewall options interface <interface> adjust-mss <number-of-bytes> + + Use this command to set the maximum segment size for IPv4 transit + packets on a specific interface (500-1460 bytes). + + +Example +""""""" + +Clamp outgoing MSS value in a TCP SYN packet to `1452` for `pppoe0` and +`1372` +for your WireGuard `wg02` tunnel. + +.. code-block:: none + + set firewall options interface pppoe0 adjust-mss '1452' + set firewall options interface wg02 adjust-mss '1372' + +IPv6 +^^^^^ + +.. cfgcmd:: set firewall options interface <interface> adjust-mss6 <number-of-bytes> + + Use this command to set the maximum segment size for IPv6 transit + packets on a specific interface (1280-1492 bytes). + + +Example +""""""" + +Clamp outgoing MSS value in a TCP SYN packet to `1280` for both `pppoe0` and +`wg02` interface. + +.. code-block:: none + + set firewall options interface pppoe0 adjust-mss6 '1280' + set firewall options interface wg02 adjust-mss6 '1280' + + + +.. hint:: When doing your byte calculations, you might find useful this + `Visual packet size calculator <https://baturin.org/tools/encapcalc/>`_. + + +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:: none + + set zone-policy zone INSIDE from OUTSIDE firewall name INSIDE-OUT + +How VyOS replies when being pinged +---------------------------------- + +By default, when VyOS receives an ICMP echo request packet destined for itself, it will answer with an ICMP echo reply, unless you avoid it through its firewall. + +With the firewall you can set rules to accept, drop or reject ICMP in, out or local traffic. You can also use the general **firewall all-ping** command. This command affects only to LOCAL (packets destined for your VyOS system), not to IN or OUT traffic. + +.. note:: **firewall all-ping** affects only to LOCAL and it always behaves in the most restrictive way + +.. code-block:: none + + set firewall all-ping enable + +When the command above is set, VyOS will answer every ICMP echo request addressed to itself, but that will only happen if no other rule is applied droping or rejecting local echo requests. In case of conflict, VyOS will not answer ICMP echo requests. + +.. code-block:: none + + set firewall all-ping disable + +When the comand above is set, VyOS will answer no ICMP echo request addressed to itself at all, no matter where it comes from or whether more specific rules are being applied to accept them. + +Example Partial Config +---------------------- + +.. code-block:: none + + firewall { + all-ping enable + broadcast-ping disable + config-trap disable + group { + network-group BAD-NETWORKS { + network 198.51.100.0/24 + network 203.0.113.0/24 + } + network-group GOOD-NETWORKS { + network 192.0.2.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 + } + } + } + } diff --git a/docs/configuration/highavailability/index.rst b/docs/configuration/highavailability/index.rst new file mode 100644 index 00000000..81cc2d44 --- /dev/null +++ b/docs/configuration/highavailability/index.rst @@ -0,0 +1,158 @@ +.. _high-availability: + +High availability +================= + +VRRP (Virtual Redundancy Protocol) provides active/backup redundancy for routers. +Every VRRP router has a physical IP/IPv6 address, and a virtual address. +On startup, routers elect the master, and the router with the highest priority becomes the master and assigns the virtual address to its interface. +All routers with lower priorities become backup routers. The master then starts sending keepalive packets to notify other routers that it's available. +If the master fails and stops sending keepalive packets, the router with the next highest priority becomes the new master and takes over the virtual address. + +VRRP keepalive packets use multicast, and VRRP setups are limited to a single datalink layer segment. +You can setup multiple VRRP groups (also called virtual routers). Virtual routers are identified by a VRID (Virtual Router IDentifier). +If you setup multiple groups on the same interface, their VRIDs must be unique, but it's possible (even if not recommended for readability reasons) to use duplicate VRIDs on different interfaces. + +Basic setup +----------- + +VRRP groups are created with the ``set high-availability vrrp group $GROUP_NAME`` commands. +The required parameters are interface, vrid, and virtual-address. + +minimal config + +.. code-block:: none + + set high-availability vrrp group Foo vrid 10 + set high-availability vrrp group Foo interface eth0 + set high-availability vrrp group Foo virtual-address 192.0.2.1/24 + +You can verify your VRRP group status with the operational mode ``run show vrrp`` command: + +.. code-block:: none + + vyos@vyos# run show vrrp + Name Interface VRID State Last Transition + ---------- ----------- ------ ------- ----------------- + Foo eth1 10 MASTER 2s + +IPv6 support +------------ + +The ``virtual-address`` parameter can be either an IPv4 or IPv6 address, but you cannot mix IPv4 and IPv6 in the same group, and will need to create groups with different VRIDs specially for IPv4 and IPv6. + +Disabling a VRRP group +---------------------- + +You can disable a VRRP group with ``disable`` option: + +.. code-block:: none + + set high-availability vrrp group Foo disable + +A disabled group will be removed from the VRRP process and your router will not participate in VRRP for that VRID. It will disappear from operational mode commands output, rather than enter the backup state. + +Setting VRRP group priority +--------------------------- + +VRRP priority can be set with ``priority`` option: + +.. code-block:: none + + set high-availability vrrp group Foo priority 200 + +The priority must be an integer number from 1 to 255. Higher priority value increases router's precedence in the master elections. + +Sync groups +----------- + +A sync group allows VRRP groups to transition together. + +.. code-block:: none + + edit high-availability + set sync-group MAIN member VLAN9 + set sync-group MAIN member VLAN20 + +In the following example, when VLAN9 transitions, VLAN20 will also transition: + +.. code-block:: none + + vrrp { + group VLAN9 { + interface eth0.9 + virtual-address 10.9.1.1/24 + priority 200 + vrid 9 + } + group VLAN20 { + interface eth0.20 + priority 200 + virtual-address 10.20.20.1/24 + vrid 20 + } + sync-group MAIN { + member VLAN20 + member VLAN9 + } + } + + +.. warning:: All items in a sync group should be similarly configured. If one VRRP group is set to a different premption delay or priority, it would result in an endless transition loop. + + +Preemption +---------- + +VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, if a router with a higher priority fails and then comes back, routers with lower priority will give up their master status. In non-preemptive mode, the newly elected master will keep the master status and the virtual address indefinitely. + +By default VRRP uses preemption. You can disable it with the "no-preempt" option: + +.. code-block:: none + + set high-availability vrrp group Foo no-preempt + +You can also configure the time interval for preemption with the "preempt-delay" option. For example, to set the higher priority router to take over in 180 seconds, use: + +.. code-block:: none + + set high-availability vrrp group Foo preempt-delay 180 + +Unicast VRRP +------------ + +By default VRRP uses multicast packets. If your network does not support multicast for whatever reason, you can make VRRP use unicast communication instead. + +.. code-block:: none + + set high-availability vrrp group Foo peer-address 192.0.2.10 + set high-availability vrrp group Foo hello-source-address 192.0.2.15 + +Scripting +--------- + +VRRP functionality can be extended with scripts. VyOS supports two kinds of scripts: health check scripts and transition scripts. Health check scripts execute custom checks in addition to the master router reachability. +Transition scripts are executed when VRRP state changes from master to backup or fault and vice versa and can be used to enable or disable certain services, for example. + +Health check scripts +^^^^^^^^^^^^^^^^^^^^ + +This setup will make the VRRP process execute the ``/config/scripts/vrrp-check.sh script`` every 60 seconds, and transition the group to the fault state if it fails (i.e. exits with non-zero status) three times: + +.. code-block:: none + + set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh + set high-availability vrrp group Foo health-check interval 60 + set high-availability vrrp group Foo health-check failure-count 3 + +Transition scripts +^^^^^^^^^^^^^^^^^^ + +Transition scripts can help you implement various fixups, such as starting and stopping services, or even modifying the VyOS config on VRRP transition. +This setup will make the VRRP process execute the ``/config/scripts/vrrp-fail.sh`` with argument ``Foo`` when VRRP fails, and the ``/config/scripts/vrrp-master.sh`` when the router becomes the master: + +.. code-block:: none + + set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" + set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" + set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst new file mode 100644 index 00000000..ee2c6354 --- /dev/null +++ b/docs/configuration/index.rst @@ -0,0 +1,22 @@ +################### +Configuration Guide +################### + +The following structure respresent the cli structure. + +.. toctree:: + :maxdepth: 1 + :includehidden: + + firewall/index + highavailability/index + interfaces/index + loadbalancing/index + nat/index + policy/index + protocols/index + service/index + system/index + trafficpolicy/index + vpn/index + zonepolicy/index
\ No newline at end of file diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst new file mode 100644 index 00000000..76c8714a --- /dev/null +++ b/docs/configuration/interfaces/bonding.rst @@ -0,0 +1,75 @@ +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:: none + + set interfaces bonding bond0 description 'my-sw1 int 23 and 24' + +You are able to choose a hash policy: + +.. code-block:: none + + 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:: none + + 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:: none + + set interfaces bonding bond0 mode '802.3ad' + +or some other modes: + +.. code-block:: none + + 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:: none + + 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:: none + + 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 diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst new file mode 100644 index 00000000..30ece53d --- /dev/null +++ b/docs/configuration/interfaces/bridge.rst @@ -0,0 +1,104 @@ +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:: none + + 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:: none + + set interfaces bridge br100 address '192.168.100.1/24' + set interfaces bridge br100 address '2001:db8:100::1/64' + +Example Result: + +.. code-block:: none + + 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 <name> stp true` command: + +.. code-block:: none + + 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:: none + + vyos@vyos:~$ show bridge + bridge name bridge id STP enabled interfaces + br100 0000.000c29443b19 yes eth1.100 + +If spanning-tree is enabled, the `show bridge <name> spanning-tree` command +can be used to show STP configuration: + +.. code-block:: none + + vyos@vyos:~$ show bridge br100 spanning-tree + br100 + bridge id 0000.000c29443b19 + designated root 0000.000c29443b19 + root port 0 path cost 0 + max age 20.00 bridge max age 20.00 + hello time 2.00 bridge hello time 2.00 + forward delay 15.00 bridge forward delay 15.00 + ageing time 300.00 + hello timer 0.47 tcn timer 0.00 + topology change timer 0.00 gc timer 64.63 + flags + + eth1.100 (1) + port id 8001 state forwarding + designated root 0000.000c29443b19 path cost 4 + designated bridge 0000.000c29443b19 message age timer 0.00 + designated port 8001 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + flags + +The MAC address-table for a bridge can be displayed using the +`show bridge <name> macs` command: + +.. code-block:: none + + vyos@vyos:~$ show bridge br100 macs + port no mac addr is local? ageing timer + 1 00:0c:29:44:3b:19 yes 0.00 diff --git a/docs/configuration/interfaces/dummy.rst b/docs/configuration/interfaces/dummy.rst new file mode 100644 index 00000000..dea4c387 --- /dev/null +++ b/docs/configuration/interfaces/dummy.rst @@ -0,0 +1,21 @@ +.. _dummy-interface: + +Dummy Interfaces +---------------- + +Dummy interfaces — much like the loopback, except you can have as many as you want. +Dummy interfaces can be used as interfaces that always stay up (in the same fashion to loopbacks in IOS), or for testing purposes. + +Configuration commands: + +.. code-block:: none + + interfaces + dummy <dum[0-999]> + + address IP address + description Description + disable Disable interface + > ip IPv4 routing parameters + > ipv6 IPv6 routing parameters + redirect Incoming packet redirection destination + > traffic-policy Traffic-policy for interface
\ No newline at end of file diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst new file mode 100644 index 00000000..18530c8a --- /dev/null +++ b/docs/configuration/interfaces/ethernet.rst @@ -0,0 +1,263 @@ + +Ethernet Interfaces +------------------- +.. _interfaces-ethernet: + +Ethernet interfaces allow for the configuration of speed, duplex, and hw-id +(MAC address). Below is an example configuration: + +.. code-block:: none + + 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:: none + + 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 <name> physical` +* `show interfaces ethernet <name> statistics` + +Statistics available are driver dependent. + +.. code-block:: none + + 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) +---------------------------- +.. _interfaces-vlan: + +802.1Q VLAN interfaces are represented as virtual sub-interfaces in VyOS. The +term used for this is `vif`. Configuration of a tagged sub-interface is +accomplished using the configuration command +`set interfaces ethernet <name> vif <vlan-id>`. + +.. code-block:: none + + 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:: none + + 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 `<name>.<vlan-id>`, e.g. `eth1.100`: + +.. code-block:: none + + 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 + + + +.. _interfaces-qinq: + +QinQ +---- + +QinQ (802.1ad_) — allows multiple VLAN tags to be inserted into a single frame. + +QinQ can be used to tunnel vlans in a vlan. + +**vif-s** and **vif-c** stand for the ethertype tags that get set: + +The inner tag is the tag which is closest to the payload portion of the frame; it is officially called C-TAG (Customer tag, with ethertype 0x8100). +The outer tag is the one closer/closest to the Ethernet header; its name is S-TAG (Service tag, ethertype 0x88a8). + +Configuration commands: + +.. code-block:: none + + interfaces + ethernet <eth[0-999]> + address <ipv4> + address <ipv6> + description <txt> + disable + ip + <usual IP options> + ipv6 + <usual IPv6 options> + vif-s <[0-4096]> + address <ipv4> + address <ipv6> + description <txt> + disable + ip + <usual IP options> + ipv6 + <usual IPv6 options> + vif-c <[0-4096]> + address <ipv4> + address <ipv6> + description <txt> + disable + ip + <usual IP options> + ipv6 + <usual IPv6 options> + + +Example: + +.. code-block:: none + + set interfaces ethernet eth0 vif-s 333 + set interfaces ethernet eth0 vif-s 333 address 192.0.2.10/32 + set interfaces ethernet eth0 vif-s 333 vif-c 777 + set interfaces ethernet eth0 vif-s 333 vif-c 777 address 10.10.10.10/24 + +.. _802.1ad: https://en.wikipedia.org/wiki/IEEE_802.1ad + +.. _pppoe: + + +PPPoE +===== + +There are two main ways to setup VyOS to connect over a PPPoE internet connection. This is due to most ISPs (Internet Service Providers) providing a DSL modem that is also a wireless router. + +**First Method:** (Common for Homes) + +In this method, the DSL Modem/Router connects to the ISP for you with your credentials preprogrammed into the device. This gives you an RFC1918_ address, such as 192.168.1.0/24 by default. + +For a simple home network using just the ISP's equipment, this is usually desirable. But if you want to run VyOS as your firewall and router, this will result in having a double NAT and firewall setup. This results in a few extra layers of complexity, particularly if you use some NAT or tunnel features. + +**Second Method:** (Common for Businesses) + +In order to have full control and make use of multiple static public IP addresses, your VyOS will have to initiate the PPPoE connection and control it. +In order for this method to work, you will have to figure out how to make your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL Transceiver device to connect between the Ethernet link of your VyOS and the phone cable. +Once your DSL Transceiver is in Bridge Mode, you should get no IP address from it. +Please make sure you connect to the Ethernet Port 1 if your DSL Transeiver has a switch, as some of them only work this way. +Once you have an Ethernet device connected, i.e. eth0, then you can configure it to open the PPPoE session for you and your DSL Transceiver (Modem/Router) just acts to translate your messages in a way that vDSL/aDSL understands. + +**Here is an example configuration:** + +.. code-block:: none + + set interface ethernet eth0 description "DSL Modem" + set interface ethernet eth0 duplex auto + set interface ethernet eth0 smp_affinity auto + set interface ethernet eth0 speed auto + set interface ethernet eth0 pppoe 0 default-route auto + set interface ethernet eth0 pppoe 0 mtu 1492 + set interface ethernet eth0 pppoe 0 name-server auto + set interface ethernet eth0 pppoe 0 user-id <PPPoE Username> + set interface ethernet eth0 pppoe 0 password <PPPoE Password> + + +* You should add a firewall to your configuration above as well by assigning it to the pppoe0 itself as shown here: + +.. code-block:: none + + set interface ethernet eth0 pppoe 0 firewall in name NET-IN + set interface ethernet eth0 pppoe 0 firewall local name NET-LOCAL + set interface ethernet eth0 pppoe 0 firewall out name NET-OUT + +* You need your PPPoE credentials from your DSL ISP in order to configure this. The usual username is in the form of name@host.net but may vary depending on ISP. +* The largest MTU size you can use with DSL is 1492 due to PPPoE overhead. If you are switching from a DHCP based ISP like cable then be aware that things like VPN links may need to have their MTU sizes adjusted to work within this limit. +* With the ``default-route`` option set to ``auto``, VyOS will only add the Default Gateway you receive from your DSL ISP to the routing table if you have no other WAN connections. If you wish to use a Dual WAN connection, change the ``default-route`` option to ``force``. + +Handling and troubleshooting +---------------------------- + +You can test connecting and disconnecting with the below commands: + +.. code-block:: none + + disconnect interface 0 + connect interface 0 + + +You can check the PPPoE connection logs with the following: + +This command shows the current statistics, status and some of the settings (i.e. MTU) for the current connection on pppoe0. + +.. code-block:: none + + show interfaces pppoe 0 + +This command shows the entire log for the PPPoE connection starting with the oldest data. Scroll down with the <space> key to reach the end where the current data is. + +.. code-block:: none + + show interfaces pppoe 0 log + + +This command shows the same log as without the 'tail' option but only starts with the last few lines and continues to show added lines until you exit with ``Ctrl + x`` + +.. code-block:: none + + show interfaces pppoe 0 log tail + +.. _RFC1918: https://tools.ietf.org/html/rfc1918 diff --git a/docs/configuration/interfaces/index.rst b/docs/configuration/interfaces/index.rst new file mode 100644 index 00000000..e22c8708 --- /dev/null +++ b/docs/configuration/interfaces/index.rst @@ -0,0 +1,199 @@ +########## +Interfaces +########## + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + bonding + bridge + dummy + ethernet + l2tpv3 + openvpn + tunnel + vxlan + wireguard + wireless + + +.. _interfaces-addresses: + +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:: none + + 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:: none + + 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:: none + + 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 :ref:`interfaces-tunnel`. + +The command is `set interfaces $type $name address $address`. Examples: + +.. code-block:: none + + 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:: none + + 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:: none + + 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:: none + + set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64 + set interfaces pseudo-ethernet peth0 ipv6 address eui64 2001:db8:aa::/64 + + +Router Advertisements +********************* + +Router advertisements are described in `RFC4861 section 4.2`_. They are part of what is known as SLAAC (Stateless Address Autoconfiguration). + +To enable or disable, use: + +.. code-block:: none + + set interfaces <interface> ipv6 router-advert send-advert <true or false> + + +To set the options described in "Router Advertisement Message Format": + +.. code-block:: none + + vyos@vyos# set interfaces <interface> ipv6 router-advert + Possible completions: + cur-hop-limit Value to be placed in the "Current Hop Limit" field in RAs + default-lifetime Value to be placed in "Router Lifetime" field in RAs + default-preference Default router preference + link-mtu Value of link MTU to place in RAs + managed-flag Value for "managed address configuration" flag in RAs + max-interval Maximum interval between unsolicited multicast RAs + min-interval Minimum interval between unsolicited multicast RAs + + name-server IPv6 address of a Recursive DNS Server + other-config-flag Value to be placed in the "other configuration" flag in RAs + +> prefix IPv6 prefix to be advertised in Router Advertisements (RAs) + reachable-time Value to be placed in "Reachable Time" field in RAs + retrans-timer Value to place in "Retrans Timer" field in RAs. + send-advert Enable/disable sending RAs + + +**Prefix Information** + +Prefix information is described in `RFC4861 section 4.6.2`_ + +.. code-block:: none + + vyos@vyos# set interfaces <interface> ipv6 router-advert prefix <h:h:h:h:h:h:h:h/x> + Possible completions: + autonomous-flag Whether prefix can be used for address auto-configuration + on-link-flag Flag that prefix can be used for on-link determination + preferred-lifetime Time in seconds that the prefix will remain preferred + valid-lifetime Time in seconds that the prefix will remain valid + +**Receiving Router Advertisements** + +To receive and accept RAs on an interface, you need to enable it with the following configuration command + +.. code-block:: none + + vyos@vyos# set system sysctl custom net.ipv6.conf.<interface name>.accept_ra value 2 + + +.. _`RFC4861 section 4.6.2`: https://tools.ietf.org/html/rfc4861#section-4.6.2 +.. _`RFC4861 section 4.2`: https://tools.ietf.org/html/rfc4861#section-4.2 +.. _RFC4862: https://tools.ietf.org/html/rfc4862 +.. _RFC4291: http://tools.ietf.org/html/rfc4291#section-2.5.1 diff --git a/docs/configuration/interfaces/l2tpv3.rst b/docs/configuration/interfaces/l2tpv3.rst new file mode 100644 index 00000000..4514412d --- /dev/null +++ b/docs/configuration/interfaces/l2tpv3.rst @@ -0,0 +1,119 @@ +.. _l2tpv3-interface: + +L2TPv3 Interfaces +----------------- + +L2TPv3 is a pseudowire protocol, you can read more about here `Wikipedia L2TPv3`_ or `RFC3921`_ + +L2TPv3 can transport any traffic including ethernet frames. L2TPv2 is limited to PPP. + + +L2TPv3 over IP +^^^^^^^^^^^^^^ + +.. code-block:: none + + # show interfaces l2tpv3 + l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + encapsulation ip + local-ip 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote-ip 203.0.113.24 + session-id 100 + tunnel-id 200 + } + +Inverse configuration has to be applied to the remote side. + +L2TPv3 over UDP +^^^^^^^^^^^^^^^ + +UDP mode works better with NAT: + +* Set local-ip to your local IP (LAN). +* Add a forwarding rule matching UDP port on your internet router. + +.. code-block:: none + + # show interfaces l2tpv3 + l2tpv3 l2tpeth10 { + address 192.168.37.1/27 + destination-port 9001 + encapsulation udp + local-ip 192.0.2.1 + peer-session-id 100 + peer-tunnel-id 200 + remote-ip 203.0.113.24 + session-id 100 + source-port 9000 + tunnel-id 200 + } + +To create more than one tunnel, use distinct UDP ports. + + +L2TPv3 over IPSec, L2 VPN (bridge) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This is the LAN extension use case. The eth0 port of the distant VPN peers will be directly connected like if there was a switch between them. + +IPSec: + +.. code-block:: none + + set vpn ipsec ipsec-interfaces <VPN-interface> + set vpn ipsec esp-group test-ESP-1 compression 'disable' + set vpn ipsec esp-group test-ESP-1 lifetime '3600' + set vpn ipsec esp-group test-ESP-1 mode 'transport' + set vpn ipsec esp-group test-ESP-1 pfs 'enable' + set vpn ipsec esp-group test-ESP-1 proposal 1 encryption 'aes128' + set vpn ipsec esp-group test-ESP-1 proposal 1 hash 'sha1' + set vpn ipsec ike-group test-IKE-1 ikev2-reauth 'no' + set vpn ipsec ike-group test-IKE-1 key-exchange 'ikev1' + set vpn ipsec ike-group test-IKE-1 lifetime '3600' + set vpn ipsec ike-group test-IKE-1 proposal 1 dh-group '5' + set vpn ipsec ike-group test-IKE-1 proposal 1 encryption 'aes128' + set vpn ipsec ike-group test-IKE-1 proposal 1 hash 'sha1' + set vpn ipsec site-to-site peer <peer-ip> authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer <peer-ip> authentication pre-shared-secret <pre-shared-key> + set vpn ipsec site-to-site peer <peer-ip> connection-type 'initiate' + set vpn ipsec site-to-site peer <peer-ip> ike-group 'test-IKE-1' + set vpn ipsec site-to-site peer <peer-ip> ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer <peer-ip> local-address <local-ip> + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 allow-nat-networks 'disable' + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 allow-public-networks 'disable' + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 esp-group 'test-ESP-1' + set vpn ipsec site-to-site peer <peer-ip> tunnel 1 protocol 'l2tp' + +Bridge: + +.. code-block:: none + + set interfaces bridge br0 description 'L2 VPN Bridge' + # remote side in this example: + # set interfaces bridge br0 address '172.16.30.18/30' + set interfaces bridge br0 address '172.16.30.17/30' + set interfaces ethernet eth0 bridge-group bridge 'br0' + set interfaces ethernet eth0 description 'L2 VPN Physical port' + +L2TPv3: + +.. code-block:: none + + set interfaces l2tpv3 l2tpeth0 bridge-group bridge 'br0' + set interfaces l2tpv3 l2tpeth0 description 'L2 VPN Tunnel' + set interfaces l2tpv3 l2tpeth0 destination-port '5000' + set interfaces l2tpv3 l2tpeth0 encapsulation 'ip' + set interfaces l2tpv3 l2tpeth0 local-ip <local-ip> + set interfaces l2tpv3 l2tpeth0 mtu '1500' + set interfaces l2tpv3 l2tpeth0 peer-session-id '110' + set interfaces l2tpv3 l2tpeth0 peer-tunnel-id '10' + set interfaces l2tpv3 l2tpeth0 remote-ip <peer-ip> + set interfaces l2tpv3 l2tpeth0 session-id '110' + set interfaces l2tpv3 l2tpeth0 source-port '5000' + set interfaces l2tpv3 l2tpeth0 tunnel-id '10' + +.. _`Wikipedia L2TPv3`: http://en.wikipedia.org/wiki/L2TPv3 +.. _`RFC3921`: https://tools.ietf.org/html/rfc3931
\ No newline at end of file diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst new file mode 100644 index 00000000..b2559c95 --- /dev/null +++ b/docs/configuration/interfaces/openvpn.rst @@ -0,0 +1,468 @@ +.. _openvpn: + +####### +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. + +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 + +Disadvantages are: + +* It's slower than IPsec due to higher protocol overhead and the fact it runs + in user mode while IPsec, on Linux, is in kernel mode + +* None of the operating systems have client software installed by default + +In the VyOS CLI, a key point often overlooked is that rather than being +configured using the `set vpn` stanza, OpenVPN is configured as a network +interface using `set interfaces openvpn`. + +OpenVPN Site-To-Site +#################### + +While many are aware of OpenVPN as a Client VPN solution, it is often +overlooked as a site-to-site VPN solution due to lack of support for this mode +in many router platforms. + +Site-to-site mode supports x.509 but doesn't require it and can also work with +static keys, which is simpler in many cases. In this example, we'll configure +a simple site-to-site OpenVPN tunnel using a 2048-bit pre-shared key. + +First, one one of the systems generate the key using the operational command +``generate openvpn key <filename>``. This will generate a key with the name +provided in the `/config/auth/` directory. Once generated, you will need to +copy this key to the remote router. + +In our example, we used the filename `openvpn-1.key` which we will reference +in our configuration. + +* The public IP address of the local side of the VPN will be 198.51.100.10 +* The remote will be 203.0.113.11 +* The tunnel will use 10.255.1.1 for the local IP and 10.255.1.2 for the remote. +* OpenVPN allows for either TCP or UDP. UDP will provide the lowest latency, + while TCP will work better for lossy connections; generally UDP is preferred + when possible. +* The official port for OpenVPN is 1194, which we reserve for client VPN; we + will use 1195 for site-to-site VPN. +* The `persistent-tunnel` directive will allow us to configure tunnel-related + attributes, such as firewall policy as we would on any normal network + interface. +* If known, the IP of the remote router can be configured using the + `remote-host` directive; if unknown, it can be omitted. We will assume a + dynamic IP for our remote router. + +Local Configuration: + +.. code-block:: none + + 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:: none + + 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:: none + + 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:: none + + 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:: none + + set protocols static interface-route 10.1.0.0/16 next-hop-interface vtun1 + +Remote Configuration: + +.. code-block:: none + + 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 revocation 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. + + +.. note:: Using **openvpn-option -reneg-sec** can be tricky. This option is used to renegotiate data channel after n seconds. When used at both server and client, the lower value will trigger the renegotiation. If you set it to 0 on one side of the connection (to disable it), the chosen value on the other side will determine when the renegotiation will occur. + + +.. code-block:: none + + 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:: none + + 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:: none + + 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:: none + + 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:: none + + set protocols static interface-route 10.23.0.0/20 next-hop-interface vtun10 + + +Client Authentication +===================== + +OpenLDAP +-------- + +Enterprise installations usually ship a kind of directory service which is used +to have a single password store for all employees. VyOS and OpenVPN support using +LDAP/AD as single user backend. + +Authentication is done by using the ``openvpn-auth-ldap.so`` plugin which is +shipped with every VyOS installation. A dedicated configuration file is required. +It is best practise to store it in ``/config`` to survive image updates + +.. code-block:: none + + set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" + +The required config file may look like: + +.. code-block:: none + + <LDAP> + # LDAP server URL + URL ldap://ldap.example.com + # Bind DN (If your LDAP server doesn't support anonymous binds) + BindDN cn=LDAPUser,dc=example,dc=com + # Bind Password password + Password S3cr3t + # Network timeout (in seconds) + Timeout 15 + </LDAP> + + <Authorization> + # Base DN + BaseDN "ou=people,dc=example,dc=com" + # User Search Filter + SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" + # Require Group Membership - allow all users + RequireGroup false + </Authorization> + +Active Directory +---------------- + +Despite the fact that AD is a superset of LDAP + +.. code-block:: none + + <LDAP> + # LDAP server URL + URL ldap://dc01.example.com + # Bind DN (If your LDAP server doesn’t support anonymous binds) + BindDN CN=LDAPUser,DC=example,DC=com + # Bind Password + Password mysecretpassword + # Network timeout (in seconds) + Timeout 15 + # Enable Start TLS + TLSEnable no + # Follow LDAP Referrals (anonymously) + FollowReferrals no + </LDAP> + + <Authorization> + # Base DN + BaseDN "DC=example,DC=com" + # User Search Filter, user must be a member of the VPN AD group + SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" + # Require Group Membership + RequireGroup false # already handled by SearchFilter + <Group> + BaseDN "OU=Groups,DC=example,DC=com" + SearchFilter "(|(cn=VPN))" + MemberAttribute memberOf + </Group> + </Authorization> + +If you only want to check if the user account is enabled and can authenticate +(against the primary group) the following snipped is sufficient: + +.. code-block:: none + + <LDAP> + URL ldap://dc01.example.com + BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com + Password ThisIsTopSecret + Timeout 15 + TLSEnable no + FollowReferrals no + </LDAP> + + <Authorization> + BaseDN "DC=example,DC=com" + SearchFilter "sAMAccountName=%u" + RequireGroup false + </Authorization> + +A complete LDAP auth OpenVPN configuration could look like the following example: + +.. code-block:: none + + vyos@vyos# show interfaces openvpn + openvpn vtun0 { + mode server + openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" + openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" + openvpn-option "--push redirect-gateway" + openvpn-option --duplicate-cn + openvpn-option --client-cert-not-required + openvpn-option --comp-lzo + openvpn-option --persist-key + openvpn-option --persist-tun + server { + domain-name example.com + max-connections 5 + name-server 1.1.1.1 + name-server 9.9.9.9 + subnet 172.18.100.128/29 + } + tls { + ca-cert-file /config/auth/ca.crt + cert-file /config/auth/server.crt + dh-file /config/auth/dh1024.pem + key-file /config/auth/server.key + } + } + +OpenVPN Client +############## + +VyOS can not only act as an OpenVPN site-to-site or Server for multiple clients. +You can indeed also configure any VyOS OpenVPN interface as an OpenVPN client +connecting to a VyOS OpenVPN server or any other OpenVPN server. + +Given the following example we have one VyOS router acting as OpenVPN server +and another VyOS router acting as OpenVPN client. The Server also pushes a +static client IP address to the OpenVPN client. Remember, clients are identified +using their CN attribute in the SSL certificate. + + +Server +====== + +.. code-block:: none + + set interfaces openvpn vtun10 encryption 'aes256' + set interfaces openvpn vtun10 hash 'sha512' + set interfaces openvpn vtun10 local-host '172.18.201.10' + set interfaces openvpn vtun10 local-port '1194' + set interfaces openvpn vtun10 mode 'server' + set interfaces openvpn vtun10 persistent-tunnel + set interfaces openvpn vtun10 protocol 'udp' + set interfaces openvpn vtun10 server client client1 ip '10.10.0.10' + set interfaces openvpn vtun10 server domain-name 'vyos.net' + set interfaces openvpn vtun10 server max-connections '250' + set interfaces openvpn vtun10 server name-server '172.16.254.30' + set interfaces openvpn vtun10 server subnet '10.10.0.0/24' + set interfaces openvpn vtun10 server topology 'subnet' + set interfaces openvpn vtun10 tls ca-cert-file '/config/auth/ca.crt' + set interfaces openvpn vtun10 tls cert-file '/config/auth/server.crt' + set interfaces openvpn vtun10 tls dh-file '/config/auth/dh.pem' + set interfaces openvpn vtun10 tls key-file '/config/auth/server.key' + set interfaces openvpn vtun10 use-lzo-compression + +Client +====== + +.. code-block:: none + + set interfaces openvpn vtun10 encryption 'aes256' + set interfaces openvpn vtun10 hash 'sha512' + set interfaces openvpn vtun10 mode 'client' + set interfaces openvpn vtun10 persistent-tunnel + set interfaces openvpn vtun10 protocol 'udp' + set interfaces openvpn vtun10 remote-host '172.18.201.10' + set interfaces openvpn vtun10 remote-port '1194' + set interfaces openvpn vtun10 tls ca-cert-file '/config/auth/ca.crt' + set interfaces openvpn vtun10 tls cert-file '/config/auth/client1.crt' + set interfaces openvpn vtun10 tls key-file '/config/auth/client1.key' + set interfaces openvpn vtun10 use-lzo-compression + +Options +------- + +We do not have CLI nodes for every single OpenVPN options. If an option is +missing, a feature request should be opened at https://phabricator.vyos.net so +all users can benefit from it. + +If you are a hacker or want to try on your own we support passing raw OpenVPN +options to OpenVPN. + +.. code-block:: none + + set interfaces openvpn vtun10 openvpn-option 'persistent-key' + +Will add `persistent-key` at the end of the generated OpenVPN configuration. +Please use this only as last resort - things might break and OpenVPN won't start +if you pass invalid options/syntax. + +Troubleshooting +############### + +VyOS provides some operational commands on OpenVPN. + +Check status +============ + +The following commands let you check tunnel status. + +.. opcmd:: show openvpn client status + + Use this command to check the tunnel status for OpenVPN client. + +.. opcmd:: show openvpn server status + + Use this command to check the tunnel status for OpenVPN server. + +.. opcmd:: show openvpn site-to-site status + + Use this command to check the tunnel status for OpenVPN site-to-site. + + +Reset OpenVPN +============= + +The following commands let you reset OpenVPN. + +.. opcmd:: reset openvpn client <text> + + Use this command to reset specified OpenVPN client. + +.. opcmd:: reset openvpn interface <interface> + + Uset this command to reset the OpenVPN process on a specific interface. + + diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst new file mode 100644 index 00000000..43c217a0 --- /dev/null +++ b/docs/configuration/interfaces/tunnel.rst @@ -0,0 +1,237 @@ +.. _interfaces-tunnel: + +Tunnel Interfaces +================= + +This article touches on 'classic' IP tunneling protocols. + +GRE is often seen as a one size fits all solution when it comes to classic IP tunneling protocols, and for a good reason. +However, there are more specialized options, and many of them are supported by VyOS. There are also rather obscure GRE options that can be useful. + +All those protocols are grouped under 'interfaces tunnel' in VyOS. Let's take a closer look at the protocols and options currently supported by VyOS. + +IPIP +---- + +This is one of the simplest types of tunnels, as defined by RFC2003_. +It takes an IPv4 packet and sends it as a payload of another IPv4 packet. For this reason, there are no other configuration options for this kind of tunnel. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation ipip + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 203.0.113.20 + set interfaces tunnel tun0 address 192.168.100.200 + +IP6IP6 +------ + +This is the IPv6 counterpart of IPIP. I'm not aware of an RFC that defines this encapsulation specifically, but it's a natural specific case of IPv6 encapsulation mechanisms described in RFC2473_. + +It's not likely that anyone will need it any time soon, but it does exist. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation ipip + set interfaces tunnel tun0 local-ip 2001:db8:aa::1/64 + set interfaces tunnel tun0 remote-ip 2001:db8:aa::2/64 + set interfaces tunnel tun0 address 2001:db8:bb::1/64 + +IPIP6 +----- + +In the future this is expected to be a very useful protocol (though there are `other proposals`_). + +As the name implies, it's IPv4 encapsulated in IPv6, as simple as that. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation ipip6 + set interfaces tunnel tun0 local-ip 2001:db8:aa::1/64 + set interfaces tunnel tun0 remote-ip 2001:db8:aa::2/64 + set interfaces tunnel tun0 address 192.168.70.80 + +6in4 (SIT) +---------- + + +6in4 uses tunneling to encapsulate IPv6 traffic over IPv4 links as defined in RFC4213_. +The 6in4 traffic is sent over IPv4 inside IPv4 packets whose IP headers have the IP protocol number set to 41. +This protocol number is specifically designated for IPv6 encapsulation, the IPv4 packet header is immediately followed by the IPv6 packet being carried. +The encapsulation overhead is the size of the IPv4 header of 20 bytes, therefore with an MTU of 1500 bytes, IPv6 packets of 1480 bytes can be sent without fragmentation. This tunneling technique is frequently used by IPv6 tunnel brokers like `Hurricane Electric`_. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 encapsulation sit + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 2001:db8:bb::1/64 + +A full example of a Tunnelbroker.net config can be found at :ref:`here <examples-tunnelbroker-ipv6>`. + +Generic Routing Encapsulation (GRE) +----------------------------------- + +A GRE tunnel operates at layer 3 of the OSI model and is repsented by IP protocol 47. The +main benefit of a GRE tunnel is that you are able to route traffic across disparate networks. +GRE also supports multicast traffic and supports routing protocols that leverage multicast to +form neighbor adjacencies. + +Configuration +^^^^^^^^^^^^^ + +A basic configuration requires a tunnel source (local-ip), a tunnel destination (remote-ip), +an encapsulation type (gre), and an address (ipv4/ipv6). Below is a configuration example +taken from a VyOS router and a Cisco IOS router. The main difference between these two +configurations is that VyOS requires you explicitly configure the encapsulation type. +The Cisco router defaults to 'gre ip' otherwise it would have to be configured as well. + +**VyOS Router:** + +.. code-block:: none + + set interfaces tunnel tun100 address '10.0.0.1/30' + set interfaces tunnel tun100 encapsulation 'gre' + set interfaces tunnel tun100 local-ip '198.51.100.2' + set interfaces tunnel tun100 remote-ip '203.0.113.10' + +**Cisco IOS Router:** + +.. code-block:: none + + interface Tunnel100 + ip address 10.0.0.2 255.255.255.252 + tunnel source 203.0.113.10 + tunnel destination 198.51.100.2 + + +Tunnel keys +^^^^^^^^^^^ + +GRE is also the only classic protocol that allows creating multiple tunnels with the same source and destination due to its support for tunnel keys. Despite its name, this feature has nothing to do with security: it's simply an identifier that allows routers to tell one tunnel from another. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 10.40.50.60/24 + set interfaces tunnel tun0 parameters ip key 10 + +.. code-block:: none + + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 172.16.17.18/24 + set interfaces tunnel tun0 parameters ip key 20 + + +GRE-Bridge +^^^^^^^^^^ +While normal GRE is for layer 3, GRE-Bridge is for layer 2. GRE-Bridge can encapsulate Ethernet frames, thus it can be bridged with other interfaces to create datalink layer segments that span multiple remote sites. + +Layer 2 GRE example: + +.. code-block:: none + + set interfaces bridge br0 + set interfaces tunnel tun0 encapsulation gre-bridge + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 parameters ip bridge-group bridge br0 + set interfaces ethernet eth1 bridge-group br0 + +As you can see, the bridge-group option for tunnels is in a rather unusual place, different from all other interfaces. + + +Troubleshooting +^^^^^^^^^^^^^^^ + +GRE is a well defined standard that is common in most networks. While not inherently difficult +to configure there are a couple of things to keep in mind to make sure the configuration performs +as expected. A common cause for GRE tunnels to fail to come up correctly include ACL or Firewall +configurations that are discarding IP protocol 47 or blocking your source/desintation traffic. + +**1. Confirm IP connectivity between tunnel local-ip and remote-ip:** + +.. code-block:: none + + vyos@vyos:~$ ping 203.0.113.10 interface 198.51.100.2 count 4 + PING 203.0.113.10 (203.0.113.10) from 198.51.100.2 : 56(84) bytes of data. + 64 bytes from 203.0.113.10: icmp_seq=1 ttl=254 time=0.807 ms + 64 bytes from 203.0.113.10: icmp_seq=2 ttl=254 time=1.50 ms + 64 bytes from 203.0.113.10: icmp_seq=3 ttl=254 time=0.624 ms + 64 bytes from 203.0.113.10: icmp_seq=4 ttl=254 time=1.41 ms + + --- 203.0.113.10 ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3007ms + rtt min/avg/max/mdev = 0.624/1.087/1.509/0.381 ms + +**2. Confirm the link type has been set to GRE:** + +.. code-block:: none + + vyos@vyos:~$ show interfaces tunnel tun100 + tun100@NONE: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1476 qdisc noqueue state UNKNOWN group default qlen 1000 + link/gre 198.51.100.2 peer 203.0.113.10 + inet 10.0.0.1/30 brd 10.0.0.3 scope global tun100 + valid_lft forever preferred_lft forever + inet6 fe80::5efe:c612:2/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 2183 27 0 0 0 0 + TX: bytes packets errors dropped carrier collisions + 836 9 0 0 0 0 + +**3. Confirm IP connectivity across the tunnel:** + +.. code-block:: none + + vyos@vyos:~$ ping 10.0.0.2 interface 10.0.0.1 count 4 + PING 10.0.0.2 (10.0.0.2) from 10.0.0.1 : 56(84) bytes of data. + 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=1.05 ms + 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=1.88 ms + 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=1.98 ms + 64 bytes from 10.0.0.2: icmp_seq=4 ttl=255 time=1.98 ms + + --- 10.0.0.2 ping statistics --- + 4 packets transmitted, 4 received, 0% packet loss, time 3008ms + rtt min/avg/max/mdev = 1.055/1.729/1.989/0.395 ms + +Virtual Tunnel Interface (VTI) +------------------------------ + +Set Virtual Tunnel Interface + +.. code-block:: none + + set interfaces vti vti0 address 192.168.2.249/30 + set interfaces vti vti0 address 2001:db8:2::249/64 + +Results in: + +.. code-block:: none + + vyos@vyos# show interfaces vti + vti vti0 { + address 192.168.2.249/30 + address 2001:db8:2::249/64 + description "Description" + } + + +.. _RFC2003: https://tools.ietf.org/html/rfc2003 +.. _RFC2473: https://tools.ietf.org/html/rfc2473 +.. _`other proposals`: https://www.isc.org/downloads/aftr +.. _RFC4213: https://tools.ietf.org/html/rfc4213 +.. _`Hurricane Electric`: https://tunnelbroker.net/ diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst new file mode 100644 index 00000000..e3eb5c43 --- /dev/null +++ b/docs/configuration/interfaces/vxlan.rst @@ -0,0 +1,305 @@ +VXLAN +----- + +VXLAN is an overlaying Ethernet over IP protocol. +It is described in RFC7348_. + +If configuring VXLAN in a VyOS virtual machine, ensure that MAC spoofing +(Hyper-V) or Forged Transmits (ESX) are permitted, otherwise forwarded frames +may be blocked by the hypervisor. + +Multicast VXLAN +^^^^^^^^^^^^^^^^ + +Example Topology: + +PC4 - Leaf2 - Spine1 - Leaf3 - PC5 + +PC4 has IP 10.0.0.4/24 and PC5 has IP 10.0.0.5/24, so they believe they are in +the same broadcast domain. + +Let's assume PC4 on Leaf2 wants to ping PC5 on Leaf3. Instead of setting Leaf3 +as our remote end manually, Leaf2 encapsulates the packet into a UDP-packet and +sends it to its designated multicast-address via Spine1. When Spine1 receives +this packet it forwards it to all other Leafs who has joined the same +multicast-group, in this case Leaf3. When Leaf3 receives the packet it forwards +it, while at the same time learning that PC4 is reachable behind Leaf2, because +the encapsulated packet had Leaf2's IP-address set as source IP. + +PC5 receives the ping echo, responds with an echo reply that Leaf3 receives and +this time forwards to Leaf2's unicast address directly because it learned the +location of PC4 above. When Leaf2 receives the echo reply from PC5 it sees that +it came from Leaf3 and so remembers that PC5 is reachable via Leaf3. + +Thanks to this discovery, any subsequent traffic between PC4 and PC5 will not +be using the multicast-address between the Leafs as they both know behind which +Leaf the PCs are connected. This saves traffic as less multicast packets sent +reduces the load on the network, which improves scalability when more Leafs are +added. + +For optimal scalability Multicast shouldn't be used at all, but instead use BGP +to signal all connected devices between leafs. Unfortunately, VyOS does not yet +support this. + +Configuration commands +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + interfaces + vxlan <vxlan[0-16777215]> + address # IP address of the VXLAN interface + bridge-group # Configure a L2 bridge-group + description # Description + group <ipv4> # IPv4 Multicast group address (required) + ip # IPv4 routing options + ipv6 # IPv6 routing options + link <dev> # IP interface for underlay of this vxlan overlay (optional) + mtu # MTU + policy # Policy routing options + remote # Remote address of the VXLAN tunnel, used for PTP instead of multicast + vni <1-16777215> # Virtual Network Identifier (required) + +Configuration Example +^^^^^^^^^^^^^^^^^^^^^ + +The setup is this: + +Leaf2 - Spine1 - Leaf3 + +Spine1 is a Cisco IOS router running version 15.4, Leaf2 and Leaf3 is each a +VyOS router running 1.2. + +This topology was built using GNS3. + +Topology: + +.. code-block:: none + + Spine1: + fa0/2 towards Leaf2, IP-address: 10.1.2.1/24 + fa0/3 towards Leaf3, IP-address: 10.1.3.1/24 + + Leaf2: + Eth0 towards Spine1, IP-address: 10.1.2.2/24 + Eth1 towards a vlan-aware switch + + Leaf3: + Eth0 towards Spine1, IP-address 10.1.3.3/24 + Eth1 towards a vlan-aware switch + +Spine1 Configuration: + +.. code-block:: none + + conf t + ip multicast-routing + ! + interface fastethernet0/2 + ip address 10.1.2.1 255.255.255.0 + ip pim sparse-dense-mode + ! + interface fastethernet0/3 + ip address 10.1.3.1 255.255.255.0 + ip pim sparse-dense-mode + ! + router ospf 1 + network 10.0.0.0 0.255.255.255 area 0 + +Multicast-routing is required for the leafs to forward traffic between each +other in a more scalable way. This also requires PIM to be enabled towards the +Leafs so that the Spine can learn what multicast groups each Leaf expect traffic +from. + +Leaf2 configuration: + +.. code-block:: none + + set interfaces ethernet eth0 address '10.1.2.2/24' + set protocols ospf area 0 network '10.0.0.0/8' + + ! Our first vxlan interface + set interfaces bridge br241 address '172.16.241.1/24' + set interfaces ethernet eth1 vif 241 bridge-group bridge 'br241' + set interfaces vxlan vxlan241 bridge-group bridge 'br241' + set interfaces vxlan vxlan241 group '239.0.0.241' + set interfaces vxlan vxlan241 link 'eth0' + set interfaces vxlan vxlan241 vni '241' + + ! Our seconds vxlan interface + set interfaces bridge br242 address '172.16.242.1/24' + set interfaces ethernet eth1 vif 242 bridge-group bridge 'br242' + set interfaces vxlan vxlan242 bridge-group bridge 'br242' + set interfaces vxlan vxlan242 group '239.0.0.242' + set interfaces vxlan vxlan242 link 'eth0' + set interfaces vxlan vxlan242 vni '242' + +Leaf3 configuration: + +.. code-block:: none + + set interfaces ethernet eth0 address '10.1.3.3/24' + set protocols ospf area 0 network '10.0.0.0/8' + + ! Our first vxlan interface + set interfaces bridge br241 address '172.16.241.1/24' + set interfaces ethernet eth1 vif 241 bridge-group bridge 'br241' + set interfaces vxlan vxlan241 bridge-group bridge 'br241' + set interfaces vxlan vxlan241 group '239.0.0.241' + set interfaces vxlan vxlan241 link 'eth0' + set interfaces vxlan vxlan241 vni '241' + + ! Our seconds vxlan interface + set interfaces bridge br242 address '172.16.242.1/24' + set interfaces ethernet eth1 vif 242 bridge-group bridge 'br242' + set interfaces vxlan vxlan242 bridge-group bridge 'br242' + set interfaces vxlan vxlan242 group '239.0.0.242' + set interfaces vxlan vxlan242 link 'eth0' + set interfaces vxlan vxlan242 vni '242' + +As you can see, Leaf2 and Leaf3 configuration is almost identical. There are +lots of commands above, I'll try to into more detail below, command +descriptions are placed under the command boxes: + +.. code-block:: none + + set interfaces bridge br241 address '172.16.241.1/24' + +This commands creates a bridge that is used to bind traffic on eth1 vlan 241 +with the vxlan241-interface. The IP-address is not required. It may however be +used as a default gateway for each Leaf which allows devices on the vlan to +reach other subnets. This requires that the subnets are redistributed by OSPF +so that the Spine will learn how to reach it. To do this you need to change the +OSPF network from '10.0.0.0/8' to '0.0.0.0/0' to allow 172.16/12-networks to be +advertised. + +.. code-block:: none + + set interfaces ethernet eth1 vif 241 bridge-group bridge 'br241' + set interfaces vxlan vxlan241 bridge-group bridge 'br241' + +Binds eth1 vif 241 and vxlan241 to each other by putting them in the same +bridge-group. Internal VyOS requirement. + +.. code-block:: none + + set interfaces vxlan vxlan241 group '239.0.0.241' + +The multicast-group used by all Leafs for this vlan extension. Has to be the +same on all Leafs that has this interface. + +.. code-block:: none + + set interfaces vxlan vxlan241 link 'eth0' + +Sets the interface to listen for multicast packets on. Could be a loopback, not +yet tested. + +.. code-block:: none + + set interfaces vxlan vxlan241 vni '241' + +Sets the unique id for this vxlan-interface. Not sure how it correlates with +multicast-address. + +.. code-block:: none + + set interfaces vxlan vxlan241 remote-port 12345 + +The destination port used for creating a VXLAN interface in Linux defaults to +its pre-standard value of 8472 to preserve backwards compatibility. A +configuration directive to support a user-specified destination port to override +that behavior is available using the above command. + +Older Examples +^^^^^^^^^^^^^^ + +Example for bridging normal L2 segment and vxlan overlay network, and using a +vxlan interface as routing interface. + +.. code-block:: none + + interfaces { + bridge br0 { + } + ethernet eth0 { + address dhcp + } + loopback lo { + } + vxlan vxlan0 { + bridge-group { + bridge br0 + } + group 239.0.0.1 + vni 0 + } + vxlan vxlan1 { + address 192.168.0.1/24 + link eth0 + group 239.0.0.1 + vni 1 + } + } + +Here is a working configuration that creates a VXLAN between two routers. Each +router has a VLAN interface (26) facing the client devices and a VLAN interface +(30) that connects it to the other routers. With this configuration, traffic +can flow between both routers' VLAN 26, but can't escape since there is no L3 +gateway. You can add an IP to a bridge-group to create a gateway. + +.. code-block:: none + + interfaces { + bridge br0 { + } + ethernet eth0 { + duplex auto + smp-affinity auto + speed auto + vif 26 { + bridge-group { + bridge br0 + } + } + vif 30 { + address 10.7.50.6/24 + } + } + loopback lo { + } + vxlan vxlan0 { + bridge-group { + bridge br0 + } + group 239.0.0.241 + vni 241 + } + } + +Unicast VXLAN +^^^^^^^^^^^^^ + +Alternative to multicast, the remote IPv4 address of the VXLAN tunnel can set directly. +Let's change the Multicast example from above: + + +.. code-block:: none + + # leaf2 and leaf3 + delete interfaces vxlan vxlan241 group '239.0.0.241' + delete interfaces vxlan vxlan241 link 'eth0' + + # leaf2 + set interface vxlan vxlan241 remote 10.1.3.3 + + # leaf3 + set interface vxlan vxlan241 remote 10.1.2.2 + +The default port udp is set to 8472. +It can be changed with ``set interface vxlan <vxlanN> remote-port <port>`` + + +.. target-notes:: + +.. _RFC7348: https://datatracker.ietf.org/doc/rfc7348/ diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst new file mode 100644 index 00000000..a7241613 --- /dev/null +++ b/docs/configuration/interfaces/wireguard.rst @@ -0,0 +1,148 @@ +.. _wireguard: + +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 +^^^^^^^^^^^^^ + +Wireguard requires the generation of a keypair, a private key which will decrypt +incoming traffic and a public key, which the peer(s) will use to encrypt traffic. + +Generate a keypair +~~~~~~~~~~~~~~~~~~ + +Generate the keypair, which creates a public and private part and stores it +within VyOS. +It will be used per default on any configured wireguard interface, even if +multiple interfaces are being configured. + +.. code-block:: none + + 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:: none + + wg01# run show wireguard pubkey + u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk= + +Wireguard Interface configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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:: none + + 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 + +.. note:: The `endpoint` must be an IP and not a fully qualified domain name (FQDN). Using a FQDN will result in unexpected behavior. + +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:: none + + 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:: none + + 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:: none + + wg01# run generate wireguard preshared-key + rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= + +Copy the key, as it is not stored on the local file system. Make sure you +distribute that key in a safe manner, it's a symmetric key, so only you and +your peer should have knowledge of its content. + +.. code-block:: none + + 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=' + +Operational commands +^^^^^^^^^^^^^^^^^^^^ + +**Show interface status** + +.. code-block:: none + + vyos@wg01# run show interfaces wireguard wg01 + + interface: wg01 + public key: xHvgSJC8RTClfvjc0oX6OALxU6GGLapjthjw7x82CSw= + private key: (hidden) + listening port: 12345 + + peer: 9Ek3R30mG6Vk+GHsENtPF0b9Ul+ftxx4dDBa1bdBxX8= + endpoint: 192.168.0.142:12345 + allowed ips: 10.2.0.0/24 + latest handshake: 4 minutes, 22 seconds ago + transfer: 860 B received, 948 B sent + +**Show public key of the default key** + +.. code-block:: none + + vyos@wg01# run show wireguard keypair pubkey default + FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM= + + +**Delete wireguard keypairs** + +.. code-block:: none + + vyos@wg01# wireguard keypair default + diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst new file mode 100644 index 00000000..a7e796e9 --- /dev/null +++ b/docs/configuration/interfaces/wireless.rst @@ -0,0 +1,55 @@ +Wireless Interfaces +------------------- +.. _interfaces-wireless: + +Wireless, for example WiFi 802.11 b/g/n, interfaces allow for connection to +WiFi networks or act as an access-point. +If your device is configurable it will appear as `wlan` in `show interfaces`. + +To be able to use the wireless interfaces you will first need to set a +regulatory domain with the country code of your locaion. + +.. code-block:: none + + set system wifi-regulatory-domain SE + +An example on how to set it up as an access point: + +.. code-block:: none + + set interfaces wireless wlan0 address '192.168.99.1/24' + set interfaces wireless wlan0 type access-point + set interfaces wireless wlan0 channel 1 + set interfaces wireless wlan0 ssid '<your ssid>' + set interfaces wireless wlan0 security wpa mode wpa2 + set interfaces wireless wlan0 security wpa cipher CCMP + set interfaces wireless wlan0 security wpa passphrase '<your passphrase>' + +Resulting in + +.. code-block:: none + + interfaces { + [...] + wireless wlan0 { + address 192.168.99.1/24 + channel 1 + mode g + security { + wpa { + cipher CCMP + mode wpa2 + passphrase "<your passphrase>" + } + } + ssid "<your ssid>" + type access-point + } + } + system { + [...] + wifi-regulatory-domain SE + } + +To get it to work as a access point with this configuration you will need +to set up a DHCP server to work with that network. diff --git a/docs/configuration/loadbalancing/index.rst b/docs/configuration/loadbalancing/index.rst new file mode 100644 index 00000000..cae2f6a5 --- /dev/null +++ b/docs/configuration/loadbalancing/index.rst @@ -0,0 +1,263 @@ +.. _load-balancing: + +WAN load balancing +================== + +Outbound traffic can be balanced between two or more outbound interfaces. +If a path fails, traffic is balanced across the remaining healthy paths, a recovered path is automatically added back to the routing table and used by the load balancer. +The load balancer automatically adds routes for each path to the routing table and balances traffic across the configured interfaces, determined by interface health and weight. + + +In a minimal, configuration the following must be provided: + + * a interface with a nexthop + * one rule with a LAN (inbound-interface) and the WAN (interface). + +lets assume we have two dhcp WAN interfaces and one LAN (eth2) + +.. code-block:: none + + set load-balancing wan interface-health eth0 nexthop 'dhcp' + set load-balancing wan interface-health eth1 nexthop 'dhcp' + set load-balancing wan rule 1 inbound-interface 'eth2' + set load-balancing wan rule 1 interface eth0 + set load-balancing wan rule 1 interface eth1 + +Balancing Rules +--------------- + +Interfaces, their weight and the type of traffic to be balanced are defined in numbered balancing rule sets. +The rule sets are executed in numerical order against outgoing packets. In case of a match the packet is sent through an interface specified in the matching rule. +If a packet doesn't match any rule it is sent by using the system routing table. Rule numbers can't be changed. + +Create a load balancing rule, rule can be a number between 1 and 9999: + +.. code-block:: none + + vyos@vyos# set load-balancing wan rule 1 + Possible completions: + description Description for this rule + > destination Destination + exclude Exclude packets matching this rule from wan load balance + failover Enable failover for packets matching this rule from wan load balance + inbound-interface Inbound interface name (e.g., "eth0") [REQUIRED] + +> interface Interface name [REQUIRED] + > limit Enable packet limit for this rule + per-packet-balancing Option to match traffic per-packet instead of the default, per-flow + protocol Protocol to match + > source Source information + +Interface weight +**************** + +Let's expand the example from above and add a weight to the interfaces. The bandwidth from eth0 is larger than eth1. +Per default outbound traffic is distributed randomly across available interfaces. Weights can be assigned to interfaces to influence the balancing. + +.. code-block:: none + + set load-balancing wan rule 1 interface eth0 weight 2 + set load-balancing wan rule 1 interface eth1 weight 1 + +66% traffic is routed to eth0 and eth1 get 33% of traffic. + +Rate limit +********** + +A packet rate limit can be set for a rule to apply the rule to traffic above or below a specified threshold. +To configure the rate limiting use: + +.. code-block:: none + + set load-balancing wan rule <rule> limit <parameter> + +* ``burst``: Number of packets allowed to overshoot the limit within ``period``. Default 5. +* ``period``: Time window for rate calculation. Possible values: ``second`` (one second), ``minute`` (one minute), ``hour`` (one hour). Default is ``second``. +* ``rate``: Number of packets. Default 5. +* ``threshold``: ``below`` or ``above`` the specified rate limit. + +Flow and packet-based balancing +******************************* + +Outgoing traffic is balanced in a flow-based manner. +A connection tracking table is used to track flows by their source address, destination address and port. +Each flow is assigned to an interface according to the defined balancing rules and subsequent packets are sent through the same interface. +This has the advantage that packets always arrive in order if links with different speeds are in use. + +Packet-based balancing can lead to a better balance across interfaces when out of order packets are no issue. Per-packet-based balancing can be set for a balancing rule with: + +.. code-block:: none + + set load-balancing wan rule <rule> per-packet-balancing + +Exclude traffic +*************** + +To exclude traffic from load balancing, traffic matching an exclude rule is not balanced but routed through the system routing table instead: + +.. code-block:: none + + set load-balancing wan rule <rule> exclude + + +Health checks +------------- + +The health of interfaces and paths assigned to the load balancer is periodically checked by sending ICMP packets (ping) to remote destinations, a TTL test or the execution of a user defined script. +If an interface fails the health check it is removed from the load balancer's pool of interfaces. To enable health checking for an interface: + +.. code-block:: none + + vyos@vyos# set load-balancing wan interface-health <interface> + Possible completions: + failure-count Failure count + nexthop Outbound interface nexthop address. Can be 'dhcp or ip address' [REQUIRED] + success-count Success count + +> test Rule number + +Specify nexthop on the path to destination, ``ipv4-address`` can be set to ``dhcp`` + +.. code-block:: none + + set load-balancing wan interface-health <interface> nexthop <ipv4-address> + +Set the number of health check failures before an interface is marked as unavailable, range for number is 1 to 10, default 1. +Or set the number of successful health checks before an interface is added back to the interface pool, range for number is 1 to 10, default 1. + +.. code-block:: none + + set load-balancing wan interface-health <interface> failure-count <number> + set load-balancing wan interface-health <interface> success-count <number> + +Each health check is configured in its own test, tests are numbered and processed in numeric order. +For multi target health checking multiple tests can be defined: + +.. code-block:: none + + vyos@vyos# set load-balancing wan interface-health eth1 test 0 + Possible completions: + resp-time Ping response time (seconds) + target Health target address + test-script Path to user defined script + ttl-limit Ttl limit (hop count) + type WLB test type + +* ``resp-time``: the maximum response time for ping in seconds. Range 1...30, default 5 +* ``target``: the target to be sent ICMP packets to, address can be an IPv4 address or hostname +* ``test-script``: A user defined script must return 0 to be considered successful and non-zero to fail. Scripts are located in /config/scripts, for different locations the full path needs to be provided +* ``ttl-limit``: For the UDP TTL limit test the hop count limit must be specified. The limit must be shorter than the path length, an ICMP time expired message is needed to be returned for a successful test. default 1 +* ``type``: Specify the type of test. type can be ping, ttl or a user defined script + +Source NAT rules +---------------- + +Per default, interfaces used in a load balancing pool replace the source IP of each outgoing packet with its own address to ensure that replies arrive on the same interface. +This works through automatically generated source NAT (SNAT) rules, these rules are only applied to balanced traffic. In cases where this behaviour is not desired, the automatic generation of SNAT rules can be disabled: + +.. code-block:: none + + set load-balancing wan disable-source-nat + +Sticky Connections +------------------ +Inbound connections to a WAN interface can be improperly handled when the reply is sent back to the client. + +.. image:: /_static/images/sticky-connections.jpg + :width: 80% + :align: center + + +Upon reception of an incoming packet, when a response is sent, it might be desired to ensure that it leaves from the same interface as the inbound one. +This can be achieved by enabling sticky connections in the load balancing: + +.. code-block:: none + + set load-balancing wan sticky-connections inbound + +Failover +-------- + +In failover mode, one interface is set to be the primary interface and other interfaces are secondary or spare. +Instead of balancing traffic across all healthy interfaces, only the primary interface is used and in case of failure, a secondary interface selected from the pool of available interfaces takes over. +The primary interface is selected based on its weight and health, others become secondary interfaces. +Secondary interfaces to take over a failed primary interface are chosen from the load balancer's interface pool, depending on their weight and health. +Interface roles can also be selected based on rule order by including interfaces in balancing rules and ordering those rules accordingly. To put the load balancer in failover mode, create a failover rule: + +.. code-block:: none + + set load-balancing wan rule <number> failover + +Because existing sessions do not automatically fail over to a new path, the session table can be flushed on each connection state change: + +.. code-block:: none + + set load-balancing wan flush-connections + +.. warning:: + + Flushing the session table will cause other connections to fall back from flow-based to packet-based balancing until each flow is reestablished. + +Script execution +---------------- + +A script can be run when an interface state change occurs. Scripts are run from /config/scripts, for a different location specify the full path: + +.. code-block:: none + + set load-balancing wan hook script-name + +Two environment variables are available: + +* ``WLB_INTERFACE_NAME=[interfacename]``: Interface to be monitored +* ``WLB_INTERFACE_STATE=[ACTIVE|FAILED]``: Interface state + +.. warning:: + + Blocking call with no timeout. System will become unresponsive if script does not return! + +Handling and monitoring +----------------------- + + +Show WAN load balancer information including test types and targets. +A character at the start of each line depicts the state of the test + +* ``+`` successful +* ``-`` failed +* a blank indicates that no test has been carried out + +.. code-block:: none + + vyos@vyos:~$ show wan-load-balance + Interface: eth0 + Status: failed + Last Status Change: Tue Jun 11 20:12:19 2019 + -Test: ping Target: + Last Interface Success: 55s + Last Interface Failure: 0s + # Interface Failure(s): 5 + + Interface: eth1 + Status: active + Last Status Change: Tue Jun 11 20:06:42 2019 + +Test: ping Target: + Last Interface Success: 0s + Last Interface Failure: 6m26s + # Interface Failure(s): 0 + +Show connection data of load balanced traffic: + +.. code-block:: none + + vyos@vyos:~$ show wan-load-balance connection + conntrack v1.4.2 (conntrack-tools): 3 flow entries have been shown. + Type State Src Dst Packets Bytes + tcp TIME_WAIT 10.1.1.13:38040 203.0.113.2:80 203.0.113.2 192.168.188.71 + udp 10.1.1.13:41891 198.51.100.3:53 198.51.100.3 192.168.188.71 + udp 10.1.1.13:55437 198.51.100.3:53 198.51.100.3 192.168.188.71 + +Restart +******* + +.. code-block:: none + + restart wan-load-balance diff --git a/docs/configuration/nat/index.rst b/docs/configuration/nat/index.rst new file mode 100644 index 00000000..9b7b69df --- /dev/null +++ b/docs/configuration/nat/index.rst @@ -0,0 +1,475 @@ +.. _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: + +.. code-block:: none + + 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:: none + + 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:: none + + 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. + +NAT Reflection/Hairpin NAT +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. 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 referred 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:: none + + 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:: none + + 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:: none + + 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:: none + + 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:: none + + 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:: none + + 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:: none + + set interfaces ethernet eth0 address '192.168.1.1/24' + set interfaces ethernet eth0 description 'Inside interface' + set interfaces ethernet eth1 address '192.0.2.30/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 '192.0.2.30' + 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 '192.0.2.30' + +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. It is also commonly used when the external IPv6 prefix is dynamic, +as it prevents the need for renumbering of internal hosts when the extern prefix changes. + +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:: none + + set rule 10 source prefix 'fc00:dead:beef::/48' + set rule 10 outbound-interface 'eth1' + set rule 10 translation prefix '2001:db8:e1::/48' + set rule 20 source prefix 'fc00:dead:beef::/48' + set rule 20 outbound-interface 'eth2' + set rule 20 translation prefix '2001:db8:e2::/48' + +Resulting in the following ip6tables rules: + +.. code-block:: none + + 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 + + +NAT before VPN +-------------- + +Some application service providers (ASPs) operate a VPN gateway to provide access to their internal resources, +and require that a connecting organisation translate all traffic to the service provider network to a source address provided by the ASP. + +Example Network +^^^^^^^^^^^^^^^ + +Here's one example of a network environment for an ASP. +The ASP requests that all connections from this company should come from 172.29.41.89 - an address that is assigned by the ASP and not in use at the customer site. + +.. figure:: /_static/images/nat_before_vpn_topology.png + :scale: 100 % + :alt: NAT before VPN Topology + + NAT before VPN Topology + + +Configuration +^^^^^^^^^^^^^ + +The required configuration can be broken down into 4 major pieces: + +* A dummy interface for the provider-assigned IP; +* NAT (specifically, Source NAT); +* IPSec IKE and ESP Groups; +* IPSec VPN tunnels. + + +Dummy interface +*************** + +The dummy interface allows us to have an equivalent of the Cisco IOS Loopback interface - a router-internal interface we can use for IP addresses the router must know about, +but which are not actually assigned to a real network. + +We only need a single step for this interface: + +.. code-block:: none + + set interfaces dummy dum0 address '172.29.41.89/32' + +NAT Configuration +***************** + +.. code-block:: none + + set nat source rule 110 description 'Internal to ASP' + set nat source rule 110 destination address '172.27.1.0/24' + set nat source rule 110 outbound-interface 'any' + set nat source rule 110 source address '192.168.43.0/24' + set nat source rule 110 translation address '172.29.41.89' + set nat source rule 120 description 'Internal to ASP' + set nat source rule 120 destination address '10.125.0.0/16' + set nat source rule 120 outbound-interface 'any' + set nat source rule 120 source address '192.168.43.0/24' + set nat source rule 120 translation address '172.29.41.89' + +IPSec IKE and ESP +***************** + + +The ASP has documented their IPSec requirements: + +* IKE Phase: + + * aes256 Encryption + * sha256 Hashes + +* ESP Phase: + + * aes256 Encryption + * sha256 Hashes + * DH Group 14 + + +Additionally, we want to use VPNs only on our eth1 interface (the external interface in the image above) + +.. code-block:: none + + set vpn ipsec ike-group my-ike ikev2-reauth 'no' + set vpn ipsec ike-group my-ike key-exchange 'ikev1' + set vpn ipsec ike-group my-ike lifetime '7800' + set vpn ipsec ike-group my-ike proposal 1 dh-group '14' + set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256' + set vpn ipsec ike-group my-ike proposal 1 hash 'sha256' + + set vpn ipsec esp-group my-esp compression 'disable' + set vpn ipsec esp-group my-esp lifetime '3600' + set vpn ipsec esp-group my-esp mode 'tunnel' + set vpn ipsec esp-group my-esp pfs 'disable' + set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256' + set vpn ipsec esp-group my-esp proposal 1 hash 'sha256' + + set vpn ipsec ipsec-interfaces interface 'eth1' + +IPSec VPN Tunnels +***************** + +We'll use the IKE and ESP groups created above for this VPN. +Because we need access to 2 different subnets on the far side, we will need two different tunnels. +If you changed the names of the ESP group and IKE group in the previous step, make sure you use the correct names here too. + +.. code-block:: none + + set vpn ipsec site-to-site peer 198.51.100.243 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 198.51.100.243 authentication pre-shared-secret 'PASSWORD IS HERE' + set vpn ipsec site-to-site peer 198.51.100.243 connection-type 'initiate' + set vpn ipsec site-to-site peer 198.51.100.243 default-esp-group 'my-esp' + set vpn ipsec site-to-site peer 198.51.100.243 ike-group 'my-ike' + set vpn ipsec site-to-site peer 198.51.100.243 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 198.51.100.243 local-address '203.0.113.46' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 local prefix '172.29.41.89/32' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 remote prefix '172.27.1.0/24' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 local prefix '172.29.41.89/32' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 remote prefix '10.125.0.0/16' + +Testing and Validation +^^^^^^^^^^^^^^^^^^^^^^ + +If you've completed all the above steps you no doubt want to see if it's all working. + +Start by checking for IPSec SAs (Security Associations) with: + +.. code-block:: none + + $ show vpn ipsec sa + + Peer ID / IP Local ID / IP + ------------ ------------- + 198.51.100.243 203.0.113.46 + + Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto + ------ ----- ------------- ------- ---- ----- ------ ------ ----- + 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all + 1 up 0.0/0.0 aes256 sha256 no 865 3600 all + +That looks good - we defined 2 tunnels and they're both up and running. + + + +.. _RFC6296: https://tools.ietf.org/html/rfc6296 +.. _ULAs: http://en.wikipedia.org/wiki/Unique_local_address diff --git a/docs/configuration/policy/index.rst b/docs/configuration/policy/index.rst new file mode 100644 index 00000000..ad829a55 --- /dev/null +++ b/docs/configuration/policy/index.rst @@ -0,0 +1,160 @@ + +###### +Policy +###### + +Routing Policies could be used to tell the router (self or neighbors) what routes and their attributes needs to be put into the routing table. + +There could be a wide range of routing policies. Some examples are below: + + * Set some metric to routes learned from a particular neighbor + * Set some attributes (like AS PATH or Community value) to advertised routes to neighbors + * Prefer a specific routing protocol routes over another routing protocol running on the same router + +Routing Policy Example +~~~~~~~~~~~~~~~~~~~~~~ + +**Policy definition:** + +.. code-block:: none + + #Create policy + set policy route-map setmet rule 2 action 'permit' + set policy route-map setmet rule 2 set as-path-prepend '2 2 2' + + #Apply policy to BGP + set protocols bgp 1 neighbor 1.1.1.2 address-family ipv4-unicast route-map import 'setmet' + set protocols bgp 1 neighbor 1.1.1.2 address-family ipv4-unicast soft-reconfiguration 'inbound' <<<< *** + + *** get policy update without bouncing the neighbor + +**Routes learned before routing policy applied:** + +.. code-block:: none + + vyos@vos1:~$ show ip bgp + BGP table version is 0, local router ID is 192.168.56.101 + Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 22.22.22.22/32 1.1.1.2 1 0 2 i < Path + + Total number of prefixes 1 + +**Routes learned after routing policy applied:** + +.. code-block:: none + + vyos@vos1:~$ sho ip b + BGP table version is 0, local router ID is 192.168.56.101 + Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 22.22.22.22/32 1.1.1.2 1 0 2 2 2 2 i < longer AS_path length + + Total number of prefixes 1 + vyos@vos1:~$ + + +.. _routing-pbr: + +Policy-Based Routing (PBR) +-------------------------- + +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). + +Transparent Proxy +^^^^^^^^^^^^^^^^^ + +The following example will show how VyOS can be used to redirect web traffic to +an external transparent proxy: + +.. code-block:: none + + 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:: none + + 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:: none + + set interfaces ethernet eth1 policy route FILTER-WEB + + +Multiple Uplinks +^^^^^^^^^^^^^^^^ + +VyOS Policy-Based Routing (PBR) works by matching source IP address ranges and +forwarding the traffic using different routing tables. + +Routing tables that will be used in this example are: + +* ``table 10`` Routing tabled used for VLAN 10 (192.168.188.0/24) +* ``table 11`` Routing tabled used for VLAN 11 (192.168.189.0/24) +* ``main`` Routing table used by VyOS and other interfaces not paritipating in PBR + +.. figure:: /_static/images/pbr_example_1.png + :scale: 80 % + :alt: PBR multiple uplinks + + Policy-Based Routing with multiple ISP uplinks (source ./draw.io/pbr_example_1.drawio) + +Add default routes for routing ``table 10`` and ``table 11`` + +.. code-block:: none + + set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.1.1 + set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2 + +Add policy route matching VLAN source addresses + +.. code-block:: none + + set policy route PBR rule 20 set table '10' + set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' + set policy route PBR rule 20 source address '192.168.188.0/24' + + set policy route PBR rule 30 set table '11' + set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' + set policy route PBR rule 30 source address '192.168.189.0/24' + +Apply routing policy to **inbound** direction of out VLAN interfaces + +.. code-block:: none + + set interfaces ethernet eth0 vif 10 policy route 'PBR' + set interfaces ethernet eth0 vif 11 policy route 'PBR' + + +**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) from PBR + +.. code-block:: none + + set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' + set policy route PBR rule 10 destination address '192.168.188.0/24' + set policy route PBR rule 10 destination address '192.168.189.0/24' + set policy route PBR rule 10 set table 'main' + +.. note:: Allows the VLAN10 and VLAN20 hosts to communicate with each other using the + main routing table. diff --git a/docs/configuration/protocols/bgp.rst b/docs/configuration/protocols/bgp.rst new file mode 100644 index 00000000..f0550fd4 --- /dev/null +++ b/docs/configuration/protocols/bgp.rst @@ -0,0 +1,144 @@ +.. _routing-bgp: + +Border Gateway Protocol (BGP) +----------------------------- + +IPv4 +^^^^ + +A simple eBGP configuration: + +**Node 1:** + +.. code-block:: none + + 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 address-family ipv4-unicast network '172.16.0.0/16' + set protocols bgp 65534 parameters router-id '192.168.0.1' + +**Node 2:** + +.. code-block:: none + + 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 address-family ipv4-unicast 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:: none + + set protocols static route 172.16.0.0/16 blackhole distance '254' + +**Node 2:** + +.. code-block:: none + + set protocols static route 172.17.0.0/16 blackhole distance '254' + + +IPv6 +^^^^ + +A simple BGP configuration via IPv6. + +**Node 1:** + +.. code-block:: none + + 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:: none + + 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:: none + + set protocols static route6 2001:db8:1::/48 blackhole distance '254' + +**Node 2:** + +.. code-block:: none + + 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:: none + + 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:: none + + 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. diff --git a/docs/configuration/protocols/igmp.rst b/docs/configuration/protocols/igmp.rst new file mode 100644 index 00000000..421c9f0f --- /dev/null +++ b/docs/configuration/protocols/igmp.rst @@ -0,0 +1,246 @@ +.. _multicast: + +######### +Multicast +######### + +VyOS facilitates IP Multicast by supporting **PIM Sparse Mode**, +**IGMP** and **IGMP-Proxy**. + + +************ +PIM and IGMP +************ + +PIM (Protocol Independent Multicast) must be configured in every +interface of every participating router. Every router must also have the +location of the Rendevouz Point manually configured. Then, +unidirectional shared trees rooted at the Rendevouz Point will +automatically be built for multicast distribution. + +Traffic from multicast sources will go to the Rendezvous Point, and +receivers will pull it from a shared tree using IGMP (Internet Group +Management Protocol). + +Multicast receivers will talk IGMP to their local router, so, besides +having PIM configured in every router, IGMP must also be configured in +any router where there could be a multicast receiver locally connected. + +VyOS supports both IGMP version 2 and version 3 (which allows +source-specific multicast). + + +Example +======= + +In the following example we can see a basic multicast setup: + +.. image:: /_static/images/multicast-basic.png + :width: 90% + :align: center + :alt: Network Topology Diagram + + + +**Router 1** + +.. code-block:: none + + set interfaces ethernet eth2 address '172.16.0.2/24' + set interfaces ethernet eth1 address '100.64.0.1/24' + set protocols ospf area 0 network '172.16.0.0/24' + set protocols ospf area 0 network '100.64.0.0/24' + set protocols igmp interface eth1 + set protocols pim interface eth1 + set protocols pim interface eth2 + set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' + +**Router 3** + +.. code-block:: none + + set interfaces dummy dum0 address '172.16.255.1/24' + set interfaces ethernet eth0 address '172.16.0.1/24' + set interfaces ethernet eth1 address '172.16.1.1/24' + set protocols ospf area 0 network '172.16.0.0/24' + set protocols ospf area 0 network '172.16.255.0/24' + set protocols ospf area 0 network '172.16.1.0/24' + set protocols pim interface dum0 + set protocols pim interface eth0 + set protocols pim interface eth1 + set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' + +**Router 2** + +.. code-block:: none + + set interfaces ethernet eth1 address '10.0.0.1/24' + set interfaces ethernet eth2 address '172.16.1.2/24' + set protocols ospf area 0 network '10.0.0.0/24' + set protocols ospf area 0 network '172.16.1.0/24' + set protocols pim interface eth1 + set protocols pim interface eth2 + set protocols pim rp address 172.16.255.1 group '224.0.0.0/4' + + + + + +Basic commands +============== + +These are the commands for a basic setup. + +.. cfgcmd:: set protocols pim interface <interface-name> + + Use this command to enable PIM in the selected interface so that it + can communicate with PIM neighbors. + + +.. cfgcmd:: set protocols pim rp address <address> group <multicast-address/mask-bits> + + Use this comand to manually configure a Rendevouz Point for PIM so + that join messages can be sent there. Set the Rendevouz Point address + and the matching prefix of group ranges covered. These values must + be shared with every router participating in the PIM network. + + +.. cfgcmd:: set protocols igmp interface eth1 + + Use this command to configure an interface with IGMP so that PIM can + receive IGMP reports and query on the selected interface. By defaul + IGMP version 3 will be used. + + + +Tuning commands +=============== + +You can also tune multicast with the following commands. + +.. cfgcmd:: set protocols pim interface <interface> dr-priority <value> + + Use this PIM command in the selected interface to set the priority + (1-4294967295) you want to influence in the election of a node to + become the Designated Router for a LAN segment. The default priority + is 1, set a higher value to give the router more preference in the + DR election process. + + +.. cfgcmd:: set protocols pim int <interface> hello <seconds> + + Use this command to configure the PIM hello interval in seconds + (1-180) for the selected interface. + + +.. cfgcmd:: set protocols pim rp keep-alive-timer <seconds> + + Use this PIM command to modify the the time out value (31-60000 + seconds) for an `(S,G) <https://tools.ietf.org/html/rfc7761#section-4.1>`_ + flow. 31 seconds is chosen for a lower bound as some hardware + platforms cannot see data flowing in better than 30 second chunks. + + +.. cfgcmd:: set protocols igmp interface <interface> join <multicast-address> source <IP-address> + + Use this command to allow the selected interface join a multicast + group defining the multicast address you want to join and the source + IP address too. + + +.. cfgcmd:: set protocols igmp interface <interface query-interval <seconds> + + Use this command to configure in the selected interface the IGMP + host query interval (1-1800) in seconds that PIM will use. + + +.. cfgcmd:: set protocols igmp interface <interface query-max-response-time <deciseconds> + + Use this command to configure in the selected interface the IGMP + query response timeout value (10-250) in deciseconds. If a report is + not returned in the specified time, it will be asumed the `(S,G) or + (*,G) state <https://tools.ietf.org/html/rfc7761#section-4.1>`_ has + timed out. + + +.. cfgcmd:: set protocols igmp interface <interface> version <version-number> + + Use this command to define in the selected interface whether you + choose IGMP version 2 or 3. The default value is 3. + + + +********** +IGMP Proxy +********** + +:abbr:`IGMP (Internet Group Management Protocol)` proxy sends IGMP host +messages on behalf of a connected client. The configuration must define +one, and only one upstream interface, and one or more downstream +interfaces. + +Configuration +============= + +.. cfgcmd:: set protocols igmp-proxy interface <interface> role <upstream | downstream> + + * **upstream:** The upstream network interface is the outgoing interface + which is responsible for communicating to available multicast data sources. + There can only be one upstream interface. + + * **downstream:** Downstream network interfaces are the distribution + interfaces to the destination networks, where multicast clients can join + groups and receive multicast data. One or more downstream interfaces must + be configured. + +.. cfgcmd:: set protocols igmp-proxy interface <interface> alt-subnet <network> + + Defines alternate sources for multicasting and IGMP data. The network address + must be on the following format 'a.b.c.d/n'. By default the router will + accept data from sources on the same network as configured on an interface. + If the multicast source lies on a remote network, one must define from where + traffic should be accepted. + + This is especially useful for the upstream interface, since the source for + multicast traffic is often from a remote location. + + This option can be supplied multiple times. + +.. cfgcmd:: set protocols igmp-proxy disable-quickleave + + Disables quickleave mode. In this mode the daemon will not send a Leave IGMP + message upstream as soon as it receives a Leave message for any downstream + interface. The daemon will not ask for Membership reports on the downstream + interfaces, and if a report is received the group is not joined again + upstream. + + If it's vital that the daemon should act exactly as a real multicast client + on the upstream interface, this function should be enabled. + + Enabling this function increases the risk of bandwidth saturation. + +.. cfgcmd:: set protocols igmp-proxy disable + + Disable this service. + +Example +------- + +Interface `eth1` LAN is behind NAT. In order to subscribe `10.0.0.0/23` +subnet multicast which is in `eth0` WAN we need to configure igmp-proxy. + +.. code-block:: none + + set protocols igmp-proxy interface eth0 role upstream + set protocols igmp-proxy interface eth0 alt-subnet 10.0.0.0/23 + set protocols igmp-proxy interface eth1 role downstream + +Operation +========= + +.. opcmd:: restart igmp-proxy + + Restart the IGMP proxy process. + + + diff --git a/docs/configuration/protocols/index.rst b/docs/configuration/protocols/index.rst new file mode 100644 index 00000000..a737a026 --- /dev/null +++ b/docs/configuration/protocols/index.rst @@ -0,0 +1,18 @@ +.. _routing: + +######### +Protocols +######### + +VyOS is a "router first" network operating system. It supports static routing, +policy routing, and dynamic routing using standard protocols (RIP, OSPF, and +BGP). + +.. toctree:: + :maxdepth: 1 + + bgp + igmp + ospf + rip + static diff --git a/docs/configuration/protocols/ospf.rst b/docs/configuration/protocols/ospf.rst new file mode 100644 index 00000000..1e70f644 --- /dev/null +++ b/docs/configuration/protocols/ospf.rst @@ -0,0 +1,139 @@ +.. _routing-ospf: + +Open Shortest Path First (OSPF) +------------------------------- + +Open Shortest Path First (OSPF) is a routing protocol for Internet Protocol +(IP) networks. It uses a link state routing (LSR) algorithm and falls into the +group of interior gateway protocols (IGPs), operating within a single autonomous +system (AS). It is defined as OSPF Version 2 in RFC2328_ (1998) for IPv4. Updates +for IPv6 are specified as OSPF Version 3 in RFC5340_ (2008). OSPF supports the +Classless Inter-Domain Routing (CIDR) addressing model. + +OSPF is a widely used IGP in large enterprise networks. + +OSPFv2 (IPv4) +^^^^^^^^^^^^^ + +In order to have a VyOS system exchanging routes with OSPF neighbors, you will at least need to configure the area and a network, + +.. code-block:: none + + set protocols ospf area 0 network 192.168.0.0/24 + +as well as the router ID. + +.. code-block:: none + + set protocols ospf parameters router-id 10.1.1.1 + +That is the minimum configuration you will need. + +Below you can see a typical configuration using 2 nodes, redistribute loopback address and the node 1 sending the default route: + +**Node 1** + +.. code-block:: none + + 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:: none + + 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 + +OSPFv3 (IPv6) +^^^^^^^^^^^^^ + +A typical configuration using 2 nodes. + +**Node 1:** + +.. code-block:: none + + 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:: none + + 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 + +.. note:: You can not easily redistribute IPv6 routes via OSPFv3 on a WireGuard + interface link. This requires you to configure link-local addresses manually + on the WireGuard interfaces, see Phabricator task T1483_. + +Example configuration for WireGuard interfaces: + +**Node 1** + +.. code-block:: none + + set interfaces wireguard wg01 address 'fe80::216:3eff:fe51:fd8c/64' + set interfaces wireguard wg01 address '192.168.0.1/24' + set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0' + set interfaces wireguard wg01 peer ospf02 allowed-ips '0.0.0.0/0' + set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345' + set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...=' + set interfaces wireguard wg01 port '12345' + set protocols ospfv3 parameters router-id 192.168.1.1 + set protocols ospfv3 area 0.0.0.0 interface 'wg01' + set protocols ospfv3 area 0.0.0.0 interface 'lo' + +**Node 2** + +.. code-block:: none + + set interfaces wireguard wg01 address 'fe80::216:3eff:fe0a:7ada/64' + set interfaces wireguard wg01 address '192.168.0.2/24' + set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0' + set interfaces wireguard wg01 peer ospf01 allowed-ips '0.0.0.0/0' + set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345' + set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...=' + set interfaces wireguard wg01 port '12345' + set protocols ospfv3 parameters router-id 192.168.1.2 + set protocols ospfv3 area 0.0.0.0 interface 'wg01' + set protocols ospfv3 area 0.0.0.0 interface 'lo' + +**Status** + +.. code-block:: none + + vyos@ospf01:~$ sh ipv6 ospfv3 neighbor + Neighbor ID Pri DeadTime State/IfState Duration I/F[State] + 192.168.0.2 1 00:00:37 Full/PointToPoint 00:18:03 wg01[PointToPoint] + + vyos@ospf02# run sh ipv6 ospfv3 neighbor + Neighbor ID Pri DeadTime State/IfState Duration I/F[State] + 192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] + +.. _RFC2328: https://tools.ietf.org/html/rfc2328 +.. _RFC5340: https://tools.ietf.org/html/rfc2340 +.. _T1483: https://phabricator.vyos.net/T1483 + diff --git a/docs/configuration/protocols/rip.rst b/docs/configuration/protocols/rip.rst new file mode 100644 index 00000000..da00e7b1 --- /dev/null +++ b/docs/configuration/protocols/rip.rst @@ -0,0 +1,22 @@ +.. _routing-rip: + +Routing Information Protocol (RIP) +---------------------------------- + +Simple RIP configuration using 2 nodes and redistributing connected interfaces. + +**Node 1:** + +.. code-block:: none + + 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:: none + + set interfaces loopback address 10.2.2.2/32 + set protocols rip network 192.168.0.0/24 + set protocols rip redistribute connected diff --git a/docs/configuration/protocols/static.rst b/docs/configuration/protocols/static.rst new file mode 100644 index 00000000..8415981b --- /dev/null +++ b/docs/configuration/protocols/static.rst @@ -0,0 +1,66 @@ +.. _routing-static: + +###### +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:: none + + 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, RFC1918_ networks are set as blackhole routes. + +This prevents these networks leaking out public interfaces, but it does not prevent +them from being used as the most specific route has the highest priority. + +.. code-block:: none + + 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. + +.. _RFC1918: https://tools.ietf.org/html/rfc1918 + +.. _routing-arp: + +Address Resolution Protocol (ARP) +--------------------------------- + +To manipulate or display ARP_ table entries, the following commands are implemented. + +adding a static arp entry +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + set protocols static arp 10.1.1.100 hwaddr 08:00:27:de:23:aa + commit + +display arp table entries +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + show protocols static arp + + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 08:00:27:de:23:2e C eth1 + 10.1.1.100 ether 08:00:27:de:23:aa CM eth1 + +.. code-block:: none + + show protocols static arp interface eth1 + Address HWtype HWaddress Flags Mask Iface + 10.1.1.1 ether 08:00:27:de:23:2e C eth1 + 10.1.1.100 ether 08:00:27:de:23:aa CM eth1 + +.. _ARP: https://en.wikipedia.org/wiki/Address_Resolution_Protocol diff --git a/docs/configuration/service/broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst new file mode 100644 index 00000000..40f738e6 --- /dev/null +++ b/docs/configuration/service/broadcast-relay.rst @@ -0,0 +1,53 @@ +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! + +Example #1: To forward all broadcast packets received on `UDP port 1900` on +`eth3`, `eth4` or `eth5` to all other interfaces in this configuration. + +.. code-block:: none + + 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' + +Example #2: To Forward all broadcasts packets received on `UDP port 6969` on +`eth3` or `eth4` to the other interface in this configuration. + +.. code-block:: none + + 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' + +Disable Instance(s) +^^^^^^^^^^^^^^^^^^^ + +Each broadcast relay instance can be individually disabled without deleting the +configured node by using the following command: + +.. code-block:: none + + set service broadcast-relay id <n> disable + +In addition you can also disable the whole service without removing the +configuration by: + +.. code-block:: none + + 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! diff --git a/docs/configuration/service/conntrack-sync.rst b/docs/configuration/service/conntrack-sync.rst new file mode 100644 index 00000000..28f16d54 --- /dev/null +++ b/docs/configuration/service/conntrack-sync.rst @@ -0,0 +1,178 @@ +Conntrack +--------- + +One of the important features built on top of the Netfilter framework is +connection tracking. Connection tracking allows the kernel to keep track of all +logical network connections or sessions, and thereby relate all of the packets +which may make up that connection. NAT relies on this information to translate +all related packets in the same way, and iptables can use this information to +act as a stateful firewall. + +The connection state however is completely independent of any upper-level +state, such as TCP's or SCTP's state. Part of the reason for this is that when +merely forwarding packets, i.e. no local delivery, the TCP engine may not +necessarily be invoked at all. Even connectionless-mode transmissions such as +UDP, IPsec (AH/ESP), GRE and other tunneling protocols have, at least, a pseudo +connection state. The heuristic for such protocols is often based upon a preset +timeout value for inactivity, after whose expiration a Netfilter connection is +dropped. + +Each Netfilter connection is uniquely identified by a (layer-3 protocol, source +address, destination address, layer-4 protocol, layer-4 key) tuple. The layer-4 +key depends on the transport protocol; for TCP/UDP it is the port numbers, for +tunnels it can be their tunnel ID, but otherwise is just zero, as if it were +not part of the tuple. To be able to inspect the TCP port in all cases, packets +will be mandatorily defragmented. + +Configuration +^^^^^^^^^^^^^ + +.. code-block:: none + + # Protocols only for which local conntrack entries will be synced (tcp, udp, icmp, sctp) + set service conntrack-sync accept-protocol + + # Queue size for listening to local conntrack events (in MB) + set service conntrack-sync event-listen-queue-size <int> + + # Protocol for which expect entries need to be synchronized. (all, ftp, h323, nfs, sip, sqlnet) + set service conntrack-sync expect-sync + + # Failover mechanism to use for conntrack-sync [REQUIRED] + set service conntrack-sync failover-mechanism + + set service conntrack-sync cluster group <string> + set service conntrack-sync vrrp sync-group <1-255> + + # IP addresses for which local conntrack entries will not be synced + set service conntrack-sync ignore-address ipv4 <x.x.x.x> + + # Interface to use for syncing conntrack entries [REQUIRED] + set service conntrack-sync interface <ifname> + + # Multicast group to use for syncing conntrack entries + set service conntrack-sync mcast-group <x.x.x.x> + + # Queue size for syncing conntrack entries (in MB) + set service conntrack-sync sync-queue-size <size> + +Example +^^^^^^^ +The next exemple is a simple configuration of conntrack-sync. + + +.. figure:: /_static/images/service_conntrack_sync-schema.png + :scale: 60 % + :alt: Conntrack Sync Example + + Conntrack Sync Example + +First of all, make sure conntrack is enabled by running + +.. code-block:: none + + show conntrack table ipv4 + +If the table is empty and you have a warning message, it means conntrack is not +enabled. To enable conntrack, just create a NAT or a firewall rule. + +.. code-block:: none + + set firewall state-policy established action accept + +You now should have a conntrack table + +.. code-block:: none + + $ show conntrack table ipv4 + TCP state codes: SS - SYN SENT, SR - SYN RECEIVED, ES - ESTABLISHED, + FW - FIN WAIT, CW - CLOSE WAIT, LA - LAST ACK, + TW - TIME WAIT, CL - CLOSE, LI - LISTEN + + CONN ID Source Destination Protocol TIMEOUT + 1015736576 10.35.100.87:58172 172.31.20.12:22 tcp [6] ES 430279 + 1006235648 10.35.101.221:57483 172.31.120.21:22 tcp [6] ES 413310 + 1006237088 10.100.68.100 172.31.120.21 icmp [1] 29 + 1015734848 10.35.100.87:56282 172.31.20.12:22 tcp [6] ES 300 + 1015734272 172.31.20.12:60286 239.10.10.14:694 udp [17] 29 + 1006239392 10.35.101.221 172.31.120.21 icmp [1] 29 + +Now configure conntrack-sync service on ``router1`` **and** ``router2`` + +.. code-block:: none + + set service conntrack-sync accept-protocol 'tcp,udp,icmp' + set service conntrack-sync event-listen-queue-size '8' + set service conntrack-sync failover-mechanism cluster group 'GROUP' # Or VRRP + set service conntrack-sync interface 'eth0' + set service conntrack-sync mcast-group '225.0.0.50' + set service conntrack-sync sync-queue-size '8' + +On the active router, you should have informations in the internal-cache of +conntrack-sync. The same current active connections number should be shown in +the external-cache of the standby router + +On active router run: + + +.. code-block:: none + + $ show conntrack-sync statistics + + Main Table Statistics: + + cache internal: + current active connections: 10 + connections created: 8517 failed: 0 + connections updated: 127 failed: 0 + connections destroyed: 8507 failed: 0 + + cache external: + current active connections: 0 + connections created: 0 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + traffic processed: + 0 Bytes 0 Pckts + + multicast traffic (active device=eth0): + 868780 Bytes sent 224136 Bytes recv + 20595 Pckts sent 14034 Pckts recv + 0 Error send 0 Error recv + + message tracking: + 0 Malformed msgs 0 Lost msgs + + + + On standby router run: + + + $ show conntrack-sync statistics + + Main Table Statistics: + + cache internal: + current active connections: 0 + connections created: 0 failed: 0 + connections updated: 0 failed: 0 + connections destroyed: 0 failed: 0 + + cache external: + current active connections: 10 + connections created: 888 failed: 0 + connections updated: 134 failed: 0 + connections destroyed: 878 failed: 0 + + traffic processed: + 0 Bytes 0 Pckts + + multicast traffic (active device=eth0): + 234184 Bytes sent 907504 Bytes recv + 14663 Pckts sent 21495 Pckts recv + 0 Error send 0 Error recv + + message tracking: + 0 Malformed msgs 0 Lost msgs + diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/dhcp-relay.rst new file mode 100644 index 00000000..0b838442 --- /dev/null +++ b/docs/configuration/service/dhcp-relay.rst @@ -0,0 +1,165 @@ + + +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:: none + + set service dhcp-relay interface eth1 + set service dhcp-relay interface eth2 + +Set the IP address of the DHCP server: + +.. code-block:: none + + 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:: none + + set service dhcp-relay relay-options relay-agents-packets discard + +Commit the changes and show the results: + +.. code-block:: none + + 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:: none + + 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:: none + + 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:: none + + set service dhcpv6-relay upstream-interface eth2 address 2001:db8:100::4 + +Commit the changes and show results: + +.. code-block:: none + + 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:: none + + show dhcpv6 relay-agent status + +The DHCPv6 relay agent can be restarted with: + +.. code-block:: none + + 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'` + +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 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` diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst new file mode 100644 index 00000000..f0d0a7e9 --- /dev/null +++ b/docs/configuration/service/dhcp-server.rst @@ -0,0 +1,444 @@ + +DHCP Server +----------- + +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:: none + + set interface ethernet eth1 address 172.16.17.1/24 + +Multiple ranges can be defined and can contain holes. + +.. code-block:: none + + 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 + + +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 range 0 start 172.16.17.100` + + Make a range of addresses available for clients starting from .100 [...] + +* :code:`set service dhcp-server shared-network-name dhcpexample subnet + 172.16.17.0/24 range 0 stop 172.16.17.199` + + [...] and ending at .199 + + +Failover +^^^^^^^^ + +VyOS provides support for DHCP failover: + +.. code-block:: none + + 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:: none + + set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'primary' + +or + +.. code-block:: none + + 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:: none + + 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 + +DHCP server options +^^^^^^^^^^^^^^^^^^^^^^^^^ + +default-router (DHCP option 003) + :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 default-router <ROUTER-IP>` + +dns-server (DHCP option 006) + :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 dns-server <DNS-SERVER-IP>` + +domain-name Client domain name (DHCP option 015) + :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-name "<DOMAIN-NAME>"` + +domain-search (DHCP option 119) + This option can be given multiple times if you need multiple search domains + :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-search "<DOMAIN_NAME_1>"` + :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-search "<DOMAIN_NAME_2>"` + + + +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:: none + + set service dhcpv6-server + +To restart the DHCPv6 server (operational mode): + +.. code-block:: none + + restart dhcpv6 server + +To show the current status of the DHCPv6 server use: + +.. code-block:: none + + show dhcpv6 server status + +Show statuses of all assigned leases: + +.. code-block:: none + + 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:: none + + set service dhcpv6-server preference <preference value> + +Delete a preference: + +.. code-block:: none + + set service dhcpv6-server preference + +Show current preference: + +.. code-block:: none + + 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:: none + + set service dhcpv6-server shared-network-name <name> subnet <ipv6net> lease-time {default <default-time> | maximum <maximum-time> | minimum <minimum-time>} + +Reset the custom lease times: + +.. code-block:: none + + delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> lease-time {default | maximum | minimum} + +Show the current configuration: + +.. code-block:: none + + show service dhcpv6-server shared-network-name <name> subnet <ipv6net> lease-time {default | maximum | minimum} + +Specify NIS domain +****************** + +A Network Information (NIS) domain can be set to be used for DHCPv6 clients: + +.. code-block:: none + + set service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-domain <nis-domain-name> + +To Delete the NIS domain: + +.. code-block:: none + + delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-domain <nis-domain-name> + +Show a configured NIS domain: + +.. code-block:: none + + show service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-domain <nis-domain-name> + +Specify NIS+ domain +******************* + +The procedure to specify a Network Information Service Plus (NIS+) domain is +similar to the NIS domain one: + +.. code-block:: none + + set service dhcpv6-server shared-network-name <name> subnet <ipv6net> nisplus-domain <nisplus-domain-name> + +To Delete the NIS+ domain: + +.. code-block:: none + + delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> nisplus-domain <nisplus-domain-name> + +Show a configured NIS domain: + + # show service dhcpv6-server shared-network-name <name> subnet <ipv6net> nisplus-domain <nisplus-domain-name> + +Specify NIS server address +************************** + +To specify a NIS server address for DHCPv6 clients: + +.. code-block:: none + + set service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-server <IPv6 address> + +Delete a specified NIS server address: + +.. code-block:: none + + delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-server <IPv6 address> + +Show specified NIS server addresses: + +.. code-block:: none + + show service dhcpv6-server shared-network-name <name> subnet <ipv6net> nis-server + +Specify NIS+ server address +*************************** + +To specify a NIS+ server address for DHCPv6 clients: + +.. code-block:: none + + set service dhcpv6-server shared-network-name <name> subnet <ipv6net> nisplus-server <IPv6 address> + +Delete a specified NIS+ server address: + +.. code-block:: none + + delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> nisplus-server <IPv6 address> + +Show specified NIS+ server addresses: + +.. code-block:: none + + show service dhcpv6-server shared-network-name <name> subnet <ipv6net> 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:: none + + set service dhcpv6-server shared-network-name <name> subnet <ipv6net> sip-server-address <IPv6 address> + +Delete a specified SIP server address: + +.. code-block:: none + + delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> sip-server-address <IPv6 address> + +Show specified SIP server addresses: + +.. code-block:: none + + show service dhcpv6-server shared-network-name <name> subnet <ipv6net> sip-server-address + +By FQDN +####### + +A name for SIP server can be specified: + +.. code-block:: none + + set service dhcpv6-server shared-network-name <name> subnet <ipv6net> sip-server-name <sip-server-name> + +Delete a specified SIP server name: + +.. code-block:: none + + delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> sip-server-name <sip-server-name> + +Show specified SIP server names: + +.. code-block:: none + + show service dhcpv6-server shared-network-name <name> subnet <ipv6net> 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:: none + + set service dhcpv6-server shared-network-name <name> subnet <ipv6net> sntp-server-address <IPv6 address> + +Delete a specified SNTP server address: + +.. code-block:: none + + delete service dhcpv6-server shared-network-name <name> subnet <ipv6net> sntp-server-address <IPv6 address> + +Show specified SNTP server addresses: + +.. code-block:: none + + show service dhcpv6-server shared-network-name <name> subnet <ipv6net> 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:: none + + 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:: none + + 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:: none + + 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:: none + + 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 + } + } + } diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst new file mode 100644 index 00000000..c83c93f9 --- /dev/null +++ b/docs/configuration/service/dns.rst @@ -0,0 +1,226 @@ +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:: none + + set service dns forwarding system + +Manually setting DNS servers for forwarding: + +.. code-block:: none + + 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:: none + + 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:: none + + set service dns forwarding domain example.com server 192.0.2.1 + +Set which networks or clients are allowed to query the DNS Server. Allow from all: + +.. code-block:: none + + set service dns forwarding allow-from 0.0.0.0/0 + +Example 1 +^^^^^^^^^ + +Router with two interfaces eth0 (WAN link) and eth1 (LAN). Split DNS for example.com. + +* DNS request for a local domain (example.com) get forwarded to 192.0.2.1 +* Other DNS requests are forwarded to Google's DNS servers. +* The IP address for the LAN interface is 192.168.0.1. + +.. code-block:: none + + 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-address 192.168.0.1 + set service dns forwarding allow-from 0.0.0.0/0 + +Example 2 +^^^^^^^^^ + +Same as example 1 but with additional IPv6 addresses for Google's public DNS +servers. + +The IP addresses for the LAN interface are 192.168.0.1 and 2001:db8::1 + +.. code-block:: none + + 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-address 2001:db8::1 + set service dns forwarding listen-address 192.168.0.1 + set service dns forwarding allow-from 0.0.0.0/0 + + +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:: none + + edit service dns dynamic interface eth0 rfc2136 <confignodename> + +Present your RNDC key to ddclient : + +.. code-block:: none + + set key /config/dyndns/mydnsserver.rndc.key + +Set the DNS server IP/FQDN : + +.. code-block:: none + + set server dns.mydomain.com + +Set the NS zone to be updated : + +.. code-block:: none + + set zone mydomain.com + +Set the records to be updated : + +.. code-block:: none + + set record dyn + set record dyn2 + +You can optionally set a TTL (note : default value is 600 seconds) : + +.. code-block:: none + + set ttl 600 + +This will generate the following ddclient config blocks: + +.. code-block:: none + + 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:: none + + edit service dns dynamic interface eth0 rfc2136 <confignode2> + +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:: none + + 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:: none + + 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:: none + + 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:: none + + 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]`. + + +.. include:: references.rst diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst new file mode 100644 index 00000000..31ff4e95 --- /dev/null +++ b/docs/configuration/service/index.rst @@ -0,0 +1,21 @@ +####### +Service +####### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + broadcast-relay + conntrack-sync + dhcp-relay + dhcp-server + dns + lldp + mdns + pppoe-server + snmp + ssh + tftp-server + webproxy diff --git a/docs/configuration/service/lldp.rst b/docs/configuration/service/lldp.rst new file mode 100644 index 00000000..dccd68fa --- /dev/null +++ b/docs/configuration/service/lldp.rst @@ -0,0 +1,97 @@ +LLDP +---- + +The Link Layer Discovery Protocol (LLDP) is a vendor-neutral +link layer protocol in the Internet Protocol Suite used by network devices for +advertising their identity, capabilities, and neighbors on an IEEE 802 local +area network, principally wired Ethernet.[1] The protocol is formally referred +to by the IEEE as Station and Media Access Control Connectivity Discovery +specified in IEEE 802.1AB and IEEE 802.3-2012 section 6 clause 79. + +LLDP performs functions similar to several proprietary protocols, such as +`Cisco Discovery Protocol`_, `Foundry Discovery Protocol`_, +Nortel Discovery Protocol and Link Layer Topology Discovery. + +Information gathered +^^^^^^^^^^^^^^^^^^^^ + +Information gathered with LLDP is stored in the device as a management +information database (MIB_) and can be queried with the Simple Network +Management Protocol (SNMP_) as specified in RFC 2922. The topology of an +LLDP-enabled network can be discovered by crawling the hosts and querying this +database. Information that may be retrieved include: + +* System name and description +* Port name and description +* VLAN name +* IP management address +* System capabilities (switching, routing, etc.) +* MAC/PHY information +* MDI power +* Link aggregation + +Configuration +^^^^^^^^^^^^^ + +* Enable service with: + + :code:`set service lldp` + +Options +******* + +* Configure a Define management-address: + + :code:`set service lldp management-address <x.x.x.x>` + +* Define listening interfaces + + :code:`set service lldp interface <all|interface name>` + +* LLDPd also implements an SNMP subagent. To Enable SNMP queries of the LLDP + database: + + :code:`set service lldp snmp enable` + +* Enable optional/other protocols + + :code:`set service lldp legacy-protocols cdp` + + Supported legacy protocols: + + * ``cdp`` - Listen for CDP for Cisco routers/switches + * ``edp`` - Listen for EDP for Extreme routers/switches + * ``fdp`` - Listen for FDP for Foundry routers/switches + * ``sonmp`` - Listen for SONMP for Nortel routers/switches + + +Display neighbors +^^^^^^^^^^^^^^^^^ + +* Display with: + +``show lldp neighbors`` + +Exemple: + +.. code-block:: none + + vyos@vyos:~# show lldp neighbors + Capability Codes: R - Router, B - Bridge, W - Wlan r - Repeater, S - Station + D - Docsis, T - Telephone, O - Other + Device ID Local Proto Cap Platform Port ID + --------- ----- ----- --- -------- ------- + swA309 eth0 LLDP ? Cisco IOS Software, GigE0/33 + + +* Options: + + * ``detail`` - Show lldp neighbors detail + * ``interface`` - Show LLDP for specified interface + +Troubleshooting +^^^^^^^^^^^^^^^ + +Use operational command ``show log lldp`` to display logs. + +.. include:: references.rst diff --git a/docs/configuration/service/mdns.rst b/docs/configuration/service/mdns.rst new file mode 100644 index 00000000..22e824ba --- /dev/null +++ b/docs/configuration/service/mdns.rst @@ -0,0 +1,30 @@ +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:: none + + 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:: none + + 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! + + +.. _`Multicast DNS`: https://en.wikipedia.org/wiki/Multicast_DNS diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst new file mode 100644 index 00000000..8e37a068 --- /dev/null +++ b/docs/configuration/service/pppoe-server.rst @@ -0,0 +1,217 @@ +PPPoE server +------------ + +VyOS utilizes `accel-ppp`_ to provide PPPoE server functionality. It can be +used with local authentication or a connected RADIUS server. + +.. note:: **Please be aware, due to an upstream bug, config changes/commits + will restart the ppp daemon and will reset existing PPPoE connections from + connected users, in order to become effective.** + +Configuration +^^^^^^^^^^^^^ + +The example below uses ACN as access-concentrator name, assigns an address +from the pool 10.1.1.100-111, terminates at the local endpoint 10.1.1.1 and +serves requests only on eth1. + +.. code-block:: none + + set service pppoe-server access-concentrator 'ACN' + set service pppoe-server authentication local-users username foo password 'bar' + set service pppoe-server authentication mode 'local' + set service pppoe-server client-ip-pool start '10.1.1.100' + set service pppoe-server client-ip-pool stop '10.1.1.111' + set service pppoe-server dns-servers server-1 '10.100.100.1' + set service pppoe-server dns-servers server-2 '10.100.200.1' + set service pppoe-server interface 'eth1' + set service pppoe-server local-ip '10.1.1.2' + + +Connections can be locally checked via the command + +.. code-block:: none + + show pppoe-server sessions + ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes + -------+----------+------------+-------------------+-------------+--------+----------+----------+---------- + ppp0 | foo | 10.1.1.100 | 08:00:27:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B + + +Client IP address pools +======================= + +To automatically assign the client an IP address as tunnel endpoint, a client IP pool is needed. The source can be either RADIUS or a local subnet or IP range definition. + +Once the local tunnel endpoint ``set service pppoe-server local-ip '10.1.1.2'`` has been defined, the client IP pool can be either defined as a range or as subnet using CIDR notation. +If the CIDR notation is used, multiple subnets can be setup which are used sequentially. + +**Client IP address via IP range definition** + +.. code-block:: none + + set service pppoe-server client-ip-pool start '10.1.1.100' + set service pppoe-server client-ip-pool stop '10.1.1.111' + + +**Client IP subnets via CIDR notation** + +.. code-block:: none + + set service pppoe-server client-ip-pool subnet '10.1.1.0/24' + set service pppoe-server client-ip-pool subnet '10.1.2.0/24' + set service pppoe-server client-ip-pool subnet '10.1.3.0/24' + + + +**RADIUS based IP pools (Framed-IP-Address)** + +To use a radius server, you need to switch to authentication mode radius and +of course need to specify an IP for the server. You can have multiple RADIUS +server configured, if you wish to achieve redundancy. + +.. code-block:: none + + set service pppoe-server access-concentrator 'ACN' + set service pppoe-server authentication mode 'radius' + set service pppoe-server authentication radius-server 10.1.100.1 secret 'secret' + set service pppoe-server interface 'eth1' + set service pppoe-server local-ip '10.1.1.2' + +RADIUS provides the IP addresses in the example above via Framed-IP-Address. + +**RADIUS sessions management DM/CoA** + +For remotely disconnect sessions and change some authentication parameters you can configure dae-server + +.. code-block:: none + + set service pppoe-server authentication radius-settings dae-server ip-address '10.1.1.2' + set service pppoe-server authentication radius-settings dae-server port '3799' + set service pppoe-server authentication radius-settings dae-server secret 'secret123' + +Example, from radius-server send command for disconnect client with username test + +.. code-block:: none + + root@radius-server:~# echo "User-Name=test" | radclient -x 10.1.1.2:3799 disconnect secret123 + +You can also use another attributes for identify client for disconnect, like Framed-IP-Address, Acct-Session-Id, etc. +Result commands appears in log + +.. code-block:: none + + show log | match Disconnect* + +Example for changing rate-limit via RADIUS CoA + +.. code-block:: none + + echo "User-Name=test,Filter-Id=5000/4000" | radclient 10.1.1.2:3799 coa secret123 + +Filter-Id=5000/4000 (means 5000Kbit down-stream rate and 4000Kbit up-stream rate) +If attribute Filter-Id redefined, replace it in radius coa request + + +Automatic VLAN creation +======================= + +VLAN's can be created by accel-ppp on the fly if via the use of the kernel module vlan_mon, which is monitoring incoming vlans and creates the necessary VLAN if required and allowed. +VyOS supports the use of either VLAN ID's or entire ranges, both values can be defined at the same time for an interface. + +.. code-block:: none + + set service pppoe-server interface eth3 vlan-id 100 + set service pppoe-server interface eth3 vlan-id 200 + set service pppoe-server interface eth3 vlan-range 500-1000 + set service pppoe-server interface eth3 vlan-range 2000-3000 + + +The pppoe-server will now create these VLANs if required and once the user session has been cancelled, and the VLAN is not necessary anymore, it will remove it again. + + + +Bandwidth Shaping +^^^^^^^^^^^^^^^^^ + +Bandwidth rate limits can be set for local users or RADIUS based attributes. + +Bandwidth Shaping for local users +================================= + +The rate-limit is set in kbit/sec. + +.. code-block:: none + + set service pppoe-server access-concentrator 'ACN' + set service pppoe-server authentication local-users username foo password 'bar' + set service pppoe-server authentication local-users username foo rate-limit download '20480' + set service pppoe-server authentication local-users username foo rate-limit upload '10240' + set service pppoe-server authentication mode 'local' + set service pppoe-server client-ip-pool start '10.1.1.100' + set service pppoe-server client-ip-pool stop '10.1.1.111' + set service pppoe-server dns-servers server-1 '10.100.100.1' + set service pppoe-server dns-servers server-2 '10.100.200.1' + set service pppoe-server interface 'eth1' + set service pppoe-server local-ip '10.1.1.2' + + +Once the user is connected, the user session is using the set limits and can be displayed via 'show pppoe-server sessions'. + +.. code-block:: none + + show pppoe-server sessions + ifname | username | ip | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes + -------+----------+------------+-------------------+-------------+--------+----------+----------+---------- + ppp0 | foo | 10.1.1.100 | 08:00:27:ba:db:15 | 20480/10240 | active | 00:00:11 | 214 B | 76 B + + +RADIUS based shaper setup +========================= + +The current attribute 'Filter-Id' is being used as default and can be setup within RADIUS: + +Filter-Id=2000/3000 (means 2000Kbit down-stream rate and 3000Kbit up-stream rate) + +The command below enables it, assuming the RADIUS connection has been setup and is working. + +.. code-block:: none + + set service pppoe-server authentication radius-settings rate-limit enable + +Other attributes can be used, but they have to be in one of the dictionaries in /usr/share/accel-ppp/radius. + + + +Practical Configuration Examples +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Dual-stack provisioning with IPv6 PD via pppoe +============================================== + +The example below covers a dual-stack configuration via pppoe-server. + +.. code-block:: none + + set service pppoe-server authentication local-users username test password 'test' + set service pppoe-server authentication mode 'local' + set service pppoe-server client-ip-pool start '192.168.0.1' + set service pppoe-server client-ip-pool stop '192.168.0.10' + set service pppoe-server client-ipv6-pool delegate-prefix '2001:db8:8003::1/48,56' + set service pppoe-server client-ipv6-pool prefix '2001:db8:8002::1/48,64' + set service pppoe-server dns-servers server-1 '8.8.8.8' + set service pppoe-server dnsv6-servers server-1 '2001:4860:4860::8888' + set service pppoe-server interface 'eth2' + set service pppoe-server local-ip '10.100.100.1' + + +The client, once successfully authenticated, will receive an IPv4 and an IPv6 /64 address, to terminate the pppoe endpoint on the client side and a /56 subnet for the clients internal use. + +.. code-block:: none + + vyos@pppoe-server:~$ sh pppoe-server sessions + ifname | username | ip | ip6 | ip6-dp | calling-sid | rate-limit | state | uptime | rx-bytes | tx-bytes + --------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- + ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 08:00:27:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB + +.. _`accel-ppp`: https://accel-ppp.org/ diff --git a/docs/configuration/service/references.rst b/docs/configuration/service/references.rst new file mode 100644 index 00000000..bee936d7 --- /dev/null +++ b/docs/configuration/service/references.rst @@ -0,0 +1,15 @@ +.. _`Cisco Discovery Protocol`: https://en.wikipedia.org/wiki/Cisco_Discovery_Protocol +.. _ddclient: http://github.com/ddclient/ddclient +.. _`Foundry Discovery Protocol`: https://en.wikipedia.org/wiki/Foundry_Discovery_Protocol +.. _MIB: https://en.wikipedia.org/wiki/Management_information_base +.. _RFC2136: https://www.ietf.org/rfc/rfc2136.txt +.. _SNMP: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol +.. _SNMPv2: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_2 +.. _SNMPv3: https://en.wikipedia.org/wiki/Simple_Network_Management_Protocol#Version_3 +.. _SSH: https://en.wikipedia.org/wiki/Secure_Shell +.. _Squid3: http://www.squid-cache.org/ +.. _Squidguard: http://www.squidguard.org/ +.. _TFTP: https://en.wikipedia.org/wiki/Trivial_File_Transfer_Protocol +.. _`arbitrary extension commands`: http://net-snmp.sourceforge.net/docs/man/snmpd.conf.html#lbAZ +.. _`accel-ppp`: https://accel-ppp.org/ +.. _`Secure Socket Tunneling Protocol`: https://en.wikipedia.org/wiki/Secure_Socket_Tunneling_Protocol diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/snmp.rst new file mode 100644 index 00000000..6418a516 --- /dev/null +++ b/docs/configuration/service/snmp.rst @@ -0,0 +1,245 @@ +SNMP +---- + +Simple Network Management Protocol (SNMP_) is an Internet Standard protocol +for collecting and organizing information about managed devices on IP networks +and for modifying that information to change device behavior. Devices that +typically support SNMP include cable modems, routers, switches, servers, +workstations, printers, and more. + +SNMP is widely used in network management for network monitoring. SNMP exposes +management data in the form of variables on the managed systems organized in +a management information base (MIB_) which describe the system status and +configuration. These variables can then be remotely queried (and, in some +circumstances, manipulated) by managing applications. + +Three significant versions of SNMP have been developed and deployed. SNMPv1 is +the original version of the protocol. More recent versions, SNMPv2c and SNMPv3, +feature improvements in performance, flexibility and security. + +SNMP is a component of the Internet Protocol Suite as defined by the Internet +Engineering Task Force (IETF). It consists of a set of standards for network +management, including an application layer protocol, a database schema, and a +set of data objects. + +Overview and basic concepts +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In typical uses of SNMP, one or more administrative computers called managers +have the task of monitoring or managing a group of hosts or devices on a +computer network. Each managed system executes a software component called an +agent which reports information via SNMP to the manager. + +An SNMP-managed network consists of three key components: + +* Managed devices +* Agent - software which runs on managed devices +* Network management station (NMS) - software which runs on the manager + +A managed device is a network node that implements an SNMP interface that +allows unidirectional (read-only) or bidirectional (read and write) access to +node-specific information. Managed devices exchange node-specific information +with the NMSs. Sometimes called network elements, the managed devices can be +any type of device, including, but not limited to, routers, access servers, +switches, cable modems, bridges, hubs, IP telephones, IP video cameras, +computer hosts, and printers. + +An agent is a network-management software module that resides on a managed +device. An agent has local knowledge of management information and translates +that information to or from an SNMP-specific form. + +A network management station executes applications that monitor and control +managed devices. NMSs provide the bulk of the processing and memory resources +required for network management. One or more NMSs may exist on any managed +network. + +.. figure:: /_static/images/service_snmp_communication_principles_diagram.png + :scale: 20 % + :alt: Principle of SNMP Communication + + Image thankfully borrowed from + https://en.wikipedia.org/wiki/File:SNMP_communication_principles_diagram.PNG + which is under the GNU Free Documentation License + +.. note:: VyOS SNMP supports both IPv4 and IPv6. + +SNMP protocol versions +^^^^^^^^^^^^^^^^^^^^^^ + +VyOS itself supports SNMPv2_ (version 2) and SNMPv3_ (version 3) where the +later is recommended because of improved security (optional authentication and +encryption). + +SNMPv2 +^^^^^^ + +SNMPv2 is the original and most commonly used version. For authorizing clients, +SNMP uses the concept of communities. Communities may have authorization set +to read only (this is most common) or to read and write (this option is not +actively used in VyOS). + +SNMP can work synchronously or asynchronously. In synchronous communication, +the monitoring system queries the router periodically. In asynchronous, the +router sends notification to the "trap" (the monitoring host). + +SNMPv2 does not support any authentication mechanisms, other than client source +address, so you should specify addresses of clients allowed to monitor the +router. Note that SNMPv2 also supports no encryption and always sends data in +plain text. + +Example +******* + +.. code-block:: none + + # Define a community + set service snmp community routers authorization ro + + # Allow monitoring access from the entire network + set service snmp community routers network 192.0.2.0/24 + set service snmp community routers network 2001::db8:ffff:eeee::/64 + + # Allow monitoring access from specific addresses + set service snmp community routers client 203.0.113.10 + set service snmp community routers client 203.0.113.20 + + # Define optional router information + set service snmp location "UK, London" + set service snmp contact "admin@example.com" + + # Trap target if you want asynchronous communication + set service snmp trap-target 203.0.113.10 + + # Listen only on specific IP addresses (port defaults to 161) + set service snmp listen-address 172.16.254.36 port 161 + set service snmp listen-address 2001:db8::f00::1 + + +SNMPv3 +^^^^^^ + +SNMPv3 (version 3 of the SNMP protocol) introduced a whole slew of new security +related features that have been missing from the previous versions. Security +was one of the biggest weakness of SNMP until v3. Authentication in SNMP +Versions 1 and 2 amounts to nothing more than a password (community string) +sent in clear text between a manager and agent. Each SNMPv3 message contains +security parameters which are encoded as an octet string. The meaning of these +security parameters depends on the security model being used. + +The securityapproach in v3 targets: + +* Confidentiality – Encryption of packets to prevent snooping by an + unauthorized source. + +* Integrity – Message integrity to ensure that a packet has not been tampered + while in transit including an optional packet replay protection mechanism. + +* Authentication – to verify that the message is from a valid source. + +Example +******* + +.. code-block:: none + + set service snmp v3 engineid '0x0aa0d6c6f450' + set service snmp v3 group defaultgroup mode 'ro' + set service snmp v3 group defaultgroup seclevel 'priv' + set service snmp v3 group defaultgroup view 'defaultview' + set service snmp v3 view defaultview oid '1' + + set service snmp v3 user testUser1 auth plaintext-key testUserKey1 + set service snmp v3 user testUser1 auth type 'md5' + set service snmp v3 user testUser1 engineid '0x0aa0d6c6f450' + set service snmp v3 user testUser1 group 'defaultgroup' + set service snmp v3 user testUser1 mode 'ro' + set service snmp v3 user testUser1 privacy type aes + set service snmp v3 user testUser1 privacy plaintext-key testUserKey1 + +After commit the resulting configuration will look like: + +.. note:: SNMPv3 keys won't we stored in plaintext. On ``commit`` the keys + will be encrypted and the encrypted key is based on the engineid! + +.. code-block:: none + + vyos@vyos# show service snmp + v3 { + engineid 0x0aa0d6c6f450 + group defaultgroup { + mode ro + seclevel priv + view defaultview + } + user testUser1 { + auth { + encrypted-key 0x3b68d4162c2c817b8e9dfb6f08583e5d + type md5 + } + engineid 0x0aa0d6c6f450 + group defaultgroup + mode ro + privacy { + encrypted-key 0x3b68d4162c2c817b8e9dfb6f08583e5d + type aes + } + } + view defaultview { + oid 1 { + } + } + } + +SNMP Extensions +^^^^^^^^^^^^^^^ + +To extend SNMP agent functionality, custom scripts can be executed every time +the agent is being called. This can be achieved by using ``arbitrary extension +commands``_. The first step is to create a functional script of course, then +upload it to your VyOS instance via the command ``scp your_script.sh +vyos@your_router:/config/user-data``. Once the script is uploaded, it needs to +be configured via the command below. + + +.. code-block:: none + + set service snmp script-extensions extension-name my-extension script your_script.sh + commit + + +The OID ``.1.3.6.1.4.1.8072.1.3.2.3.1.1.4.116.101.115.116``, once called, will +contain the output of the extension. + +.. code-block:: none + + root@vyos:/home/vyos# snmpwalk -v2c -c public 127.0.0.1 nsExtendOutput1 + NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."my-extension" = STRING: hello + NET-SNMP-EXTEND-MIB::nsExtendOutputFull."my-extension" = STRING: hello + NET-SNMP-EXTEND-MIB::nsExtendOutNumLines."my-extension" = INTEGER: 1 + NET-SNMP-EXTEND-MIB::nsExtendResult."my-extension" = INTEGER: 0 + +SolarWinds +^^^^^^^^^^ + +If you happen to use SolarWinds Orion as NMS you can also use the Device +Templates Management. A template for VyOS can be easily imported. + +Create a file named ``VyOS-1.3.6.1.4.1.44641.ConfigMgmt-Commands`` using the +following content: + +.. code-block:: none + + <Configuration-Management Device="VyOS" SystemOID="1.3.6.1.4.1.44641"> + <Commands> + <Command Name="Reset" Value="set terminal width 0${CRLF}set terminal length 0"/> + <Command Name="Reboot" Value="reboot${CRLF}Yes"/> + <Command Name="EnterConfigMode" Value="configure"/> + <Command Name="ExitConfigMode" Value="commit${CRLF}exit"/> + <Command Name="DownloadConfig" Value="show configuration commands"/> + <Command Name="SaveConfig" Value="commit${CRLF}save"/> + <Command Name="Version" Value="show version"/> + <Command Name="MenuBased" Value="False"/> + <Command Name="VirtualPrompt" Value=":~"/> + </Commands> + </Configuration-Management> + +.. include:: references.rst diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst new file mode 100644 index 00000000..3af71899 --- /dev/null +++ b/docs/configuration/service/ssh.rst @@ -0,0 +1,150 @@ +SSH +--- + +Secure Shell (SSH_) is a cryptographic network protocol for operating network +services securely over an unsecured network.[1] The standard TCP port for SSH +is 22. The best known example application is for remote login to computer +systems by users. + +SSH provides a secure channel over an unsecured network in a client-server +architecture, connecting an SSH client application with an SSH server. Common +applications include remote command-line login and remote command execution, +but any network service can be secured with SSH. The protocol specification +distinguishes between two major versions, referred to as SSH-1 and SSH-2. + +The most visible application of the protocol is for access to shell accounts +on Unix-like operating systems, but it sees some limited use on Windows as +well. In 2015, Microsoft announced that they would include native support for +SSH in a future release. + +SSH was designed as a replacement for Telnet and for unsecured remote shell +protocols such as the Berkeley rlogin, rsh, and rexec protocols. +Those protocols send information, notably passwords, in plaintext, +rendering them susceptible to interception and disclosure using packet +analysis. The encryption used by SSH is intended to provide confidentiality +and integrity of data over an unsecured network, such as the Internet. + +Configuration +^^^^^^^^^^^^^ + +Enabling SSH only requires you to add ``service ssh port NN``, where 'NN' is +the port you want SSH to listen on. By default, SSH runs on port 22. + +.. code-block:: none + + set service ssh port 22 + +Options +******* + +* Listening address - Specify the IPv4/IPv6 listening address for connection + requests. Multiple ``listen-address`` nodes can be defined. + + :code:`set service ssh listen-address <address>` + +* Allow ``root`` login, this can be set to allow ``root`` logins on SSH + connections, however it is not advisable to use this setting as this bears + serious security risks. The default system user possesses all required + privileges. + + :code:`set service ssh allow-root` + +* Allowed ciphers - A number of allowed ciphers can be specified, use multiple + occurrences to allow multiple ciphers. + + :code:`set service ssh ciphers <cipher>` + + Available ciphers: + + * `3des-cbc` + * `aes128-cbc` + * `aes192-cbc` + * `aes256-cbc` + * `aes128-ctr` + * `aes192-ctr` + * `aes256-ctr` + * `arcfour128` + * `arcfour256` + * `arcfour` + * `blowfish-cbc` + * `cast128-cbc` + +* Disable password authentication - If SSH key authentication is set up, + password-based user authentication can be disabled. This hardens security! + + :code:`set service ssh disable-password-authentication` + +* Disable host validation - Disable the host validation through reverse DNS + lookups. + + :code:`set service ssh disable-host-validation` + +* MAC algorithms - Specifies the available MAC (message authentication code) + algorithms. The MAC algorithm is used in protocol version 2 for data + integrity protection. Multiple algorithms can be entered. + + :code:`set service ssh macs <macs>` + + Supported MACs: + + * `hmac-md5` + * `hmac-md5-96` + * `hmac-ripemd160` + * `hmac-sha1` + * `hmac-sha1-96` + * `hmac-sha2-256` + * `hmac-sha2-512` + * `umac-64@openssh.com` + * `umac-128@openssh.com` + * `hmac-md5-etm@openssh.com` + * `hmac-md5-96-etm@openssh.com` + * `hmac-ripemd160-etm@openssh.com` + * `hmac-sha1-etm@openssh.com` + * `hmac-sha1-96-etm@openssh.com` + * `hmac-sha2-256-etm@openssh.com` + * `hmac-sha2-512-etm@openssh.com` + * `umac-64-etm@openssh.com` + * `umac-128-etm@openssh.com` + + +Key Authentication +################## + +It is highly recommended to use SSH Key authentication. By default there is +only one user (``vyos``), and you can assign any number of keys to that user. +You can generate a ssh key with the ``ssh-keygen`` command on your local +machine, which will (by default) save it as ``~/.ssh/id_rsa.pub`` which is in +three parts: + + ``ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAA...VByBD5lKwEWB username@host.example.com`` + +Only the type (``ssh-rsa``) and the key (``AAAB3N...``) are used. Note that +the key will usually be several hundred characters long, and you will need to +copy and paste it. Some terminal emulators may accidentally split this over +several lines. Be attentive when you paste it that it only pastes as a single +line. The third part is simply an identifier, and is for your own reference. + + +**Assign SSH Key to user** + +Under the user (in this example, ``vyos``), add the public key and the type. +The `identifier` is simply a string that is relevant to you. + +.. code-block:: none + + set system login user vyos authentication public-keys 'identifier' key "AAAAB3Nz...." + set system login user vyos authentication public-keys 'identifier' type ssh-rsa" + +You can assign multiple keys to the same user by changing the identifier. In +the following example, both Unicron and xrobau will be able to SSH into VyOS +as the ``vyos`` user using their own keys. + +.. code-block:: none + + set system login user vyos authentication public-keys 'Unicron' key "AAAAB3Nz...." + set system login user vyos authentication public-keys 'Unicron' type ssh-rsa + set system login user vyos authentication public-keys 'xrobau' key "AAAAQ39x...." + set system login user vyos authentication public-keys 'xrobau' type ssh-rsa + + + diff --git a/docs/configuration/service/tftp-server.rst b/docs/configuration/service/tftp-server.rst new file mode 100644 index 00000000..9ce46b02 --- /dev/null +++ b/docs/configuration/service/tftp-server.rst @@ -0,0 +1,42 @@ +TFTP +---- + +Trivial File Transfer Protocol (TFTP_) is a simple lockstep File Transfer +Protocol which allows a client to get a file from or put a file onto a remote +host. One of its primary uses is in the early stages of nodes booting from a +local area network. TFTP has been used for this application because it is very +simple to implement. + +Example +^^^^^^^ + +.. code-block:: none + + # If you want to enable uploads, else TFTP server will act as read-only (optional) + set service tftp-server allow-upload + + # Directory for TFTP server content + set service tftp-server directory '/config/tftpboot' + + # On which addresses we want to listen for incoming TFTP connections? (mandatory) + set service tftp-server listen-address '2001:db8:ffee::1' + set service tftp-server listen-address '10.10.1.1' + +.. note:: Choose your ``directory`` location carefully or you will loose the + content on image upgrades. Any directory under ``/config`` is save at this + will be migrated. + +.. note:: Configuring a listen-address is essential for the service to work. + +The resulting configuration will look like: + +.. code-block:: none + + vyos@vyos# show service + tftp-server { + allow-upload + directory /config/tftpboot + listen-address 2001:db8:ffee::1 + listen-address 10.10.1.1 + } + diff --git a/docs/configuration/service/webproxy.rst b/docs/configuration/service/webproxy.rst new file mode 100644 index 00000000..61546cda --- /dev/null +++ b/docs/configuration/service/webproxy.rst @@ -0,0 +1,152 @@ +Webproxy +-------- + +The proxy service in VyOS is based on Squid3 and some related modules. + +Squid is a caching and forwarding HTTP web proxy. It has a wide variety of +uses, including speeding up a web server by caching repeated requests, +caching web, DNS and other computer network lookups for a group of people +sharing network resources, and aiding security by filtering traffic. Although +primarily used for HTTP and FTP, Squid includes limited support for several +other protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does +not support the SOCKS protocol. + +All examples here assumes that your inside ip address is ``192.168.0.1``. +Replace with your own where applicable. + +URL Filtering is provided by Squidguard_. + +Configuration +^^^^^^^^^^^^^^ + +.. code-block:: none + + # Enable proxy service + set service webproxy listen-address 192.168.0.1 + + # By default it will listen to port 3128. If you wan't something else you have to define that. + set service webproxy listen-address 192.168.0.1 port 2050 + + # By default the transparent proxy on that interface is enabled. To disable that you simply + set service webproxy listen-address 192.168.0.1 disable-transparent + + # Block specific urls + set service webproxy url-filtering squidguard local-block myspace.com + + # If you want to you can log these blocks + set service webproxy url-filtering squidguard log local-block + + +Options +******* + +Filtering by category +^^^^^^^^^^^^^^^^^^^^^ + +If you wan't to use existing blacklists you have to create/download a database +first. Otherwise you will not be able to commit the config changes. + +.. code-block:: none + + vyos@vyos# commit + [ service webproxy ] + Warning: no blacklists installed + Unknown block-category [ads] for policy [default] + + [[service webproxy]] failed + Commit failed + +* Download/Update complete blacklist + + :code:`update webproxy blacklists` + +* Download/Update partial blacklist + + :code:`update webproxy blacklists category ads` + + Use tab completion to get a list of categories. + +* To auto update the blacklist files + + :code:`set service webproxy url-filtering squidguard auto-update update-hour 23` + +* To configure blocking add the following to the configuration + + :code:`set service webproxy url-filtering squidguard block-category ads` + + :code:`set service webproxy url-filtering squidguard block-category malware` + +Authentication +^^^^^^^^^^^^^^ + +The embedded Squid proxy can use LDAP to authenticate users against a company +wide directory. The following configuration is an example of how to use Active +Directory as authentication backend. Queries are done via LDAP. + +.. code-block:: none + + vyos@vyos# show service webproxy + authentication { + children 5 + credentials-ttl 60 + ldap { + base-dn DC=example,DC=local + bind-dn CN=proxyuser,CN=Users,DC=example,DC=local + filter-expression (cn=%s) + password Qwert1234 + server ldap.example.local + username-attribute cn + } + method ldap + realm "VyOS Webproxy" + } + cache-size 100 + default-port 3128 + listen-address 192.168.188.103 { + disable-transparent + } + +* ``base-dn`` set the base directory for the search +* ``bind-dn`` and ``password``: set the user, which is used for the ldap search +* ``filter-expression``: set the exact filter which a authorized user match in a ldap-search. In this example every User is able to authorized. + +You can find more about the ldap authentication `here <http://www.squid-cache.org/Versions/v3/3.2/manuals/basic_ldap_auth.html>`_ + +Adjusting cache size +^^^^^^^^^^^^^^^^^^^^ + +The size of the proxy cache can be adjusted by the user. + +.. code-block:: none + + set service webproxy cache-size + Possible completions: + <0-4294967295> + Disk cache size in MB (default 100) + 0 Disable disk caching + 100 + +Bypassing the webproxy +^^^^^^^^^^^^^^^^^^^^^^ + +Some services don't work correctly when being handled via a web proxy. +So sometimes it is useful to bypass a transparent proxy: + +* To bypass the proxy for every request that is directed to a specific + destination: + + :code:`set service webproxy whitelist destination-address 198.51.100.33` + + :code:`set service webproxy whitelist destination-address 192.0.2.0/24` + + +* To bypass the proxy for every request that is coming from a specific source: + + :code:`set service webproxy whitelist source-address 192.168.1.2` + + :code:`set service webproxy whitelist source-address 192.168.2.0/24` + + (This can be useful when a called service has many and/or often changing + destination addresses - e.g. Netflix.) + +.. include:: references.rst diff --git a/docs/configuration/system/console.rst b/docs/configuration/system/console.rst new file mode 100644 index 00000000..730c9da1 --- /dev/null +++ b/docs/configuration/system/console.rst @@ -0,0 +1,17 @@ +.. _serial-console: + +Serial console +============== + + + +Configuring Console +------------------- + +.. code-block:: none + + vyos@vyos# set system console + Possible completions: + +> device Serial console device name + +> network Network based console logging + powersave Enable screen blank powersaving on VGA console
\ No newline at end of file diff --git a/docs/configuration/system/eventhandler.rst b/docs/configuration/system/eventhandler.rst new file mode 100644 index 00000000..4421e79c --- /dev/null +++ b/docs/configuration/system/eventhandler.rst @@ -0,0 +1,48 @@ +.. _event-handler: + +Event Handler +------------- + +Event handler allows you to execute scripts when a string that matches a regex appears in a text stream (e.g. log file). + +It uses "feeds" (output of commands, or a named pipes) and "policies" that define what to execute if a regex is matched. + +.. code-block:: none + + system + event-handler + feed <name> + description <feed description> + policy <policy name> + source + preset + syslog # Use the syslog logs for feed + custom + command <command to execute> # E.g. "tail -f /var/log/somelogfile" + named-pipe <path to a names pipe> + policy <policy name> + description <policy description> + event <event name> + description <event description> + pattern <regex> + run <command to run> + +In this small example a script runs every time a login failed and an interface goes down + +.. code-block:: none + + vyos@vyos# show system event-handler + feed Syslog { + policy MyPolicy + source { + preset syslog + } + } + policy MyPolicy { + description "Test policy" + event BadThingsHappened { + pattern "authentication failure" + pattern "interface \.* index \d+ .* DOWN.*" + run /config/scripts/email-to-admin + } + }
\ No newline at end of file diff --git a/docs/configuration/system/flow-accounting.rst b/docs/configuration/system/flow-accounting.rst new file mode 100644 index 00000000..9c876001 --- /dev/null +++ b/docs/configuration/system/flow-accounting.rst @@ -0,0 +1,81 @@ +.. _flow-accounting: + +NetFlow is a feature that was introduced on Cisco routers around 1996 that +provides the ability to collect IP network traffic as it enters or exits an +interface. By analyzing the data provided by NetFlow, a network administrator +can determine things such as the source and destination of traffic, class of +service, and the causes of congestion. A typical flow monitoring setup (using +NetFlow) consists of three main components: + +* Flow exporter: aggregates packets into flows and exports flow records towards + one or more flow collectors +* Flow collector: responsible for reception, storage and pre-processing of flow + data received from a flow exporter +* Analysis application: analyzes received flow data in the context of intrusion + detection or traffic profiling, for example + +For connectionless protocols as like ICMP and UDP, a flow is considered complete +once no more packets for this flow appear after configurable timeout. + +NetFlow is usually enabled on a per-interface basis to limit load on the router +components involved in NetFlow, or to limit the amount of NetFlow records +exported. + +VyOS supports flow accounting through NetFlow (version 5, 9 and 10) or sFlow. + +Flow Accounting +--------------- + +In order for flow accounting information to be collected and displayed for an +interface, the interface must be configured for flow accounting. The following +example shows how to configure ``eth0`` and ``bond3`` for flow accounting. + +.. code-block:: none + + set system flow-accounting interface eth0 + set system flow-accounting interface bond3 + + +NetFlow is a protocol originating from Cisco Systems. It works on level3. +VyOS supports version 5, 9 and 10 (IPFIX - IP Flow Information Export) + +NetFlow v5 example: + +.. code-block:: none + + set system flow-accounting netflow engine-id 100 + set system flow-accounting netflow version 5 + set system flow-accounting netflow server 192.168.2.10 port 2055 + +Displaying Flow Accounting Information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once flow accounting is configured on an interfaces it provides the ability to +display captured network traffic information for all configured interfaces. + +The following op-mode command shows flow accounting for eth0. + +.. code-block:: none + + vyos@vyos:~$ show flow-accounting interface eth0 + flow-accounting for [eth0] + Src Addr Dst Addr Sport Dport Proto Packets Bytes Flows + 0.0.0.0 192.0.2.50 811 811 udp 7733 591576 0 + 0.0.0.0 192.0.2.50 811 811 udp 7669 586558 1 + 192.0.2.200 192.0.2.51 56188 22 tcp 586 36504 1 + 192.0.2.99 192.0.2.51 61636 161 udp 46 6313 4 + 192.0.2.99 192.0.2.51 61638 161 udp 42 5364 9 + 192.0.2.99 192.0.2.51 61640 161 udp 42 5111 3 + 192.0.2.200 192.0.2.51 54702 22 tcp 86 4432 1 + 192.0.2.99 192.0.2.51 62509 161 udp 24 3540 1 + 192.0.2.99 192.0.2.51 0 0 icmp 49 2989 8 + 192.0.2.99 192.0.2.51 54667 161 udp 18 2658 1 + 192.0.2.99 192.0.2.51 54996 161 udp 18 2622 1 + 192.0.2.99 192.0.2.51 63708 161 udp 18 2622 1 + 192.0.2.99 192.0.2.51 62111 161 udp 18 2622 1 + 192.0.2.99 192.0.2.51 61646 161 udp 16 1977 4 + 192.0.2.99 192.0.2.51 56038 161 udp 10 1256 1 + 192.0.2.99 192.0.2.51 55570 161 udp 6 1146 1 + 192.0.2.99 192.0.2.51 54599 161 udp 6 1134 1 + 192.0.2.99 192.0.2.51 56304 161 udp 8 1029 1 + diff --git a/docs/configuration/system/host-information.rst b/docs/configuration/system/host-information.rst new file mode 100644 index 00000000..71209412 --- /dev/null +++ b/docs/configuration/system/host-information.rst @@ -0,0 +1,175 @@ +.. _host-information: + +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:: none + + set system host-name <hostname> + +.. note:: Only letters, numbers and hyphens are allowed. + +Show host name: + +.. code-block:: none + + show system host-name + +Delete host name: + +.. code-block:: none + + delete system host-name <hostname> + +Example: Set system hostname to 'RT01': + +.. code-block:: none + + set system host-name RT01 + commit + show system host-name + host-name RT01 + +Domain Name +^^^^^^^^^^^ + +A domain name is the label (name) assigned to a computer network and is thus +unique. + +Set the system's domain: + +.. code-block:: none + + set system domain-name <domain> + +.. note:: Only letters, numbers, hyphens and periods are allowed. + +Show domain: + +.. code-block:: none + + show system domain-name + +Remove domain name: + +.. code-block:: none + + set system delete domain-name <domain> + +Example: Set system domain to example.com: + +.. code-block:: none + + 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 +:ref:`interfaces-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:: none + + set system static-host-mapping host-name <hostname> inet <IP address> + +Show static mapping: + +.. code-block:: none + + 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:: none + + 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:: none + + set system static-host-mapping host-name <hostname> alias <alias> + +Show aliases: + +.. code-block:: none + + show system static-mapping + +Delete alias: + +.. code-block:: none + + delete system static-host-mapping host-name <hostname> alias <alias> + +Example: Set alias `router1` for system with hostname `RT01`: + +.. code-block:: none + + 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 <IP 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:: none + + set protocols static route 0.0.0.0/0 next-hop <gateway ip> + +Delete the default route from the system + +.. code-block:: none + + delete protocols static route 0.0.0.0/0 + +Show default route: + +.. code-block:: none + + 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 diff --git a/docs/configuration/system/index.rst b/docs/configuration/system/index.rst new file mode 100644 index 00000000..07ba2ff5 --- /dev/null +++ b/docs/configuration/system/index.rst @@ -0,0 +1,24 @@ +.. _system: + +System +====== + +After a basic system setup by setting up :ref:`interfaces-addresses`, VyOS +should be ready for further configuration which is described in this chapter. + + +.. toctree:: + :maxdepth: 2 + + host-information + console + eventhandler + flow-accounting + login + ip + ipv6 + name-server + ntp + syslog + task-scheduler + time-zone
\ No newline at end of file diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/ip.rst new file mode 100644 index 00000000..6c158de9 --- /dev/null +++ b/docs/configuration/system/ip.rst @@ -0,0 +1,75 @@ +.. _ip: + +IPv4 +==== + +System configuration commands +----------------------------- + + +.. cfgcmd:: set system ip disable-forwarding + + Use this command to disable IPv4 forwarding on all interfaces. + + +.. cfgcmd:: set system ip arp table-size <number> + + Use this command to define the maximum number of entries to keep in + the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). + + +.. cfgcmd:: set system ip multipath layer4-hashing + + Use this command to use Layer 4 information for IPv4 ECMP hashing. + + +Operational commands +-------------------- + + +show commands +^^^^^^^^^^^^^ + +See below the different parameters available for the IPv4 **show** command: + +.. code-block:: + + vyos@vyos:~$ show ip + Possible completions: + access-list Show all IP access-lists + as-path-access-list + Show all as-path-access-lists + bgp Show Border Gateway Protocol (BGP) information + community-list + Show IP community-lists + extcommunity-list + Show extended IP community-lists + forwarding Show IP forwarding status + groups Show IP multicast group membership + igmp Show IGMP (Internet Group Management Protocol) information + large-community-list + Show IP large-community-lists + multicast Show IP multicast + ospf Show IPv4 Open Shortest Path First (OSPF) routing information + pim Show PIM (Protocol Independent Multicast) information + ports Show IP ports in use by various system services + prefix-list Show all IP prefix-lists + protocol Show IP route-maps per protocol + rip Show Routing Information Protocol (RIP) information + route Show IP routes + + +reset commands +^^^^^^^^^^^^^^ + +And the different IPv4 **reset** commands available: + +.. code-block:: + + vyos@vyos:~$ reset ip + Possible completions: + arp Reset Address Resolution Protocol (ARP) cache + bgp Clear Border Gateway Protocol (BGP) statistics or status + igmp IGMP clear commands + multicast IP multicast routing table + route Reset IP route diff --git a/docs/configuration/system/ipv6.rst b/docs/configuration/system/ipv6.rst new file mode 100644 index 00000000..8b00ccf8 --- /dev/null +++ b/docs/configuration/system/ipv6.rst @@ -0,0 +1,202 @@ +.. _ipv6: + + +IPv6 +==== + +System configuration commands +----------------------------- + +.. cfgcmd:: set system ipv6 disable + + Use this command to disable assignment of IPv6 addresses on all + interfaces. + + +.. cfgcmd:: set system ipv6 disable-forwarding + + Use this command to disable IPv6 forwarding on all interfaces. + + +.. cfgcmd:: set system ipv6 neighbor table-size <number> + + Use this command to define the maximum number of entries to keep in + the Neighbor cache (1024, 2048, 4096, 8192, 16384, 32768). + + +.. cfgcmd:: set system ipv6 strict-dad + + Use this command to disable IPv6 operation on interface when + Duplicate Address Detection fails on Link-Local address. + + +.. cfgcmd:: set system ipv6 multipath layer4-hashing + + Use this command to user Layer 4 information for ECMP hashing. + +.. cfgcmd:: set system ipv6 blacklist + + Use this command to prevent the IPv6 kernel module from being loaded. + + + +Operational commands +-------------------- + +Show commands +^^^^^^^^^^^^^ + + +.. opcmd:: show ipv6 neighbors + + Use this command to show IPv6 Neighbor Discovery Protocol information. + + +.. opcmd:: show ipv6 groups + + Use this command to show IPv6 multicast group membership. + + +.. opcmd:: show ipv6 forwarding + + Use this command to show IPv6 forwarding status. + +.. opcmd:: show ipv6 route + + Use this command to show IPv6 routes. + + + Check the many parameters available for the `show ipv6 route` command: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 route + Possible completions: + <Enter> Execute the current command + <X:X::X:X> Show IPv6 routes of given address or prefix + <X:X::X:X/M> + bgp Show IPv6 BGP routes + cache Show kernel IPv6 route cache + connected Show IPv6 connected routes + forward Show kernel IPv6 route table + isis Show IPv6 ISIS routes + kernel Show IPv6 kernel routes + ospfv3 Show IPv6 OSPF6 routes + ripng Show IPv6 RIPNG routes + static Show IPv6 static routes + summary Show IPv6 routes summary + table Show IP routes in policy table + + +.. opcmd:: show ipv6 prefix-list + + Use this command to show all IPv6 prefix lists + + There are different parameters for getting prefix-list information: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 prefix-list + Possible completions: + <Enter> Execute the current command + <WORD> Show specified IPv6 prefix-list + detail Show detail of IPv6 prefix-lists + summary Show summary of IPv6 prefix-lists + +.. opcmd:: show ipv6 access-list + + Use this command to show all IPv6 access lists + + You can also specify which IPv6 access-list should be shown: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 access-list + Possible completions: + <Enter> Execute the current command + <text> Show specified IPv6 access-list + + + +.. opcmd:: show ipv6 bgp + + Use this command to show IPv6 Border Gateway Protocol information. + + + In addition, you can specify many other parameters to get BGP + information: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 bgp + Possible completions: + <Enter> Execute the current command + <X:X::X:X> Show BGP information for given address or prefix + <X:X::X:X/M> + community Show routes matching the communities + community-list + Show routes matching the community-list + filter-list Show routes conforming to the filter-list + large-community + Show routes matching the large-community-list + large-community-list + neighbors Show detailed information on TCP and BGP neighbor connections + prefix-list Show routes matching the prefix-list + regexp Show routes matching the AS path regular expression + summary Show summary of BGP neighbor status + + + +.. opcmd:: show ipv6 ospfv3 + + Use this command to get information about OSPFv3. + + You can get more specific OSPFv3 information by using the parameters + shown below: + + .. code-block:: none + + vyos@vyos:~$ show ipv6 ospfv3 + Possible completions: + <Enter> Execute the current command + area Show OSPFv3 spf-tree information + border-routers + Show OSPFv3 border-router (ABR and ASBR) information + database Show OSPFv3 Link state database information + interface Show OSPFv3 interface information + linkstate Show OSPFv3 linkstate routing information + neighbor Show OSPFv3 neighbor information + redistribute Show OSPFv3 redistribute External information + route Show OSPFv3 routing table information + +.. opcmd:: show ipv6 ripng + + Use this command to get information about the RIPNG protocol + +.. opcmd:: show ipv6 ripng status + + Use this command to show the status of the RIPNG protocol + + + +Reset commands +^^^^^^^^^^^^^^ + +.. opcmd:: reset ipv6 bgp <address> + + Use this command to clear Border Gateway Protocol statistics or + status. + + +.. opcmd:: reset ipv6 neighbors <address | interface> + + Use this command to reset IPv6 Neighbor Discovery Protocol cache for + an address or interface. + +.. opcmd:: reset ipv6 route cache + + Use this command to flush the kernel IPv6 route cache. + An address can be added to flush it only for that route. + + + diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/login.rst new file mode 100644 index 00000000..c34e41a0 --- /dev/null +++ b/docs/configuration/system/login.rst @@ -0,0 +1,129 @@ +.. _systemusers: + +Login +----- + +The default VyOS user account (`vyos`), as well as newly created user accounts, +have all capabilities to configure the system. All accounts have sudo capabilities +and therefore can operate as root on the system. Setting the level to admin is +optional, all accounts on the system will have admin privileges. + +Both local administered and remote administered RADIUS (Remote Authentication +Dial-In User Service) accounts are supported. + +Local +^^^^^ + +Create user account `jsmith` and the password `mypassword`. + +.. code-block:: none + + set system login user jsmith full-name "Johan Smith" + set system login user jsmith authentication plaintext-password mypassword + +The command: + +.. code-block:: none + + show system login + +will show the contents of :code:`system login` configuration node: + +.. code-block:: none + + user jsmith { + authentication { + encrypted-password $6$0OQHjuQ8M$AYXVn7jufdfqPrSk4/XXsDBw99JBtNsETkQKDgVLptXogHA2bU9BWlvViOFPBoFxIi.iqjqrvsQdQ./cfiiPT. + plaintext-password "" + } + full-name "Johan Smith" + level admin + } + +SSH with Public Keys +******************** + +The following command will load the public key `dev.pub` for user `jsmith` + +.. code-block:: none + + 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:: none + + loadkey jsmith scp://devuser@dev001.vyos.net/home/devuser/.ssh/dev.pub + +In addition SSH public keys can be fully added using the CLI. Each key can be +given a unique identifier, `calypso` is used oin the example below to id an SSH +key. + +.. code-block:: none + + set system login user jsmith authentication public-keys callisto key 'AAAAB3Hso...Q==' + set system login user jsmith authentication public-keys callisto type 'ssh-rsa' + +RADIUS +^^^^^^ + +VyOS supports using one or more RADIUS servers as backend for user authentication. + +The following command sets up two servers for RADIUS authentication, one with a +discrete timeout of `5` seconds and a discrete port of `1812` and the other using +a default timeout and port. + +.. code-block:: none + + set system login radius-server 192.168.1.2 secret 's3cr3t0815' + set system login radius-server 192.168.1.2 timeout '5' + set system login radius-server 192.168.1.2 port '1812' + set system login radius-server 192.168.1.3 secret 's3cr3t0816' + +This configuration results in: + +.. code-block:: none + + show system login + radius-server 192.168.1.2 { + secret s3cr3t0815 + timeout 5 + port 1812 + } + radius-server 192.168.1.3 { + secret s3cr3t0816 + } + +.. note:: If you wan't to have admin users to authenticate via RADIUS it is + essential to sent the ``Cisco-AV-Pair shell:priv-lvl=15`` attribute. Without + the attribute you will only get regular, non privilegued, system users. + +Source Address +************** + +RADIUS servers could be hardened by only allowing certain IP addresses to connect. +As of this the source address of each RADIUS query can be configured. If this is +not set incoming connections to the RADIUS server will use the nearest interface +address pointing towards the RADIUS server - making it error prone on e.g. OSPF +networks when a link fails. + +.. code-block:: none + + set system login radius-source-address 192.168.1.254 + +Login Banner +^^^^^^^^^^^^ + +You are able to set post-login or pre-login messages with the following lines: + +.. code-block:: none + + set system login banner pre-login "UNAUTHORIZED USE OF THIS SYSTEM IS PROHIBITED\n" + set system login banner post-login "Welcome to VyOS" + +the **\\n** create a newline. + + + diff --git a/docs/configuration/system/name-server.rst b/docs/configuration/system/name-server.rst new file mode 100644 index 00000000..70848f6d --- /dev/null +++ b/docs/configuration/system/name-server.rst @@ -0,0 +1,68 @@ +.. _system-dns: + +########## +System DNS +########## + + +This section describes configuring DNS on the system, namely: + + * DNS name servers + * Domain search order + + +DNS name servers +================ + +.. cfgcmd:: set system name-server <address> + + Use this command to specify a DNS server for the system to be used + for DNS lookups. More than one DNS server can be added, configuring + one at a time. Both IPv4 and IPv6 addresses are supported. + + + +Example +------- + +In this example, some *OpenNIC* servers are used, two IPv4 addresses +and two IPv6 addresses: + + +.. code-block:: none + + set system name-server 176.9.37.132 + set system name-server 195.10.195.195 + set system name-server 2a01:4f8:161:3441::1 + set system name-server 2a00:f826:8:2::195 + + +Domain search order +=================== + +In order for the system to use and complete unqualified host names, a +list can be defined which will be used for domain searches. + + +.. cfgcmd:: set system domain-search domain <domain> + + Use this command to define domains, one at a time, so that the system + uses them to complete unqualified host names. Maximum: 6 entries. + + +.. note:: Domain names can include letters, numbers, hyphens and periods + with a maximum length of 253 characters. + + +Example +------- + +The system is configured to attempt domain completion in the following +order: vyos.io (first), vyos.net (second) and vyos.network (last): + + +.. code-block:: none + + set system domain-search domain vyos.io + set system domain-search domain vyos.net + set system domain-search domain vyos.network diff --git a/docs/configuration/system/ntp.rst b/docs/configuration/system/ntp.rst new file mode 100644 index 00000000..95ff0692 --- /dev/null +++ b/docs/configuration/system/ntp.rst @@ -0,0 +1,19 @@ +.. _ntp: + +NTP +=== + +there are 3 default NTP server set. You are able to change them. + +.. code-block:: none + + set system ntp server 0.pool.ntp.org + set system ntp server 1.pool.ntp.org + set system ntp server 2.pool.ntp.org + +To set up VyOS as an NTP responder, you must specify the listen address and optionally the permitted clients. + +.. code-block:: none + + set system ntp listen-address 192.168.199.1 + set system ntp allow-clients address 192.168.199.0/24 diff --git a/docs/configuration/system/syslog.rst b/docs/configuration/system/syslog.rst new file mode 100644 index 00000000..9f3e1a28 --- /dev/null +++ b/docs/configuration/system/syslog.rst @@ -0,0 +1,224 @@ +.. _syslog: + +###### +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 +======= + +Syslog supports logging to multiple targets, those targets could be a plain +file on your VyOS installation itself, a serial console or a remote syslog +server which is reached via :abbr:`IP (Internet Protocol)` UDP/TCP. + +Console +------- + +.. cfgcmd:: set system syslog console facility <keyword> level <keyword> + +Log syslog messages to ``/dev/console``, for an explanation on +:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords +see tables below. + + +Custom File +----------- + +.. cfgcmd:: set system syslog file <filename> facility <keyword> level <keyword> + +Log syslog messages to file specified via `<filename>`, for en explanation on +:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see +tables below. + +.. cfgcmd:: set system syslog file <filename> archive size <size> + +Syslog will write `<size>` kilobytes into the file specified by `<filename>`. +After this limit has been reached, the custom file is "rotated" by logrotate +and a new custom file is created. + +.. cfgcmd:: set system syslog file <filename> archive file <number> + +Syslog uses logrotate to rotate logiles after a number of gives bytes. We keep +as many as `<number>` rotated file before they are deleted on the system. + + +Remote Host +----------- + +Logging to a remote host leaves the local logging configuration intact, it +can be configured in parallel to a custom file or console logging. You can log +to multiple hosts at the same time, using either TCP or UDP. The default is +sending the messages via port 514/UDP. + + +.. cfgcmd:: set system syslog host <address> facility <keyword> level <keyword> + +Log syslog messages to remote host specified by `<address>`. The address can be +specified by either FQDN or IP address. For en explanation on +:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see +tables below. + + +.. cfgcmd:: set system syslog host <address> facility <keyword> protocol <udp|tcp> + +Configure protocol used for communication to remote syslog host. This can be +either UDP or TCP. + + +Local User Account +------------------ + +.. cfgcmd:: set system syslog user <username> facility <keyword> level <keyword> + +If logging to a local user account 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. For en explanation on +:ref:`syslog_facilities` keywords and :ref:`syslog_severity_level` keywords see +tables below. + +.. _syslog_facilities: + +Facilities +========== + +List of facilities used by syslog. Most facilities names are self explanatory. +Facilities local0 - local7 common usage is f.e. as network logs facilities for +nodes and network equipment. Generally it depends on the situation how to +classify logs and put them to facilities. See facilities more as a tool rather +than a directive to follow. + +Facilities can be adjusted to meet the needs of the user: + ++----------+----------+----------------------------------------------------+ +| Facility | Keyword | Description | +| Code | | | ++==========+==========+====================================================+ +| | all | All facilities | ++----------+----------+----------------------------------------------------+ +| 0 | kern | Kernel messages | ++----------+----------+----------------------------------------------------+ +| 1 | user | User-level messages | ++----------+----------+----------------------------------------------------+ +| 2 | mail | Mail system | ++----------+----------+----------------------------------------------------+ +| 3 | daemon | System daemons | ++----------+----------+----------------------------------------------------+ +| 4 | auth | Security/authentication messages | ++----------+----------+----------------------------------------------------+ +| 5 | syslog | Messages generated internally by syslogd | ++----------+----------+----------------------------------------------------+ +| 6 | lpr | Line printer subsystem | ++----------+----------+----------------------------------------------------+ +| 7 | news | Network news subsystem | ++----------+----------+----------------------------------------------------+ +| 8 | uucp | UUCP subsystem | ++----------+----------+----------------------------------------------------+ +| 9 | cron | Clock daemon | ++----------+----------+----------------------------------------------------+ +| 10 | security | Security/authentication messages | ++----------+----------+----------------------------------------------------+ +| 11 | ftp | FTP daemon | ++----------+----------+----------------------------------------------------+ +| 12 | ntp | NTP subsystem | ++----------+----------+----------------------------------------------------+ +| 13 | logaudit | Log audit | ++----------+----------+----------------------------------------------------+ +| 14 | logalert | Log alert | ++----------+----------+----------------------------------------------------+ +| 15 | clock | clock daemon (note 2) | ++----------+----------+----------------------------------------------------+ +| 16 | local0 | local use 0 (local0) | ++----------+----------+----------------------------------------------------+ +| 17 | local1 | local use 1 (local1) | ++----------+----------+----------------------------------------------------+ +| 18 | local2 | local use 2 (local2) | ++----------+----------+----------------------------------------------------+ +| 19 | local3 | local use 3 (local3) | ++----------+----------+----------------------------------------------------+ +| 20 | local4 | local use 4 (local4) | ++----------+----------+----------------------------------------------------+ +| 21 | local5 | local use 5 (local5) | ++----------+----------+----------------------------------------------------+ +| 22 | local6 | use 6 (local6) | ++----------+----------+----------------------------------------------------+ +| 23 | local7 | local use 7 (local7) | ++----------+----------+----------------------------------------------------+ + +.. _syslog_severity_level: + +Severity Level +============== + ++-------+---------------+---------+-------------------------------------------+ +| Value | Severity | Keyword | Description | ++=======+===============+=========+===========================================+ +| | | all | Log everything | ++-------+---------------+---------+-------------------------------------------+ +| 0 | Emergency | emerg | System is unusable - a panic condition | ++-------+---------------+---------+-------------------------------------------+ +| 1 | Alert | alert | Action must be taken immediately - A | +| | | | condition that should be corrected | +| | | | immediately, such as a corrupted system | +| | | | database. | ++-------+---------------+---------+-------------------------------------------+ +| 2 | Critical | crit | Critical conditions - e.g. hard drive | +| | | | errors. | ++-------+---------------+---------+-------------------------------------------+ +| 3 | Error | err | Error conditions | ++-------+---------------+---------+-------------------------------------------+ +| 4 | Warning | warning | Warning conditions | ++-------+---------------+---------+-------------------------------------------+ +| 5 | Notice | notice | Normal but significant conditions - | +| | | | conditions that are not error conditions, | +| | | | but that may require special handling. | ++-------+---------------+---------+-------------------------------------------+ +| 6 | Informational | info | Informational messages | ++-------+---------------+---------+-------------------------------------------+ +| 7 | Debug | debug | Debug-level messages - Messages that | +| | | | contain information normally of use only | +| | | | when debugging a program. | ++-------+---------------+---------+-------------------------------------------+ + + +Display Logs +============ + +.. opcmd:: show log [all | authorization | cluster | conntrack-sync | ...] + +Display log files of given category on the console. Use tab completion to get +a list of available categories. Thos categories could be: all, authorization, +cluster, conntrack-sync, dhcp, directory, dns, file, firewall, https, image +lldp, nat, openvpn, snmp, tail, vpn, vrrp + +If no option is specified, this defaults to `all`. + +.. opcmd:: show log image <name> [all | authorization | directory | file <file name> | tail <lines>] + +Log messages from a specified image can be displayed on the console. Details of +allowed parameters: + +.. list-table:: + :widths: 25 75 + :header-rows: 0 + + * - all + - Display contents of all master log files of the specified image + * - authorization + - Display all authorization attempts of the specified image + * - directory + - Display list of all user-defined log files of the specified image + * - file <file name> + - Display contents of a specified user-defined log file of the specified image + * - tail + - Display last lines of the system log of the specified image + * - <lines> + - Number of lines to be displayed, default 10 + +When no options/parameters are used, the contents of the main syslog file are +displayed. diff --git a/docs/configuration/system/task-scheduler.rst b/docs/configuration/system/task-scheduler.rst new file mode 100644 index 00000000..7fe49988 --- /dev/null +++ b/docs/configuration/system/task-scheduler.rst @@ -0,0 +1,60 @@ +.. _task-scheduler: + + +Task scheduler +-------------- + +| Task scheduler — allows scheduled task execution. Note that scripts excecuted this way are executed as root user - this may be dangerous. +| Together with :ref:`commandscripting` this can be used for automating configuration. + +.. code-block:: none + + system + task-scheduler + task <name> + cron-spec <UNIX cron time spec> + executable + arguments <arguments string> + path <path to executable> + interval + <int32>[mhd] + +Interval +******** + +You are able to set the time as an time interval. + +.. code-block:: none + + set system task-scheduler task <name> interval <value><suffix> + +Sets the task to execute every N minutes, hours, or days. Suffixes: + + * m — minutes + * h — hours + * d — days + +If suffix is omitted, minutes are implied. + +Or set the execution time in common cron time. + +.. code-block:: none + + set system task-scheduler task TEST crontab-spec "* * * 1 *" + +Example +******* + +.. code-block:: none + + system + task-scheduler + task mytask + interval 2h + executable + path /config/scripts/mytask + arguments "arg1 arg2 arg3" + task anothertask + cron-spec "* * * 1 *" + executable + path /config/scripts/anothertask
\ No newline at end of file diff --git a/docs/configuration/system/time-zone.rst b/docs/configuration/system/time-zone.rst new file mode 100644 index 00000000..9e1690e8 --- /dev/null +++ b/docs/configuration/system/time-zone.rst @@ -0,0 +1,11 @@ +.. _timezone: + +Time Zone +========= + +To set the system time zone type: + +.. code-block:: none + + [edit] + vyos@vyos# set system time-zone [time-zone]
\ No newline at end of file diff --git a/docs/configuration/trafficpolicy/index.rst b/docs/configuration/trafficpolicy/index.rst new file mode 100644 index 00000000..6beb660e --- /dev/null +++ b/docs/configuration/trafficpolicy/index.rst @@ -0,0 +1,1197 @@ +.. _qos: + +############## +Traffic Policy +############## + +The generic name of Quality of Service or Traffic Control involves +things like shaping traffic, scheduling or dropping packets, which +are the kind of things you may want to play with when you have, for +instance, a bandwidth bottleneck in a link and you want to somehow +prioritize some type of traffic over another. + +tc_ is a powerful tool for Traffic Control found at the Linux kernel. +However, its configuration is often considered a cumbersome task. +Fortunately, VyOS eases the job through its CLI, while using ``tc`` as +backend. + + +How to make it work +=================== + +In order to have VyOS Traffic Control working you need to follow 2 +steps: + + 1. **Create a traffic policy**. + + 2. **Apply the traffic policy to an interface ingress or egress**. + + +But before learning to configure your policy, we will warn you +about the different units you can use and also show you what *classes* +are and how they work, as some policies may require you to configure +them. + + +Units +===== + +When configuring your traffic policy, you will have to set data rate +values, watch out the units you are managing, it is easy to get confused +with the different prefixes and suffixes you can use. VyOS will always +show you the different units you can use. + +Prefixes +-------- + +They can be **decimal** prefixes. + + .. code-block:: none + + kbit (10^3) kilobit per second + mbit (10^6) megabit per second + gbit (10^9) gigabit per second + tbit (10^12) terabit per second + + kbps (8*10^3) kilobyte per second + mbps (8*10^6) megabyte per second + gbps (8*10^9) gigabyte per second + tbps (8*10^12) terabyte per second + +Or **binary** prefixes. + + .. code-block:: none + + kibit (2^10 = 1024) kibibit per second + mibit (2^20 = 1024^2) mebibit per second + gibit (2^30 = 1024^3) gibibit per second + tbit (2^40 = 1024^4) tebibit per second + + kibps (1024*8) kibibyte (KiB) per second + mibps (1024^2*8) mebibyte (MiB) per second + gibps (1024^3*8) gibibyte (GiB) per second + tibps (1024^4*8) tebibyte (TiB) per second + + +Suffixes +-------- + +A *bit* is written as **bit**, + + .. code-block:: none + + kbit (kilobits per second) + mbit (megabits per second) + gbit (gigabits per second) + tbit (terabits per second) + +while a *byte* is written as a single **b**. + + .. code-block:: none + + kbps (kilobytes per second) + mbps (megabytes per second) + gbps (gigabytes per second) + + + + +.. _classes: + +Classes +======= + +In the :ref:`creating_a_traffic_policy` section you will see that +some of the policies use *classes*. Those policies let you distribute +traffic into different classes according to different parameters you can +choose. So, a class is just a specific type of traffic you select. + +The ultimate goal of classifying traffic is to give each class a +different treatment. + + +Matching traffic +---------------- + +In order to define which traffic goes into which class, you define +filters (that is, the matching criteria). Packets go through these matching rules +(as in the rules of a firewall) and, if a packet matches the filter, it +is assigned to that class. + +In VyOS, a class is identified by a number you can choose when +configuring it. + + +.. note:: The meaning of the Class ID is not the same for every type of + policy. Normally policies just need a meaningless number to identify + a class (Class ID), but that does not apply to every policy. + The the number of a class in a Priority Queue it does not only + identify it, it also defines its priority. + + +.. code-block:: none + + set traffic-policy <policy> <policy-name> class <class-ID> match <class-matching-rule-name> + + +In the command above, we set the type of policy we are going to +work with and the name we choose for it; a class (so that we can +differentiate some traffic) and an identifiable number for that class; +then we configure a matching rule (or filter) and a name for it. + +A class can have multiple match filters: + +.. code-block:: none + + set traffic-policy shaper MY-SHAPER class 30 match HTTP + set traffic-policy shaper MY-SHAPER class 30 match HTTPs + +A match filter can contain multiple criteria and will match traffic if +all those criteria are true. + +For example: + +.. code-block:: none + + set traffic-policy shaper MY-SHAPER class 30 match HTTP ip protocol tcp + set traffic-policy shaper MY-SHAPER class 30 match HTTP ip source port 80 + +This will match TCP traffic with source port 80. + +There are many parameters you will be able to use in order to match the +traffic you want for a class: + + - **Ethernet (protocol, destination address or source address)** + - **Interface name** + - **IPv4 (DSCP value, maximum packet length, protocol, source address,** + **destination address, source port, destination port or TCP flags)** + - **IPv6 (DSCP value, maximum payload length, protocol, source address,** + **destination address, source port, destination port or TCP flags)** + - **Firewall mark** + - **VLAN ID** + +When configuring your filter, you can use the ``Tab`` key to see the many +different parameters you can configure. + + +.. code-block:: none + + vyos@vyos# set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER + Possible completions: + description Description for this match + > ether Ethernet header match + interface Interface name for this match + > ip Match IP protocol header + > ipv6 Match IPV6 header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match + + + +As shown in the example above, one of the possibilities to match packets +is based on marks done by the firewall, `that can give you a great deal of flexibility`_. + +You can also write a description for a filter: + +.. code-block:: none + + set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER description "My filter description" + + + +.. note:: An IPv4 TCP filter will only match packets with an IPv4 header length of + 20 bytes (which is the majority of IPv4 packets anyway). + + +.. note:: IPv6 TCP filters will only match IPv6 packets with no header extension, see + https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers + + +Default +------- + +Often you will also have to configure your *default* traffic in the same +way you do with a class. *Default* can be considered a class as it +behaves like that. It contains any traffic that did not match any +of the defined classes, so it is like an open class, a class without +matching filters. + + +Class treatment +--------------- + +Once a class has a filter configured, you will also have to define what +you want to do with the traffic of that class, what specific +Traffic-Control treatment you want to give it. You will have different +possibilities depending on the Traffic Policy you are configuring. + +.. code-block:: none + + vyos@vyos# set traffic-policy shaper MY-SHAPER class 30 + Possible completions: + bandwidth Bandwidth used for this class + burst Burst size for this class (default: 15kb) + ceiling Bandwidth limit for this class + codel-quantum + fq-codel - Number of bytes used as 'deficit' (default 1514) + description Description for this traffic class + flows fq-codel - Number of flows (default 1024) + interval fq-codel - Interval (milliseconds) used to measure the delay (default 100) + +> match Class matching rule name + priority Priority for usage of excess bandwidth + queue-limit Maximum queue size (packets) + queue-type Queue type for this class + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target fq-codel - Acceptable minimum queue delay (milliseconds) + + +For instance, with :code:`set traffic-policy shaper MY-SHAPER class 30 set-dscp EF` +you would be modifying the DSCP field value of packets in that class to +Expedite Forwarding. + + + DSCP values as per :rfc:`2474` and :rfc:`4595`: + + +---------+------------+--------+------------------------------+ + | 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 | + +---------+------------+--------+------------------------------+ + + + + +.. _embed: + +Embedding one policy into another one +------------------------------------- + +Often we need to embed one policy into another one. It is possible to do +so on classful policies, by attaching a new policy into a class. For +instance, you might want to apply different policies to the different +classes of a Round-Robin policy you have configured. + +A common example is the case of some policies which, in order to be +effective, they need to be applied to an interface that is directly +connected where the bottleneck is. If your router is not +directly connected to the bottleneck, but some hop before it, you can +emulate the bottleneck by embedding your non-shaping policy into a +classful shaping one so that it takes effect. + +You can configure a policy into a class through the ``queue-type`` +setting. + +.. code-block:: none + + set traffic-policy shaper FQ-SHAPER bandwidth 4gbit + set traffic-policy shaper FQ-SHAPER default bandwidth 100% + set traffic-policy shaper FQ-SHAPER default queue-type fq-codel + +As shown in the last command of the example above, the `queue-type` +setting allows these combinations. You will be able to use it +in many policies. + +.. note:: Some policies already include other embedded policies inside. + That is the case of Shaper_: each of its classes use fair-queue + unless you change it. + +.. _creating_a_traffic_policy: + + +Creating a traffic policy +========================= + +VyOS lets you control traffic in many different ways, here we will cover +every possibility. You can configure as many policies as you want, but +you will only be able to apply one policy per interface and direction +(inbound or outbound). + +Some policies can be combined, you will be able to embed_ a different +policy that will be applied to a class of the main policy. + +.. hint:: **If you are looking for a policy for your outbound traffic** + but you don't know which one you need and you don't want to go + through every possible policy shown here, **our bet is that highly + likely you are looking for a** Shaper_ **policy and you want to** + :ref:`set its queues <embed>` **as FQ-CoDel**. + +Drop Tail +--------- + +| **Queueing discipline:** PFIFO (Packet First In First Out). +| **Applies to:** Outbound traffic. + +This the simplest queue possible you can apply to your traffic. Traffic +must go through a finite queue before it is actually sent. You must +define how many packets that queue can contain. + +When a packet is to be sent, it will have to go through that queue, so +the packet will be placed at the tail of it. When the packet completely +goes through it, it will be dequeued emptying its place in the queue and +being eventually handed to the NIC to be actually sent out. + +Despite the Drop-Tail policy does not slow down packets, if many packets +are to be sent, they could get dropped when trying to get enqueued at +the tail. This can happen if the queue has still not been able to +release enough packets from its head. + +This is the policy that requieres the lowest resources for the same +amount of traffic. But **very likely you do not need it as you cannot +get much from it. Sometimes it is used just to enable logging.** + +.. cfgcmd:: set traffic-policy drop-tail <policy-name> queue-limit <number-of-packets> + + Use this command to configure a drop-tail policy (PFIFO). Choose a + unique name for this policy and the size of the queue by setting the + number of packets it can contain (maximum 4294967295). + + +Fair Queue +---------- + +| **Queueing discipline:** SFQ (Stochastic Fairness Queuing). +| **Applies to:** Outbound traffic. + +Fair Queue is a work-conserving scheduler which schedules the +transmission of packets based on flows, that is, it balances traffic +distributing it through different sub-queues in order to ensure +fairness so that each flow is able to send data in turn, preventing any +single one from drowning out the rest. + + +.. cfgcmd:: set traffic-policy fair-queue <policy-name> + + Use this command to create a Fair-Queue policy and give it a name. + It is based on the Stochastic Fairness Queueing and can be applied to + outbound traffic. + +In order to separate traffic, Fair Queue uses a classifier based on +source address, destination address and source port. The algorithm +enqueues packets to hash buckets based on those tree parameters. +Each of these buckets should represent a unique flow. Because multiple +flows may get hashed to the same bucket, the hashing algorithm is +perturbed at configurable intervals so that the unfairness lasts only +for a short while. Perturbation may however cause some inadvertent +packet reordering to occur. An advisable value could be 10 seconds. + +One of the uses of Fair Queue might be the mitigation of Denial of +Service attacks. + +.. cfgcmd:: set traffic-policy fair-queue <policy-name> hash-interval <seconds>` + + Use this command to define a Fair-Queue policy, based on the + Stochastic Fairness Queueing, and set the number of seconds at which + a new queue algorithm perturbation will occur (maximum 4294967295). + +When dequeuing, each hash-bucket with data is queried in a round robin +fashion. You can configure the length of the queue. + +.. cfgcmd:: set traffic-policy fair-queue <policy-name> queue-limit <limit> + + Use this command to define a Fair-Queue policy, based on the + Stochastic Fairness Queueing, and set the number of maximum packets + allowed to wait in the queue. Any other packet will be dropped. + +.. note:: Fair Queue is a non-shaping (work-conserving) policy, so it + will only be useful if your outgoing interface is really full. If it + is not, VyOS will not own the queue and Fair Queue will have no + effect. If there is bandwidth available on the physical link, you can + embed_ Fair-Queue into a classful shaping policy to make sure it owns + the queue. + + + +.. _FQ-CoDel: + +FQ-CoDel +-------- + +| **Queueing discipline** Fair/Flow Queue CoDel. +| **Applies to:** Outbound Traffic. + +The FQ-CoDel policy distributes the traffic into 1024 FIFO queues and +tries to provide good service between all of them. It also tries to keep +the length of all the queues short. + +FQ-CoDel fights bufferbloat and reduces latency without the need of +complex configurations. It has become the new default Queueing +Discipline for the interfaces of some GNU/Linux distributions. + +It uses a stochastic model to classify incoming packets into +different flows and is used to provide a fair share of the bandwidth to +all the flows using the queue. Each flow is managed by the CoDel +queuing discipline. Reordering within a flow is avoided since Codel +internally uses a FIFO queue. + +FQ-CoDel is based on a modified Deficit Round Robin (DRR_) queue +scheduler with the CoDel Active Queue Management (AQM) algorithm +operating on each queue. + + +.. note:: FQ-Codel is a non-shaping (work-conserving) policy, so it + will only be useful if your outgoing interface is really full. If it + is not, VyOS will not own the queue and FQ-Codel will have no + effect. If there is bandwidth available on the physical link, you can + embed_ FQ-Codel into a classful shaping policy to make sure it owns + the queue. If you are not sure if you need to embed your FQ-CoDel + policy into a Shaper, do it. + + +FQ-CoDel is tuned to run ok with its default parameters at 10Gbit +speeds. It might work ok too at other speeds without configuring +anything, but here we will explain some cases when you might want to +tune its parameters. + +When running it at 1Gbit and lower, you may want to reduce the +`queue-limit` to 1000 packets or less. In rates like 10Mbit, you may +want to set it to 600 packets. + +If you are using FQ-CoDel embedded into Shaper_ and you have large rates +(100Mbit and above), you may consider increasing `quantum` to 8000 or +higher so that the scheduler saves CPU. + +On low rates (below 40Mbit) you may want to tune `quantum` down to +something like 300 bytes. + +At very low rates (below 3Mbit), besides tuning `quantum` (300 keeps +being ok) you may also want to increase `target` to something like 15ms +and increase `interval` to something around 150 ms. + + +.. cfgcmd:: set traffic-policy fq-codel <policy name> codel-quantum <bytes> + + Use this command to configure an fq-codel policy, set its name and + the maximum number of bytes (default: 1514) to be dequeued from a + queue at once. + +.. cfgcmd:: set traffic-policy fq-codel <policy name> flows <number-of-flows> + + Use this command to configure an fq-codel policy, set its name and + the number of sub-queues (default: 1024) into which packets are + classified. + +.. cfgcmd:: set traffic-policy fq-codel <policy name> interval <miliseconds> + + Use this command to configure an fq-codel policy, set its name and + the time period used by the control loop of CoDel to detect when a + persistent queue is developing, ensuring that the measured minimum + delay does not become too stale (default: 100ms). + +.. cfgcmd:: set traffic-policy fq-codel <policy-name> queue-limit <number-of-packets>` + + Use this command to configure an fq-codel policy, set its name, and + define a hard limit on the real queue size. When this limit is + reached, new packets are dropped (default: 10240 packets). + +.. cfgcmd:: set traffic-policy fq-codel <policy-name> target <miliseconds>` + + Use this command to configure an fq-codel policy, set its name, and + define the acceptable minimum standing/persistent queue delay. This + minimum delay is identified by tracking the local minimum queue delay + that packets experience (default: 5ms). + + +Example +^^^^^^^ + +A simple example of an FQ-CoDel policy working inside a Shaper one. + + +.. code-block:: none + + set traffic-policy shaper FQ-CODEL-SHAPER bandwidth 2gbit + set traffic-policy shaper FQ-CODEL-SHAPER default bandwidth 100% + set traffic-policy shaper FQ-CODEL-SHAPER default queue-type fq-codel + + + +Limiter +------- + +| **Queueing discipline:** Ingress policer. +| **Applies to:** Inbound traffic. + +Limiter is one of those policies that uses classes_ (Ingress qdisc is +actually a classless policy but filters do work in it). + +The limiter performs basic ingress policing of traffic flows. Multiple +classes of traffic can be defined and traffic limits can be applied to +each class. Although the policer uses a token bucket mechanism +internally, it does not have the capability to delay a packet as a +shaping mechanism does. Traffic exceeding the defined bandwidth limits +is directly dropped. A maximum allowed burst can be configured too. + +You can configure classes (up to 4090) with different settings and a +default policy which will be applied to any traffic not matching any of +the configured classes. + + +.. note:: In the case you want to apply some kind of **shaping** to your + **inbound** traffic, check the ingress-shaping_ section. + + +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> match <match-name> description <description> + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090), a class matching rule name and its + description. + + +Once the matching rules are set for a class, you can start configuring +how you want matching traffic to behave. + + +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class-ID> bandwidth <rate> + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090) and the maximum allowed bandwidth for + this class. + + +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class-ID> burst <burst-size> + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090) and the burst size in bytes for this + class (default: 15). + + +.. cfgcmd:: set traffic-policy limiter <policy-name> default bandwidth <rate> + + Use this command to configure an Ingress Policer, defining its name + and the maximum allowed bandwidth for its default policy. + + +.. cfgcmd:: set traffic-policy limiter <policy-name> default burst <burst-size> + + Use this command to configure an Ingress Policer, defining its name + and the burst size in bytes (default: 15) for its default policy. + + +.. cfgcmd:: set traffic-policy limiter <policy-name> class <class ID> priority <value> + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090), and the priority (0-20, default 20) in + which the rule is evaluated (the lower the number, the higher the + priority). + + + +Network Emulator +---------------- + +| **Queueing discipline:** netem (Network Emulator) + TBF (Token Bucket Filter). +| **Applies to:** Outbound traffic. + +VyOS Network Emulator policy emulates the conditions you can suffer in a +real network. You will be able to configure things like rate, burst, +delay, packet loss, packet corruption or packet reordering. + +This could be helpful if you want to test how an application behaves +under certain network conditions. + + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> bandwidth <rate> + + Use this command to configure the maximum rate at which traffic will + be shaped in a Network Emulator policy. Define the name of the policy + and the rate. + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> burst <burst-size> + + Use this command to configure the burst size of the traffic in a + Network Emulator policy. Define the name of the Network Emulator + policy and its traffic burst size (it will be configured through the + Token Bucket Filter qdisc). Default:15kb. It will only take effect if + you have configured its bandwidth too. + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> network-delay <delay> + + Use this command to configure a Network Emulator policy defining its + name and the fixed amount of time you want to add to all packet going + out of the interface. The latency will be added through the + Token Bucket Filter qdisc. It will only take effect if you have + configured its bandwidth too. You can use secs, ms and us. Default: + 50ms. + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> packet-corruption <percent> + + Use this command to emulate noise in a Network Emulator policy. Set + the policy name and the percentage of corrupted packets you want. A + random error will be introduced in a random position for the chosen + percent of packets. + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> packet-loss <percent>` + + Use this command to emulate packet-loss conditions in a Network + Emulator policy. Set the policy name and the percentage of loss + packets your traffic will suffer. + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> packet-reordering <percent>` + + Use this command to emulate packet-reordering conditions in a Network + Emulator policy. Set the policy name and the percentage of reordered + packets your traffic will suffer. + +.. cfgcmd:: set traffic-policy network-emulator <policy-name> queue-limit <limit> + + Use this command to define the length of the queue of your Network + Emulator policy. Set the policy name and the maximum number of + packets (1-4294967295) the queue may hold queued at a time. + + + +Priority Queue +-------------- + +| **Queueing discipline:** PRIO. +| **Applies to:** Outbound traffic. + + +The Priority Queue is a classful scheduling policy. It does not delay +packets (Priority Queue is not a shaping policy), it simply dequeues +packets according to their priority. + +.. note:: Priority Queue, as other non-shaping policies, is only useful + if your outgoing interface is really full. If it is not, VyOS will + not own the queue and Priority Queue will have no effect. If there is + bandwidth available on the physical link, you can embed_ Priority + Queue into a classful shaping policy to make sure it owns the queue. + In that case packets can be prioritized based on DSCP. + +Up to seven queues -defined as classes_ with different priorities- can +be configured. Packets are placed into queues based on associated match +criteria. Packets are transmitted from the queues in priority order. If +classes with a higher priority are being filled with packets +continuously, packets from lower priority classes will only be +transmitted after traffic volume from higher priority classes decreases. + + +.. note:: In Priority Queue we do not define clases with a meaningless + class ID number but with a class priority number (1-7). The lower the + number, the higher the priority. + + +As with other policies, you can define different type of matching rules +for your classes: + +.. code-block:: none + + vyos@vyos# set traffic-policy priority-queue MY-PRIO class 3 match MY-MATCH-RULE + Possible completions: + description Description for this match + > ether Ethernet header match + interface Interface name for this match + > ip Match IP protocol header + > ipv6 Match IPV6 header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match + + +As with other policies, you can embed_ other policies into the classes +(and default) of your Priority Queue policy through the ``queue-type`` +setting: + +.. code-block:: none + + vyos@vyos# set traffic-policy priority-queue MY-PRIO class 3 queue-type + Possible completions: + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing based on DSCP + random-detect + Random Early Detection (RED) + + +.. cfgcmd:: set traffic-policy priority-queue <policy-name> class <class-ID> queue-limit <limit>` + + Use this command to configure a Priority Queue policy, set its name, + set a class with a priority from 1 to 7 and define a hard limit on + the real queue size. When this limit is reached, new packets are + dropped. + + + +.. _Random-Detect: + +Random-Detect +------------- + + +| **Queueing discipline:** Generalized Random Early Drop. +| **Applies to:** Outbound traffic. + +A simple Random Early Detection (RED) policy would start randomly +dropping packets from a queue before it reaches its queue limit thus +avoiding congestion. That is good for TCP connections as the gradual +dropping of packets acts as a signal for the sender to decrease its +transmission rate. + +In contrast to simple RED, VyOS' Random-Detect uses a Generalized Random +Early Detect policy that provides different virtual queues based on the +IP Precedence value so that some virtual queues can drop more packets +than others. + +This is achieved by using the first three bits of the ToS (Type of +Service) field to categorize data streams and, in accordance with the +defined precedence parameters, a decision is made. + +IP precedence as defined in :rfc:`791`: + + +------------+----------------------+ + | Precedence | Priority | + +============+======================+ + | 7 | Network Control | + +------------+----------------------+ + | 6 | Internetwork Control | + +------------+----------------------+ + | 5 | CRITIC/ECP | + +------------+----------------------+ + | 4 | Flash Override | + +------------+----------------------+ + | 3 | Flash | + +------------+----------------------+ + | 2 | Immediate | + +------------+----------------------+ + | 1 | Priority | + +------------+----------------------+ + | 0 | Routine | + +------------+----------------------+ + + +Random-Detect could be useful for heavy traffic. One use of this +algorithm might be to prevent a backbone overload. But only for TCP +(because dropped packets could be retransmitted), not for UDP. + + +.. cfgcmd:: set traffic-policy random-detect <policy-name> bandwidth <bandwidth> + + Use this command to configure a Random-Detect policy, set its name + and set the available bandwidth for this policy. It is used for + calculating the average queue size after some idle time. It should be + set to the bandwidth of your interface. Random Detect is not a + shaping policy, this command will not shape. + +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> average-packet <bytes> + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what the size of its average-packet should be + (in bytes, default: 1024). + +.. note:: When configuring a Random-Detect policy: **the higher the + precedence number, the higher the priority**. + +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> mark-probability <value> + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what its mark (drop) probability will be. Set the + probability by giving the N value of the fraction 1/N (default: 10). + + +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> maximum-threshold <packets> + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what its maximum threshold for random detection will + be (from 0 to 4096 packets, default: 18). At this size, the marking + (drop) probability is maximal. + +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> minimum-threshold <packets> + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what its minimum threshold for random detection will + be (from 0 to 4096 packets). If this value is exceeded, packets + start being eligible for being dropped. + + +The default values for the minimum-threshold depend on IP precedence: + + +------------+-----------------------+ + | Precedence | default min-threshold | + +============+=======================+ + | 7 | 16 | + +------------+-----------------------+ + | 6 | 15 | + +------------+-----------------------+ + | 5 | 14 | + +------------+-----------------------+ + | 4 | 13 | + +------------+-----------------------+ + | 3 | 12 | + +------------+-----------------------+ + | 2 | 11 | + +------------+-----------------------+ + | 1 | 10 | + +------------+-----------------------+ + | 0 | 9 | + +------------+-----------------------+ + + +.. cfgcmd:: set traffic-policy random-detect <policy-name> precedence <IP-precedence-value> queue-limit <packets> + + Use this command to configure a Random-Detect policy and set its + name, then name the IP Precedence for the virtual queue you are + configuring and what the maximum size of its queue will be (from 1 to + 1-4294967295 packets). Packets are dropped when the current queue + length reaches this value. + + +If the average queue size is lower than the **min-threshold**, an +arriving packet will be placed in the queue. + +In the case the average queue size is between **min-threshold** and +**max-threshold**, then an arriving packet would be either dropped or +placed in the queue, it will depend on the defined **mark-probability**. + +If the current queue size is larger than **queue-limit**, +then packets will be dropped. The average queue size depends on its +former average size and its current one. + +If **max-threshold** is set but **min-threshold is not, then +**min-threshold** is scaled to 50% of **max-threshold**. + +In principle, values must be +:code:`min-threshold` < :code:`max-threshold` < :code:`queue-limit`. + + + + +Rate Control +------------ + +| **Queueing discipline:** Tocken Bucket Filter. +| **Applies to:** Outbound traffic. + +Rate-Control is a classless policy that limits the packet flow to a set +rate. It is a pure shaper, it does not schedule traffic. Traffic is +filtered based on the expenditure of tokens. Tokens roughly correspond +to bytes. + +Short bursts can be allowed to exceed the limit. On creation, the +Rate-Control traffic is stocked with tokens which correspond to the +amount of traffic that can be burst in one go. Tokens arrive at a steady +rate, until the bucket is full. + +.. cfgcmd:: set traffic-policy rate-control <policy-name> bandwidth <rate> + + Use this command to configure a Rate-Control policy, set its name + and the rate limit you want to have. + +.. cfgcmd:: set traffic-policy rate-control <policy-name> burst <burst-size> + + Use this command to configure a Rate-Control policy, set its name + and the size of the bucket in bytes which will be available for + burst. + + +As a reference: for 10mbit/s on Intel, you might need at least 10kbyte +buffer if you want to reach your configured rate. + +A very small buffer will soon start dropping packets. + +.. cfgcmd:: set traffic-policy rate-control <policy-name> latency + + Use this command to configure a Rate-Control policy, set its name + and the maximum amount of time a packet can be queued (default: 50 + ms). + + +Rate-Control is a CPU-friendly policy. You might consider using it when +you just simply want to slow traffic down. + +.. _DRR: + +Round Robin +----------- + +| **Queueing discipline:** Deficit Round Robin. +| **Applies to:** Outbound traffic. + +The round-robin policy is a classful scheduler that divides traffic in +different classes_ you can configure (up to 4096). You can embed_ a +new policy into each of those classes (default included). + +Each class is assigned a deficit counter (the number of bytes that a +flow is allowed to transmit when it is its turn) initialized to quantum. +Quantum is a parameter you configure which acts like a credit of fix +bytes the counter receives on each round. Then the Round-Robin policy +starts moving its Round Robin pointer through the queues. If the deficit +counter is greater than the packet's size at the head of the queue, this +packet will be sent and the value of the counter will be decremented by +the packet size. Then, the size of the next packet will be compared to +the counter value again, repeating the process. Once the queue is empty +or the value of the counter is insufficient, the Round-Robin pointer +will move to the next queue. If the queue is empty, the value of the +deficit counter is reset to 0. + +At every round, the deficit counter adds the quantum so that even large +packets will have their opportunity to be dequeued. + + +.. cfgcmd:: set traffic-policy round-robin <policy name> class + <class-ID> quantum <packets> + + Use this command to configure a Round-Robin policy, set its name, set + a class ID, and the quantum for that class. The deficit counter will + add that value each round. + +.. cfgcmd:: set traffic-policy round-robin <policy name> class + <class ID> queue-limit <packets> + + Use this command to configure a Round-Robin policy, set its name, set + a class ID, and the queue size in packets. + +As with other policies, Round-Robin can embed_ another policy into a +class through the ``queue-type`` setting. + +.. code-block:: none + + vyos@vyos# set traffic-policy round-robin DRR class 10 queue-type + Possible completions: + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing based on DSCP + + + + +.. _Shaper: + +Shaper +------ + +| **Queueing discipline:** Hierarchical Token Bucket. +| **Applies to:** Outbound traffic. + + +The Shaper policy does not guarantee a low delay, but it does guarantee +bandwidth to different traffic classes and also lets you decide how to +allocate more traffic once the guarantees are met. + +Each class can have a guaranteed part of the total bandwidth defined for +the whole policy, so all those shares together should not be higher +than the policy's whole bandwidth. + +If guaranteed traffic for a class is met and there is room for more +traffic, the ceiling parameter can be used to set how much more +bandwidth could be used. If guaranteed traffic is met and there are +several classes willing to use their ceilings, the priority parameter +will establish the order in which that additional traffic will be +allocated. Priority can be any number from 0 to 7. The lower the number, +the higher the priority. + + +.. cfgcmd:: set traffic-policy shaper <policy-name> bandwidth <rate> + + Use this command to configure a Shaper policy, set its name + and the maximum bandwidth for all combined traffic. + + +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> bandwidth <rate> + + Use this command to configure a Shaper policy, set its name, define + a class and set the guaranteed traffic you want to allocate to that + class. + +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> burst <bytes> + + Use this command to configure a Shaper policy, set its name, define + a class and set the size of the `tocken bucket`_ in bytes, which will + be available to be sent at ceiling speed (default: 15Kb). + +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> ceiling <bandwidth> + + Use this command to configure a Shaper policy, set its name, define + a class and set the maximum speed possible for this class. The + default ceiling value is the bandwidth value. + +.. cfgcmd:: set traffic-policy shaper <policy-name> class <class-ID> priority <0-7> + + Use this command to configure a Shaper policy, set its name, define + a class and set the priority for usage of available bandwidth once + guarantees have been met. The lower the priority number, the higher + the priority. The default priority value is 0, the highest priority. + + +As with other policies, Shaper can embed_ other policies into its +classes through the ``queue-type`` setting and then configure their +parameters. + + +.. code-block:: none + + vyos@vyos# set traffic-policy shaper HTB class 10 queue-type + Possible completions: + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing based on DSCP + random-detect + Random Early Detection (RED) + + +.. code-block:: none + + vyos@vyos# set traffic-policy shaper HTB class 10 + Possible completions: + bandwidth Bandwidth used for this class + burst Burst size for this class (default: 15kb) + ceiling Bandwidth limit for this class + codel-quantum + fq-codel - Number of bytes used as 'deficit' (default 1514) + description Description for this traffic class + flows fq-codel - Number of flows (default 1024) + interval fq-codel - Interval (milliseconds) used to measure the delay (default 100) + +> match Class matching rule name + priority Priority for usage of excess bandwidth + queue-limit Maximum queue size (packets) + queue-type Queue type for this class + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target fq-codel - Acceptable minimum queue delay (milliseconds) + + + +.. note:: If you configure a class for **VoIP traffic**, don't give it any + *ceiling*, otherwise new VoIP calls could start when the link is + available and get suddenly dropped when other classes start using + their assigned *bandwidth* share. + + +Example +^^^^^^^ + +A simple example of Shaper using priorities. + + +.. code-block:: none + + set traffic-policy shaper MY-HTB bandwidth '50mbit' + set traffic-policy shaper MY-HTB class 10 bandwidth '20%' + set traffic-policy shaper MY-HTB class 10 match DSCP ip dscp 'EF' + set traffic-policy shaper MY-HTB class 10 queue-type 'fq-codel' + set traffic-policy shaper MY-HTB class 20 bandwidth '10%' + set traffic-policy shaper MY-HTB class 20 ceiling '50%' + set traffic-policy shaper MY-HTB class 20 match PORT666 ip destination port '666' + set traffic-policy shaper MY-HTB class 20 priority '3' + set traffic-policy shaper MY-HTB class 20 queue-type 'fair-queue' + set traffic-policy shaper MY-HTB class 30 bandwidth '10%' + set traffic-policy shaper MY-HTB class 30 ceiling '50%' + set traffic-policy shaper MY-HTB class 30 match ADDRESS30 ip source address '192.168.30.0/24' + set traffic-policy shaper MY-HTB class 30 priority '5' + set traffic-policy shaper MY-HTB class 30 queue-type 'fair-queue' + set traffic-policy shaper MY-HTB default bandwidth '10%' + set traffic-policy shaper MY-HTB default ceiling '100%' + set traffic-policy shaper MY-HTB default priority '7' + set traffic-policy shaper MY-HTB default queue-type 'fair-queue' + + +Applying a traffic policy +========================= + +Once a traffic-policy is created, you can apply it to an interface: + +.. code-block:: none + + set interfaces etherhet eth0 traffic-policy out WAN-OUT + +You can only apply one policy per interface and direction, but you could +reuse a policy on different interfaces and directions: + +.. code-block:: none + + set interfaces ethernet eth0 traffic-policy in WAN-IN + set interfaces etherhet eth0 traffic-policy out WAN-OUT + set interfaces etherhet eth1 traffic-policy in LAN-IN + set interfaces etherhet eth1 traffic-policy out LAN-OUT + set interfaces ethernet eth2 traffic-policy in LAN-IN + set interfaces ethernet eth2 traffic-policy out LAN-OUT + set interfaces etherhet eth3 traffic-policy in TWO-WAY-POLICY + set interfaces etherhet eth3 traffic-policy out TWO-WAY-POLICY + set interfaces etherhet eth4 traffic-policy in TWO-WAY-POLICY + set interfaces etherhet eth4 traffic-policy out TWO-WAY-POLICY + +Getting queueing information +---------------------------- + +.. opcmd:: show queueing <interface-type> <interface-name> + + Use this command to see the queueing information for an interface. + You will be able to see a packet counter (Sent, Dropped, Overlimit + and Backlog) per policy and class configured. + + + +.. _ingress-shaping: + +The case of ingress shaping +=========================== + +| **Applies to:** Inbound traffic. + +For the ingress traffic of an interface, there is only one policy you +can directly apply, a **Limiter** policy. You cannot apply a shaping +policy directly to the ingress traffic of any interface because shaping +only works for outbound traffic. + +This workaround lets you apply a shaping policy to the ingress traffic +by first redirecting it to an in-between virtual interface +(`Intermediate Functional Block`_). There, in that virtual interface, +you will be able to apply any of the policies that work for outbound +traffic, for instance, a shaping one. + +That is how it is possible to do the so-called "ingress shaping". + + +.. code-block:: none + + set traffic-policy shaper MY-INGRESS-SHAPING bandwidth 1000kbit + set traffic-policy shaper MY-INGRESS-SHAPING default bandwidth 1000kbit + set traffic-policy shaper MY-INGRESS-SHAPING default queue-type fair-queue + + set interfaces input ifb0 traffic-policy out MY-INGRESS-SHAPING + set interfaces ethernet eth0 redirect ifb0 + +.. warning:: + + Do not configure IFB as the first step. First create everything else + of your traffic-policy, and then you can configure IFB. + Otherwise you might get the ``RTNETLINK answer: File exists`` error, + which can be solved with ``sudo ip link delete ifb0``. + + +.. _that can give you a great deal of flexibility: https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches +.. _tc: https://en.wikipedia.org/wiki/Tc_(Linux) +.. _tocken bucket: https://en.wikipedia.org/wiki/Token_bucket +.. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve +.. _Intermediate Functional Block: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb diff --git a/docs/configuration/vpn/dmvpn.rst b/docs/configuration/vpn/dmvpn.rst new file mode 100644 index 00000000..e6487292 --- /dev/null +++ b/docs/configuration/vpn/dmvpn.rst @@ -0,0 +1,420 @@ +.. _vpn-dmvpn: + +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". If you do set the `remote-ip` directive at any point, the interface will need to be `delete`'d from the config and recreated without the `remote-ip` config ever being set. + +.. figure:: /_static/images/vpn_dmvpn_topology01.png + :scale: 40 % + :alt: Baseline DMVPN topology + + Baseline DMVPN topology + +HUB Configuration +^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + interfaces + tunnel <tunN> { + address <ipv4> + encapsulation gre + local-ip <public ip> + multicast enable + description <txt> + parameters { + ip { + <usual IP options> + } + } + } + } + protocols { + nhrp { + tunnel <tunN> { + cisco-authentication <key phrase> + holding-time <seconds> + multicast dynamic + redirect + } + } + } + vpn { + ipsec { + esp-group <text> { + lifetime <30-86400> + mode tunnel + pfs enable + proposal <1-65535> { + encryption aes256 + hash sha1 + } + proposal <1-65535> { + encryption 3des + hash md5 + } + } + ike-group <text> { + key-exchange ikev1 + lifetime <30-86400> + proposal <1-65535> { + encryption aes256 + hash sha1 + } + proposal <1-65535> { + encryption aes128 + hash sha1 + } + } + ipsec-interfaces { + interface <ethN> + } + profile <text> { + authentication { + mode pre-shared-secret + pre-shared-secret <key phrase> + } + bind { + tunnel <tunN> + } + esp-group <text> + ike-group <text> + } + } + } + +HUB Example Configuration: + +.. code-block:: none + + set interfaces ethernet eth0 address '198.51.100.41/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 198.51.100.41 + 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 + +HUB on AWS Configuration Specifics +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Setting this up on AWS will require a "Custom Protocol Rule" for protocol number "47" (GRE) Allow Rule in TWO places. Firstly on the VPC Network ACL, and secondly on the security group network ACL attached to the EC2 instance. This has been tested as working for the offical AMI image on the AWS Marketplace. (Locate the correct VPC and security group by navigating through the details pane below your EC2 instance in the AWS console) + +SPOKE Configuration +^^^^^^^^^^^^^^^^^^^ + +SPOKE1 Configuration: + +.. code-block:: none + + interfaces + tunnel <tunN> { + address <ipv4> + encapsulation gre + local-ip <public ip> + multicast enable + description <txt> + parameters { + ip { + <usual IP options> + } + } + } + } + protocols { + nhrp { + tunnel <tunN> { + cisco-authentication <key phrase> + map <ipv4/net> { + nbma-address <ipv4> + register + } + holding-time <seconds> + multicast nhs + redirect + shortcut + } + } + } + vpn { + ipsec { + esp-group <text> { + lifetime <30-86400> + mode tunnel + pfs enable + proposal <1-65535> { + encryption aes256 + hash sha1 + } + proposal <1-65535> { + encryption 3des + hash md5 + } + } + ike-group <text> { + key-exchange ikev1 + lifetime <30-86400> + proposal <1-65535> { + encryption aes256 + hash sha1 + } + proposal <1-65535> { + encryption aes128 + hash sha1 + } + } + ipsec-interfaces { + interface <ethN> + } + profile <text> { + authentication { + mode pre-shared-secret + pre-shared-secret <key phrase> + } + bind { + tunnel <tunN> + } + esp-group <text> + ike-group <text> + } + } + } + +SPOKE1 Example Configuration + +.. code-block:: none + + 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 198.51.100.41 + 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:: none + + interfaces + tunnel <tunN> { + address <ipv4> + encapsulation gre + local-ip <public ip> + multicast enable + description <txt> + parameters { + ip { + <usual IP options> + } + } + } + } + protocols { + nhrp { + tunnel <tunN> { + cisco-authentication <key phrase> + map <ipv4/net> { + nbma-address <ipv4> + register + } + holding-time <seconds> + multicast nhs + redirect + shortcut + } + } + } + vpn { + ipsec { + esp-group <text> { + lifetime <30-86400> + mode tunnel + pfs enable + proposal <1-65535> { + encryption aes256 + hash sha1 + } + proposal <1-65535> { + encryption 3des + hash md5 + } + } + ike-group <text> { + key-exchange ikev1 + lifetime <30-86400> + proposal <1-65535> { + encryption aes256 + hash sha1 + } + proposal <1-65535> { + encryption aes128 + hash sha1 + } + } + ipsec-interfaces { + interface <ethN> + } + profile <text> { + authentication { + mode pre-shared-secret + pre-shared-secret <key phrase> + } + bind { + tunnel <tunN> + } + esp-group <text> + ike-group <text> + } + } + } + +SPOKE2 Example Configuration + +.. code-block:: none + + 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 198.51.100.41 + 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 + + +.. _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/configuration/vpn/index.rst b/docs/configuration/vpn/index.rst new file mode 100644 index 00000000..522842d1 --- /dev/null +++ b/docs/configuration/vpn/index.rst @@ -0,0 +1,17 @@ +.. _vpn: + +.. include:: references.rst + +VPN +=== + +This chapter describes the available VPN services provided by VyOS. + +.. toctree:: + :hidden: + + l2tp + site2site_ipsec + ipsec + dmvpn + pptp diff --git a/docs/configuration/vpn/ipsec.rst b/docs/configuration/vpn/ipsec.rst new file mode 100644 index 00000000..38849f67 --- /dev/null +++ b/docs/configuration/vpn/ipsec.rst @@ -0,0 +1,190 @@ +.. _gre-ipsec: + +GRE/IPsec +--------- + +Generic Routing Encapsulation (GRE), GRE/IPsec (or IPIP/IPsec, SIT/IPsec, or any +other stateless tunnel protocol over IPsec) is the usual way to protect the +traffic inside a tunnel. + +An advantage of this scheme is that you get a real interface with its own +address, which makes it easier to setup static routes or use dynamic routing +protocols without having to modify IPsec policies. The other advantage is that +it greatly simplifies router to router communication, which can be tricky with +plain IPsec because the external outgoing address of the router usually doesn't +match the IPsec policy of typical site-to-site setup and you need to add special +configuration for it, or adjust the source address for outgoing traffic of your +applications. GRE/IPsec has no such problem and is completely transparent for +the applications. + +GRE/IPIP/SIT and IPsec are widely accepted standards, which make this scheme +easy to implement between VyOS and virtually any other router. + +For simplicity we'll assume that the protocol is GRE, it's not hard to guess +what needs to be changed to make it work with a different protocol. We assume +that IPsec will use pre-shared secret authentication and will use AES128/SHA1 +for the cipher and hash. Adjust this as necessary. + +.. NOTE:: VMWare users should ensure that VMXNET3 adapters used, e1000 adapters + have known issue with GRE processing + +IPsec policy matching GRE +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The first and arguably cleaner option is to make your IPsec policy match GRE +packets between external addresses of your routers. This is the best option if +both routers have static external addresses. + +Suppose the LEFT router has external address 192.0.2.10 on its eth0 interface, +and the RIGHT router is 203.0.113.45 + +On the LEFT: + +.. code-block:: none + + # GRE tunnel + set interfaces tunnel tun0 encapsulation gre + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 203.0.113.45 + set interfaces tunnel tun0 address 10.10.10.1/30 + + ## IPsec + set vpn ipsec ipsec-interfaces interface eth0 + + # IKE group + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '2' + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes128' + set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha1' + + # ESP group + set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes128' + set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha1' + + # IPsec tunnel + set vpn ipsec site-to-site peer 203.0.113.45 authentication mode pre-shared-secret + set vpn ipsec site-to-site peer 203.0.113.45 authentication pre-shared-secret MYSECRETKEY + + set vpn ipsec site-to-site peer 203.0.113.45 ike-group MyIKEGroup + set vpn ipsec site-to-site peer 203.0.113.45 default-esp-group MyESPGroup + + set vpn ipsec site-to-site peer 203.0.113.45 local-address 192.0.2.10 + + # This will match all GRE traffic to the peer + set vpn ipsec site-to-site peer 203.0.113.45 tunnel 1 protocol gre + +On the RIGHT, setup by analogy and swap local and remote addresses. + + +Source tunnel from loopbacks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The scheme above doesn't work when one of the routers has a dynamic external +address though. The classic workaround for this is to setup an address on a +loopback interface and use it as a source address for the GRE tunnel, then setup +an IPsec policy to match those loopback addresses. + +We assume that the LEFT router has static 192.0.2.10 address on eth0, and the +RIGHT router has a dynamic address on eth0. + +**Setting up the GRE tunnel** + +On the LEFT: + +.. code-block:: none + + set interfaces loopback lo address 192.168.99.1/32 + + set interfaces tunnel tun0 encapsulation gre + set interfaces tunnel tun0 address 10.10.10.1/30 + set interfaces tunnel tun0 local-ip 192.168.99.1 + set interfaces tunnel tun0 remote-ip 192.168.99.2 + +On the RIGHT: + +.. code-block:: none + + set interfaces loopback lo address 192.168.99.2/32 + + set interfaces tunnel tun0 encapsulation gre + set interfaces tunnel tun0 address 10.10.10.2/30 + set interfaces tunnel tun0 local-ip 192.168.99.2 + set interfaces tunnel tun0 remote-ip 192.168.99.1 + +**Setting up IPSec** + +However, now you need to make IPsec work with dynamic address on one side. The +tricky part is that pre-shared secret authentication doesn't work with dynamic +address, so we'll have to use RSA keys. + +First, on both routers run the operational command "generate vpn rsa-key bits +2048". You may choose different length than 2048 of course. + +.. code-block:: none + + vyos@left# run generate vpn rsa-key bits 2048 + Generating rsa-key to /config/ipsec.d/rsa-keys/localhost.key + + Your new local RSA key has been generated + The public portion of the key is: + + 0sAQO2335[long string here] + +Then on the opposite router, add the RSA key to your config. + +.. code-block:: none + + set vpn rsa-keys rsa-key-name LEFT rsa-key KEYGOESHERE + +Now you are ready to setup IPsec. You'll need to use an ID instead of address +for the peer on the dynamic side. + +On the LEFT (static address): + +.. code-block:: none + + set vpn rsa-keys rsa-key-name RIGHT rsa-key <PUBLIC KEY FROM THE RIGHT> + + set vpn ipsec ipsec-interfaces interface eth0 + + set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 + set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 + set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 + + set vpn ipsec site-to-site peer @RIGHT authentication mode rsa + set vpn ipsec site-to-site peer @RIGHT authentication rsa-key-name RIGHT + set vpn ipsec site-to-site peer @RIGHT default-esp-group MyESPGroup + set vpn ipsec site-to-site peer @RIGHT ike-group MyIKEGroup + set vpn ipsec site-to-site peer @RIGHT local-address 192.0.2.10 + set vpn ipsec site-to-site peer @RIGHT connection-type respond + set vpn ipsec site-to-site peer @RIGHT tunnel 1 local prefix 192.168.99.1/32 # Additional loopback address on the local + set vpn ipsec site-to-site peer @RIGHT tunnel 1 remote prefix 192.168.99.2/32 # Additional loopback address on the remote + + +On the RIGHT (dynamic address): + +.. code-block:: none + + set vpn rsa-keys rsa-key-name LEFT rsa-key <PUBLIC KEY FROM THE LEFT> + + set vpn ipsec ipsec-interfaces interface eth0 + + set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 + set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 + + set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 + set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 + set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 + + set vpn ipsec site-to-site peer 192.0.2.10 authentication id @RIGHT + set vpn ipsec site-to-site peer 192.0.2.10 authentication mode rsa + set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa-key-name LEFT + set vpn ipsec site-to-site peer 192.0.2.10 remote-id @LEFT + set vpn ipsec site-to-site peer 192.0.2.10 connection-type initiate + set vpn ipsec site-to-site peer 192.0.2.10 default-esp-group MyESPGroup + set vpn ipsec site-to-site peer 192.0.2.10 ike-group MyIKEGroup + set vpn ipsec site-to-site peer 192.0.2.10 local-address any + set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 local prefix 192.168.99.2/32 # Additional loopback address on the local + set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote diff --git a/docs/configuration/vpn/l2tp.rst b/docs/configuration/vpn/l2tp.rst new file mode 100644 index 00000000..64223475 --- /dev/null +++ b/docs/configuration/vpn/l2tp.rst @@ -0,0 +1,131 @@ +.. _l2tp: + +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:: none + + set vpn ipsec ipsec-interfaces interface eth0 + set vpn ipsec nat-traversal enable + set vpn ipsec nat-networks allowed-network 0.0.0.0/0 + + set vpn l2tp remote-access outside-address 203.0.113.2 + set vpn l2tp remote-access client-ip-pool start 192.168.255.1 + set vpn l2tp remote-access client-ip-pool stop 192.168.255.254 + set vpn l2tp remote-access ipsec-settings authentication mode pre-shared-secret + set vpn l2tp remote-access ipsec-settings authentication pre-shared-secret <secret> + set vpn l2tp remote-access authentication mode local + set vpn l2tp remote-access authentication local-users username <username> password <password> + +In the example above an external IP of 203.0.113.2 is assumed. + +If a local firewall policy is in place on your external interface you will need +to open: + +* UDP port 500 (IKE) +* IP protocol number 50 (ESP) +* UDP port 1701 for IPsec + +In addition when NAT is detected by the VPN client ESP is encapsulated in UDP +for NAT-traversal: + +* UDP port 4500 (NAT-T) + +Example: + +.. code-block:: none + + set firewall name OUTSIDE-LOCAL rule 40 action 'accept' + 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:: none + + 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:: none + + 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:: none + + 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:: none + + set vpn l2tp remote-access authentication mode <local|radius> + +In addition one or more RADIUS_ servers can be configured to server for user +authentication. This is done using the `radius server` and `radius server key` +nodes: + +.. code-block:: none + + 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 +********************* + +If you are using e.g. OSPF as IGP always the nearest interface facing the RADIUS +server is used. With VyOS 1.2 you can bind all outgoing RADIUS requests to a +single source IP e.g. the loopback interface. + +.. code-block:: none + + set vpn l2tp remote-access authentication radius source-address 3.3.3.3 + +Above command will use `3.3.3.3` as source IPv4 address for all RADIUS queries +on this NAS. + + +.. _`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 diff --git a/docs/configuration/vpn/pptp.rst b/docs/configuration/vpn/pptp.rst new file mode 100644 index 00000000..72b3feb0 --- /dev/null +++ b/docs/configuration/vpn/pptp.rst @@ -0,0 +1,47 @@ +.. _pptp: + +PPTP-Server +----------- + +The Point-to-Point Tunneling Protocol (PPTP_) has been implemented in VyOS only for backwards compatibility. +PPTP has many well known security issues and you should use one of the many other new VPN implementations. + +As per default and if not otherwise defined, mschap-v2 is being used for authentication and mppe 128-bit (stateless) for encryption. +If no gateway-address is set within the configuration, the lowest IP out of the /24 client-ip-pool is being used. For instance, in the example below it would be 192.168.0.1. + +server example +^^^^^^^^^^^^^^ + +.. code-block:: none + + set vpn pptp remote-access authentication local-users username test password 'test' + set vpn pptp remote-access authentication mode 'local' + set vpn pptp remote-access client-ip-pool start '192.168.0.10' + set vpn pptp remote-access client-ip-pool stop '192.168.0.15' + set vpn pptp remote-access gateway-address '10.100.100.1' + set vpn pptp remote-access outside-address '10.1.1.120' + + +client example (debian 9) +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Install the client software via apt and execute pptpsetup to generate the configuration. + + +.. code-block:: none + + apt-get install pptp-linux + pptpsetup --create TESTTUNNEL --server 10.1.1.120 --username test --password test --encrypt + pon TESTTUNNEL + +The command pon TESTUNNEL establishes the PPTP tunnel to the remote system. + + +All tunnel sessions can be checked via: + +.. code-block:: none + + run sh pptp-server sessions + ifname | username | calling-sid | ip | type | comp | state | uptime + --------+----------+-------------+--------------+------+------+--------+---------- + ppp0 | test | 10.1.1.99 | 192.168.0.10 | pptp | mppe | active | 00:00:58 diff --git a/docs/configuration/vpn/references.rst b/docs/configuration/vpn/references.rst new file mode 100644 index 00000000..49b65cb0 --- /dev/null +++ b/docs/configuration/vpn/references.rst @@ -0,0 +1,10 @@ +.. _`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 +.. _PPTP: https://en.wikipedia.org/wiki/Point-to-Point_Tunneling_Protocol diff --git a/docs/configuration/vpn/site2site_ipsec.rst b/docs/configuration/vpn/site2site_ipsec.rst new file mode 100644 index 00000000..e0156a6f --- /dev/null +++ b/docs/configuration/vpn/site2site_ipsec.rst @@ -0,0 +1,299 @@ +.. _size2site_ipsec: + +Site-to-Site +============ + +Site-to-site mode provides a way to add remote peers, which could be configured to exchange encrypted information between them and VyOS itself or connected/routed networks. + +To configure site-to-site connection you need to add peers with the ``set vpn ipsec site-to-site`` command. + +You can identify a remote peer with: + +* IPv4 or IPv6 address. This mode is easiest for configuration and mostly used when a peer has a public static IP address; +* Hostname. This mode is similar to IP address, only you define DNS name instead of an IP. Could be used when a peer has a public IP address and DNS name, but an IP address could be changed from time to time; +* Remote ID of the peer. In this mode, there is no predefined remote address nor DNS name of the peer. This mode is useful when a peer doesn't have a publicly available IP address (NAT between it and VyOS), or IP address could be changed. + +Each site-to-site peer has the next options: + +* ``authentication`` - configure authentication between VyOS and a remote peer. Suboptions: + + * ``id`` - ID for the local VyOS router. If defined, during the authentication it will be send to remote peer; + + * ``mode`` - mode for authentication between VyOS and remote peer: + + * ``pre-shared-secret`` - use predefined shared secret phrase, must be the same for local and remote side; + + * ``rsa`` - use simple shared RSA key. The key must be defined in the ``set vpn rsa-keys`` section; + + * ``x509`` - use certificates infrastructure for authentication. + + * ``pre-shared-secret`` - predefined shared secret. Used if configured ``mode pre-shared-secret``; + + * ``remote-id`` - define an ID for remote peer, instead of using peer name or address. Useful in case if the remote peer is behind NAT or if ``mode x509`` is used; + + * ``rsa-key-name`` - shared RSA key for authentication. The key must be defined in the ``set vpn rsa-keys`` section; + + * ``use-x509-id`` - use local ID from x509 certificate. Cannot be used when ``id`` is defined; + + * ``x509`` - options for x509 authentication mode: + + * ``ca-cert-file`` - CA certificate file. Using for authenticating remote peer; + + * ``cert-file`` - certificate file, which will be used for authenticating local router on remote peer; + + * ``crl-file`` - file with the Certificate Revocation List. Using to check if a certificate for the remote peer is valid or revoked; + + * ``key`` - a private key, which will be used for authenticating local router on remote peer: + + * ``file`` - path to the key file; + + * ``password`` - passphrase private key, if needed. + +* ``connection-type`` - how to handle this connection process. Possible variants: + + * ``initiate`` - do initial connection to remote peer immediately after configuring and after boot. In this mode the connection will not be restarted in case of disconnection, therefore should be used only together with DPD or another session tracking methods; + + * ``respond`` - do not try to initiate a connection to a remote peer. In this mode, the IPSec session will be established only after initiation from a remote peer. Could be useful when there is no direct connectivity to the peer due to firewall or NAT in the middle of the local and remote side. + +* ``default-esp-group`` - ESP group to use by default for traffic encryption. Might be overwritten by individual settings for tunnel or VTI interface binding; + +* ``description`` - description for this peer; + +* ``dhcp-interface`` - use an IP address, received from DHCP for IPSec connection with this peer, instead of ``local-address``; + +* ``force-encapsulation`` - force encapsulation of ESP into UDP datagrams. Useful in case if between local and remote side is firewall or NAT, which not allows passing plain ESP packets between them; + +* ``ike-group`` - IKE group to use for key exchanges; + +* ``ikev2-reauth`` - reauthenticate remote peer during the rekeying process. Can be used only with IKEv2: + + * ``yes`` - create a new IKE_SA from the scratch and try to recreate all IPsec SAs; + + * ``no`` - rekey without uninstalling the IPsec SAs; + + * ``inherit`` - use default behavior for the used IKE group. + +* ``local-address`` - local IP address for IPSec connection with this peer. If defined ``any``, then an IP address which configured on interface with default route will be used; + +* ``tunnel`` - define criteria for traffic to be matched for encrypting and send it to a peer: + + * ``disable`` - disable this tunnel; + + * ``esp-group`` - define ESP group for encrypt traffic, defined by this tunnel; + + * ``local`` - define a local source for match traffic, which should be encrypted and send to this peer: + + * ``port`` - define port. Have effect only when used together with ``prefix``; + + * ``prefix`` - IP network at local side. + + * ``protocol`` - define the protocol for match traffic, which should be encrypted and send to this peer; + + * ``remote`` - define the remote destination for match traffic, which should be encrypted and send to this peer: + + * ``port`` - define port. Have effect only when used together with ``prefix``; + + * ``prefix`` - IP network at remote side. + +* ``vti`` - use a VTI interface for traffic encryption. Any traffic, which will be send to VTI interface will be encrypted and send to this peer. Using VTI makes IPSec configuration much flexible and easier in complex situation, and allows to dynamically add/delete remote networks, reachable via a peer, as in this mode router don't need to create additional SA/policy for each remote network: + + * ``bind`` - select a VTI interface to bind to this peer; + + * ``esp-group`` - define ESP group for encrypt traffic, passed this VTI interface. + +Examples: +------------------ + +IKEv1 +^^^^^ + +Example: + +* WAN interface on `eth1` +* left subnet: `192.168.0.0/24` site1, server side (i.e. locality, actually + there is no client or server roles) +* left local_ip: `198.51.100.3` # server side WAN IP +* right subnet: `10.0.0.0/24` site2,remote office side +* right local_ip: `203.0.113.2` # remote office side WAN IP + +.. code-block:: none + + # 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 203.0.113.2 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 203.0.113.2 authentication pre-shared-secret 'SomePreSharedKey' + set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'office-srv-ike' + set vpn ipsec site-to-site peer 203.0.113.2 local-address '198.51.100.3' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 allow-nat-networks 'disable' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 allow-public-networks 'disable' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 esp-group 'office-srv-esp' + set vpn ipsec site-to-site peer 203.0.113.2 tunnel 0 local prefix '192.168.0.0/24' + set vpn ipsec site-to-site peer 203.0.113.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 198.51.100.3 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 198.51.100.3 authentication pre-shared-secret 'SomePreSharedKey' + set vpn ipsec site-to-site peer 198.51.100.3 ike-group 'office-srv-ike' + set vpn ipsec site-to-site peer 198.51.100.3 local-address '203.0.113.2' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 allow-nat-networks 'disable' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 allow-public-networks 'disable' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 esp-group 'office-srv-esp' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 local prefix '10.0.0.0/21' + set vpn ipsec site-to-site peer 198.51.100.3 tunnel 0 remote prefix '192.168.0.0/24' + +Show status of new setup: + +.. code-block:: none + + vyos@srv-gw0:~$ show vpn ike sa + Peer ID / IP Local ID / IP + ------------ ------------- + 203.0.113.2 198.51.100.3 + 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 + ------------ ------------- + 203.0.113.2 198.51.100.3 + 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:: none + + # 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:: none + + # 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' + +IKEv2 +^^^^^ + +Imagine the following topology + +.. figure:: /_static/images/vpn_s2s_ikev2.png + :scale: 50 % + :alt: IPSec IKEv2 site2site VPN + + IPSec IKEv2 site2site VPN (source ./draw.io/vpn_s2s_ikev2.drawio) + + +.. note:: Don't get confused about the used /31 tunnel subnet. RFC3031_ gives + you additional information for using /31 subnets on point-to-point links. + +**left** + +.. code-block:: none + + set interfaces vti vti10 address '10.0.0.2/31' + + set vpn ipsec esp-group ESP_DEFAULT compression 'disable' + set vpn ipsec esp-group ESP_DEFAULT lifetime '3600' + set vpn ipsec esp-group ESP_DEFAULT mode 'tunnel' + set vpn ipsec esp-group ESP_DEFAULT pfs 'dh-group19' + set vpn ipsec esp-group ESP_DEFAULT proposal 10 encryption 'aes256gcm128' + set vpn ipsec esp-group ESP_DEFAULT proposal 10 hash 'sha256' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection action 'hold' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection interval '30' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection timeout '120' + set vpn ipsec ike-group IKEv2_DEFAULT ikev2-reauth 'no' + set vpn ipsec ike-group IKEv2_DEFAULT key-exchange 'ikev2' + set vpn ipsec ike-group IKEv2_DEFAULT lifetime '10800' + set vpn ipsec ike-group IKEv2_DEFAULT mobike 'disable' + set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 dh-group '19' + set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 encryption 'aes256gcm128' + set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 hash 'sha256' + set vpn ipsec ipsec-interfaces interface 'eth0.201' + set vpn ipsec site-to-site peer 172.18.202.10 authentication id '172.18.201.10' + set vpn ipsec site-to-site peer 172.18.202.10 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 172.18.202.10 authentication pre-shared-secret 'secretkey' + set vpn ipsec site-to-site peer 172.18.202.10 authentication remote-id '172.18.202.10' + set vpn ipsec site-to-site peer 172.18.202.10 connection-type 'initiate' + set vpn ipsec site-to-site peer 172.18.202.10 ike-group 'IKEv2_DEFAULT' + set vpn ipsec site-to-site peer 172.18.202.10 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 172.18.202.10 local-address '172.18.201.10' + set vpn ipsec site-to-site peer 172.18.202.10 vti bind 'vti10' + set vpn ipsec site-to-site peer 172.18.202.10 vti esp-group 'ESP_DEFAULT' + +**right** + +.. code-block:: none + + set interfaces vti vti10 address '10.0.0.3/31' + + set vpn ipsec esp-group ESP_DEFAULT compression 'disable' + set vpn ipsec esp-group ESP_DEFAULT lifetime '3600' + set vpn ipsec esp-group ESP_DEFAULT mode 'tunnel' + set vpn ipsec esp-group ESP_DEFAULT pfs 'dh-group19' + set vpn ipsec esp-group ESP_DEFAULT proposal 10 encryption 'aes256gcm128' + set vpn ipsec esp-group ESP_DEFAULT proposal 10 hash 'sha256' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection action 'hold' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection interval '30' + set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection timeout '120' + set vpn ipsec ike-group IKEv2_DEFAULT ikev2-reauth 'no' + set vpn ipsec ike-group IKEv2_DEFAULT key-exchange 'ikev2' + set vpn ipsec ike-group IKEv2_DEFAULT lifetime '10800' + set vpn ipsec ike-group IKEv2_DEFAULT mobike 'disable' + set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 dh-group '19' + set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 encryption 'aes256gcm128' + set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 hash 'sha256' + set vpn ipsec ipsec-interfaces interface 'eth0.202' + set vpn ipsec site-to-site peer 172.18.201.10 authentication id '172.18.202.10' + set vpn ipsec site-to-site peer 172.18.201.10 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 172.18.201.10 authentication pre-shared-secret 'secretkey' + set vpn ipsec site-to-site peer 172.18.201.10 authentication remote-id '172.18.201.10' + set vpn ipsec site-to-site peer 172.18.201.10 connection-type 'initiate' + set vpn ipsec site-to-site peer 172.18.201.10 ike-group 'IKEv2_DEFAULT' + set vpn ipsec site-to-site peer 172.18.201.10 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 172.18.201.10 local-address '172.18.202.10' + set vpn ipsec site-to-site peer 172.18.201.10 vti bind 'vti10' + set vpn ipsec site-to-site peer 172.18.201.10 vti esp-group 'ESP_DEFAULT' + +.. _RFC3031: https://tools.ietf.org/html/rfc3021 diff --git a/docs/configuration/zonepolicy/index.rst b/docs/configuration/zonepolicy/index.rst new file mode 100644 index 00000000..5da40d6d --- /dev/null +++ b/docs/configuration/zonepolicy/index.rst @@ -0,0 +1,9 @@ +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 example to zone-based firewalls can be found here: :ref:`examples-zone-policy`.
\ No newline at end of file |